jm.pascal

Alfresco Java Client SDK

Blog Post created by jm.pascal Employee on Nov 17, 2016

Introduction

Alfresco has recently focused a lot of time and energy to develop and strengthen its Public API. Gavin Cornwell talked a lot about it in his series of blog post 

 

With Alfresco Community Edition 201611 EA Release we are happy to announce a new project called Alfresco Java Client SDK available in Early Access Mode. 

 

This project contains Java lib project to consume easily Alfresco Public REST API. It include a set of APIs that allows developers to quickly build Alfresco-enabled Java & Android applications.

 

Installation

In your Java/Android application using Maven/Gradle simply add the following dependency: 

 

MAVEN

<dependency>
<groupId>org.alfresco.client</groupId>
<artifactId>alfresco-java-client</artifactId>
<version>1.0.0-beta1</version>
</dependency>

 

GRADLE

compile 'org.alfresco.client:alfresco-java-client:1.0.0-beta1'

 

You are now able to use the SDK.

 

Prerequisites

In order to follow along you'll need an environment to do so, firstly download and install the 5.2.c Early Access Community Release. In our case we will consider Alfresco is available at http://localhost:8080/alfresco and the "admin" user is available and has "admin" as password.

 

Overview

Setup Client Object

To use the SDK, the first thing to do is to create an AlfrescoClient object. This object is responsible to interact with Alfresco REST API via various specialised Services object. For those who already used Alfresco Android SDK the approach is very similar except the Alfresco Java Client SDK is compatible on both Java/Android platform.

 

To setup the Client there's a Builder where you can define parameters like Logging Level, HTTP Layer, Serialization/Deserialization, authentication mechanism etc... For the simplicity of this blog post we will use the quickest way.

AlfrescoClient client = new AlfrescoClient.Builder().connect("http://localhost:8080/alfresco", "admin", "admin").build();

 

 

Using Services

With AlfrescoClient you can now use services as they are defined in API Explorer

The following list illustrates what services are currently present.

//Retrieve user activities and site activities
ActivityStreamAPI activityAPI = client.getActivityStreamAPI();
//Retrieve and manage comments
CommentAPI commentAPI = client.getCommentsAPI();
//Retrieve Favorites information,
FavoritesAPI favoritesAPI = client.getFavoritesAPI();
//Retrieve and manage file/folder
NodesAPI nodesAPI = client.getNodesAPI();
//Retrieve user information,
PeopleAPI peopleAPI = client.getPeopleAPI();
//Retrieve and manage ratings
RatingsAPI ratingAPI = client.getRatingsAPI();
//Retrieve and manage sites informations
SitesAPI siteAPI = client.getSitesAPI();
//Retrieve and manage tags
TagAPI tagAPI = client.getTagsAPI();
//Retrieve and manage tags
RenditionsAPI renditionAPI = client.getRenditionsAPI();
//Retrieve and manage Shared Links
SharedLinksAPI sharedLinkAPI = client.getSharedLinksAPI();
//Retrieve and manage Trashcan
TrashcanAPI trashcanAPI = client.getTrashcanAPI();

 

Let's say we want to retrieve the root folder. In this case we need the NodesAPI

NodesAPI nodesAPI = client.getNodesAPI();

so now we can request the API to retrieve the list of children

Response<NodeRepresentation> rootFolderSyncResponse = nodesAPI.getNodeCall(NodesAPI.FOLDER_ROOT).execute();

Make a Request

You might not completely understand the preceding code snippet and it's normal. Indeed the main difference between Alfresco Android SDK and the Alfresco Java Client is how you create network request and interact with the remote Alfresco server.

 

The Java Client allows the developer to make a synchronous or asynchronous HTTP request via a Call Object (Thanks to Retrofit). Each service methods are Call Objects you can execute synchronously via execute() method or asynchronuously via enqueue() method. If we take our example we have something like

// Retrieve Root Node Info Synchronuously
Response<NodeRepresentation> rootFolderResponse = nodesAPI.getNodeCall(NodesAPI.FOLDER_ROOT).execute();

// Retrieve Root Node Info Asynchronuously
nodesAPI.getNodeCall(NodesAPI.FOLDER_ROOT).enqueue(new Callback<NodeRepresentation>()
{
   @Override
   public void onResponse(Call<NodeRepresentation> call, Response<NodeRepresentation> response)
   {
      //Retrieve Root Node Info
   }

   @Override
   public void onFailure(Call<NodeRepresentation> call, Throwable t)
   {
      //Something wrong happened
            }
});

An advantage with this approach is the possibility to support with only one lib two different platforms. For Android development network requests can't be done in the main thread and requires a mechanism to do it in another thread. In this case the SDK supports this use case. It also support the use case of a simple Java Batch file where we can execute everything in the main thread.

 

Retrieve the Response

The result Object after a Call execution is called a Response. This object contains all information received from the web server. It's here you can retrieve the HTTP Info like Response status with isSuccessful() method, HTTP Response via code() or HTTP Headers via headers().

If the Response is successful you can retrieve the model object associated with body() i.e in our case the NodeRepresentation.

If the Response is not successful error information are available via errorBody() method.

 

Collections and model Object

The Alfresco REST API has a specific format to handle collection like a list of Nodes, list of comments, list of sites... Each collection item is represented within an entry object which is contained in an entries array. In the SDK we removed this notion of entries/entry and replace it with ResultPaging/Object.

 

Object or model Object is the representation of the REST API Response. Very often it's the Json data parsed into Plain Old Java Object (POJO).

ResultPaging contains information about the listing i.e pagination, count and list of objects like  ResultPaging<NodeRepresentation> or ResultPaging<CommentRepresentation>

 

As you can see with this approach we have access to both the HTTP Information AND Model Object. The Client SDK is responsible to create all those final, ready to use objects for you without having to parse it.

 

An extra thing

And that's not all. Thanks again to Retrofit the Java Client SDK is able to interact with Alfresco REST API in Reactive way using RxJava. In this case instead of using Call Object we use Observable Object in RxJava. Our example become something like 

// Retrieve Root Node Info in Reactive Way
nodesAPI.getNodeObservable(NodesAPI.FOLDER_ROOT)
.subscribe(root -> Assert.assertEquals(root.getName(), "Company Home"));

 

Conclusion

As you saw during this post the main goals of this SDK is to let the developer choose the best approach to interact with Alfresco REST API regarding its platform and requirements. Our goal is to create the choice, make it easy to use and let you play with it.

 

 

More Usage

With the following Blog Posts we will follow Gavin Cornwell  examples (as listed in the introduction) and see how we can achieve the same experience using the Java Client SDK.

 

Outcomes