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
The client library depends on:
net.sf.ezmorph:ezmorph- for JSON support
- Since Nuxeo 5.6,
net.sf.json-lib:json-libis being replaced with
org.apache.httpcomponents:httpclient- for HTTP support
javax.mail- for multipart content support
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
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
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
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
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
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
Note the usage of
Now get the file to upload and put it into the newly created document.
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
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
The complete example
Here is the complete code of the example. For more examples, see the unit tests in