PI Web API client library for Java and Android (2017 R2)

Overview

This repository has the source code package of the PI Web API client library for Java and Android. This version was developed on top of the PI Web API 2017 R2 swagger specification.

Requirements

• JDK
• Maven

Local 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.1.1</version>
</dependency>

Gradle users

Add this dependency to your project's build file:

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

Others

At first generate the JAR by executing:

mvn package

Then manually install the following JARs:

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

Download from JitPack repository (Gradle and Maven)

You can download the package through JitPack. Just follow the steps described here.

Documentation

All classes and methods are described on the DOCUMENTATION.

Notes

• Is is highly recommended to turn debug mode on in case you are using PI Web API 2017 R2+ in order to receive more detailed exception errors. This can be achieved by creating or editing the DebugMode attribute's value to TRUE from the System Configuration element.
• The X-Requested-With header is added to work with CSRF defences.

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.

PIWebApiClientclient = newPIWebApiClient("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

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

Create a new PI Point

PIDataServerdataServer = client.getDataServer().getByPath("\\\\MARC-PI2016, null, 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, null); 

Get PI Points WebIds

PIPointpoint1 = client.getPoint().getByPath("\\\\JUPITER001\\sinusoid", null, null);
PIPointpoint2 = client.getPoint().getByPath("\\\\JUPITER001\\sinusoidu", null, null);
PIPointpoint3 = client.getPoint().getByPath("\\\\JUPITER001\\cdt158", null, null);

Get recorded values in bulk using the StreamSet/GetRecordedAdHoc

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

Send values in bulk using the StreamSet/UpdateValuesAdHoc

PIItemsStreamValuesstreamValuesItems = newPIItemsStreamValues();
PIStreamValuesstreamValue1 = newPIStreamValues();
PIStreamValuesstreamValue2 = newPIStreamValues();
PIStreamValuesstreamValue3 = newPIStreamValues();
PITimedValuevalue1 = newPITimedValue();
PITimedValuevalue2 = newPITimedValue();
PITimedValuevalue3 = newPITimedValue();
PITimedValuevalue4 = newPITimedValue();
PITimedValuevalue5 = newPITimedValue();
PITimedValuevalue6 = newPITimedValue();
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 = newArrayList<PITimedValue>();
values1.add(value1);
values1.add(value2);
streamValue1.setItems(values1);
List<PITimedValue> values2 = newArrayList<PITimedValue>();
values2.add(value3);
values2.add(value4);
streamValue2.setItems(values2);
List<PITimedValue> values3 = newArrayList<PITimedValue>();
values3.add(value5);
values3.add(value6);
streamValue3.setItems(values3);
List<PIStreamValues> streamValues = newArrayList<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

PIElementmyElement = client.getElement().getByPath("\\\\PISRV1\\Element", null,null);
PIItemsAttributeattributes = client.getElement().getAttributes(myElement.getWebId(), null, 1000, null, false, null, null,null,null,null,0,null,null, null);

PI Web API Batch

Map<String, PIRequest> batch = newHashMap<String, PIRequest>();
PIRequestreq1 = newPIRequest();
PIRequestreq2 = newPIRequest();
PIRequestreq3 = newPIRequest();
req1.setMethod("GET");
req1.setResource("https://marc-web-sql.marc.net/piwebapi/points?path=\\\\MARC-PI2016\\sinusoid");
req2.setMethod("GET");
req2.setResource("https://marc-web-sql.marc.net/piwebapi/points?path=\\\\MARC-PI2016\\cdt158");
req3.setMethod("GET");
req3.setResource("https://marc-web-sql.marc.net/piwebapi/streamsets/value?webid={0}&webid={1}");
List<String> parameters = newArrayList<>();
parameters.add("$.1.Content.WebId");
parameters.add("$.2.Content.WebId" );
req3.setParameters(parameters);
List<String> parentIds = newArrayList<>();
parentIds.add("1");
parentIds.add("2");
req3.setParentIds(parentIds);
batch.put("1", req1);
batch.put("2", req2);
batch.put("3", req3);
Map<String, PIResponse> batchResponse = client.getBatch().execute(batch);
Objectcontent1 = batchResponse.get("1").getContent();
Objectcontent2 = batchResponse.get("2").getContent();
Objectcontent3 = batchResponse.get("3").getContent();
JSONjson = newJSON(client.getApiClient());
PIPointpointBatch1 = json.deserialize(json.serialize(content1), newTypeToken<PIPoint>(){}.getType());
PIPointpointBatch2 = json.deserialize(json.serialize(content2), newTypeToken<PIPoint>(){}.getType());
PIItemsStreamValuebatchStreamValues = json.deserialize(json.serialize(content3), newTypeToken<PIItemsStreamValue>(){}.getType());

Getting WebID 2.0 information

stringwebIdType = "Full";
PIAssetServerpiAssetServer = client.AssetServer.GetByPath(Constants.AF_SERVER_PATH, null, webIdType);
WebIdInfopiAssetServerWebIdInfo = client.WebIdHelper.GetWebIdInfo(piAssetServer.WebId);
PIAttributepiAttribute = client.Attribute.GetByPath(Constants.AF_ATTRIBUTE_PATH, null, webIdType);
WebIdInfopiAttributeWebIdInfo = client.WebIdHelper.GetWebIdInfo(piAttribute.WebId);

Generating WebID 2.0 client side

Stringweb_id1 = client.getWebIdHelper().generateWebIdByPath("\\\\PISRV1\\CDF144_Repeated24h_forward", PIPoint.class, null);
Stringweb_id2 = client.getWebIdHelper().generateWebIdByPath("\\\\PISRV1\\Universities\\UC Davis\\Buildings\\Academic Surge Building|Electricity Totalizer", PIAttribute.class, PIElement.class);

Licensing

Copyright 2018 OSIsoft, LLC.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Please see the file named LICENSE.md.