RFID Software Developer's Guide Table Of ContentsPrevious ChapterNext ChapterNoIndex


C H A P T E R  2
Using RFID Information Server Client API

This chapter describes the client API for interfacing with RFID Information Server. The following topics are covered:

Connecting to RFID Information Server

The com.sun.autoid.epcis.client.EpcisConnection class represents a communication link between the application and RFID Information Server. An instance of the connection class can support multiple requests. The transport protocol used by the connection is specified using the appropriate constructor.

This section contains the following code examples:


CODE EXAMPLE 2-2 Establishing a Connection Using JMS on Sun Java System Application Server 
EpcisConnection conn = new EpcisConnection(

"file:///imq_admin_objects", // file system JNDI provider URL

"TopicConnectionFactory", // name of the connection factory

"epcisTopic", // name of the topic

"true",      // user JMS (true or false) 

"myname",    // user name

"mypassword");  // password

 


CODE EXAMPLE 2-3 Establishing a Connection Using JMS on BEA WebLogic 8.1 [1] 
EcpisConnection conn = new EpcisConnection (

"weblogic.jndi.WLInitialContextFactory", // JNDI initial context factory

"t3://localhost:7001", // JNDI provider URL

"jms/TopicConnectionFactory", // name of the connection factory

"jms/epcisTopic", // name of the topic

"true",

"username", // authentication username

"password"); // authentication password

 

Closing the Connection

Calling the close() method on the connection calls the close() method of the underlying HttpURLConnection or TopicConnection object. It is recommended that the call to the close() method be captured in a finally block.


CODE EXAMPLE 2-4 Closing the Connection 
EpcisConnection conn = null;

try {

        conn = ... //initialize the connection here

} catch (Exception e) {

        e.printStackTrace();

} finally {

        try {

            conn.close();

        } catch (Exception e) {

                e.printStackTrace();

        }

}

Exchanging Data With RFID Information Server

Transfer objects are client-side representations of data that are exchanged between RFID Information Server and the application. The data in a transfer object may be persisted in one or more database tables. The Java class to database object relationships are listed in TABLE 2-1.

Unit, Product, Organization, Container, Sensor, ContainerType, Transaction and Observation are all Transfer objects.

You would typically expect to be able to insert, query, modify and delete these objects from the database. But the Transaction and Observation objects are exceptions to this rule. You use the UpdateRequest object to record an Observation or Transaction. Once an Observation or Transaction is recorded, it cannot be modified. In addition, an Observation cannot be deleted. There is no notion of erasing a past observation. The OBSERVATION_LOG maintains the history of observations.


TABLE 2-1 Java Class to Database Objects Relationships

Package Name

Java Class Name

Database Object

com.sun.autoid.epcis.client

ValueObjectWrapper

 

 

Unit

An entry in the UNIT table. A Unit could be a case, pallet or any other entity being tracked

 

Product

An entry in the PRODUCT table

 

Organization

An entry in the ORGANIZATION table.

 

Sensor

An entry in the SENSOR table

 

Observation

An entry in the OBSERVATION_LOG or CURRENT_OBSERVATION table

 

ContainerType

An entry in the CONTAINER_TYPE table

 

TagAllocation

An entry in the TAG_ALLOCATION table

 

TagAllocationLog

An entry in the TAG_ALLOCATION_LOG table

 

 

 

com.sun.autoid.epcis.business

 

 

Container

A set of rows in the CONTAINMENT table that correspond to a hierarchy of containers.

 

Transaction

A set of rows in the TX_LOG table grouped by TX_ID.

 

 

 

com.sun.autoid.epcis.dao

 

 

 

PrimaryKey

A primary key value and table name


Modifying RFID Information Server Tables

A request class represents a update, delete or query request to the Information Server. All request classes extend the abstract com.sun.autoid.epcis.client.Request class. Instances of a request class are converted to an XML format so that they can be sent over the wire.


TABLE 2-2 Request Classes and Code Examples

Class

Description

Code Examples

UpdateRequest

Provides methods to update the RFID Information Server database tables. Instances of this class process insert and modify operations on Unit, Product, Organization, Container, Sensor and ContainerType transfer objects.

CODE EXAMPLE 2-5

CODE EXAMPLE 2-6

CODE EXAMPLE 2-7

 

 

 

DeleteRequest

Provides methods to delete entries from the RFID Information Server tables. For most tables, the class uses a PrimaryKey object to identify the entry to delete.

CODE EXAMPLE 2-8

CODE EXAMPLE 2-9

CODE EXAMPLE 2-10

 

 

 



CODE EXAMPLE 2-5 Inserting a Unit

EpcisConnection conn = new EpcisConnection(...)

UpdateRequest updateReq = new UpdateRequest(conn);

Unit unit = new Unit();

unit.setEpc("urn:epc:id:gid:2.1.1");

unit.setExpiryDate(Calendar.getInstance());

unit.setProductId("1");

unit.setUnitType("ITEM");

unit.setAttr1("192.168.1.2"); // persists the non-EPC data

UpdateResponse updateResp = updateReq.add(unit);



CODE EXAMPLE 2-6 Inserting a Transaction

ArrayList epcs = new ArrayList();

epcs.add("urn:epc:id:gid:1.402.1");

epcs.add("urn:epc:id:gid:1.301.2");

Transaction trans = new Transaction("PO-909", Calendar.getInstance(), null, epcs);

updateResp = updateReq.createTransaction(trans);



CODE EXAMPLE 2-7 Inserting Observations

DeltaEvent deltaEvent = ...

Sensor sensor = EventUtil.toSensor(deltaEvent);

UpdateResponse updateResp = updateReq.postPML(sensor);



CODE EXAMPLE 2-8 Deleting a Container

DeleteRequest deleteReq = new DeleteRequest(conn);

PrimaryKey pk =

new PrimaryKey("urn:epc:id:gid:1.402.1", "CONTAINMENT");

ArrayList pkList =new ArrayList();

pkList.add(pk);

DeleteResponse deleteResp =

deleteReq.deleteByPk(pkList); 

 


Note - Containers can be deleted by specifying the parent EPC of the container. The method only deletes the contents of the top most container. If the children of the of the parent EPC are containers then their contents are not deleted.



CODE EXAMPLE 2-9 Deleting a Unit

PrimaryKey pk = new PrimaryKey("urn:epc:id:gid:1.103.1", "UNIT");

ArrayList pkList =new ArrayList();

pkList.add(pk);

DeleteResponse deleteResp = deleteReq.deleteByPk(pkList);



CODE EXAMPLE 2-10 Deleting a Transaction

ArrayList txIdList = new ArrayList();

txIdList.add("PO-909");

DeleteResponse deleteResp = deleteReq.deleteTxById(txIdList);



Note - The TX_LOG table does not have a primary key. The transaction to delete is identified by the TX_ID value.


Querying RFID Information Server Database Tables

Query conditions are expressed as simple attribute comparisons. The comparators - eq, lt and gt - are valid and can be used when comparing the values of fixed attributes. When comparing the value of an extended attribute only the eq operator is valid. If more than one condition is specified, then they are appended using the AND operator. If no conditions are specified then the query returns all the entries in the selected table.

TABLE 2-3 lists the query classes and code examples.


TABLE 2-3 Query Request Classes and Code Examples

Class

Description

Code Example

FindByAttrRequest

Handles queries on a specified table in the RFID Information Server

CODE EXAMPLE 2-11

 

 

CODE EXAMPLE 2-12

 

 

CODE EXAMPLE 2-13

ContainmentRequest

Handles queries on the CONTAINMENT table. A containment query condition can express a parent or child relationship. It can also specify if the search should recursively return all the EPCs in the hierarchy or only the immediate EPCs.

CODE EXAMPLE 2-14

CODE EXAMPLE 2-15

 

 

 



CODE EXAMPLE 2-11 All Transactions in the TX_LOG Table

FindByAttrRequest findReq =

new FindByAttrRequest(conn, "TX_LOG");

FindByAttrResponse findResp = findReq.process();

 



CODE EXAMPLE 2-12 Query for a specific EPC from the OBSERVATION Table 


FindByAttrRequest findReq =

new FindByAttrRequest(conn, "OBSERVATION_LOG");

findReq.addCondition

("OBSERVATION_VALUE", "urn:epc:id:gid:1.402.1", "eq");

findResp = findReq.process();

 


CODE EXAMPLE 2-13 Conditional Query From the UNIT Table

FindByAttrRequest findReq =

new FindByAttrRequest(conn, "UNIT");

findReq.addCondition

("EXPIRY_DATE", Calendar.getInstance(), "gt");

findReq.addCondition("PRODUCT_ID", new Integer(1), "eq");

findResp = findReq.process(); 

 


CODE EXAMPLE 2-14 Querying for the Parent of an EPC Recursively 
ContainmentResponse contReq = new ContainmentRequest(conn);

ContainmentResponse contResp = contReq.process("urn:epc:id:gid:1.103.1", ContainmentRequest.PARENT_OF,

true);


CODE EXAMPLE 2-15 Querying for the Immediate Child EPCs of a Given EPC 
ContainmentResponse  contResp = contReq.process("urn:epc:id:gid:1.402.1", ContainmentRequest.CHILD_OF,

false);

Processing RFID Information Server Responses

A response message from the Information Server is marshalled into a response object. All response classes extend com.sun.autoid.epcis.client.Response. TABLE 2-4 lists the response classes with examples.


TABLE 2-4 Response Classes and Code Examples

Class

Description

Code Example

Update Response

Represents the status of the update request. Failure status is captured as a string. The status reported by a JDBC driver is returned verbatim

CODE EXAMPLE 2-16

DeleteResponse

Represents the status of a delete request. Failure status is captured as a string.

CODE EXAMPLE 2-17

FindByAttrResponse

Collects all the transfer objects that are returned as a result of a FindByAttrRequest. The transfer objects are generally returned as ArrayLists. The ArrayList may contain zero or more elements.

CODE EXAMPLE 2-18

and

CODE EXAMPLE 2-19

 

 

 

ContainmentResponse

This class can return the result as an ArrayList of EPCs or as a Container object. The former is useful if quick traversal of the result set is needed while the latter preserves the hierarchical relationships between the EPSs.

CODE EXAMPLE 2-20 and CODE EXAMPLE 2-21

 

 

 



CODE EXAMPLE 2-16 Testing the Success of an Update Request 
UpdateResponse updateResp = updateReq.modify(unit);

System.out.println("ModifyUnit. Success -> " + updateResp.success() + ". Should be true");


CODE EXAMPLE 2-17 Testing the Success of a Delete Request 
DeleteResponse deleteResp = deleteReq.deleteByPk(pkList);

System.out.println("Success -> " +  deleteResp.success());


CODE EXAMPLE 2-18 Print the Number of Transaction Objects Returned 
FindByAttrResponse findResp = findReq.process();

System.out.println("Results -> Got " + findResp.getTransactions().size() );


CODE EXAMPLE 2-19 Print the Attribute Value of the Returned UNIT Object 


FindByAttrRequest  findReq = new FindByAttrRequest(conn, "UNIT");

findReq.addCondition("EPC", "urn:epc:id:gid:1.103.1", "eq");

findResp = findReq.process();

System.out.println("Results -> Got " + findResp.getUnits().size() );

if (findResp.getUnits().size() > 0)

{

    Unit unit = (Unit)findResp.getUnits().get(0);

    System.out.println("Got unit with manufacture date : " + unit.getManufactureDate());

}


CODE EXAMPLE 2-20 Using getResultSet() 
ContainmentResponse contResp = contReq.process("urn:epc:id:gid:1.103.1",                                                            ContainmentRequest.PARENT_OF,                                                            true);

System.out.println("Results -> Got " + contResp.getResultSet().size() );


CODE EXAMPLE 2-21 Using getRoot() 
ContainmentResponse contResp = contReq.process("urn:epc:id:gid:1.103.1",                                                            ContainmentRequest.PARENT_OF,                                                            true);

System.out.println("Results -> Got " + contResp.getRoot().getEpc() );

Handling Exceptions

Use the classes of the package, com.sun.autoid.epcis.EPCISException

1 (TableFootnote) If the initial-context-factory is not specified, the default is com.sun.jndi.fscontext.RefFSContextFactory.


  RFID Software Developer's Guide 819-1698-10 Table Of ContentsPrevious ChapterNext ChapterNoIndex


Copyright © 2004, Sun Microsystems, Inc. All Rights Reserved.