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.
ActivityStreamAPI activityAPI = client.getActivityStreamAPI();
CommentAPI commentAPI = client.getCommentsAPI();
FavoritesAPI favoritesAPI = client.getFavoritesAPI();
NodesAPI nodesAPI = client.getNodesAPI();
PeopleAPI peopleAPI = client.getPeopleAPI();
RatingsAPI ratingAPI = client.getRatingsAPI();
SitesAPI siteAPI = client.getSitesAPI();
TagAPI tagAPI = client.getTagsAPI();
RenditionsAPI renditionAPI = client.getRenditionsAPI();
SharedLinksAPI sharedLinkAPI = client.getSharedLinksAPI();
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
Response<NodeRepresentation> rootFolderResponse = nodesAPI.getNodeCall(NodesAPI.FOLDER_ROOT).execute();
nodesAPI.getNodeCall(NodesAPI.FOLDER_ROOT).enqueue(new Callback<NodeRepresentation>()
{
@Override
public void onResponse(Call<NodeRepresentation> call, Response<NodeRepresentation> response)
{
}
@Override
public void onFailure(Call<NodeRepresentation> call, Throwable t)
{
}
});
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
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.
