Using jExperience java services

To communicate with jCustomer / Apache Unomi, jExperience is using a set of Java services. These java services can be used from custom modules to serve many use cases, such as: 

• Creating a Jahia component and display any visitor profile property (first name, ..)
• Creating a Jahia component to display the most visited blog articles 
• Creating a Jahia component to display the bookmarks of a visitor
• Creating a Jahia component to display the last 10 visited page views
• Creating a choicelist initalizer for marketer to select a profile property
• etc.. 

Why use jExperience java services? 

Since jCustomer has a REST API, it is possible to call it directly from your Jahia module, however it is not recommended for several reasons: 

• Cluster management, if a jCustomer server is down, you'll want your http call to reach the other nodes
• Cookies: if your custom module makes a call to jCustomer public endpoint without the right cookies or profile ids, you will end up creating fake profiles and have wrong statistics
• Httpclient management: It's easy to forget to close your client or to end up with too many or not enough connections.
• Timeout: if for any reason jCustomer takes too long to respond, you don't want this to slow down the rendering of your webpage and ensure that it stills goes through
• Authentication: Some calls to jCustomer are protecter and need to be authenticated

To cover all the use cases described above and to make it easier to communicate with jCustomer, jExperience exposes 2 kind of services:

• To communicate with jCustomer public endpoint (context.json)
• To communicate with jCustomer private endpoints. 

Calling jCustomer public endpoint

2 methods are available to communicate with jCustomer endpoint "context.json", they can be found in the class ContextServerService:

• ContextResponse executeAsyncContextRequest(ContextRequest contextRequest, HttpServletRequest request, String siteKey) 
• void executeContextRequest(ContextRequest contextRequest, HttpServletRequest request, String siteKey)

As you guessed, these are very similar methods, the first one can be used to execute asynchronous http requests, where reading the response is not needed. The second one, can be used to execute synchronous calls and return an Apache Unomi object: ContextResponse.

These methods take the following parameters:

• ContextRequest contextRequest : A java object defined in Apache Unomi project. It is where most information of the request will be added.
• HttpServletRequest : The http reques, needed to read cookies, http headers and IP address if needed
• String siteKey : The name of the site in jahia, the scope in jCustomer 

Also note that the these methods take the following jExperience configuration / feature into account:

• jexperience.timeoutInMilliseconds : When the jexperience.timeoutInMilliseconds is reached, the execution will continue, even if jCustomer didn't respond. This value can be set in the configuration file defining the connection to jCustomer.
• wem.disableWem : If jExperience javascript tracking is disabled for the current visitor profile, these methods wont be executed.

Calling jCustomer private / admin endpoint 

3 java methods are available to communicate with Unomi REST APIs (admin / private endpoints), they can also be found in the class ContextServerService:

• <T> T executePostRequest(String siteKey, String path, Object json, List<Cookie> cookies, Map<String, String> headers, Class<T> tClass) throws IOException;
• <T> T executeGetRequest(String siteKey, String path, List<Cookie> cookies, Map<String, String> headers, Class<T> tClass) throws IOException;
• <T> T executeDeleteRequest(String siteKey, String path, List<Cookie> cookies, Map<String, String> headers, Class<T> tClass) throws IOException;

These methods take the following parameters:

• String siteKey : The name of the site in jahia, the scope in jCustomer 
• String path : Tthe path of the REST API that you need to reach. For instance "/cxs/scoring/query".
• Object json (for executePostRequest) only Tthe json object describing the payload (strings are also allowed but not recommended) 
• List<Cookie> cookies : Usually set to null when communicating with jCustomer REST API
• Map<String, String> headers : Usually set to null when communicating with jCustomer REST API
• Class<T> tClass : The java class of the object that will be returned by jCustomer. This class can be found in the Apache Unomi library and depends on the path that you're reaching.

The timeout used for such calls is hardcoded to 30 seconds.