Programmer : Connector Programmer : Using the Push API Client : Operations and states
 
Operations and states
 
Operations
Document statuses
Session handling
Operations
The basic PAPI operations are the following:
Operation
Description
AddDocument
Creates a document including the parts, URI, metas, etc.
GetDocumentStatus
Using the documents URIs, it retrieves the stamps and their statuses to determine the statuses of documents.
Delete
The following methods are available:
• delete a document identified by its URI.
• deleteDocumentRootPath – deletes a collection of documents (recursively or not) matching a given root path. The hierarchy is based on the slashes “/”of the URI.
• deleteDocumentsWithPrefix – deletes all child documents under a root prefix. This method is useful if the document hierarchy is not based on slashes, but can be risky as it does not have any filtering mechanism. For example, if you have the following documents:
◦ eno:bo:master
◦ eno:bo:masterpart
◦ eno:bo:masterpart:subpart1
◦ eno:bo:master:subpart2
Using deleteDocumentsWithPrefix(“eno:bo:master”) will delete all documents with this prefix, even if you want to delete eno:bo:master and eno:bo:master:subpart2 only.
Enumerate
Lists the Exalead CloudView documents and their stamps, given a URI prefix (recursively or not).
Checkpoints
Sets, retrieves or removes checkpoints. For example, to perform incremental updates easily.
UpdateDocument
Updates a document including parts and metas.
Document statuses
Because some operations are performed asynchronously (add, delete, set checkpoint), it's important to know at which state of the processing flow the command is performed.
The above operations can have the following document statuses:
Status
Description
Initial
Data is only in the source (not already sent to the index by the connector).
Pushed
The document has been received by the Exalead CloudView index, but can be lost if a crash occurs before the sync.
All Add(), Delete() operations create a document in the Pushed state.
GetDocumentStatus(), GetCheckpoint(), EnumerateCheckpointsInfo() operate on documents pushed, synced, and searchable.
Synced
The document has been securely synced to disk. This guarantees crash-proofness. Documents cannot be lost.
EnumeratesSyncedEntries() operates on document synced.
Searchable
The document can be found at search time.
Session handling
The Push API session handling mechanism helps guarantee the consistency of a stream of PAPI operations, even in the event of a PAPI server restart between operations.
The mechanism can be used by calling startPushSession() before sending your PAPI operations, and stopPushSession() at the end of your operations. If an unexpected restart occurs, the next operation will trigger a session identifier mismatch.
Internally, startPushSession asks the remote Push API server for its current session identifier, created when the server starts. This identifier will be used in all further client commands to ensure that the server keeps the same identifier. Any command with a session identifier mismatch will fail with an error. stopPushSession clears the current session identifier. All further client commands will no longer use the session identifier after this call.
Note: For a managed connector, the startPushSession() and stopPushSession calls are made automatically by the framework and do not have to be included in the connector code. For an unmanaged connector, the startPushSession() and stopPushSession calls must be included manually in the connector code.