ATS : REST Operations - Configuring the client


Setting default values for any REST client

The ActionLibraryConfigurator can be used(as the REST client API is part of the ATS Action Library) to get and set some default values for the rest client:

ActionLibraryConfigurator.getInstance().setRestDefaultResponseMediaType( RESTMediaType.APPLICATION_XML );

Using this example we set the default response media type to "application/xml" and this will be the type of content we expect unless we explicitly specify another type using the setResponseMediaType method of the RESTClient class

Use the different methods of the ActionLibraryConfigurator which start with getRest... or setRest... to see all the supported configuration values.



Logging by setting verbose mode

In verbose mode you can trace all HTTP requests and responses.You can select what to log - just headers, bodies or both.

RestClient client = new RestClient( <target URI> );
client.setVerboseMode( RestClient.RestDebugLevel.HEADERS );

This way you will see a similar logging:

INFO  17:52:35 rest.RestClient: Sending the following requests:
           http://10.10.10.10:8080/TestRestServer/services/peoplepage/post
           Accept: application/xml; charset=UTF-8
           Content-Type: text/plain; charset=UTF-8
INFO  17:52:36 rest.RestClient: Receiving the following responses:
           Date: Fri, 21 Aug 2015 14:55:04 GMT
           Transfer-Encoding: chunked
           Content-Type: application/xml;charset=UTF-8
           Server: Apache-Coyote/1.1

In case you have registered to be used Apache HTTP Connector, then verbose logging has a side effect. In that case Apache HTTP Client is used beneath.  And changing log level via RestClient.setVerboseMode() applies change globally to the Apache HTTP Client. So any other HTTP operations  client will use the last severity set. It is recommended to reset back verbosity level at the end of a test (for example in @AfterMethod ot @AfterClass).



Logging by using a proxy

Here are the details. Same for both HttpClient and RestClient.



Set certificate file

This is how you can set some SSL certificate

RestClientConfigurator configurator = new RestClientConfigurator();
configurator.setSSLCertificate( pemCertificate, pemPassword );
client.setClientConfigurator( configurator );



Set transport encryption protocol

Here is example how to set encryption protocol (TLS) to use for HTTPS connections.


RestClient client = new RestClient( <target URI> );

// set TLS protocol to use like TLSv1, TLSv1.1, TLSv1.2
client.setSupportedProtocols(new String[]{"TLSv1.2"});

// execute a REST method
RestResponse response = client.get();

The default TLS version is 1.2



Register some Jersey provider

Currently ATS REST client is using Jersey as underlying third party library. Jersey is giving you an option to register different providers which will affect its behavior.

Jackson JSON processing provider

By default Jersey is using Moxy as its entity processing provider. This is the default provider and it is distributed with ATS, so you do not need to do anything to enable it.

But if you want to use another provider, you must explicitly state it. The Jersey guide info is here

Following are the steps to enable the jersey-media-json-jackson module. You will need to add to the classpath the needed dependencies as they are not distributed by ATS. The list with all dependencies is here

Then you can use code like the following to instruct Jersey to use Jackson provider for processing JSON objects:

RestClientConfigurator configurator = new RestClientConfigurator();

configurator.registerProvider( new JacksonFeature() );
configurator.registerProviderClass( JacksonJsonProvider.class );
configurator.registerProviderClass( JacksonJaxbJsonProvider.class );

client.setClientConfigurator( configurator );

Setting Multipart entity processing provider

Following are the steps to enable the  jersey-media-multipart module. You will need to add to the classpath the needed dependencies as they are not distributed by ATS. The list with all dependencies is here

Then you can use code like the following to make Jersey capable of processing multi-part entities:

RestClientConfigurator configurator = new RestClientConfigurator();

configurator.registerProvider( new MultiPartFeature() );
configurator.registerProvider( MultiPartWriter.class );
configurator.registerProvider( MultiPartReaderClientSide.class );

client.setClientConfigurator( configurator );



Register third-party connector provider


Since 4.0.6, a custom connector provider can be used, instead of the default one (org.glassfish.jersey.client.HttpUrlConnectorProvider)

Here is an example for the verified Apache connector case (using Apache HTTP Components HttpClient under the hood) :


Java code
RestClientConfigurator configurator = new RestClientConfigurator();

Map<String, Object> properties = new HashMap<String, Object>();
// put some Apache properties (optional) See ApacheClientProperties for more information
configurator.registerApacheConnectorProvider();
// or this one -> configurator.registerConnectorProvider( new ApacheConnectorProvider(), properties ); // or null for properties

client.setClientConfigurator( configurator );

This also requires specific dependency to be added in your project. For the above example the Maven dependency is:

Maven POM dependency
<dependency> 
    <groupId>org.glassfish.jersey.connectors</groupId>
    <artifactId>jersey-apache-connector</artifactId>
    <version>${org.glassfish.jersey.jersey-client.version}</version> <!-- This version should match Jersey client version like 2.25.1 for ATS 4.0.6 -->
</dependency>



Use connection pool for connection management

Since 4.0.6, a connection pool can be used to manage connections.

Note that the default connector provider (HttpUrlConnector ) does not support pooling at all, but instead creates a new connection each time a REST method is invoked.

So an Apache connector must be registered, in order to use this feature.

Here is an example how to use this feature:

Java code
...
// boilerplate code
RestClientConfigurator configurator = new RestClientConfigurator();
configurator.registerApacheConnectorProvider();
RestClient client = new RestClient(SERVER_URL);
client.setClientConfigurator( configurator );
// the important line
client.setUsePooling(true);
...



Automatically buffer the response's body

Using connection pool is useful, but one caveat is that user always has to be sure that connections are released to the pool. This requires that the response's body is properly consumed (either fully read or explicitly buffered)

But if you are interested only in the response's status code/message and not the body, you can enable automatic buffering of the body.

Response's body buffering restrictions

This feature will not work if the response's body is larger than 10MB. Also if the body is chunked, by enabling this feature,  you can be presented with OutOfMemoryError.

So be careful when you are using this feature

Here is an example:

Java code
...
// boilerplate code
RestClientConfigurator configurator = new RestClientConfigurator();
configurator.registerApacheConnectorProvider();
RestClient client = new RestClient(SERVER_URL);
client.setClientConfigurator( configurator );

// the important line
client.setUsePooling(true);
client.setBufferResponse(true);
RestResponse response = client.post();
assertEquals(response.getStatusCode(), 200); // here we are interested only in the status code's value and nothing else
...

Executing non-standart HTTP methods

Some HTTP methods, like PATCH, are non-standard. Since ATS is using the HttpUrlConnection as a underlying medium for REST operations, those methods does not work.

In order to use them, you need to use/register another Jersey connector - Apache connector.

A simple example follows:

First, if you are using Maven, add this dependency in your pom.xml <dependencies> section

<dependency>
    <groupId>org.glassfish.jersey.connectors</groupId>
    <artifactId>jersey-apache-connector</artifactId>
    <version>2.25.1</version> <!-- or some other version, corresponding the other Jersey-related components. Currently ATS uses 2.25.1 and 2.27 is tested as well -->
</dependency>

// Note that this code may fail, because we do not provide request body, but if no Java exception is thrown, you have configured your project successfully.
RestClient rc = new RestClient(<SOME_URL>);
RestClientConfigurator rcc = new RestClientConfigurator();
rcc.registerApacheConnectorProvider();
rc.setClientConfigurator(rcc);
rc.execute("PATCH");



Back to parent page

Go to Table of Contents