Consortium Activities Projects Forge Events

Connector

1 Connector

----
#toc("" "" "")
----

1.1 Introduction

In this section we will provide information regarding the deployment and the configuration of the connector components.

The connector is composed by two collaborating components the server part and the client part. These terms should not be taken with their strict meaning because both components act at some time in their lifecycle as a server and as a client. These terms represent their position in the AspireRFID framework. The connector server is located next two the EPCIS component and the connector client is located next to the client application that requires information from EPCIS. They act as proxies to automate the process of communicating with an EPCIS repository. More information about the role of the connectors can be acquired from Aspire's deliverable [2.4 Requirements and specifications>http://fp7-aspire.eu/fileadmin/aspire/docs/D2_4.pdf].

1.1 Users Guide

1.1.1 Deployment

Both connector components are designed to work in a Java application server (e.g. tomcat) so they are provided as a web archive (i.e. war). The connector client can also be embedded within a client application if required. This means that it can function either within a web container or in standalone mode, functionality that can be selected through configuration files.
Instructions on how to deploy the provided war files are dependent on the application server that you may choose to use. For the latest version of tomcat, all you have to do is place a copy of the war files within the webapps directory located at the tomcat installation folder.

1.1.1 Configuration

Configuration files exist within the war files under the folder props with the name *application.properties*. You can either edit them before deployment or after deployment based on your needs and on the application server that you are using. Following we will describe the configuration options for each connector component.

1.1.1.1 Connector server
This is the configuration file of the connector server. We will explain each one of the configuration options.
{code}
callbackDestinationUrl=http://localhost:8899
epcisQueryIfceUrl=http://localhost:8080/epcis/query
epcisCaptureIfceUrl=http://localhost:8080/epcis/capture
queryName=SimpleEventQuery
timeDifferenceFromUTC=+02:00
{code}

*callbackDestinationUrl*: This generally does not need to be changed. It defines a TCP server where query subscriptions to the EPCIS repository will return their results to. If this is defined incorrectly the connector will not be able to receive any query results from the EPCIS repository.

*epcisQueryIfceUrl*: This property holds the location of the EPCIS query interface that we are interested in getting information from, as defined by the [EPCglobal EPCIS standard>http://www.epcglobalinc.org/standards/epcis]

*epcisCaptureIfceUrl*: This is the URL of location of the EPCIS capture interface.

*queryName*: The only available query name is the SimpleEventQuery. Unless another query is implemented at the EPCIS query interface, this should not be changed.

*timeDifferenceFromUTC*: This is the time difference of the local time from the [UTC>http://en.wikipedia.org/wiki/Utc] or [GMT>http://en.wikipedia.org/wiki/Gmt]. It is required for the generation of specific EPCIS events. The format is ±HH:MM.

1.1.1.1 Connector client
{code}
connectorServerUrl = http://localhost:8080/Connector-1.0/connector
{code}

*connectorServerUrl*: The endpoint of the connector server. The first part, i.e. ~~http://localhost:8080/Connector-1.0~~ is the location where the connector server has been deployed. The second part, i.e. ~~connector~~ is the web service that the client uses to communicate with the server and subscribe for new queries.

*isConnectorClientStandaloneModeOn*: Possible values: true or false. This defines whether the connector client is deployed as a standalone web application or is embedded within a client application. If this property is set to *false* and the war file is deployed to an application server, an embedded servlet will be used to deploy the web services of the connector client. On the other hand, if this property is set to true, an embedded trivial application server will be opened by the connector client, on the port defined by the *standaloneConnectorClientPort* property, and the web service will be deployed on this server.

1.1 Developers Guide

The Connector components provide SOAP based web services to subscribe to new EPCIS transactions and to receive new events information. As it has been mentioned above there are two components than compose the Connector functionality: The Connector Server or Connector Engine and the Connector Client.

1.1.1 Connector Engine

This component is responsible for receiving query (subscription or polling) requests from the client, to translate this information to EPCIS query information and then forward any event details from the EPCIS repository to the connector client via the web service that the client exposes.
The engine provides two web services to start and stop a transaction observation. The *startObservingTransaction* and the *stopObservingTransaction*. Both of these operations require (among others) a specific type of object to be passwd that encapsulates all mandatory and optional information for the query, the *SubscriptionParameters* object.

*SubscriptionParameters*
{code}
<xs:complexType name="subscriptionParameters">
    <xs:sequence>
        <xs:element name="doPoll" type="xs:boolean"/>
        <xs:element minOccurs="0" name="initialTime" type="xs:dateTime"/>
        <xs:element minOccurs="0" name="queryDayOfMonth" type="xs:string"/>
        <xs:element minOccurs="0" name="queryDayOfWeek" type="xs:string"/>
        <xs:element minOccurs="0" name="queryHour" type="xs:string"/>
        <xs:element minOccurs="0" name="queryMin" type="xs:string"/>
        <xs:element minOccurs="0" name="queryMonth" type="xs:string"/>
        <xs:element minOccurs="0" name="querySec" type="xs:string"/>
        <xs:element minOccurs="0" name="replyEndpoint" type="xs:string"/>
        <xs:element name="reportIfEmpty" type="xs:boolean"/>
        <xs:element minOccurs="0" name="subscriptionId" type="xs:string"/>
        <xs:element minOccurs="0" name="transactionId" type="xs:string"/>
        <xs:element minOccurs="0" name="transactionType" type="xs:string"/>
    </xs:sequence>
</xs:complexType>
{code}

* *doPoll*: If false, then a new subscription will be registered within the EPCIS with information that is provided with other elements. If true then the query will be executed only once. Mandatory for new subscriptions.
* *initialTime*: This parameter defines the time constraint after which all matching events will be returned. If doPoll is false, and the initialTime refers to the past, the old matching events will be returned within the first response message. Mandatory for new subscriptions.
* *queryX*: This category of parameters define the time interval that the query will be executed within the EPCIS repository if doPoll is false. At least one of the parameters should be defined in this case. These parameters take a comma separated list of integers that define the query schedule. For example, if querySec has the value ~~1,31~~ then the query will be executed on the 1st and 31st second of every minute. For more information you should read chapter ~~8.2.5.3 Query Schedule~~ of the ~~EPCglobal EPC Information Services (EPCIS) Version 1.0.1 Specification~~. Mandatory for new subscriptions.
* *replyEndpoint*: Defines the web service endpoint of the Connector Client that query results should be posted to. Mandatory for new subscriptions.
* *reportIfEmpty*: Indicates whether a query result will be send to the Connector client even if there is no matching event. Mandatory for new subscriptions.
* *subscriptionId*: Should be a universally unique identifier to identify a subscription. Mandatory if doPoll false.
* *transactionId*: Indicates the events that we are interested in. Mandatory for new subscriptions and for deletions.
* *transactionType*: Indicates the optional event type that we are interested in. Optional. Mandatory in deletions only if it had been defined in the initial subscription.

The *startObservingTransaction operation* requires this object as a parameter.

The *stopObservingTransaction operation* takes as a parameter a subscription parameters object along with a boolean value which indicates if the transaction id that we want to stop observing has been completed, in order to send a Transaction Event to the EPCIS repository and delete the transaction designated in the SubscriptionParameters object. If the deletion of the  transaction is not required then the parameters construct should only contain the subscriptionId element.

Refer to the {attach:ConnectorEngine.wsdl} for the web service definition.

1.1.1 Connector client

This component is responsible for receiving query (subscription or polling) requests from a software that uses the client component, submit the query to the Connector Engine and receive query responses from the latter.
The component provides one web services to receive events from the engine based on subscribed or polled queries. This operation is called asynchronously from the engine when event information is available and receives an Event object that encapsulates information provided by EPCIS events which are defined by the EPCIS 1.0.1 specification.

*Event*
{code}
<xs:complexType name="event">
    <xs:sequence>
        <xs:element minOccurs="0" name="action" type="xs:string"/>
        <xs:element minOccurs="0" name="bizLocationId" type="xs:string"/>
        <xs:element minOccurs="0" name="bizStepId" type="xs:string"/>
        <xs:element maxOccurs="unbounded" minOccurs="0" name="bizTransactionList" nillable="true" type="xs:string"/>
        <xs:element maxOccurs="unbounded" minOccurs="0" name="childEpcs" nillable="true" type="xs:string"/>
        <xs:element minOccurs="0" name="dispositionId" type="xs:string"/>
        <xs:element minOccurs="0" name="epcClass" type="xs:string"/>
        <xs:element maxOccurs="unbounded" minOccurs="0" name="epcList" nillable="true" type="xs:string"/>
        <xs:element name="eventTime" type="xs:long"/>
        <xs:element minOccurs="0" name="parentId" type="xs:string"/>
        <xs:element name="quantity" type="xs:int"/>
        <xs:element minOccurs="0" name="readPointId" type="xs:string"/>
        <xs:element minOccurs="0" name="subscriptionId" type="xs:string"/>
    </xs:sequence>
</xs:complexType>
{code}

Refer to the {attach:ConnectorClient.wsdl} for the web service definition.

The client can be either deployed separately in an application server, e.g. Apache Tomcat, or it may be embedded within a client application and deploy the web service through an embedded Jetty application server. The first task is done automatically. The second is done by calling the *startStandaloneMode* method of the org.ow2.aspirerfid.connectors.client.ConnectorClientImpl class.

The client application should implement the *org.ow2.aspirerfid.connectors.api.ClientEventHandler* interface and register itself through the *setEventHandler* of the org.ow2.aspirerfid.connectors.client.ConnectorClientImpl class so that it may receive the events and do the whatever it wants.

The client application should use the org.ow2.aspirerfid.connectors.client.RegistrationManager operations to register or execute new queries passing a SubscriptionParameters object and unregister from existing subscriptions.

1.1.1 Work to do

* Make Connector engine subscription information persistent.