// Copyright 2011 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.enterprise.adaptor;

import java.io.*;
import java.net.URI;
import java.util.Date;

/**
 * Interface provided to {@link Adaptor#getDocContent
 * Adaptor.getDocContent(Request, Response)} for performing the actions needed
 * to satisfy a request.
 *
 * <p>There are several ways that a request can be processed. In the simplest
 * case an Adaptor always sets different pieces of metadata, calls {@link
 * #getOutputStream}, and writes the document contents. If the document does not
 * exist, it should call {@link #respondNotFound} instead.
 *
 * <p>For improved efficiency during recrawl by the GSA, an Adaptor should check
 * {@link Request#hasChangedSinceLastAccess} and call {@link
 * #respondNotModified} when it is {@code true}. This prevents the Adaptor from
 * ever needing to retrieve the document contents and metadata.
 */
public interface Response {
  /**
   * Respond to the GSA or other client that it already has the latest version
   * of a file and its metadata. If you have called other methods on this object
   * to provide various metadata, the effects of those methods will be ignored.
   *
   * <p>If called, this must be the last call to this interface. Once you call
   * this method, for the rest of the processing, exceptions may no longer be
   * communicated to clients cleanly.
   */
  public void respondNotModified() throws IOException;

  /**
   * Respond to the GSA or other client that the request document does not
   * exist. If you have called other methods on this object, the effects of
   * those methods will be ignored.
   *
   * <p>If called, this must be the last call to this interface. Once you call
   * this method, for the rest of the processing, exceptions may no longer be
   * communicated to the clients cleanly.
   */
  public void respondNotFound() throws IOException;

  /**
   * Get stream to write document contents to. There is no need to flush or
   * close the {@code OutputStream} when done.
   *
   * <p>If called, this must be the last call to this interface (although, for
   * convenience, you may call this method multiple times). Once you call this
   * method, for the rest of the processing, exceptions may no longer be
   * communicated to clients cleanly.
   */
  public OutputStream getOutputStream() throws IOException;

  /**
   * Describe the content type of the document.
   */
  public void setContentType(String contentType);

  /**
   * Provide the last modification time of the document.
   */
  public void setLastModified(Date lastModified);

  /**
   * Add metadata element that applies to the document. Providing multiple
   * values for the same key is supported; simply repeat the call once for each
   * value.
   *
   * @param key the key of metadata element
   * @param value the value of metadata element
   * @throws NullPointerException if {@code key} or {@code value}
   *     is {@code null}
   */
  public void addMetadata(String key, String value);

  /**
   * Provide the document's ACLs for early-binding security on the GSA. By
   * default, the document's ACL will be {@code null}, which means the document
   * is public if the document isn't marked as secure via {@link #setSecure}.
   */
  public void setAcl(Acl acl);

  /**
   * Provide alternative ACLs for this document, uniquely identified by
   * response document's {@code DocId} and {@code fragment}.
   */
  public void putNamedResource(String fragment, Acl acl);

  /**
   * Mark the document as secure, for use with late-binding security. By
   * default, the secure setting will be {@code false}, which means the document
   * is public if there are no ACLs. ACLs should be used, if possible, instead
   * of setting this option to {@code true}. When {@code true}, the GSA needs to
   * be correctly configured to issue a SAML request to the Adaptor.
   * Setting ACLs to non-null will override setSecure and send secure indicator
   * to GSA.
   */
  public void setSecure(boolean secure);

  /**
   * Add a hyperlink for the GSA to follow without modifying the document
   * contents. This is equivalent to the following HTML: {@code
   * <a href='$uri'>$text</a>}. If you want to link to a {@link DocId}, then you
   * may use the {@link DocIdEncoder} provided by {@link
   * AdaptorContext#getDocIdEncoder} to produce an appropriate URI.
   *
   * @param uri the URI of the anchor
   * @param text the text of the anchor, or {@code null}
   * @throws NullPointerException if {@code uri} is {@code null}
   */
  public void addAnchor(URI uri, String text);

  /**
   * Whether the GSA should index the content for searching. When {@code true},
   * the document will not be visible in search results. This does not change
   * the GSA's behavior of following links within the document to find other
   * documents. By default, the GSA will index the document (a value of {@code
   * false}).
   *
   * @param noIndex {@code true} when the GSA shouldn't index this document
   */
  public void setNoIndex(boolean noIndex);

  /**
   * Whether the GSA should follow the links within the document to find other
   * documents. By default, the GSA will follow links (a value of {@code
   * false}).
   *
   * @param noFollow {@code true} when the GSA shouldn't follow links from this
   *     document to find other documents
   */
  public void setNoFollow(boolean noFollow);

  /**
   * Whether the GSA should show the "Cached" link in search results for this
   * document. By default, the GSA will show the "Cached" link (a value of
   * {@code false}).
   *
   * @param noArchive {@code true} when the GSA shouldn't show the "Cached"
   *     link in search results
   */
  public void setNoArchive(boolean noArchive);

  /**
   * Set the URI to be displayed in search results. If {@code null}, then the
   * crawl URI representing the {@code DocId} is used. The default is {@code
   * null}.
   *
   * @param displayUrl URI to be used for this document in search results
   */
  public void setDisplayUrl(URI displayUrl);

  /**
   * Instruct the GSA to not recrawl the document after the initial
   * retrieval. The default is {@code false}.
   *
   * @param crawlOnce if {@code true}, the document does not need to be
   *     recrawled periodically
   */
  public void setCrawlOnce(boolean crawlOnce);

  /**
   * Instruct the GSA to "lock" the document into its index. When the license
   * limit is reached on the GSA, it deletes unlocked documents before locked
   * documents while making room for new documents. The default is {@code
   * false}.
   *
   * @param lock if {@code true}, keep this document in the index in preference
   *     to unlocked documents
   */
  public void setLock(boolean lock);
}