Gentics Mesh Java Client

Installation

You can add the following maven dependency and repository to your project to get the Gentics Mesh Java client dependencies.

…
	<dependency>
		<artifactId>mesh-rest-client</artifactId>
		<groupId>com.gentics.mesh</groupId>
		<version>${mesh.version}</version>
	</dependency>
…
	<repositories>
		<repository>
			<id>maven.gentics.com</id>
			<name>Gentics Maven Repository</name>
			<url>https://maven.gentics.com/maven2</url>
			<releases>
				<enabled>true</enabled>
			</releases>
			<snapshots>
				<enabled>true</enabled>
			</snapshots>
		</repository>
	</repositories>
…

Java REST Client

The REST client can be used to interact with all Gentics Mesh API Endpoints.

Usage:

MeshRestClient client = MeshRestClient.create("localhost", 8080, false);
client.setLogin("username", "password");
client.login().toCompletable().blockingAwait();

NodeListResponse nodes = client.findNodes("demo", new NodeParametersImpl().setLanguages("en")).blockingGet();
for (NodeResponse nodeResponse : nodes.getData()) {
	System.out.println(nodeResponse.getUuid());
	System.out.println(nodeResponse.getFields().getStringField("name").getString());
}

SSL handling

Usage:

// Set config settings
Builder builder = MeshRestClientConfig.newConfig();
builder.addTrustedCA("certs/server.pem");
builder.setClientCert("certs/alice.pem");
builder.setClientKey("certs/alice.key");
builder.setHost("demo.getmesh.io");
builder.setPort(443);
builder.setSsl(true);
builder.setHostnameVerification(false);
builder.setBasePath("/api/v2");

// Create the client
MeshRestClient client = MeshRestClient.create(builder.build());
UserResponse meInfo = client.me().blockingGet();
System.out.println(meInfo.toJson());

Methods to set the client key which will be used during SSL handshake:

MeshRestClientConfig.Builder#setClientKey(String path)
MeshRestClientConfig.Builder#setClientKey(InputStream ins)
MeshRestClientConfig.Builder#setClientKey(byte[] data)

Methods to set the client certificate which will be used during SSL handshake:

MeshRestClientConfig.Builder#setClientCert(String path)
MeshRestClientConfig.Builder#setClientCert(InputStream ins)
MeshRestClientConfig.Builder#setClientCert(byte[] data)

Methods to add one or more trusted CAs for the client:

MeshRestClientConfig.Builder#addTrustedCA(String path)
MeshRestClientConfig.Builder#addTrustedCA(InputStream ins)
MeshRestClientConfig.Builder#addTrustedCA(byte[] data)

Method to set the hostname verification checks:

MeshRestClientConfig.Builder#setHostnameVerification(boolean flag)

Connection Leaks

In most cases, the connection to Mesh will implicitly be closed when the response object is created. The only exceptions are when loading binary data or doing a webroot or webrootField request (where the response might contain binary data).

For those requests, it is important to make sure, that the response is properly closed in all cases, especially when the response data is not (fully) consumed (e.g. when an error happens while consuming the binary data).

Incorrect example:

client.downloadBinaryField("demo", "01ecd6048ee21471bb90af6deea40d2c", "en", "image")
	.toSingle()
	.doOnSuccess(response -> {
		// an exception might be thrown here, which would leave the response open
	})
	.subscribe();

Better example:

client.downloadBinaryField("demo", "01ecd6048ee21471bb90af6deea40d2c", "en", "image")
	.toSingle()
	.doAfterSuccess(response -> {
		// we explicitly need to close the response here
		response.close();
	})
	.doOnSuccess(response -> {
		// an exception might be thrown here
	})
	.subscribe();

Example with blocking code:

// try-with-resource will make sure, that close() is called on the response
try (MeshBinaryResponse response = client.downloadBinaryField("demo", "01ecd6048ee21471bb90af6deea40d2c", "en", "image")
	.toSingle().blockingGet()) {
	// an exception might be thrown here
}

Use HTTP/2

Since Mesh supports serving over HTTP/2 out of the box, Mesh REST client allows limiting connection protocol to HTTP/2, so instead of time-consuming protocol support check and upgrade the client may use HTTP/2 right away. This is achievable with using Java API MeshRestClientConfig.setProtocolVersion().

Minification and pretty printing the REST payloads

The possibility to either save the amount of payload transferred by the REST requests/responses, or pretty print them for better human readability, is present. By setting the request’s setMinifyJson(boolean) flag one may control the request body minification. Default value is true, so the payloads to send are not human-readable.

NodeListResponse nodes = client.findNodes("demo", new NodeParametersImpl().setLanguages("en")).setMinifyJson(false).blockingGet();

For the control of a response body minification one needs a DisplayParameters#setMinify(boolean) set to the desired request. This parameter override the server-side JSON minification setup per each request. See HTTP Server Options for the server-side configuration.

NodeListResponse nodes = client.findNodes("demo", new NodeParametersImpl().setLanguages("en"), new DisplayParametersImpl().setMinify(false)).blockingGet();

Gentics Mesh Java Client