You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@streampipes.apache.org by bo...@apache.org on 2021/03/09 19:19:34 UTC
[incubator-streampipes-extensions] 02/03: [STREAMPIPES-301] add
javadoc comments
This is an automated email from the ASF dual-hosted git repository.
bossenti pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/incubator-streampipes-extensions.git
commit d42c96a1dc60d881fc93ad3c43dbff1416d5be5b
Author: bossenti <bo...@posteo.de>
AuthorDate: Tue Mar 9 13:27:17 2021 +0100
[STREAMPIPES-301] add javadoc comments
---
.../connect/adapters/opcua/OpcNode.java | 46 ++++++++++-
.../streampipes/connect/adapters/opcua/OpcUa.java | 93 ++++++++++++++++++----
.../adapters/opcua/utils/OpcUaNodeVariants.java | 5 ++
.../connect/adapters/opcua/utils/OpcUaTypes.java | 5 ++
.../connect/adapters/opcua/utils/OpcUaUtil.java | 27 ++++++-
5 files changed, 160 insertions(+), 16 deletions(-)
diff --git a/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/OpcNode.java b/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/OpcNode.java
index 6903a33..7a9fb82 100644
--- a/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/OpcNode.java
+++ b/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/OpcNode.java
@@ -21,12 +21,25 @@ package org.apache.streampipes.connect.adapters.opcua;
import org.eclipse.milo.opcua.stack.core.types.builtin.NodeId;
import org.apache.streampipes.sdk.utils.Datatypes;
+/**
+ * OpcNode is a StreamPipes internal model of an OPC UA node.
+ * It's main purpose is to ease the handling of nodes within StreamPipes.
+ */
+
public class OpcNode {
String label;
Datatypes type;
NodeId nodeId;
int opcUnitId;
+ /**
+ * Constructor for class OpcNode without an OPC UA unit identifier. <br>
+ * Unit identifier is set to zero as default.
+ *
+ * @param label name of the OPC UA node
+ * @param type datatype of the OPC UA node
+ * @param nodeId identifier of the OPC UA node
+ */
public OpcNode(String label, Datatypes type, NodeId nodeId) {
this.label = label;
this.type = type;
@@ -34,6 +47,16 @@ public class OpcNode {
this.opcUnitId = 0;
}
+ /**
+ * Constructor for class OpcNode with an OPC UA unit identifier. <br>
+ * This identifier references to an OPC UA measurement unit, e.g. degree celsius. <br>
+ * With {@link OpcNode#getQudtURI()} the OPC UA internal ID is mapped to the QUDT unit ontology <br>
+ *
+ * @param label name of the OPC UA node
+ * @param type datatype of the OPC UA node
+ * @param nodeId identifier of the OPC UA node
+ * @param opcUnitId OPC UA internal unit identifier
+ */
public OpcNode(String label, Datatypes type, NodeId nodeId, Integer opcUnitId){
this.label = label;
this.type = type;
@@ -67,7 +90,28 @@ public class OpcNode {
public int getOpcUnitId() {return this.opcUnitId;}
- public boolean hasUnitId() {return this.opcUnitId !=0; }
+ public boolean hasUnitId() {
+ // zero is the default case when no unit id is present
+ return this.opcUnitId !=0;
+ }
+ /**
+ * Returns the corresponding QUDT URI if the {@code opcUnitId} is given,
+ * otherwise it returns an empty string. <br>
+ * Currently, there are only two examples added. <br>
+ * Other units have to be added manually, please have a look at the <a href="http://opcfoundation.org/UA/EngineeringUnits/UNECE/UNECE_to_OPCUA.csv"> OPC UA unitID mapping table</a>. <br>
+ *
+ * @return QUDT URI as string of the given unit
+ */
+ public String getQudtURI(){
+ switch (this.opcUnitId){
+ case 17476:
+ return "http://qudt.org/vocab/unit#DEG";
+ case 4408652:
+ return "http://qudt.org/vocab/unit#DegreeCelsius";
+ default:
+ return "";
+ }
+ }
}
diff --git a/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/OpcUa.java b/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/OpcUa.java
index 48bed89..5c723f9 100644
--- a/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/OpcUa.java
+++ b/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/OpcUa.java
@@ -61,6 +61,10 @@ import java.util.function.BiConsumer;
import java.util.stream.Collectors;
import java.util.stream.Stream;
+/***
+ * Wrapper class for all OPC UA specific stuff. <br>
+ * Is used both in the {@link OpcUaPullAdapter} and {@link OpcUaSubscriptionAdapter}.
+ */
public class OpcUa {
static Logger LOG = LoggerFactory.getLogger(OpcUa.class);
@@ -76,11 +80,23 @@ public class OpcUa {
private static final AtomicLong clientHandles = new AtomicLong(1L);
+ /***
+ *
+ * @return current {@link org.eclipse.milo.opcua.sdk.client.OpcUaClient}
+ */
public OpcUaClient getClient() {
return this.client;
}
+ /**
+ * Constructor for security level {@code None} and OPC server given by url
+ *
+ * @param opcServerURL complete OPC UA server url
+ * @param namespaceIndex namespace index of the given node
+ * @param nodeId node identifier
+ * @param selectedNodeNames list of node names provided from {@link OpcUaUtil#resolveOptions(String, StaticPropertyExtractor)}
+ */
public OpcUa(String opcServerURL, int namespaceIndex, String nodeId, List<String> selectedNodeNames) {
this.opcServerURL = opcServerURL;
@@ -95,10 +111,29 @@ public class OpcUa {
}
}
+ /**
+ * Constructor for security level {@code None} and OPC server given by hostname and port number
+ *
+ * @param opcServer OPC UA hostname
+ * @param opcServerPort OPC UA port number
+ * @param namespaceIndex namespace index of the given node
+ * @param nodeId node identifier
+ * @param selectedNodeNames list of node names provided from {@link OpcUaUtil#resolveOptions(String, StaticPropertyExtractor)}
+ */
public OpcUa(String opcServer, int opcServerPort, int namespaceIndex, String nodeId, List<String> selectedNodeNames) {
this( opcServer + ":" + opcServerPort, namespaceIndex, nodeId, selectedNodeNames);
}
+ /**
+ * Constructor for security level {@code Sign} and OPC server given by url
+ *
+ * @param opcServerURL complete OPC UA server url
+ * @param namespaceIndex namespace index of the given node
+ * @param nodeId node identifier
+ * @param username username to authenticate at the OPC UA server
+ * @param password corresponding password to given user name
+ * @param selectedNodeNames list of node names provided from {@link OpcUaUtil#resolveOptions(String, StaticPropertyExtractor)}
+ */
public OpcUa(String opcServerURL, int namespaceIndex, String nodeId, String username, String password, List<String> selectedNodeNames) {
this(opcServerURL, namespaceIndex, nodeId, selectedNodeNames);
this.unauthenticated = false;
@@ -106,6 +141,17 @@ public class OpcUa {
this.password = password;
}
+ /**
+ * Constructor for OPC UA security level {@code Sign} and OPC server given by hostname and port number
+ *
+ * @param opcServer OPC UA hostname
+ * @param opcServerPort OPC UA port number
+ * @param namespaceIndex namespace index of the given node
+ * @param nodeId node identifier
+ * @param username username to authenticate at the OPC UA server
+ * @param password corresponding password to given user name
+ * @param selectedNodeNames list of node names provided from {@link OpcUaUtil#resolveOptions(String, StaticPropertyExtractor)}
+ */
public OpcUa(String opcServer, int opcServerPort, int namespaceIndex, String nodeId, String username, String password, List<String> selectedNodeNames) {
this (opcServer, opcServerPort, namespaceIndex, nodeId, selectedNodeNames);
this.unauthenticated = false;
@@ -113,6 +159,11 @@ public class OpcUa {
this.password = password;
}
+ /**
+ * Creates {@link OpcUa} instance in accordance with the given {@link org.apache.streampipes.sdk.extractor.StaticPropertyExtractor}.
+ * @param extractor extractor for user inputs
+ * @return {@link OpcUa} instance based on information from {@code extractor}
+ */
public static OpcUa from(StaticPropertyExtractor extractor) {
String selectedAlternativeConnection = extractor.selectedAlternativeInternalId(OpcUaLabels.OPC_HOST_OR_URL.name());
@@ -160,6 +211,11 @@ public class OpcUa {
}
+ /***
+ * Creates {@link OpcUa} instance in accordance with the given {@link org.apache.streampipes.model.connect.adapter.AdapterDescription}
+ * @param adapterDescription description of current adapter
+ * @return {@link OpcUa} instance based on information from {@code adapterDescription}
+ */
public static OpcUa from(AdapterDescription adapterDescription){
StaticPropertyExtractor extractor =
@@ -168,6 +224,11 @@ public class OpcUa {
return from(extractor);
}
+ /***
+ * Establishes appropriate connection to OPC UA endpoint depending on the {@link OpcUa} instance
+ *
+ * @throws Exception
+ */
public void connect() throws Exception {
List<EndpointDescription> endpoints = DiscoveryClient.getEndpoints(this.opcServerURL).get();
@@ -235,6 +296,12 @@ public class OpcUa {
);
}
+ /***
+ * Search for related nodes relative to {@link OpcUa#node}
+ * @param selectNodes indicates whether only nodes of {@link OpcUa#selectedNodeNames} should be returned
+ * @return List of {@link OpcNode}s related to {@link OpcUa#node}
+ * @throws AdapterException
+ */
public List<OpcNode> browseNode(boolean selectNodes) throws AdapterException {
List<OpcNode> referenceDescriptions = browseNode(node, selectNodes);
@@ -282,6 +349,12 @@ public class OpcUa {
return result;
}
+ /***
+ * Search for related nodes relative to {@link OpcUa#node}
+ * @param selectNodes indicates whether only nodes of {@link OpcUa#selectedNodeNames} should be returned
+ * @return List of {@link OpcNode}s related to {@link OpcUa#node}
+ * @throws AdapterException
+ */
private List<OpcNode> browseNode(NodeId browseRoot, boolean selectNodes) throws AdapterException {
List<OpcNode> result = new ArrayList<>();
@@ -389,6 +462,12 @@ public class OpcUa {
}
+ /***
+ * Register subscriptions for given OPC UA nodes
+ * @param nodes List of {@link org.eclipse.milo.opcua.stack.core.types.builtin.NodeId}
+ * @param opcUaSubscriptionAdapter current instance of {@link OpcUaSubscriptionAdapter}
+ * @throws Exception
+ */
public void createListSubscription(List<NodeId> nodes, OpcUaSubscriptionAdapter opcUaSubscriptionAdapter) throws Exception {
/*
* create a subscription @ 1000ms
@@ -464,20 +543,6 @@ public class OpcUa {
return true;
}
- // utility function for mapping UPC Unit Ids to QUDT entities
- // has to be maintained manually
- // information about OPC Unit IDs can be found under: opcfoundation.org/UA/EngineeringUnits/UNECE/UNECE_to_OPCUA.csv
- public static String mapUnitIdToQudt(int unitId){
- switch (unitId){
- case 17476:
- return "http://qudt.org/vocab/unit#DEG";
- case 4408652:
- return "http://qudt.org/vocab/unit#DegreeCelsius";
- default:
- return "";
- }
- }
-
public List<String> getSelectedNodeNames() {
return selectedNodeNames;
diff --git a/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/utils/OpcUaNodeVariants.java b/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/utils/OpcUaNodeVariants.java
index 0361556..265d756 100644
--- a/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/utils/OpcUaNodeVariants.java
+++ b/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/utils/OpcUaNodeVariants.java
@@ -20,6 +20,11 @@ package org.apache.streampipes.connect.adapters.opcua.utils;
import javax.annotation.Nullable;
+/**
+ * Enum that maintains different variants of OPC UA nodes. <br>
+ * Not yet completed. <br>
+ *
+ */
public enum OpcUaNodeVariants {
Property(68),
EUInformation(887);
diff --git a/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/utils/OpcUaTypes.java b/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/utils/OpcUaTypes.java
index 4ddab4d..aae7ae1 100644
--- a/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/utils/OpcUaTypes.java
+++ b/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/utils/OpcUaTypes.java
@@ -24,6 +24,11 @@ import org.apache.streampipes.sdk.utils.Datatypes;
public class OpcUaTypes {
+ /**
+ * Maps OPC UA data types to internal StreamPipes data types
+ * @param o data type id as UInteger
+ * @return StreamPipes internal data type
+ */
public static Datatypes getType(UInteger o) {
if (UInteger.valueOf(4).equals(o) | UInteger.valueOf(6).equals(o) | UInteger.valueOf(8).equals(o) | UInteger.valueOf(27).equals(o)) {
return Datatypes.Integer;
diff --git a/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/utils/OpcUaUtil.java b/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/utils/OpcUaUtil.java
index 1fadfb6..77b8a82 100644
--- a/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/utils/OpcUaUtil.java
+++ b/streampipes-connect-adapters/src/main/java/org/apache/streampipes/connect/adapters/opcua/utils/OpcUaUtil.java
@@ -17,8 +17,16 @@ import java.net.URI;
import java.util.ArrayList;
import java.util.List;
+/***
+ * Collection of several utility functions in context of OPC UA
+ */
public class OpcUaUtil {
+ /***
+ * Ensures server address starts with {@code opc.tcp://}
+ * @param serverAddress server address as given by user
+ * @return correctly formated server address
+ */
public static String formatServerAddress(String serverAddress) {
if (!serverAddress.startsWith("opc.tcp://")) {
@@ -28,6 +36,13 @@ public class OpcUaUtil {
return serverAddress;
}
+ /***
+ * OPC UA specific implementation of {@link org.apache.streampipes.connect.adapter.Adapter}
+ * @param adapterStreamDescription
+ * @return guess schema
+ * @throws AdapterException
+ * @throws ParseException
+ */
public static GuessSchema getSchema(SpecificAdapterStreamDescription adapterStreamDescription) throws AdapterException, ParseException {
GuessSchema guessSchema = new GuessSchema();
EventSchema eventSchema = new EventSchema();
@@ -45,7 +60,7 @@ public class OpcUaUtil {
allProperties.add(PrimitivePropertyBuilder
.create(opcNode.getType(), opcNode.getLabel())
.label(opcNode.getLabel())
- .measurementUnit(new URI(OpcUa.mapUnitIdToQudt(opcNode.getOpcUnitId())))
+ .measurementUnit(new URI(opcNode.getQudtURI()))
.build());
} else {
allProperties.add(PrimitivePropertyBuilder
@@ -71,8 +86,15 @@ public class OpcUaUtil {
}
+ /***
+ * OPC UA specific implementation of {@link org.apache.streampipes.container.api.ResolvesContainerProvidedOptions#resolveOptions(String, StaticPropertyExtractor)}. }
+ * @param requestId
+ * @param parameterExtractor
+ * @return {@code List<Option>} with available node names for the given OPC UA configuration
+ */
public static List<Option> resolveOptions (String requestId, StaticPropertyExtractor parameterExtractor) {
+ // access mode and host/url have to be selected
try {
parameterExtractor.selectedAlternativeInternalId(OpcUaLabels.OPC_HOST_OR_URL.name());
parameterExtractor.selectedAlternativeInternalId(OpcUaLabels.ACCESS_MODE.name());
@@ -111,6 +133,9 @@ public class OpcUaUtil {
return key;
}
+ /***
+ * Enum for all possible labels in the context of OPC UA adapters
+ */
public enum OpcUaLabels {
OPC_HOST_OR_URL,
OPC_URL,