A Basic Java API for Asset Control

In this article I will show you how to use the Basic AC Java API to connect to an Asset Control environment.

This is setting the scene for further articles on how to work with Static Data, Timeseries Data, Timeseries Validation Functions, Formula Engine etc.

For the full list of articles in this series, see here.

Prerequisites

What you need

In order to follow along with this and the other articles in this series, you will need:

The Basic Java API for Asset Control in one of two flavours:
As a source from its repository on GitHub. Or as a ready-to-use JAR file.
The underlying AC Java API 4.4.x which you can download from the Asset Control User Website.
A working Asset Control environment to connect to. (See here for a tutorial on how to set this up.)

Prepare your working environment

I will use Intellij IDEA as my IDE and Maven as the build tool. If your choice of tools is different, you may need to adjust the following instructions and commands accordingly.

Build the Basic Java API for AC from source

If you chose to download the Basic Java API as a source from GitHub, you can use Maven to build the ac-api-basic-1.0.0.jar file:

mhabook:ac-api-basic mha$ mvn package
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building ac-api-basic 1.0.0
[INFO] ------------------------------------------------------------------------
[INFO]
...
[INFO] Building jar: /Volumes/MacSecondary/sandbox/stuff/ac-api-basic/target/ac-api-basic-1.0.0.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 10.051 s
[INFO] Finished at: 2018-07-28T10:03:23+01:00
[INFO] Final Memory: 30M/366M
[INFO] ------------------------------------------------------------------------
mhabook:ac-api-basic mha$

Add libraries to your local Maven repository

The Basic Java API library - whether just built as shown above or downloaded directly from S3 - should be added to your local Maven repository:

mhabook:ac-api-basic mha$ mvn install:install-file -Dfile=target/ac-api-basic-1.0.0.jar -DgroupId=io.terrafino -DartifactId=ac-api-basic -Dversion=1.0.0 -Dpackaging=jar

Similarly, the Asset Control Java API 4.4.x should also be added to your local Maven repository. You will see why in the next section.

Get coding

With the preliminaries out of the way I can now get coding.

Maven dependencies

I set up a simple Maven Java project in IntelliJ and add the following dependencies in its pom.xml:

        <dependency>
            <groupId>asset-control</groupId>
            <artifactId>ac-server-api</artifactId>
            <version>4.4.27</version>
        </dependency>
        <dependency>
            <groupId>io.terrafino</groupId>
            <artifactId>ac-api-basic</artifactId>
            <version>1.0.0</version>
        </dependency>

ac.properties

I create a src/main/resources/ac.properties with the following content (adjust yours as needed):

host=acbox
installation=AC 7.3
user=acdba
password=welcome

log4j.properties

You may also want to add a src/main/resources/log4j.properties like the one below or similar:

# Root logger option
log4j.rootLogger=DEBUG, stdout

# Direct log messages to stdout
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.Target=System.out
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %m%n

Connect to AC

Now, opening up and closing a connection to your Asset Control environment is as simple as:


  AcConnection conn = AcConnection.getDefaultConnection();
  // do something useful here
  conn.disconnect();

Please keep in mind that while code examples are kept brief you can download and inspect the source code. I recommend having a look at the included tests to see the code in action.

Thank you for reading.

In the next article I will show how to work with Static Data using this API.