The examples are included in the public matterial-api project at gitlab.

Preface

matterial-api

Take a look at the matterial-api, which is publicly available at gitlab. This project defines the api-objects.

Maven POM

Create a pom.xml to start implementing a simple java client for the matterial-app and add our matterial-api as dependency:

<dependency>
    <groupId>matterial</groupId>
    <artifactId>matterial-api</artifactId>
    <version>${matterial.api.version}</version>
</dependency>

Session handling

Matterial is based on a standard cookie based session handling.
You may want to implement something like that:

protected static final String SESSION_COOKIE_NAME = "JSESSIONID";

protected String sessionId;
protected String getSessionId() {
    if(this.sessionId == null) {
        this.sessionId = UUID.randomUUID().toString().replaceAll("-", "").toUpperCase().concat(".node1");
    }
    return this.sessionId;
}
protected void updateSession(Response resp) {
    Map<String, NewCookie> cookies = resp.getCookies();
    NewCookie sessionCookie = cookies.get(SESSION_COOKIE_NAME);
    if(sessionCookie != null) {
        String sessionId = sessionCookie.getValue();
        this.sessionId = sessionId;
    }
}

Basic rest-client

You have to implement a basic rest-client to invoke matterial-api.
A possible implementation will define some constants for the request-options and uses Resteasy to create a basic client:

public static final int REQUEST_NOTHING = 0;
public static final int REQUEST_XML = 1;
public static final int REQUEST_JSON = 2;
public static final int REQUEST_PLAIN = 3;
public static final int REQUEST_HTML = 4;
protected Builder createClient(String path, int acceptedResponse) {
		Client client = ResteasyClientBuilder.newClient();
    WebTarget target = client.target(path);
    Builder builder = null;
    if(acceptedResponse == REQUEST_XML) {
        builder = target.request(MediaType.APPLICATION_XML_TYPE);
    }
    else if(acceptedResponse == REQUEST_JSON) {
        builder = target.request(MediaType.APPLICATION_JSON_TYPE);
    }
    else if(acceptedResponse == REQUEST_PLAIN) {
        builder = target.request(MediaType.TEXT_PLAIN_TYPE);
    }
    else if(acceptedResponse == REQUEST_HTML) {
        builder = target.request(MediaType.TEXT_HTML_TYPE);
    }
    else {
        builder = target.request();
    }
    builder.cookie(SESSION_COOKIE_NAME, this.getSessionId());
    return builder;
}

You can use this code to implement the request-methods your application needs.

GET requesting JSON

protected Response get(String path) {
    return this.createClient(path, REQUEST_JSON).get();
}

PUT JSON and requesting JSON

protected Response put(String path, Object entity) {
    return this.createClient(path, REQUEST_JSON).put(Entity.json(entity));
}

DELETE requesting PLAIN

protected Response deleteRequestPlain(String path) {
    return this.createClient(path, REQUEST_PLAIN).delete();
}

…

Base-path

The base-path of your matterial-app-client should always be:

String basePath = "https://my.matterial.com/mtr-backend/";

Example

Hello world

A simple hello world would look like this:

String path = basePath+"test";
Response resp = this.getNothing(path);
String hello = resp.readEntity(String.class);
logger.info("helloworld() - RESULT: {}", hello);

Login

A basic login with username / password could be implemented like this:

public LoginData login(String userName, String password) {
    String path = this.basePath + APPLICATION_PATH + "/" + Api.LOGON;
    Logon logon = new Logon(userName, password);
    LoginData loginData = null;
    try(Response resp = this.post(path, logon)) {
        this.updateSession(resp);
        loginData = resp.readEntity(LoginData.class);
    }
    return loginData;
}

Logout

A simple logout goes like this:

public void logout() {
    String path = this.basePath + APPLICATION_PATH + "/" + Api.LOGON;
    try(Response resp = this.deleteRequestPlain(path);) {
        boolean loggedOut = resp.readEntity(Boolean.class);
    }
}

Fetch documents

To fetch all documents (meta-data) from matterial:

public ListResult<Document> loadDocuments() {
    String path = this.basePath + APPLICATION_PATH+"/" + Api.DOCUMENT;
    ListResult<Document> lr = null;
    try(Response resp = this.get(path+
             "?"+PARAM_ALL_LANGUAGES+"=true"+
             "&"+PARAM_LOAD_ADDITIONAL_PROPERTIES+"=true"+
             "&"+PARAM_LOAD_ATTACHMENTS+"=true"+
             "&"+PARAM_LIMIT+"=10"+
             "&"+PARAM_COUNT+"=true")) {
        lr = resp.readEntity(new GenericType<ListResult<Document>>() {});
    }
    return lr;
}

Load document main content

Matterial stored meta-data and main-content of a document separately, so you have load it accordingly.

public String loadDocumentContent(long documentId, String languageKey) {
    String path = this.basePath + APPLICATION_PATH+"/" + Api.DOCUMENT;
    String content = null;
    try(Response resp = this.getNothing(path+"/"+documentId+"/"+FILE+"?"+PARAM_LANGUAGE_KEY+"="+languageKey)) {
        try(InputStream in = resp.readEntity(InputStream.class)) {
            if(in != null) {
                content = IOUtils.toString(in, CharEncoding.UTF_8);
            }
        }
        catch (IOException e) {
            logger.error("loadDocumentContent() - ", e);
        }
    }
    return content;
}

Complete example

To implement your own client you may start with these two classes taken from the matterial-api project at gitlab:

• The general RestClient
• The MtrRestClient

You can also find some samples:

• SavedSearchRequest
• AdvancedLogin
• LotsOfData