sun java system rfid software 3 -...

Sun Java System RFID Software 3.0 Adapter Development Guide

February 2006

Java RFID RFID System

Date — June, 2004

Copyright 2006 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. All rights reserved.

Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more U.S. patents or pending patent applications in the U.S. and in other countries.

U.S. Government Rights – Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements.

This distribution may include materials developed by third parties.

Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd.

Sun, Sun Microsystems, the Sun logo, the Solaris logo, the Java Coffee Cup logo, docs.sun.com, Java, Solaris, Jini, J2EE, J2SE, JDBC, EJB, Sun ONE studio, and JMX are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc.

The OPEN LOOK and Sun™ Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun’s licensees who implement OPEN LOOK GUIs and otherwise comply with Sun’s written license agreements.

Products covered by and information contained in this publication are controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical or biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited.

DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

Copyright 2006 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. Tous droits réservés.

Sun Microsystems, Inc. détient les droits de propriété intellectuelle relatifs à la technologie incorporée dans le produit qui est décrit dans ce document. En particulier, et ce sans limitation, ces droits de propriété intellectuelle peuvent inclure un ou plusieurs brevets américains ou des applications de brevet en attente aux Etats-Unis et dans d’autres pays.

Cette distribution peut comprendre des composants développés par des tierces personnes.

Certaines composants de ce produit peuvent être dérivées du logiciel Berkeley BSD, licenciés par l’Université de Californie. UNIX est une arque déposée aux Etats-Unis et dans d’autres pays; elle est licenciée exclusivement par X/Open Company, Ltd.

Sun, Sun Microsystems, le logo Sun, le logo Solaris, le logo Java Coffee Cup, docs.sun.com, Java, Solaris, Jini, J2EE, J2SE, JDBC, EJB, Sun ONE studio, et JMX sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux Etats-Unis et dans d’autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d’autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc.

L’interface d’utilisation graphique OPEN LOOK et Sun™ a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît les efforts de pionniers de Xerox pour la recherche et le développement du concept des interfaces d’utilisation visuelle ou graphique pour l’industrie de l’informatique. Sun détient une licence non exclusive de Xerox sur l’interface d’utilisation graphique Xerox, cette licence couvrant également les licenciés de Sun qui mettent en place l’interface d’utilisation graphique OPEN LOOK et qui, en outre, se conforment aux licences écrites de Sun.

- 2-

Sun Java System RFID Software 3.0 Adapter Development Guide — February 2006

Les produits qui font l’objet de cette publication et les informations qu’il contient sont régis par la legislation américaine en matière de contrôle des exportations et peuvent être soumis au droit d’autres pays dans le domaine des exportations et importations. Les utilisations finales, ou utilisateurs finaux, pour des armes nucléaires, des missiles, des armes chimiques ou biologiques ou pour le nucléaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou réexportations vers des pays sous embargo des Etats-Unis, ou vers des entités figurant sur les listes d’exclusion d’exportation américaines, y compris, mais de manière non exclusive, la liste de personnes qui font objet d’un ordre de ne pas participer, d’une façon directe ou indirecte, aux exportations des produits ou des services qui sont régis par la legislation américaine en matière de contrôle des exportations et la liste de ressortissants spécifiquement designés, sont rigoureusement interdites.

LA DOCUMENTATION EST FOURNIE "EN L’ETAT" ET TOUTES AUTRES CONDITIONS, DECLARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L’APTITUDE A UNE UTILISATION PARTICULIERE OU A L’ABSENCE DE CONTREFACON.

- 3-


Table of ContentsTable of Contents.......................................................................................4Introduction 1............................................................................................5Theory of Operation 2...............................................................................6

Adapter in RFID Software Event Manager...........................................6Reader Adapter Framework...................................................................7State Controller....................................................................................10

Installation Procedure 3...........................................................................13Building Adapters 4..................................................................................14

Create Adapter Source Code with NetBeans IDE................................14Compile and build Adapter within IDE...............................................15Create Adapter Source Code without IDE...........................................15Edit Adapter Source Code...................................................................16Compile Adapter Source Code............................................................18Test Adapter Source Code...................................................................18

Integrating the JAR File into the RFID Event Manager 5.......................19Useful Links and References 6................................................................21

Sun Java System RFID Software 3.0...................................................21NetBeans IDE 4.1................................................................................21Junit 3.8.1............................................................................................21EPCglobal............................................................................................21

Appendix I Sample Adapter....................................................................22Source Code List..................................................................................22How-to Use it.......................................................................................22

- 4-


Introduction 1Sun Java System RFID Software 3.0 Adapter Development Guide is aimed at simplifying the process of building adapters for various RFID readers, printers or other devices to work with Sun Java System RFID Software 3.0. It gives customers an adapter development environment as part of Sun's RFID solution. During the development, a set of abstract Java methods must be implemented by the reader adapter in order to interface correctly to the Event Manager of Sun's RFID software. The reader adapter implements these methods by populating them with the protocol specific code required for communication with the RFID reader.

This toolkit includes adapter coding templates, ant building xml files and Junit testing templates. The toolkit is delivered in two methods. One method is in Netbeans 4.1 module, another method is zipped ant scripts. In the first method, after installing the RfidToolkit NetBeans module, with a few button clicks , users can generate the source code to develop a new reader's adapter. In the second method, users can use ant script provided in the package to generate the source code without any Integrated Development Environment (IDE). In either way, users need to modify several reader communication interface, then ready for compiling using the build.xml file. Before deploying the new adapter to Sun's RFID software, users can edit the testing code provided by this toolkit to test the adapter's basic functionality without touching RFID software environment settings and configuration files. The toolkit also simplifies the adapter deployment process by providing “ant deploy” task.

This document will first briefly introduce what a reader adapter does and does not do, which functionality the underneath reader adapter framework features and which states an adapter may go through. Then it will describe the toolkit installation procedures, how to use the templates to develop an adapter for a reader, how to write and perform Junit tests for the new adapter and how to deploy the new adapter to Sun Java System RFID Software 3.0. At last, some useful links and readings are also recommended to make development easy. Finally, Appendix I lists the sample code of the adapter for the PMLReader emulator which is part of Sun Java System RFID Software 3.0. Aside of this document, a set of JavaDoc is provided for the adapter development specifically.

Users should install Sun Java System RFID Software 3.0 and read its installation , administration guide and EPCglobal tag specification before developing adapters.

- 5-


Theory of Operation 2

Adapter in RFID Software Event ManagerThe Sun Java System RFID Event Manager consists of a collection of services, named Business Processing Semantics, or BPS. Each of these services may contain one or more components linked in a chain to process events. Typically, an adapter component is at the beginning of this chain to obtain EPC data from readers/printers or send command to those devices, filters in the middle to filter out noise or do other filtering actions, while connectors (also called loggers) are at the end to collect data for the backend processes, such as to send to the Sun Java System RFID Information Server.

Each component is required to register itself with the Sun Java System RFID Event Manager Framework upon initialization. The registration process consists of reading configuration parameters, creation of counters, time monitors, management hooks, and the installation of the component into the appropriate chain. Once registered, the Reader Adapter connects to the RFID reader and begins gathering RFID events.

A reader adapter is built on top of the Reader Adapter Framework. Its main classes include ReaderAdapter main class, ReaderIO class and StateController

- 6-


class. There is also a ReaderMBean interface which extends framework's Mbean interface to make the adapter as SNMP managed object. In the general cases, users may leave it empty unless there are extra functions that need to be managed through SNMP.

Reader Adapter FrameworkThe Reader Adapter Framework provides a layer of abstraction across various readers/printers to reduce repetitive work. For example, Connection management is implemented at the Abstract Reader Adapter layer common to all readers. The specific Reader Adapter implements the actual connection protocol to the device, but the framework implements the connection establishment, timeout detection, message retransmission, and connection resetting. The specific Reader Adapter does not need to worry about reestablishing connections or retransmitting requests. When the specific Reader Adapter detects a connection error, it propagates a ConnectionResetException or a TimeoutException, and the Reader Adapter Framework handles the reestablishment of the connection.

The Reader Adapter need not implement the Event Manager event processing mechanisms. The Reader Adapter simply needs to provide a collection of EPC Events to the Reader Adapter Framework. The Framework also handles the error reporting and logging, as well as updating the status of the Reader Adapter. Data counters and time monitors are also updated by the Reader Adapter Framework every time the individual adapter returns data from the RFID Reader.

The components of adapter framework are AbstractReaderAdapter, AbstractReaderIO and AbstractStateController. The AbstractReaderAdapter registers the hardware specific reader adapter into Event Manger, connect the adapter with other Event Manager services and propagate connection results back to Event Manager services. The hardware specific reader adapter just needs to implement hardware specific configuration/registration functions.

- 7-


The following configuration properties common to all adapters are configured in the common adapter framework creation mechanism:

• LogLevel

Specifies the detail level of the information recorded in the log files

• Location

Specifies the physical location of the reader

• ScanDuration

Specifies the amount of time the antennae should be pulsed searching for data

• CommunicationTimeout

Specifies the amount of time to wait for replies from the reader after the adapter sends a requested

• Reader EPC Identifier and Antenna EPC Identifier

Specifies the EPC value associated with the reader and its antennae, for example: urn:epc:tag:gid-96:1.1.1.

• GatherUserData

Enables or disables the automatic gathering of User Data during the transponder (physical tag) inventory operation. If set to true all queries for identity of the transponder will also result in the gathering of the user Data Memory Bank contents

AbstractReaderIO class implements the I/O functions to communicate with a device, such as open a TCP/IP socket, send bytes or strings to the socket, read from the socket. It defines a set of abstract methods to be implemented by all the devices. The section on “Edit Adapter Source Code” gives more details on these methods. The hardware specific reader I/O functions should be implemented on top of this abstract class.

- 8-


The common configuration properties shared by all the readers are

• Hostname

Specifies the name or address of the reader

• Port

Specifies the port number where the reader listens for communication

The AbstractStateController class implements most of the state control logic using a State Machine with a predefined set of common states that can be reused by the individual Reader Adapters. The State Machine runs an asynchronous thread that executes the state transitions and listens for commands from other software modules. The State Controller consists of the State Machine, a set of states, and the conditions that trigger a state transition. The individual Reader Adapter specifies the set of states that will be used when it instantiates the State Controller. A default State Controller (with predefined states and state transitions is provided) and expected to be used by most Reader Adapters.

This abstract class provides the setAutoReader method to configure the autoRead property common to all the reader adapters.

- 9-


• Autoread

Specifies whether the reader adapter should be set into a mode where continuously listens for data from the reader and posts it to its Event Listeners

State ControllerProvided by RFID Software, the following generic states are defined:

• Connect

Implements the generic connection management and retry mechanism, as well as sets the connection status of the device.

• Initialize

Invokes the reader adapter specific implementation to notify the RFID reader that the Event Manager will begin communicating with it. It also invokes the reader adapter specific implementation to obtain the RFID Reader firmware information.

• AutoReadSetup

Discovers if the RFID reader supports Automode, if not it transitions to ContinuousRead State to setup the local implementation.

• ContinuousRead

It queues a getTagList command and processes it. As soon as the command is completed, a new one will be scheduled when this state is invoked again.

• Wait

Waits for a predefined amount of time, usually invoked after network connectivity problems to allow for recovery time.

• CommandListener

Blocks until a command is ready to be executed.

• CommandExecution

Executes the command queued.

• TagListener

Blocks until data is available from the RFID reader and processes it. If a command is received in the meantime, aborts listening for data from the reader and switches to the next state, otherwise loops and listens again.

• Terminate

Disconnect, and cleanup the session with the RFID reader. Notify reader that the Event Manager is done communicating with it.

The State Controller provides the ability to the individual Reader Adapter to define new states, and new state transitions. The following diagram depicts the states and the state transitions that compose the default State Controller:

- 10-


- 11-


Default State Controller

- 12-


Installation Procedure 3A NetBeans plug-in is provided to enable developers to create adapters within the rich NetBeans Integrated Development Environment (IDE). The com-sun-autoid-toolkit.nbm plug-in has been tested on NetBeans 4.1 IDE which can be downloaded from http://netbeans.org and the Junit distribution included in NetBeans 4.1. You an also download Junit from http://junit.org . A reference to related documents/tutorials/books can be found in Chapter 6. To install the plugin-in module, launch NetBeans and proceed as follows:

1. Choose Tools -> Update Center from the main window.

On the first page of the wizard, select the “Install Manually Downloaded Module” button and click Next.

2. On the “Select Modules to Install” page, click Add.

In the file chooser, navigate to the module com-sun-autoid-toolkit.nbm Select the file and click OK.

3. The modules should appear in the Include in Install panel, shown on the next page. If the module is not shown, this indicates that the same version of the module has previously been installed.

4. Click through the rest of wizard to finish installation.

Refer to the Sun Java System RFID Software Developers Guide for detailed instructions on how to install the com-sun-autoid-toolkit.nbm NetBeans module.

- 13-


http://junit.org/

http://netbeans.org/

Building Adapters 4

Create Adapter Source Code with NetBeans IDEOnce the RFID Software Toolkit has been properly installed in NetBeans 4.1, the user can create an adapter from templates. In NetBeans 4.1,

1. Create a New Project:

1. Choose File -> New from the main menu

2. Select the RfidToolkit Category

3. Select RfidAdapter Project

- 14-


4. Click Next

2. Enter a name for the Project, the Project Location, a name for the Java package to be created and the name of the Reader.

3. The example in the above screen shot will create the Java source for “MyReader”, in the package: com.mycompany.adapter.

Compile and build Adapter within IDERefer to Chapter 2 of the Sun Java System RFID Software Developer's Guide for instructions on how to setup the NetBeans environment, and build projects within NetBeans.

Create Adapter Source Code without IDEYou can build adapters without the NetBeans IDE by using the environment included in the adapterPkg directory.

1. Modify parameters in file build.properties

• work.dir – the working directory for developing the adapter.

• package.path – the source code will be generated under work.dir/src/package.path

• package.name – for example, com.mycomany.adapter

• reader.name – for example, Reader123

- 15-


2. Build the source by executing Ant.

> ant

The working environment is now setup at work.dir.

Edit Adapter Source CodeMainly, two files generated from templates need to be modified: MyReaderReaderIO.java and MyReaderAdapterTest.java. The first java file is the reader communicate interface and the latter one is to test MyReader adapter's basic functions. Simply search for “TODO” keyword in the code, and follow the instruction.

Basically, in MyReaderReaderIO.java, a set of abstract Java methods must be implemented by the reader adapter in order to interface correctly to the Event Manager of Sun's RFID software through the use of the adapter interface. The Reader Adapter implements these methods by populating them with the protocol specific code required for communication with the RFID Reader. The following are the set of methods the reader adapter must implement, the sample adapter source code gives some examples on how to use them and AbstractReaderIO's JavaDoc listed all the useful methods:

• tellReader

Performs the actual exchange of bytes with the reader. It call send method to send commands in either byte or string format to the socket connection to the reader. If response needed, users can call getLine or readDataByte method to read the reader's response.

• initialize

Performs the reader specific initialization sequence. It usually obtains "hostname" and "port" by calling properties.getProperty(). Then calls tellReader() to send the hardware specific initial commands to the reader.

• isAutoModeSupported

Returns true if AutoMode is supported by this reader

• setAutoModeOn

Sets the reader into Automatic mode, where the reader constantly generates taglist results and communicates them back to the adapter.

• setAutoModeOff

Turns off automatic mode.

• getTagList

Provides the list of RFID tags discovered by the RFID Reader while in interactive mode. It first sends a command to reader using tellReader method to request for data, then wait for data. The data is assembled to a LinkedList of IdentifierListEvent object. Please see JavaDoc for the reference.

• listenForTags

Provides the list of RFID tags discovered by the RFID Reader while interactive mode is not enabled. For the reader which needs to receive read command to send data to host, the body of this method should call getTagList method. For the readers which is capable to send data to host

- 16-


automatically, this method can be implemented to read data from socket using either getLine or readDataByte method. In the later case, this method can be used by getTagList when waiting for data from reader.

• writeIdentifier

Programs the EPC number into the tag

• readUserData

Reads the contents of the user data memory bank from the transponder identified.

• writeUserData

Writes the specified data into the User Data memory bank of the transponder identified by identifier.

• getUserDataSize

The Transponder's User Memory is divided in blocks, each block containing a number of bytes. This method returns the total number of bytes in the User Memory Area, equivalent to blockCount * blockSize.

• getTagProtocol

Obtains the Protocol of the transponder identified by identifier.

• getTagType

Obtains the type of transponder identified by identifier.

• lockEpc

Locks the EPC/ Identifier area of the transponder when this is read/write.

• lockUserData

Locks the User Memory area of the transponder.

• killTag

Permanently kills the transponder.

• getFirmwareVersion

Provides the version of the firmware running on the service.

• getSupportedProtocols

Provides a list of protocols supported by the reader.

• Terminate

Signals the reader to terminate its processing. Donot close connection here, this is handled by the framework.

• getAntennaPower

Obtains the power level of the antenna.

• getAntennaStatus

Provides the operating state of the antenna specified.

• setAntennaPower

Sets the antenna power attenuation level.

- 17-


• changeIndicators

Turns on or off Indicators attached to the reader.

The file MyReaderAdapterTest.java uses Junit testing framework to provide several tests:

• testAutoRead

Tests automatically reading from the connected reader

• testGetTaglist

Tests to get single RFID from the reader

• testFirmwareVersion

Tests to get firmware version from the reader

• testSupportedProtocols

Tests to get the supported protocols from the reader

• testAdditionalCmds

Users can put additional command testing here.

Actually, it is not necessary to modify above testing methods, except for the last one. Users just need to modify the reader connection properties, such as IP address, port, reader EPC, in MyReaderAdapterTest.java.

Compile Adapter Source CodeTo compile the adapter source code, follow these steps:

1. Make sure that the source code package is put under a directory named “src”, and move build.xml and build.properties file to the same level of “src” directory. For example: the source code is under directory “work.dir/src/com/mycompany/adapter”, then move build files to “work.dir”.

2. Modify build.properties file based on the Sun's RFID Software installation location, and junit.jar location. Also provide test suite name (in this example, it is com.mycompany.adapter.MyReaderSuite) and target jar file name.

3. Compile using command “ant jars”

Test Adapter Source CodeAssume MyReaderAdapterTest.java has been edit, the reader is connected and powered on, the Junit testing for the adapter source code can be done by typing:

> ant test

If it reports “Tests run: 6, Failures: 0, Errors: 0”, the Junit tests are passed.

- 18-


Integrating the JAR File into the RFID Event Manager 5

1. Launch the Sun Java System RFID Configuration Manager

2. Create a new Profile for this adapter in the RFID Configuration Manager and configure its properties by following these steps.

1. From the RFID Configuration Manager menu, choose Components->Device Profiles

2. From the RFID Role and Component Editor menu, choose Profile-> New.

1. Setup the Profile properties with the information of the adapter just created. Ensure that the default Properties needed by the Adapter are entered.

- 19-


2. Click Ok.

The profile for this adapter is now added to the navigation tree in the left pane.

3. Add the JAR file for the new adapter by following these steps:

1. From the RFID Role and Component Editor, choose Plug-in -> Add Implementation Class JAR.

2. Use the file chooser to navigate to the new JAR file, select it and click Ok.

4. Close the RFID Role and Component Editor window.

5. Choose File->Save.

The new Profile for the adapter is now ready to be used when creating new Devices. To test, follow the steps in the Sun Java System RFID Software Administration Guide to configure a new Device using this Profile.

- 20-


Useful Links and References 6

Sun Java System RFID Software 3.0General site: http://www.sun.com/software/solutions/rfid/

Document site: http://docs.sun.com/

NetBeans IDE 4.1Download site: http://www.netbeans.info/downloads/download.php?a=arch&p=1A User Guide: http://www.netbeans.org/kb/using-netbeans

Junit 3.8.1Download site: http://prdownloads.sourceforge.net/junit

A quick Start Guide: http://junit.sourceforge.net/doc/testinfected/testing.htm

A Cook Book: http://junit.sourceforge.net/doc/cookbook/cookbook.htm

EPCglobalSpecification: http://www.epcglobalinc.org/standards_technology/specifications.html

- 21-


http://wwws.sun.com/software/solutions/rfid/

http://www.epcglobalinc.org/standards_technology/specifications.html

http://prdownloads.sourceforge.net/junit

http://www.netbeans.org/kb/using-netbeans/

http://www.netbeans.info/downloads/download.php?a=arch&p=1

http://junit.sourceforge.net/doc/cookbook/cookbook.htm

http://junit.sourceforge.net/doc/testinfected/testing.htm

http://docs.sun.com/

Appendix I Sample Adapter

Source Code ListSampleAdapter.java

– The main Java class for the sample adapter. This adapter works with the PMLReader emulator from Sun Java System RFID Software.

SampleAdapterMBean.java

– An interface extends the ReaderMBean of Sun Java System RFID Software.

SampleStateController.java

– The state controller for the sample adapter.

SampleReaderIO.java

– The primary methods to communicate with the PMLReader emulator.

SampleAdapterTest.java and SampleSuite.java

– Junit testing code

How-to Use itFirst, modify the entries in the file build.properties according your system environment.

To compile, type

> ant

To run Junit testing, type

> ant test

Follow the instructions in Chapter 4 to integrate into the Sun Java System RFID Software.

- 22-


sun java system rfid software 3 -...

Documents