// Copyright 2010 Google Inc.
//
// 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.connector.spi;
import java.io.OutputStream;
import java.util.Iterator;
import javax.sql.DataSource;
/**
* This interface is not implemented.
*
* A local persistent store of information about documents that is managed by
* the Connector Manager for connectors.
* <p>
* Document metadata is automatically persisted (or deleted) for documents by
* the Connector Manager:
* <ul>
* <li>for documents in {@link DocumentList} objects returned by the connector
* in response to {@link TraversalManager#startTraversal()} or
* {@link TraversalManager#resumeTraversal(String)} calls</li>
* <li>provided the connector explicitly sets the
* {@link SpiConstants#PROPNAME_MANAGER_SHOULD_PERSIST} property to {@code true}
* </li>
* <li>and provided the {@link SpiConstants#PROPNAME_ACTION} property is not set
* to {@link SpiConstants.ActionType#DELETE} (if it is, then the document is
* removed from the local store)</li>
* <li>however, only those metadata items that are keys in the
* {@link SpiConstants#PERSISTABLE_ATTRIBUTES} map are persisted</li>
* </ul>
* In addition, connector implementors may use the
* {@link #storeDocument(Document)} method to programmatically store a document
* in the local store without sending it through the traversal manager.
* <p>
* The connector may explicitly request stored information to be returned
* through the {@link #findDocument(String)}, {@link #getDocumentIterator()} and
* {@link #getDocumentIterator(String)} calls. These calls return
* {@link Document} objects; again, only those keys in the
* {@link SpiConstants#PERSISTABLE_ATTRIBUTES} map will be populated.
* <p>
* If necessary, the connector developer can also get access to the underlying
* document table in the database implementation of this store by:
* <ul>
* <li>getting it's name through the
* {@link LocalDocumentStore#getDocTableName()} call</li>
* <li>getting a {@link DataSource} object by calling
* {@link LocalDatabase#getDataSource()}</li>
* <li>constructing SQL queries and submitting them through JDBC</li>
* </ul>
* The connector implementor should not create records in this table through
* JDBC.
*
* @see ConnectorPersistentStore
* @since 2.8
* @deprecated This interface has never been publicly implemented
*/
@Deprecated
public interface LocalDocumentStore {
/**
* Finds a {@link Document} in the Connector Manager's per-document store by
* docid. If not found, null is returned. If found, the {@code Document}
* returned contains only the persisted attributes. See
* {@link SpiConstants#PERSISTABLE_ATTRIBUTES}.
*
* @param docid the docid to search for
* @return a {@link Document} or {@code null}, if this document is not found.
*/
public Document findDocument(String docid);
/**
* Returns an iterator of all documents in the store created by this
* connector instance, in sorted order by docid.
* The result iterator is read-only. It will not support
* {@link Iterator#remove()}.
* <p>
* The documents returned will be non-null and will contain only the
* persisted attributes. See {@link SpiConstants#PERSISTABLE_ATTRIBUTES}.
* <p>
* <strong>Note:</strong> The {@code LocalDocumentStore} implementation
* buffers information stored via {@link #storeDocument(Document)}, then
* writes records out in batches. Consequently unflushed documents will
* not yet be available for retrieval. Consider calling {@link #flush()}
* before getting an Iterator. Similarly, the document {@code Iterator}
* implementation fetches documents in batches, so the Iterator may
* return documents that were committed to the document store after the
* {@code Iterator} was created.
*
* @return an {@link Iterator} of all documents created by this connector
* instance, in order by docid
*/
public Iterator<Document> getDocumentIterator();
/**
* Returns an iterator of all documents in the store created by this
* connector instance whose docids are {@code > } the specified docid,
* in sorted order by docid.
* The result iterator is read-only. It will not support
* {@link Iterator#remove()}.
* <p>
* The documents returned will be non-null and will contain only the
* persisted attributes. See {@link SpiConstants#PERSISTABLE_ATTRIBUTES}.
* <p>
* <strong>Note:</strong> The {@code LocalDocumentStore} implementation
* buffers information stored via {@link #storeDocument(Document)}, then
* writes records out in batches. Consequently unflushed documents will
* not yet be available for retrieval. Consider calling {@link #flush()}
* before getting an Iterator. Similarly, the document {@code Iterator}
* implementation fetches documents in batches, so the Iterator may
* return documents that were committed to the document store after the
* {@code Iterator} was created.
*
* @param docid the docid after which to start the iteration, if {@code null}
* or empty, all documents created by this connector are returned
* @return an {@link Iterator} of all documents created by this connector
* instance whose docid exceeds the supplied docid, in order by docid
*/
public Iterator<Document> getDocumentIterator(String docid);
/**
* Persists information about a document. Any attributes that are not keys in
* the {@link SpiConstants#PERSISTABLE_ATTRIBUTES} table will be ignored.
* <p>
* <strong>Note:</strong> The {@code LocalDocumentStore} implementation
* buffers information stored via {@link #storeDocument(Document)}, then
* writes records out in batches for improved document store performance.
* The buffered records are flushed to the document store periodically
* and at the end of processing a traversal batch. See {@link #flush()}.
*
* @param document a {@link Document}
*/
public void storeDocument(Document document);
/**
* Flushes all changes pending in the table. This method is
* similar to {@link OutputStream#flush()}: it is an indication that, if any
* documents previously added or deleted have not yet been committed to the
* store, such records should immediately be committed.
*/
public void flush();
/**
* Returns the table name of the underlying implementation table.
* The connector developer should not use this to do operations that could be
* done directly through this {@code LocalDocumentStore} object. We expect
* this to be used to do queries with non-updatable cursors, involving joins
* between this table and other tables independently managed by the connector.
*
* @return the table name of the underlying table
*/
public String getDocTableName();
}