BaSyx XQuery Submodel provider

XQuery servlet

The XQuery sub model provider enables the use of XQuery to provide sub models with read-only properties. XQuery uses query scripts to extract and present information from XML files to the user of XQuery. The XQuery provider enables users to export the result of XQuery queries as read-only sub model properties. The provider is configured with a main configuration file. It is implemented by servlet class org.eclipse.basyx.components.servlets.XMLXQueryServlet. It accepts the following configuration parameter:

config: Path to configuration file

The following snippet illustrates an Apache Tomcat configuration for the CFG sub model provider Example_XQueryProvider. It configures the location of the configuration file inside the WEB-INF folder and configures the URL pattern that is used to access the sub model to /Testsuite/components/BaSys/1.0/provider/xmlxquery

  <servlet>
    <servlet-name>Example_XQueryProvider</servlet-name>
    <servlet-class> org.eclipse.basyx.components.servlets.XMLXQueryServlet </servlet-class>
 
    <init-param>
        <param-name>config</param-name>
        <param-value>/WEB-INF/config/xmlqueryprovider/xmlqueryprovider.properties</param-value>
    </init-param>
 
    <load-on-startup>5</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>Example_XQueryProvider</servlet-name>
    <url-pattern>/Testsuite/components/BaSys/1.0/provider/xmlxquery/*</url-pattern>
  </servlet-mapping>

The main configuration file of the XQuery sub model provider contains the sub model meta data and sub model properties that are exported by the XQuery sub model provider. The following properties are supported for describing sub model meta data. The provider makes sure that meta data is exported as conforming sub model meta data. For a more in depth description, please refer to <<<PDF>>>.

basyx.submodelID	ID of sub model
basePath	Base path for query files
xmlFile	XML file that is queried relative to base path
properties	Comma separated list of properties that are exported by the XQuery provider

For each property, a get operation may be defined:

<propertyname>_get

XQuery operation that retrieves the property value

The provider implements get operations by executing XQuery operations. An XQuery operation must be provided as an individual query file. The following example illustrates an XQuery file that retrieves sensors whose weight exceeds the weight of 10.00:

for $sensor in fn:doc('database.xml')/sensors/sensor 
where xs:decimal($sensor/weight) gt 10.00
return
  $sensor/name

Configuration file example

The following example configuration illustrates a minimalistic configuration for the XQuery provider:

# ##############################################################
# XML query Sub model provider configuration file
# ##############################################################
 
# ##############################################################
# Sub model provider configuration
 
basyx.submodelID    = XMLQTestSubmodel
 
# ##############################################################
# XML configuration
 
basepath           = WEB-INF/config/xmlqueryprovider
xmlFile            = database.xml
 
# ##############################################################
# XML sub model configuration
 
properties         = properties/heavySensorNames 
 
properties/heavySensorNames_get         = heavySensorNames.xq

XML database example

The following example database.xml file contains sensors and their weight values:

<sensors>
  <sensor>
    <name>SensorA</name>
    <kind>LightSensor</kind>
    <weight>14.06</weight>
  </sensor>
  <sensor>
    <name>SensorB</name>
    <kind>LightSensor</kind>
    <weight>8.03</weight>
  </sensor>
  <sensor>
    <name>SensorC</name>
    <kind>WeightSensor</kind>
    <weight>21</weight>
  </sensor>
  <sensor>
    <name hasLongName='true'>
    	SensD
    	<longName>SensorD</longName>
    </name>
    <kind>LightSensor</kind>
    <weight>18.01</weight>
  </sensor>
  <sensor>
    <name>13</name>
    <kind>WeightSensor</kind>
    <weight>21</weight>
  </sensor>
</sensors>

XQuery sub model provider Java example

The following code snippets illustrate the XQuery sub model provider use from the JAVA SDK. The sub model provider exports properties that may be read with the readElementValue primitive.

• Connect to XQuery sub model provider via directory service. XQuerysub model provider is available with ID XMLXQueryFileTestAAS.

// Connect to sub model "XMLXQueryFileTestAAS"
VABElementProxy connSubModel = this.connManager.connectToVABElement("XMLXQueryFileTestAAS");

• Read property value from a property exported by XQueryprovider. The provider runs the XQuery whenever the property value is accessed.

// Get property value
Object value1 = connSubModel.readElementValue("/aas/submodels/XMLQTestSubmodel/properties/heavySensorNames");