The XMS Java SDK Developer Guide

Introduction

This page aims to provide you with a reference on how to develop software interacting with XMS using the dedicated XMS Java SDK. Through this SDK, you will be able to manage XMS with the same flexibility that you can find in the Python SDK or the XMS Web Console.

Maven Dependency

If using Apache Maven as project management tool, a single dependency is required to add XMS SDK to your classpath:

Maven dependency to include in your pom.xml file

<dependency>
    <groupId>org.ow2.xlcloud.xms</groupId>
    <artifactId>xms-sdk</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

error  As of the moment of writing this tutorial, 0.0.1-SNAPSHOT is a current version of xms-sdk artifact. You should, however, check which version is most up-to-date and use the newest XMS SDK (that always covers all current XMS API operations).

XMS Java SDK configuration

Configuring XMS endpoint

In order to interact with the XMS API, you have to set its server URL. You can do this through a properties file.

File /src/main/resources/sdk-demo.properties

xmsApiUri=http://your-server-ip-or-domain-name:8090/xlcloud-xms/

Then, create a class:

Class SdkDemoUtils

import javax.enterprise.inject.Produces;
import org.xlcloud.config.PropertiesFilename;

public class SdkDemoUtils {
    private static final String PROPERTIES_FILENAME = "sdk-demo.properties";

    public @Produces @PropertiesFilename
    String getPropertiesFilename() {
        return PROPERTIES_FILENAME;
    }
}

Wherever @PropertiesFilename is needed, it will look for this producer. The name of the files containing the properties will therefore be injected at the right place.

Setting up OAuth 2.0 bearer token

XMS ReST API uses OAuth 2.0 for request authorization. XMS Java SDK simplifies setting up the access token value through dependency injection with dedicated qualifier @OAuth2BearerToken. If using dependency injection (like CDI) in your project, a simple producer method can be used to setup token values for request. The following example demonstrates one of the possible solutions:

The Java class to set the token

import javax.enterprise.inject.Produces;
import org.xlcloud.rest.client.OAuth2BearerToken;

public class XmsSdkBearerTokenFactoryBean {
    
    @Produces @OAuth2BearerToken
    public String getOAuth2BearerToken() {
        code that returns the valid bearer token value goes here
    }
}

The actual implementation of the producer method strongly depends on the way your application acquires this token (e.g. by implementing one of the standard OAuth 2.0 flows more described in Identity and Access Management).

This separation of security access from application code results in much cleaner and simpler business logic implementation.

Note that, unlike XMS endpoint, bearer tokens are usually not static and can differ between requests (e.g. different users will be represented by different access tokens). Code your bearer token factory method accordingly and apply appropriate scopes to XMS SDK beans. 

Developing with XMS Java SDK

Having your XMS SDK fully configured now, you can simply implement your business logic against a set of xms-api interfaces (see org.xlcloud.service.api for details).

To inject interfaces to your bean, just import the appropriate package at the beginning of your class file, and inject the interface within your class with the @Inject annotation.

Example of interface injection

import org.xlcloud.service.api.AccountsApi;

public class AccountsDemoBean {
    @Inject
    private AccountsApi accountsApi;

 The rest of the code goes here...
}

Response cache

Every operations ivokes API with GET operation is cached inside SDK according to Cache-Control Header of the response. Response is cached in the private cache of the access token. Invocation of some operations, manipulating with the state of the application clears some cached objects.

Handling XMS ReST API error codes

Since XMS exposes a proper ReSTful API, it uses different HTTP status codes for different states of responses. If, for example, the user is not allowed to call a given method, 403 Forbidden will be returned as HTTP status code (with an appropriate error message and detailed description). XMS Java SDK automatically translates erroneous responses into dedicated Java exceptions, allowing developers to implement their code accordingly.

You can find below the list of all of the Java exceptions that can be thrown by the SDK (located in the org.xlcloud.rest.exception package):

  • AuthenticateException for HTTP 401
  • DuplicatedEntityException for HTTP 409
  • ForbiddenException for HTTP 403
  • InternalErrorException for HTTP 500
  • ObjectNotFoundException for HTTP 404
  • ValidationException for HTTP 403
  • CacheException for problems with the cache
  • BaseException for other HTTP errors

You can find an example on how to handle exceptions and retrieve the full error message in the section below, using the try/catch instruction.

Practical example: listing XLcloud accounts in your Web Application

The following code snippets present a JSF facelet and its corresponding backing bean that are responsible for listing all available XLcloud accounts:

JSF snippet (using PrimeFaces for styling)

<h:form>
  <h:dataTable var="account" value="#{accountListBean.accounts}">
    <h:column headerText="ID">
        <h:outputText value="#{account.id}" binding="#{accountId}" />
    </h:column>
    <h:column headerText="Name">
        <h:outputText value="#{account.name}" />
    </h:column>
    <h:column headerText="Users">
        <h:outputText value="#{account.users}" />
    </h:column>
  </h:dataTable>
</h:form>
<p:messages id="messages" showDetail="true" autoUpdate="true" closable="true" />

In the Java class (BakingBean) which will be responsible for all actions involving accounts

import java.util.List;

import javax.inject.Inject;
import javax.inject.Named;

import org.xlcloud.service.Account;
import org.xlcloud.service.api.AccountsApi;

@Named
public class AccountListBean {

    @Inject
    private AccountsApi accountsApi;
    
    public List<Account> getAccounts() {
        try {
            return accountsApi.getAccounts().getAccount();
        }
        catch(ForbiddenException e) {
            FacesContext context = FacesContext.getCurrentInstance();
            context.addMessage(null, new FacesMessage(FacesMessage.SEVERITY_ERROR,"Error", e.toString()));
           }
    }
}

We test if the accounts retrieval went well through the try/catch instruction. If the listing is not permitted, it will display a message containing the error within the #messages section of the page.

For more info, please consult Oracle's documentation for IOException.

The outcome should be similar to this:

https://129.184.11.121:8443/download/attachments/9241070/Java%20SDK%20demo.png?version=1&modificationDate=1380019896243&api=v2

Links and resources

Please note that every XMS Java SDK method is documented within the Java doc.

You can find below official docs and specs regarding major components or principles:

And here are some simplified and intelligible information regarding these notions.


This wiki is licensed under a Creative Commons 2.0 license
XWiki Enterprise 5.4.6 - Documentation - Legal Notice

Site maintained by