This guide is intended to help users getting started with the Fosstrak EPCIS Webadapter module. The EPCIS Webadapter adds a RESTful, fully Web-enabled, API to a standard EPCIS repository. While the EPCIS Webadapter can be deployed on top of any standard compliant EPCIS Repository, this guide outlines the steps to follow in order to set up the EPCIS Webadapter to work with the Fosstrak EPCIS Repository.
Please note that the EPCIS Webadapter is not an EPCglobal standardized interface and currently is still a beta Fosstrak module.
As the project is part of an ongoing research project, your feedback is very valuable to us! We created a questionnaire where we try to better understand your experience and where you can ask us for new features or improvements, thanks a lot for your answers: Feedback form. If this guide does not answer the questions you may have, feel free to post them to the Fosstrak mailing list.
The project was started in frame of the Web of Things initiative at ETH Zurich. It is a collaboration between the Distributed Systems Lab of ETH, the Auto-ID Labs (MIT and Zurich), the Software Engineering Group of the University of Fribourg and SAP Research Zurich.
This module offers an additional, RESTful, integration interface, or API (Application Programming Interface) for the EPCIS upon which a different range of applications can be built thanks to a lightweight and Web-enabled RESTful architecture. It offers access to all standard EPCIS functionality through a native Web interface.
Using the EPCIS Webadapter:
The WS-* type of integration architecture is well adapted to combine business applications. For example, it can be used to integrate EPCIS data about the status of a shipment with an ERP (Enterprise Resource Planning) application.
However, WS-* applications are complex systems with high entry barriers and require developer expertise in the domain. Hence, they are not well adapted for more light-weight and ad-hoc application scenarios. Furthermore, the WS-* protocols are known to be rather verbose. Moreover, they do not fully meet the requirements of resource-constrained devices such as mobile phones and wireless sensor/actuator networks often not providing WS-* server or even client stacks.
The EPCIS Webadapter is a optional plugin that that offers an additional RESTful interface on top of any standard-compliant EPCIS. Using this approach, each query, tagged object, location or RFID reader gets a unique URL that can be linked to, exchanged in emails, browsed for, bookmarked, and consumed from any scripting or programming language understanding the HTTP protocol.
The EPCIS Webadapter has three main goals:
The module basically translates the incoming RESTful request into SOAP requests on the original EPCIS. It further takes care of reformatting the results into several Web formats such as HTML, JSON, Atom and XML. The plugin is based on Jersey, an implementation of the Java Standard for RESTful Web Services (JAX-RS). For generating Atom feeds for query subscriptions, it uses the Apache Abdera framework.
More information about the architecture of the project can be found in this paper.
The EPCIS Webadapter and some of the applications built upon can be directly tested from our demo server.
This section includes a step-by-step tutorial describing how to set up the EPCIS Webadapter to work with the Fosstrak EPCIS Repository.
The EPCIS Webadapter can be deployed on top of any standard compliant EPCIS Repository. To install the Fosstrak EPCIS Repository please refer to EPCIS Repository User Guide. To go on with this installation guide, all you need is the root URL of an EPCIS Repository (e.g., http://localhost:8080/epcis-repository-0.4.2).
The EPCIS Webadapter can be deployed in any Java compliant Web/Application server that supports the deployment of JAX-RS based applications. It was successfully tested with Tomcat (6.x) and the Glassfish (3.x) Application Server.
To deploy it on Tomcat simply copy the EPCIS Webadapter-VERSION_NUMBER.war archive to CATALINA_BASE/webapps folder of Tomcat which will auto-deploy the application. Alternatively you can also use the Tomcat manager Webapp and upload the EPCIS Webadapter-VERSION_NUMBER.war>>> archive there.
If the deployment was successful you should be able to browse to:
http://HOST:PORT/epcis-webadapter-VERSION_NUMBER
and see a Web-page there. From there click on the "EPCIS Webadapter" link. Since this triggers the initial configuration phase of the EPCIS Webadapter (creation of the internal databased, etc.), this might take a while. Please do not interrupt this phase.
The EPCIS Webadapter is configured to automatically connect to a local EPCIS instance on: http://localhost:8080/epcis-repository-0.4.2. To change the instance it connects to go to:
http://HOST:PORT/epcis-webadapter-VERSION_NUMBER/rest/API_VERSION/config/epcisurl
There, you can specify a new instance of an EPCIS repository the Webadapter should connect to. Any standard-compliant EPCIS repository should work. However, the EPCIS Webadapter was tested on the Fosstrak EPCIS Repository.
The EPCIS Webadapter also offers clients to register to queries for which updates are delivered to standard Atom feeds. This enables clients to register to EPC queries without requiring them to run an HTTP server. The EPCIS Webadapter embeds an Atom server (based on Apache Abdera). However, the Webadapter can be configured to publish the queries updates to any AtomPub compliant server.
To change the AtomPub server it pushes updates to, go to:
http://HOST:PORT/epcis-webadapter-VERSION_NUMBER/rest/API_VERSION/config/feedurl
and provide a valid URL to an AtomPub server endpoint.
The EPCIS Webadapter adds a RESTful, fully Web-enabled, API to a standard EPCIS repository. If you are not familiar with REST, we invite you to read this paper, which briefly presents REST in the context of the EPCIS Webadapter.
Using this approach, each query, tagged object, location or RFID reader gets a unique URL that can be linked to, exchanged in emails, browsed for bookmarked, etc. Furthermore, these resources can be accessed using the standard HTTP 1.1 protocol. Thus, any platform that understands HTTP protocol can consume data from the EPCIS Webadapter in a straightforward way.
The simplest way to used the EPCIS Webadapter is to use the HTML representation of resources. Pointing any browser to:
http://HOST:PORT/epcis-webadapter-VERSION_NUMBER
will give you access to the HTML representation. From there you can:
Note that each URL you will encounter in the HTML representation is unique and referenceable. Thus, you can bookmark any result for later use or sharing.
The EPCIS Webadapter makes it easier to create lightweight (e.g., mobile, Web) applications that consume EPC data. From a developer view point, all the interaction with the EPCIS Webadapter occurs through the exhaustive use of HTTP 1.1.
Basically, the Webadapter covers all the functionality of a standard EPCIS repository, plus some more advanced query capabilities. The best way to find how to access this functionality is to explore the HTML representation. There are basically two ways of formulating queries:
Both interfaces will directly display the query results. You can then use the resulting URLs from your application.
For example, let's say we are looking for all the EPC events for the business location: urn:ch:sap:regensdorf:frc. We first use the "Browsable Event Finder" to formulate this query. We directly see the query result and copy the query URL to use it in our application, we just need to GET:
http://HOST:PORT/epcis-webadapter-VERSION_NUMBER/rest/API_VERSION/eventquery/result?location=urn:ch:sap:regensdorf:frc
Similarly, we can use the "Browsable Event Finder" to find out, for instance, all the readers at location "urn:de:maxhavelaar:hamburg:shipyard". We do so by clicking on "Browsable Event Finder", on "urn:de:maxhavelaar:hamburg:shipyard" and finally on "List of Read Points". This returns us a list of all the readers at urn:de:maxhavelaar:hamburg:shipyard.
As before, we can use the created URL for retrieving this list from our application, we just need to GET:
http://HOST:PORT/epcis-webadapter-VERSION_NUMBER/rest/API_VERSION/location/urn:de:maxhavelaar:hamburg:shipyard/reader
Any client that can communicate with the Web (e.g., using the java.net package) can consume RESTful Web services. However, several tools can help you make this even more straightforward:
As a RESTful API, the EPCIS Webadapter offers several representations (i.e., formats) for resources identified by the following mime-types:
A client requests a particular format through the standard HTTP 1.1 content-negotiation mechanism.
More concretely it does this by setting the Accept header of the HTTP packet to one (or a list) of accepted/preferred formats. As an example, we can use cURL to get the list of all EPC events for the business location: urn:ch:sap:regensdorf:frc in JSON:
curl -X GET -H Accept:application/json http://localhost:8080/EPCIS Webadapter-0.0.1-SNAPSHOT/rest/0.0.1/eventquery/result?reader=urn:br:maxhavelaar:natal:shipyard:incoming
The EPCIS Webadapter also provides a WADL (Web Application Description Language) file to describe the resources it offers. While this can be practical in some cases, WADL-based REST clients are subject to many critisims in the REST community as a clean and browsable HTML representation covers almost all the expressive power of WADL already.
However, if you do need a WADL for your application, you can find it by sending OPTIONS to:
http://HOST:PORT/epcis-webadapter-VERSION_NUMBER/rest/API_VERSION/
The EPCIS Webadapter also features an Atom Web feed subscription and generation system on top of the EPCIS Subscription Standard. This is especially useful since, unlike the original EPCIS Subscription system, it does not require clients to run a server with a tailored Web application that listens to the subscribed endpoint. Thus, it is more adapted to more lightweight clients such as mobile phones, sensor networks, Web browsers, etc.
To create an Atom feed you first need to create the query URL. This is best achieved by using the "Browsable Event Finder" or the "Query Form". Once you have the query URL you can subscribe to it by calling PUT, for example on:
http://HOST:PORT/epcis-webadapter-VERSION_NUMBER/rest/API_VERSION/eventquery/subscription?reader=urn:epc:id:sgln:unifr.perolles.cafeteria
Or with cURL:
curl -X PUT -H Accept:application/xml http://HOST:PORT/EPCIS Webadapter-VERSION_NUMBER/rest/API_VERSION/eventquery/subscription?reader=urn:epc:id:sgln:unifr.perolles.cafeteria
You can then get the feeds by calling GET on:
http://HOST:PORT/epcis-webadapter-VERSION_NUMBER/rest/feed
The EPCIS Webadapter can be easily used from any language supporting sockets. However, it is very straightforward to use in combination with HTTP client libraries. Here, we provide two examples in Java using two different HTTP library.
This an example of a query on the EPCIS Webadapter using the Apache HTTP Client in Java. This call uses the "query" resource to get all the EPC events that occurred at urn:ch:sap:regensdorf:frc:storage. Note that this query was successfully tested on a desktop computer as well as on an Android 2.2 mobile device:
import java.io.IOException; import org.apache.http.client.ClientProtocolException; import org.apache.http.client.HttpClient; import org.apache.http.client.ResponseHandler; import org.apache.http.client.methods.HttpGet; import org.apache.http.impl.client.BasicResponseHandler; import org.apache.http.impl.client.DefaultHttpClient; [...] public String querywebadapter() { String result = null; HttpClient httpclient = new DefaultHttpClient(); HttpGet request = new HttpGet("http://localhost:8080/EPCIS Webadapter-0.0.1-SNAPSHOT/rest/0.0.1/eventquery/result?reader=urn:ch:sap:regensdorf:frc:storage"); request.addHeader("Accept", "application/json"); ResponseHandler<String> handler = new BasicResponseHandler(); try { result = httpclient.execute(request, handler); } catch (ClientProtocolException e) { //handle exception } catch (IOException e) { //handle exception } httpclient.getConnectionManager().shutdown(); return result; }
In this more compact version, we use the Jersey JAX-RS Client library in Java to get all the locations registered by the EPCIS Repository on which the EPCIS Webadapter is plugged:
import com.sun.jersey.api.client.Client; import com.sun.jersey.api.client.WebResource; public String queryWebAdapterJersey() { Client client = Client.create(); WebResource webResource = client.resource("http://localhost:8080/EPCIS Webadapter-0.0.1-SNAPSHOT/rest/0.0.1/location"); return webResource.accept("application/xml").get(String.class); }
"The XML and JSON links of the HTML representations do not work"
We identified that on some browsers (e.g., Chrome) the Javascript that offers to visualize different representations directly from the HTML page does not work. It was successfully tested on Firefox. If you want to see the other representations please refer to Requesting Different Formats
"I get the following exception when deploying the EPCIS Webadapter"
java.lang.NullPointerException org.fosstrak.webadapters.epcis.db.InternalDatabase.getConfigurationEntry(InternalDatabase.java:202) org.fosstrak.webadapters.epcis.db.InternalDatabase.initializeIfNotPresent(InternalDatabase.java:121) org.fosstrak.webadapters.epcis.db.InternalDatabase.<init>(InternalDatabase.java:73) org.fosstrak.webadapters.epcis.db.InternalDatabase.getInstance(InternalDatabase.java:84) ...
This is a known bug due to the fact that the SQLite embedded database-driver the EPCIS Webadapter uses is based on JNI. Thus, in some containers (e.g., Tomcat) it can only be loaded once and is not released when undeploying the application. The only workaround we currently have is to restart the Tomcat instance. We are working on migrating the SQLite database to one that does not require the use of a JNI driver.
As the project is part of an ongoing research project, your feedback is very valuable to us! We created a questionnaire where we try to better understand your experience and where you can ask us for new features or improvements, thanks a lot for your answers: Feedback form.