Developer Guide for the Federation Gateway Clients

The acumos-fgw-client library provides clients for using the public “E5” and private interfaces of the Acumos machine-learning platform’s Federation Gateway.

This document offers guidance for both client developers and client users (developers who want to use the clients in their Java projects).

Maven Dependency

The client jar is deployed to these Nexus repositories at the Linux Foundation:

<repository>
        <id>releases</id>
        <url>https://nexus.acumos.org/content/repositories/releases</url>
</repository>

Use this dependency information, ideally with the latest version number shown in the release notes:

<dependency>
        <groupId>org.acumos.federation</groupId>
        <artifactId>acumos-fgw-client</artifactId>
        <version>2.x.x</version>
</dependency>
<dependency>
        <groupId>org.acumos.federation</groupId>
        <artifactId>acumos-fgw-client-config</artifactId>
        <version>2.x.x</version>
</dependency>

Building and Packaging

As of this writing the build (continuous integration) process is fully automated in the Linux Foundation system using Gerrit and Jenkins. This section describes how to perform local builds for development and testing.

Prerequisites

The build and test machine needs the following:

  1. Java version 1.8
  2. Maven version 3
  3. Connectivity to Maven Central to download required jars

Use maven to build and package the client jar using this command:

mvn package

Client Packages

The client consists of several Maven sub-projects each defining one or more Java packages.

acumos-fgw-client-config
Dependency::
<dependency>
<groupId>org.acumos.federation</groupId> <artifactId>acumos-fgw-client-config</artifactId> <version>2.x.x-SNAPSHOT</version>

</dependency>

Packages:
org.acumos.federation.client.config
This contains pure bean classes for specifying TLS (SSL) and authentication parameters to be used by a client. These beans use Project Lombok for automatic generation of code for their setter, getter, constructor, equals, and hashcode methods. Their code may be found under src/main/lombok.
acumos-fgw-client-test
Dependency::
<dependency>
<groupId>org.acumos.federation</groupId> <artifactId>acumos-fgw-client-test</artifactId> <version>2.x.x-SNAPSHOT</version> <scope>test</scope>

</dependency>

Packages:
org.acumos.federation.client.test
This contains classes for mocking out client responses in junit testing in order to test applications using the clients (such as the Federation Gateway itself) as well as test key- and trust-store files for using the clients to test servers supporting the REST APIs. It also contains convenience routines for generating configuration beans using those key- and trust-store files and for mapping single quotes to double quotes for writing JSON strings in Java code with a minimum of backslashes.
acumos-fgw-client
Dependency::
<dependency>
<groupId>org.acumos.federation</groupId> <artifactId>acumos-fgw-client</artifactId> <version>2.x.x-SNAPSHOT</version>

</dependency>

Packages:
org.acumos.federation.client.data
This contains pure bean classes for messages sent between the clients and the Federation Gateway server that are unique to those APIs. These beans use Project Lombok for automatic generation of code for their setter, getter, constructor, equals, and hashcode methods. Their code may be found under src/main/lombok.
org.acumos.federation.client
This contains the actual client code, itself, consisting of a ClientBase class used as the common superclass for both interfaces, and FederationClient and GatewayClient for the public “E5” and private interfaces, respectively.

Client Usage Example

A Java class named “ClientDemo” demonstrates use of the clients. Please browse for this file in the client project test area using this link: ClientDemo.java.