com.yahoo.documentapi

Class DocumentAccess

java.lang.Object

com.yahoo.documentapi.DocumentAccess

Direct Known Subclasses:

LocalDocumentAccess, MessageBusDocumentAccess

public abstract class DocumentAccess
extends Object

This is the starting point of the document api. This api provides access to documents in a document repository. The document api contains four separate access types:

• Synchronous random access - provided by SyncSession, allows simple access where throughput is not a concern.
• Asynchronous random access - provided by AsyncSession, allows document repository writes and random access with high throughput.
• Visiting - provided by VisitorSession, allows a set of documents to be accessed in an order decided by the document repository. This allows much higher read throughput than random access.
• Subscription - provided by SubscriptionSession, allows changes to a defined set of documents in the repository to be visited.

This class is the factory for creating the four session types mentioned above.

There may be multiple implementations of the document api classes. If default configuration is sufficient, use the createDefault() method to return a running document access. Note that there are running threads within an access object, so you must shut it down when done.

An implementation of the Document Api may support just a subset of the access types defined in this interface. For example, some document repositories, like indexes, are write only. Others may support random access, but not visiting and subscription. Any method which is not supported by the underlying implementation will throw UnsupportedOperationException.

Access to this class is thread-safe.

Author:

bratseth, Einar Rosenvinge, Simon Thoresen

Field Summary

Fields

Modifier and Type	Field and Description
private com.yahoo.config.subscription.ConfigSubscriber	documentTypeConfigSubscriber
private com.yahoo.document.DocumentTypeManager	documentTypeManager

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DocumentAccess(DocumentAccessParams params) Constructs a new document access object.

Method Summary

Modifier and Type	Method and Description
abstract AsyncSession	createAsyncSession(AsyncParameters parameters) Returns a session for asynchronous document access.
static DocumentAccess	createDefault() This is a convenience method to return a document access object with all default parameter values.
abstract SubscriptionSession	createSubscription(SubscriptionParameters parameters) Creates a subscription and returns a session for getting data from it.
abstract SyncSession	createSyncSession(SyncParameters parameters) Returns a session for synchronous document access.
abstract VisitorDestinationSession	createVisitorDestinationSession(VisitorDestinationParameters parameters) Creates a destination session for receiving data from visiting.
abstract VisitorSession	createVisitorSession(VisitorParameters parameters) Run a visitor with the given visitor parameters, and get the result back here.
com.yahoo.document.DocumentTypeManager	getDocumentTypeManager() Returns the DocumentTypeManager used by this DocumentAccess.
abstract SubscriptionSession	openSubscription(SubscriptionParameters parameters) Returns a session for document subscription.
void	shutdown() Shuts down the underlying sessions used by this DocumentAccess; subsequent use of this DocumentAccess will throw unspecified exceptions, depending on implementation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

documentTypeManager

private final com.yahoo.document.DocumentTypeManager documentTypeManager

documentTypeConfigSubscriber

private final com.yahoo.config.subscription.ConfigSubscriber documentTypeConfigSubscriber

Constructor Detail

DocumentAccess

protected DocumentAccess(DocumentAccessParams params)

Constructs a new document access object.

Parameters:

params - The parameters to use for setup.

Method Detail

createDefault

public static DocumentAccess createDefault()

This is a convenience method to return a document access object with all default parameter values. The client that calls this method is also responsible for shutting the object down when done. If an error occurred while attempting to create such an object, this method will throw an exception.

Returns:

A running document access object with all default configuration.

createSyncSession

public abstract SyncSession createSyncSession(SyncParameters parameters)

Returns a session for synchronous document access. Use this for simple access.

Parameters:

parameters - The parameters of this sync session.

Returns:

A session to use for synchronous document access.

Throws:

UnsupportedOperationException - If this access implementation does not support synchronous access.

RuntimeException - If an error prevented the session from being created.

createAsyncSession

public abstract AsyncSession createAsyncSession(AsyncParameters parameters)

Returns a session for asynchronous document access. Use this if high operation throughput is required.

Parameters:

parameters - The parameters of this async session.

Returns:

A session to use for asynchronous document access.

Throws:

UnsupportedOperationException - If this access implementation does not support asynchronous access.

RuntimeException - If an error prevented the session from being created.

createVisitorSession

public abstract VisitorSession createVisitorSession(VisitorParameters parameters)
                                             throws com.yahoo.document.select.parser.ParseException

Run a visitor with the given visitor parameters, and get the result back here.

Parameters:

parameters - The parameters of this visitor session.

Returns:

A session used to track progress of the visitor and get the actual data returned.

Throws:

UnsupportedOperationException - If this access implementation does not support visiting.

RuntimeException - If an error prevented the session from being created.

com.yahoo.document.select.parser.ParseException - If the document selection string could not be parsed.

createVisitorDestinationSession

public abstract VisitorDestinationSession createVisitorDestinationSession(VisitorDestinationParameters parameters)

Creates a destination session for receiving data from visiting. The visitor must be started and progress tracked through a visitor session.

Parameters:

parameters - The parameters of this visitor destination session.

Returns:

A session used to get the actual data returned.

Throws:

UnsupportedOperationException - If this access implementation does not support visiting.

createSubscription

public abstract SubscriptionSession createSubscription(SubscriptionParameters parameters)

Creates a subscription and returns a session for getting data from it. Use this to get document operations being done by other parties.

Parameters:

parameters - The parameters of this subscription session.

Returns:

A session to use for document subscription.

Throws:

UnsupportedOperationException - If this access implementation does not support subscription.

RuntimeException - If an error prevented the session from being created.

openSubscription

public abstract SubscriptionSession openSubscription(SubscriptionParameters parameters)

Returns a session for document subscription. Use this to get document operations being done by other parties.

Parameters:

parameters - The parameters of this subscription session.

Returns:

A session to use for document subscription.

Throws:

UnsupportedOperationException - If this access implementation does not support subscription.

RuntimeException - If an error prevented the session from being created.

shutdown

public void shutdown()

Shuts down the underlying sessions used by this DocumentAccess; subsequent use of this DocumentAccess will throw unspecified exceptions, depending on implementation. Classes overriding this must call super.shutdown().

getDocumentTypeManager

public com.yahoo.document.DocumentTypeManager getDocumentTypeManager()

Returns the DocumentTypeManager used by this DocumentAccess.

Returns:

The document type manager.