Announcing PI Web API client library for Java and Android

Introduction

Today we release our first version of the PI Web API client library for Java and Android. This library was generated using the Swagger specification available on PI Web API 2017+.

PI JDBC still is our official solution for retrieving PI data to Java environments. Nevertheless, there are a lot of advantages using this open-source project:

• You don't need to know SQL to start coding! You just need to know how to program in Java. Since PI JDBC uses PI OLEDB Provider and PI OLEDB Enterprise under the hood, the developer needs to write SQL queries in order to retrieve/update PI data.
• There are more methods available in PI Web API than PI JDBC. Besides, that queries against PI AF through PI JDBC and PI OLEDB Enterprise are still read-only in (written in August, 2017).
• The machines running your Java applications don't need any additional software to be installed. This is not the case for PI JDBC, which needs to be installed on all the machines running the custom Java app.
• You can develop Android apps with this library. PI JDBC does not allow you to do the same.

Requirements

• PI Web API 2017 installed within your domain using Basic Authentication.
• Building this PI Web API client library requires JDK and Maven to be installed.
• If you are using the .NET Core version of this library, you should have .NET Core 1.1 installed on your machine.

Installation

To install the API client library to your local Maven repository, simply execute on the project folder:

mvn install

To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

mvn deploy

Refer to the official documentation for more information.

Usage

After building this client library using Maven, create a new Java project using your favorite IDE. Using Maven or Gradle, add the library according to the instructions below:

Maven users

Add this dependency to your project's POM:

<dependency>
  <groupId>com.osisoft.pidevclub</groupId> 
  <artifactId>piwebapi</artifactId>
  <version>1.0.0</version>
</dependency>

Gradle users

Add this dependency to your project's build file:

compile 'com.osisoft.pidevclub:piwebapi:1.0.0'

Others

At first generate the JAR by executing:

mvn package 

Then manually install the following JARs:

• target/piwebapi-1.0.0.jar
• target/lib/*.jar

Source Code

The InterlliJ project that generates the final library is available on the src folder. You might want to add or edit a method and rebuild the solution in order to generate custom assemblies. The links from the GitHub repository is below:

• GitHub - osimloeff/PI-Web-API-Client-Java-Android: PI Web API Client library for Java and Android

Documentation

All classes and methods are described on the DOCUMENTATION.

Examples

Please check the PIWebApiTests.java from the Java test module of this repository. Below there are also code snippets written in Java for you to get started using this library:

Create an instance of the PI Web API top level object.

PIWebApiClient client = new PIWebApiClient("https://marc-web-sql.marc.net/piwebapi", username, password, false, true);  

This library is only compatible with PI Web API Basic Authentication. As a result, you must provide the username and password.

Get the PI Data Archive WebId

PIDataServer dataServer = client.getDataServer().getByPath("\\\\MARC-PI2016", null);

Create a new PI Point

PIDataServer dataServer = client.getDataServer().getByPath("\\\\MARC-PI2016, null);
PIPoint newPoint = new PIPoint();
newPoint.setName("SINUSOID_TEST5");
newPoint.setDescriptor("Test PI Point for Java PI Web API Client");
newPoint.setPointClass("classic");
newPoint.setPointType("float32");
newPoint.setFuture(false);
ApiResponse<Void> res =  client.getDataServer().createPointWithHttpInfo(dataServer.getWebId(),newPoint);     

Get PI Points WebIds

PIPoint point1 = client.getPoint().getByPath("\\\\JUPITER001\\sinusoid", null);
PIPoint point2 = client.getPoint().getByPath("\\\\JUPITER001\\sinusoidu", null);
PIPoint point3 = client.getPoint().getByPath("\\\\JUPITER001\\cdt158", null);

Get recorded values in bulk using the StreamSet/GetRecordedAdHoc

List<String> webIds = new ArrayList<String>();
webIds.add(point1.getWebId());
webIds.add(point2.getWebId());
webIds.add(point3.getWebId());
PIItemsStreamValues piItemsStreamValues = client.getStreamSet().getRecordedAdHoc(webIds,null, "*", null, true, 1000, null, "*-3d",null);

Send values in bulk using the StreamSet/UpdateValuesAdHoc

PIItemsStreamValues streamValuesItems = new PIItemsStreamValues();
PIStreamValues streamValue1 = new PIStreamValues();
PIStreamValues streamValue2 = new PIStreamValues();
PIStreamValues streamValue3 = new PIStreamValues();
PITimedValue value1 = new PITimedValue();
PITimedValue value2 = new PITimedValue();
PITimedValue value3 = new PITimedValue();
PITimedValue value4 = new PITimedValue();
PITimedValue value5 = new PITimedValue();
PITimedValue value6 = new PITimedValue();
value1.setValue(2);
value1.setTimestamp("*-1d");
value2.setValue(3);
value2.setTimestamp("*-2d");
value3.setValue(4);
value3.setTimestamp("*-1d");
value4.setValue(5);
value4.setTimestamp("*-2d");
value5.setValue(6);
value5.setTimestamp("*-1d");
value6.setValue(7);
value6.setTimestamp("*-2d");
streamValue1.setWebId(point1.getWebId());
streamValue2.setWebId(point2.getWebId());
streamValue3.setWebId(point3.getWebId());


List<PITimedValue> values1 = new ArrayList<PITimedValue>();
values1.add(value1);
values1.add(value2);
streamValue1.setItems(values1);


List<PITimedValue> values2 = new ArrayList<PITimedValue>();
values2.add(value3);
values2.add(value4);
streamValue2.setItems(values2);


List<PITimedValue> values3 = new ArrayList<PITimedValue>();
values3.add(value5);
values3.add(value6);
streamValue3.setItems(values3);


List<PIStreamValues> streamValues = new ArrayList<PIStreamValues>();
streamValues.add(streamValue1);
streamValues.add(streamValue2);
streamValues.add(streamValue3);
ApiResponse<PIItemsItemsSubstatus> res = client.getStreamSet().updateValuesAdHocWithHttpInfo(streamValues, null,null);

Get element and its attributes given an AF Element path

PIElement myElement = client.getElement().getByPath("\\\\MARC-PI2016\\CrossPlatformLab\\marc.adm", null);
PIItemsAttribute attributes = client.getElement().getAttributes(myElement.getWebId(), null, 1000, null, false, null, null,null,null,null,0,null,null);

Final Remarks

As you could realize by looking at the example, it is pretty easy to use this client library on your Java apps. Please provide your feedback by posting your comments below!

·         You don't need to know SQL to start coding! You just need to know how to program in Java. Since PI JDBC uses PI OLEDB Provider and PI OLEDB Enterprise under the hood, the developer needs to write SQL queries in order to retrieve/update PI data.

·         There are more methods available in PI Web API than PI JDBC. Besides, that queries against PI AF through PI JDBC and PI OLEDB Enterprise are still read-only in (written in August, 2017).

·         The machines running your Java applications don't need any additional software to be installed. This is not the case for PI JDBC, which needs to be installed on all the machines running the custom Java app.

·         You can develop Android apps with this library. PI JDBC does not allow you to do the same.

·         Although it was not tested, the performance should be better for calls in bulk. PI Web API client library allows you to retrieve and send data in bulk. This feature is not available on PI JDBC yet.