Overview

What is the Java Client?

The ACE Java Client is the official Java client library to use against ACE, and contains support for reading content as well as searching for content.

The client is available both as a vanilla Java component and as a caching Spring component. Please see below for more information.

Setup

The ACE Java client is acquired into a project using its Maven dependency:

<dependency>
  <groupId>com.atex</groupId>
  <artifactId>ace-java-client</artifactId>
  <version>VERSION</version>
</dependency>

You can view the list of released versions here.

Instantiating a client

Vanilla component

The vanilla ACE client is instantiated using it's builder class. Example:

AceClient client = new AceClientBuilder().build();

See further below for configuration and client builder options.

Spring component

The Spring ACE client is instantiated using Spring component injection. First of all, make sure Spring knows about the component, either by importing the component (using @Import) or by package scanning (using @ComponentScan):

@Import({ SpringAceClient.class })

@ComponentScan(basePackages = { "com.atex.ace.client.spring" })

Then let Spring auto-wire the client:

@AutoWired
private SpringAceClient client;

Configuring the client

The ACE Java Client has the following properties configurable:

Content service location - the location (URL) of the content service in ACE Core.
Search service location - the location (URL) of the search service in ACE Core.
View - the content view to use during content retrieval.
Variant - the content variant to use during content retrieval.
Maximum total number of connections - the total maximum number of concurrent connections the client is allowed to use at any given time.
Maximum number of connections per route - the maximum number of concurrent connections the client is allowed to use against a given server destination.
Maximum number of HTTP redirects - the maximum number of HTTP redirects a client operation is allowed.
HTTP connection timeout - the maximum amount of time (in milliseconds) a client operation connection is allowed to consume.
HTTP request timeout - the maximum amount of time (in milliseconds) a client operation request is allowed to consume.
HTTP socket timeout - the maximum amount of inactivity (in milliseconds) a client operation is allowed on a given connection.
Default request parameters - a set of key / value pairs that will be sent with every request to the ACE Content service as query parameters when reading content.
Kafka bootstrap servers - a Kafka connection string specifying the location(s) of your Kafka server(s). Format: "server:port,server2:port". Please see the Kafka documentation (https://kafka.apache.org/documentation) for more information. Only available in the Spring component.
Kafka topic - the name of the Kafka topic to subscribe to for content cache invalidation. Only available in the Spring component.
Maximum size of the in-memory cache(s) - the maximum number of entries in the in-memory content caches. Only available in the Spring component.

Vanilla component configuration

The vanilla component is configured using the builder class during instantiation. Examples:

Map<String, String> defaultParameters = new HashMap<>();
defaultParameters.put("customParameter", "someValue");

AceClient client = new AceClientBuilder()
    .usingContentServiceLocation("http://ace.local:8080/content-service/content")
    .usingSearchServiceLocation("http://ace.local:8080/search-service/public/select")
    .usingMaxConnectionsPerRoute(30)
    .usingMaxTotalConnections(150)
    .withDefaultParameters(defaultParameters)
    .forVariant("web")
    .forView("acePublic")
    .build();

AceClientSettings settings = ... // already existing settings object

AceClient client = new AceClientBuilder()
    .usingSettings(settings)
    .build();

Spring component configuration

The Spring component is configured using Spring configuration. Example (application.properties):

# Locations configuration
atex.ace.client.service.contentServiceLocation=http://ace.local:8080/content-service/content
atex.ace.client.service.searchServiceLocation=http://ace.local:8080/search-service/public/select

# General configuration
atex.ace.client.service.variant=web
atex.ace.client.service.view=acePublic

# Connection configuration
atex.ace.client.service.max-connections-total=150
atex.ace.client.service.max-connections-per-route=30
atex.ace.client.service.http-max-redirects=5
atex.ace.client.service.http-connect-timeout=3000
atex.ace.client.service.http-request-timeout=3000
atex.ace.client.service.http-socket-timeout=2000

# Default request parameters
atex.ace.client.service.defaultParameters.customParameter=someValue

# Individual cache size configuration
atex.ace.client.cache.alias-cache-maximum-size=32768
atex.ace.client.cache.version-cache-maximum-size=32768
atex.ace.client.cache.content-cache-maximum-size=32768

# Default cache size configuration
atex.ace.client.cache.maximum-size=32768

# Kafka configuration
atex.ace.client.kafka.bootstrap-servers=ace.local:9092
atex.ace.client.kafka.topic=aceEvents

Caching

The Spring component has internal content caches which is used to improve performance.

Cache configuration

The client use three different caches (Caffeine):

ace-client.alias - mappings between content aliases and their respective main aliases
ace-client.version - mappings between content main aliases and content versions
ace-client.content - content data storage for content versions

Cache invalidation

Eviction from the content caches are performed using the ACE Kafka change topic. Whenever a mutation event arrives on the topic, the cache mapping in the ace-client.version cache (see above) is evicted, which will lead to the content being read from the server at the next client request.

NOTE: The ACE Kafka change topic is internal to the Atex products, and should not be relied upon by project functionality.

Context data

Using the Spring component, it's possible to set request-specific data that will be used for all requests to the ACE Content service when reading content.

Setting context data

Map<String, String> contextParameters = new HashMap<>();
contextParameters.put("contextKey", "contextValue");

RequestContext.setRequestData(new RequestData(contextParameters));

The key value pair contextKey / contextValue will be sent as a query parameter to every content read operation against the ACE Content service.

Clearing context data

It's important to remember to clear the context data when the request has completed.

RequestContext.clear();

Usage

Reading content

/**
 * Reading content from the client. Aspects are available either
 * as Maps or as typed objects.
 */

Content<?> content = client.getContent(Alias.fromString("uuid/123e4567-e89b-12d3"));

Map<String, Object> myAspect = content.getAspect("myAspect");

/**
 * You can read aspects as typed by providing the target class.
 */

MyAspect myAspect = content.getAspect("myAspect", MyAspect.class);

/**
 * You can also pass parameters when retrieving content. These will be
 * passed on to the pipeline being executed on the server side.
 */

Map<String, String> parameters = new HashMap<>();
parameters.put("key", "value");

Content<?> content = client.getContent(Alias.fromString("uuid/123e4567-e89b-12d3"), parameters);

Searching

Query query = new Query("*:*")
    .fq("field:value")
    .fq("field2:value2")
    .start(20)
    .rows(20)
    .sort("updatedDate_dt desc");

// The search result contains all the 'hits' as well as facetting metadata, if requested in the query
SearchResult searchResults = client.search(query);

/**
 * Faceting metadata from the search result is available explicitly
 * if present in the search service response.
 */

Query query = new Query("*:*").
    fq("ace_type_s:(articleContent)").
    param("facet", "on").param("facet.field", "ace_type_s");

SearchResult searchResult = client.search(query);
FacetingResult facetingResult = searchResult.getFacetingResult();