Push API Client Implementation Recommendations

You should follow certain conventions for method interface and method names:

• The interface should be called PushAPI. For example, PushAPI(Java), IPushAPI(C#)…

• The HttpPushAPI class implements PushAPI. The constructor must be in the form:

  HttpPushAPI(PushAPIVersion version, String host, String port, String connectorName, 
  String connectorType, String login, String password)

• The FakePushAPI class implements PushAPI. This class is optional and should be a simulator for test.

• The PushAPIFactory class should be implemented to create HttpPushAPI and FakePushAPI

  • PushAPI createFake() (optional)

  • PushAPI createHttp(PushAPIVersion version, String host, String port, String connectorName, String connectorType, String login, String password)

The following description is based on C# naming conventions.

Argument	Description
host	The Push API server host name.
port	The Push API server port number (by default, <BASEPORT> + 2).
PushAPIVersion	The Push API version. For the moment, the only accepted value is PAPI_V4 for Exalead CloudView 5.x and 6.x For example, PushAPIVersion.PAPI_V4
connectorName	The name of the connector.
connectorType	The type of the connector. It is mainly used for license checking purpose (the available connector types are described in your product license).
login	The basic authentication login string. If not null, the basic authentication mode will be enabled.
password	The basic authentication password string. If not null, the basic authentication mode will be enabled. Login and Password must either be both null or not null.

Each class must implement specific methods.

The Push API client should use an asynchronous mechanism while treating add and delete operations. This means that requested add or delete operations are accepted immediately but will be executed later. Every method of the Push API client should send exceptions as follows:

• ServerUnavailableException – when the remote Exalead CloudView product cannot be reached (network or overload errors).

• InvalidConnectorException – if the Exalead CloudView Push API server does not recognize the client Connector name.

• UnknownErrorException – when an unexpected error occurs.

Additionally, we recommend implementing optional exceptions. List of possible error types:

• InvalidConnectorNameError

• InvalidParameterError

• UnknownError

For languages that do not support the exception mechanism, the language error management should be used instead. The convention for error serialization is the following:

<error>
 <type> ... </type>
    <short_message>  ... </short_message>
    <message>  ... </message>
</error>

Because some operations on documents and checkpoints are performed asynchronously (add, delete, set checkpoint), it's important to know at which state of the processing flow the command is performed.

Operations can have the following processing statuses:

Status	Description
Pushed	The operation has been received by Exalead CloudView, but can be lost if a crash occurs before the sync. All add, delete, and set checkpoints (Add(), Delete(), SetCheckpoint()) operations create a document in the Pushed state.
Synced	The operation has been synced to disk, to guarantee crash-proofness. The operation cannot be lost anymore. When you synchronize explicitly or choose to synchronize when you set a checkpoint, all documents and checkpoint operations are synced to disk.
Searchable	The operation has been propagated to the index, and documents can be found at search time.

The following methods operate on documents in specific states:

Methods	operate on documents with statuses...
Enumerating checkpoints and synced entries, getting checkpoints and counting synced entries: EnumeratesSyncedEntries() GetCheckpoint() EnumerateCheckpointsInfo() countSyncedEntries()	synced and searchable.
Getting document status and clearing checkpoints: GetDocumentStatus() ClearAllCheckpoints()	pushed, synced, and searchable.