Using Nuxeo Automation Client

As we've seen in previous examples you can invoke a remote automation server using any language or HTTP tool you want. Nuxeo already provides a high level client implementation for Java programmers. Using this client API simplifies your task since it handles all the protocol level details.

To use the java automation client you need to put a dependency on the following maven artifact:

For a direct download, see https://maven.nuxeo.org/.

This documentation applies for nuxeo-automation-client versions greater or equal to 5.4.

The client library depends on:

• net.sf.json-lib:json-lib, net.sf.ezmorph:ezmorph - for JSON support
• Since Nuxeo 5.6, net.sf.json-lib:json-lib is being replaced with org.codehaus.jackson:jackson-core-asl and org.codehaus.jackson:jackson-mapper-asl.
• org.apache.httpcomponents:httpcore, org.apache.httpcomponents:httpclient - for HTTP support
• javax.mail - for multipart content support

Query example

Here is the same example as the one in Java API example - execute the "SELECT * FROM Document" query against a remote automation server:

You can see using the automation client is mush easier than writing yourself all the protocol details as in the previous example Using Java API

You can see the code above has 3 distinctive parts:

1. Opening a connection.
2. Invoking remote operations
3. Destroying the client.

So before using the Automation Client you should first create a new client that is connecting to a remote address you can specify through the constructor URL argument. (As the remote server URL you should use the URL of the Automation service):

No connection to the remote service is made at this step. The automation service definition will be downloaded the first time you create a session. A local registry of available operations are created from the service definition sent by the server.

The local registry of operations contains all operations on the server - but you can invoke only operations that are accessible to your user - otherwise a 404 (operation not found) will be sent by the server)

Once you created a client instance you must create a new session to be able to start to invoke remote operations. When creating a session you should pass the credentials to be used to authenticate against the server.

So you create a new session by calling:

This will authenticates you onto the server using the basic authentication scheme. If needed, you can use another authentication
scheme by setting an interceptor.

Using a session you can now invoke remote operations. To create a new invocation request you should pass in the right operation or chain ID:

and then populate the request with all the required arguments:

You can see in our example you have to specify only the query argument. If you have more arguments you call in turn the set method for each of these arguments. If you need to specify execution context parameters you can use request.setContextProperty method. The same, if you need to specify custom HTTP headers you can use the request.setHeader method.

After having filled all the required request information you can execute the request by calling the execute method.

The client API provides both synchronous and asynchronous execution For an asynchronous execution you can make a call to the execute(AsyncCallback<Object> cb) method. Beware that you can set the timeout in milliseconds for the wait of the aynchronous thread pool termination at client shutdown by passing it to the HttpAutomationClient constructor: public HttpAutomationClient(String url, long httpConnectionTimeout, long asyncAwaitTerminationTimeout). Default value is 2 seconds. If you don't use any asynchronous call you can set this timeout to 0 in order not to wait at client shutdown.

Setting the HTTP connection timeout You can set a timeout in milliseconds for the HTTP connection in order to avoid an infinite wait in case of a network cut or if the Nuxeo server is not responding. Just pass it to the HttpAutomationClient constructor: public HttpAutomationClient(String url, long httpConnectionTimeout, long asyncAwaitTerminationTimeout). Default value is 0 = no timeout.

Executing a request will either thrown an exception or return the result. The result object can be null if the operation has no result (i.e. a void operation) - otherwise a Java object is returned. The JSON result is automatically decoded into a proper Java object. The following objects are supported as operation results:

• Document - a document object
• Documents - a list of documents
• Blob - a file
• Blobs - a file list

In case the operation invocation fails - an exception described by a JSON entity will be sent by the server and the client will automatically decode it into a real java exception derived from org.nuxeo.ecm.automation.client.jaxrs.RemoteException.

Before sending the request the client will check the operation arguments to see if they match the operation definition and will throw an exception if some required argument is missing. The request will be sent only after validation successfully completes.

The query example is pretty simply. The query operation doesn't need an input object to be executed. (i.e. the input can be null). But most operations require an input. In that case you must call request.setInput method to set the input. We will see more about this in the following examples.

If you prefer a most compact notation you can use the fluent interface way of calling methods:

When you are done with the client you must call the client.disconnect method to free any resource held by the client. Usually this is done only once when the client application is shutdown. Creating new client instances and destroying them may be costly so you should use a singleton client instance and use it from different threads (which is safe).

If you need different logins then creating one session per login. A session is thread safe.

Blob upload example

In this example we assume we already have a session instance.
The example will create a new File document into the root "/" document and then will upload a file into. Finally we will download back this file.

First get the root document and create a new File document at location /myfile

Note the usage of setInput() method. This is to specify that the create operation must be executed in the context of the root document - so the new document will be created under the root document. Also you can notice that the input object is a Document instance.

Now get the file to upload and put it into the newly created document.

The last execute call will return null since the HEADER_NX_VOIDOP header was used. This is to avoid receiving back from the server the blob we just uploaded.

Note that to upload a file we need to use a Blob object that wrap the file to upload.

Now get the the file document where the blob was uploaded. Then retrieve the blob remote URL from the document metadata. We can use this URL to download the blob.

You can see we used the special HEADER_NX_SCHEMAS header to specify we want all properties of the document to be included in the response.

Now download the file located on the server under the path we retrieved from the document properties:

We can do the same by invoking the Blob.Get operation.

The complete example

Here is the complete code of the example. For more examples, see the unit tests in nuxeo-automation-server project.