Features

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:

• lowering the entry barrier for developers and foster rapid prototyping by bringing the EPCIS data closer to Web languages such as Javascript or Python.

• allowing users to directly access, share and bookmark EPCIS queries and their results through any standard Web-browser, without the need to install any additional software. With this module, every resource of the EPC network gets a unique URL and subscription to queries are delivered as Web Feeds (using the Atom standard).

• Offering a more light-weight access to the data. This enables creating applications in which the EPCIS data are directly consumed by resource-constrained devices (e.g., Wireless sensor networks, mobile phones, etc.) without requiring proxy or translation gateways.

Architecture

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.

Setting up an 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).

Deploying the EPCIS Webadapter

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.

Configuring the EPCIS Webadapter

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.

Tools for Interacting with the RESTful API

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:

• HTTP Client Libraries such as the Apache HTTP Client are available on most platforms (e.g., Android) and help you formulate RESTful request within a few lines of code.
• Programming languages such as PHP, Python, Javascript, Ruby have full built in support for consuming RESTful Web Services over HTTP.
• In the Java world, implementations of the JAX-RS standard provide high level client API (e.g., Jersey Client API) that literally reduce the complexity of communicating with RESTful service to a couple of lines.
• For testing, tools such as the Poster Firefox Extension, or the cURL command-line tool are great to test all the features of HTTP and RESTful APIs.

Requesting Different Formats

As a RESTful API, the EPCIS Webadapter offers several representations (i.e., formats) for resources identified by the following mime-types:

• text/html: a Web page, including page layout, navigation menu and logos. This representation is human-friendly and meant for Web browsers.
• application/xhtml+xml: contains just the core business of the resource, without layout, navigation or images. It is meant to be embedded into other Web pages or used in Web Mashups.
• text/xml: is an XML representation, strictly following the XML Schema of the EPCIS standard.
• application/xml: is an XML representation containing the whole state of the resource (e.g., links to sub-resources, etc.).
• application/json: is a JSON representation of a resource and its state. JSON is a lightweight alternative to XML which is often used in Web Mashups or mobile applications.

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/

Working with Feeds

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

Sample Calls using HTTP and REST Client Libraries

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.

Simple Example Using the Apache HTTP Client

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;
    }

Simple Example Using the Jersey JAX-RS Client Library

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);
    }