Operations and states

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.