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.

	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, null);

Create a new PI Point

	PIDataServer dataServer = 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

	PIPoint point1 = client.getPoint().getByPath("\\\\JUPITER001\\sinusoid", null, null);
	PIPoint point2 = client.getPoint().getByPath("\\\\JUPITER001\\sinusoidu", null, null);
	PIPoint point3 = client.getPoint().getByPath("\\\\JUPITER001\\cdt158", null, 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, null, null,"*-3d",null, 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("\\\\PISRV1\\Element", null,null);
	PIItemsAttribute attributes = 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 = new HashMap<String, PIRequest>();
	PIRequest req1 = new PIRequest();
	PIRequest req2 = new PIRequest();
	PIRequest req3 = new PIRequest();
	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 = new ArrayList<>();
	parameters.add("$.1.Content.WebId");
	parameters.add("$.2.Content.WebId" );
	req3.setParameters(parameters);


	List<String> parentIds = new ArrayList<>();
	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);

	Object content1 = batchResponse.get("1").getContent();
	Object content2 = batchResponse.get("2").getContent();
	Object content3 = batchResponse.get("3").getContent();

	JSON json = new JSON(client.getApiClient());
	PIPoint pointBatch1 = json.deserialize(json.serialize(content1), new TypeToken<PIPoint>(){}.getType());
	PIPoint pointBatch2 = json.deserialize(json.serialize(content2), new TypeToken<PIPoint>(){}.getType());
	PIItemsStreamValue batchStreamValues = json.deserialize(json.serialize(content3), new TypeToken<PIItemsStreamValue>(){}.getType());

Getting WebID 2.0 information

	string webIdType = "Full";
	PIAssetServer piAssetServer = client.AssetServer.GetByPath(Constants.AF_SERVER_PATH, null, webIdType);
	WebIdInfo piAssetServerWebIdInfo = client.WebIdHelper.GetWebIdInfo(piAssetServer.WebId);

	PIAttribute piAttribute = client.Attribute.GetByPath(Constants.AF_ATTRIBUTE_PATH, null, webIdType);
	WebIdInfo piAttributeWebIdInfo = client.WebIdHelper.GetWebIdInfo(piAttribute.WebId);

Generating WebID 2.0 client side

	String web_id1 = client.getWebIdHelper().generateWebIdByPath("\\\\PISRV1\\CDF144_Repeated24h_forward", PIPoint.class, null);
	String web_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.