Package com.yahoo.documentapi.local

Class LocalDocumentAccess

  • public class LocalDocumentAccess
extends DocumentAccess
    The main class of the local implementation of the document api. To easily obtain an instance of this, with the documents using the schemas (.sd-files) in a given directoy, use the com.yahoo.vespa.application test module and DocumentAccesses.ofSchemas(schemaDirectory)
    Author:
    bratseth, jonmv

    • Method Detail

      • createSyncSession

        public LocalSyncSession createSyncSession​(SyncParameters parameters)
        Description copied from class: DocumentAccess
        Returns a session for synchronous document access. Use this for simple access.
        Specified by:
        createSyncSession in class DocumentAccess
        Parameters:
        parameters - the parameters of this sync session
        Returns:
        a session to use for synchronous document access

      • createAsyncSession

        public LocalAsyncSession createAsyncSession​(AsyncParameters parameters)
        Description copied from class: DocumentAccess
        Returns a session for asynchronous document access. Use this if high operation throughput is required.
        Specified by:
        createAsyncSession in class DocumentAccess
        Parameters:
        parameters - the parameters of this async session.
        Returns:
        a session to use for asynchronous document access.

      • createVisitorSession

        public LocalVisitorSession createVisitorSession​(VisitorParameters parameters)
                                         throws com.yahoo.document.select.parser.ParseException
        Description copied from class: DocumentAccess
        Run a visitor with the given visitor parameters, and get the result back here.
        Specified by:
        createVisitorSession in class DocumentAccess
        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:
        com.yahoo.document.select.parser.ParseException - if the document selection string could not be parsed

      • createSubscription

        public SubscriptionSession createSubscription​(SubscriptionParameters parameters)
        Description copied from class: DocumentAccess
        Creates a subscription and returns a session for getting data from it. Use this to get document operations being done by other parties.
        Specified by:
        createSubscription in class DocumentAccess
        Parameters:
        parameters - The parameters of this subscription session
        Returns:
        a session to use for document subscription

      • openSubscription

        public SubscriptionSession openSubscription​(SubscriptionParameters parameters)
        Description copied from class: DocumentAccess
        Returns a session for document subscription. Use this to get document operations being done by other parties.
        Specified by:
        openSubscription in class DocumentAccess
        Parameters:
        parameters - the parameters of this subscription session
        Returns:
        a session to use for document subscription

      • setPhaser

        public void setPhaser​(Phaser phaser)
        Sets a Phaser for synchronization of otherwise async operations in sessions backed by this. AsyncSession and VisitorSession are by nature async. The LocalAsyncSession is, by default, synchronous, i.e., responses are sent by the thread that sends the document operations. LocalVisitorSession, on the other hand, is asynchronous by default, i.e., all documents are sent by a dedicated sender thread. To enable more advanced testing using the LocalDocumentAccess, this method lets the user specify a Phaser used to synchronize the sending of documents from the visitor, and the responses for the document operations — which are then also done by a dedicated thread pool, instead of the caller thread. When this is set, a party is registered with the phaser for the sender thread (visit) or for each document operation (async-session). The thread that sends a document (visit) or response (async-session) then arrives and awaits advance before sending each response, so the user can trigger these documents and responses. After the document or response is delivered, the thread arrives and awaits advance, so the user can wait until the document or response has been delivered. This also ensures memory visibility. The visit sender thread deregisters when the whole visit is done; the async session threads after each operation. Example usage: 
         
 void testOperations(LocalDocumentAccess access) {
   List<Response> responses = new ArrayList<>();
   Phaser phaser = new Phaser(1);    // "1" to register self
   access.setPhaser(phaser);
   AsyncSession session = access.createAsyncSession(new AsyncParameters().setReponseHandler(responses::add));
   session.put(documentPut);
   session.get(documentId);
                                     // Operations wait for this thread to arrive at "phaser"
   phaser.arriveAndAwaitAdvance();   // Let operations send their responses
                                     // "responses" may or may not hold the responses now
   phaser.arriveAndAwaitAdvance();   // Wait for operations to complete sending responses, memory visibility, etc.
                                     // "responses" now has responses from all previous operations
   phaser.arriveAndDeregister();     // Deregister so further operations flow freely
 }