Using LAPIS in Java - aaronmalone/lapis GitHub Wiki

LAPIS includes a Java client for incorporating steering in Java applications.

Dependencies

To use the LAPIS client in Java, you will need the lapis-java-client .jar file (as of the time of this writing, lapis-java-client-0.4.1-jar-with-dependencies.jar). All necessary dependencies are packaged within this .jar file, so it will be the only .jar file you need in order to use LAPIS.

Instantiate a LapisApi object

The main object through which you will interact with LAPIS will be an instance of edu.osu.lapis.LapisApi (hereafter, a LapisApi object). To start using LAPIS in your Java application, instantiate a LapisApi object. When you instantiate the object, you also create a LAPIS node. The LAPIS node is potentially part of a network of LAPIS nodes, but does not have to be. Here is an example of instantiating a LapisAPI object in such a way that the resulting LAPIS node is a coordinator node:

// this creates a coordinator node
String myNodeName = "Java-node";
String myAddress = "http://localhost:7788";
LapisApi lapisApi = new LapisApi(myNodeName, myAddress);

Note that the LapisAPI constructor used above--the constructor that takes two arguments: the node name and the node address--creates a coordinator node. If you intend to use LAPIS in a standalone application, and not as part of a network of LAPIS nodes, you should use this constructor.

To create a non-coordinator node:

// this creates a non-coordinator node
String myNodeName = "non-coordinator-node-in-Java";
String coordinatorAddress = "http://localhost:7788";
String myAddress = "http://localhost:8899";
LapisApi lapisApi = new LapisApi(myNodeName, coordinatorAddress, myAddress);

Note that a non-coordinator node will immediately attempt to connect to the network coordinator at the specified coordinator address. An exception will be thrown if it is unable to connect.

Publishing variables

As of this time, variables published through LAPIS's Java client must be String objects, Map objects, or one-, two-, or three-dimensional arrays of a Java primitives. Note that String objects must be published as read-only variables in LAPIS, since Java String objects are immutable.

To publish a variable using the LAPIS Java API:

final int[] ints = new int[] {8, 6, 7, -5, 3, 0, 9};
//lapisApi is an instance of edu.osu.lapis.LapisApi
lapisApi.publish("publishedInts", ints);

In the example above, an array of integers is published with the name "publishedInts". Other LAPIS nodes on a network can access the present state of ints by using the published name of the variable.

Note that the recommend practice is to publish final variables. Published variables should not be re-assigned. Re-assigning a published variable causes two problems. It prevents the application from changing the value of the published variable that is exposed through the REST interface, and it prevents any changes made through the REST interface (either manually or programmatically by other nodes in a LAPIS network) from being seen within the Java application.

Redacting published variables

Most applications will have no need to un-publish variables, but if you wish to remove a previously-published variable, you can use the redact method:

//lapisApi is an instance of edu.osu.lapis.LapisApi
lapisApi.redact("nameOfPreviouslyPublishedVariable");

Note that the argument passed to the redact method is the name of the published variable within LAPIS, not the published object itself.

Get and set variables published by other nodes

LAPIS nodes within the same LAPIS network can get and set each other's published variables, as in the example below:

// "doubles" is an array of doubles published by a node named "otherNode"
String variableName = "doubles";
String otherNodeName = "otherNode";

// get the value of the published variable by referring to the "full name"
double[] localDoubles = lapisApi.getArrayOfDouble(otherNodeName, variableName);

// make some change and set the value on the other node
for(int i = 0; i < localDoubles.length; ++i) {
    localDoubles[i] = Math.sqrt(localDoubles[i]);
}
lapisApi.set(otherNodeName, variableName, localDoubles);