# Programming with the ALE and ALEPC APIs

# Sample Java Applications

The following sections describe how to use the sample Java applications provided in your WebLogic RFID Edge Server installation. The sample applications illustrate the use of the Java language binding for the ALE interface. Unlike other parts of WebLogic RFID Edge Server, the sample applications are free for you to use and modify for your own purposes. You can use them as a starting point for developing your own applications.

- Overview of Sample Java Applications
- Setting Up Your Development Environment
- Compiling and Running the Samples
- ImmediateSample: Getting Started Reading Tags
- ImmediateSample: Event Cycles and Reliability
- ImmediateSample: Reading from Different Readers
- SubscribeSample: Exploring Asynchronous Event Cycle Delivery
- ImmediateProgramSample: Writing Tags
- ProgrammingSample: Exploring Programming Cycles and EPC Caches
- JMS Samples
- Workflow Sample XML Files

## Overview of Sample Java Applications

Several samples are provided with WebLogic RFID Edge Server:

- `ImmediateSample` — Shows how to use the XML serializer and deserializer, and the `immediate` method. The sample program reads an `ECSpec` from an XML file, activates it for one event cycle using the `immediate` method, and displays the results in XML to the RFID Edge Server console.
- `SubscribeSample` — Shows how to use the `subscribe` and `unsubscribe` methods, as well as several other administrative methods within the ALE API. The sample provides a simple command-line interface that lets you define `ECSpec` instances from XML files, subscribe a delivery address to a previously defined `ECSpec`, unsubscribe a delivery address, and list existing `ECSpec` instances and subscriptions. As well as illustrating the use of several ALE methods, this sample serves as a useful command-line utility program in its own right.
- `ImmediateProgramSample` — Shows a simple example of how to use the ALEPC API to program an Electronic Product Code (EPC) value into a tag using a specified logical reader. The programming cycle specification is read from an XML file, and the programming cycle reports are printed as XML.
- `ProgrammingSample` — Shows how to use the `ALEPC` methods to manipulate Programming Cycles and EPC Caches.
- `Workflow` — Contains sample XML files that define workflows.

## Setting Up Your Development Environment

To compile and run the sample applications, you need to install both the Java Development Kit (JDKTM) 1.4 or later, and the WebLogic RFID Edge Server software.

For detailed information about system requirements, prerequisite software, and how to install WebLogic RFID Edge Server, see Installing WebLogic RFID Edge Server.

## Compiling and Running the Samples

The instructions for running all samples are the same:

1. From the `RFID_EDGE_HOME/bin` subdirectory of your WebLogic RFID Edge Server installation, run these scripts in the following sequence:

- `RunReaderSim` (if you are using the Reader Simulator)
- `RunEdgeServer` (required)
- `RunAdminConsole` (optional)

These files end with the suffix `.sh` or `.bat`, depending on your platform.

2. Go to the directory for the sample program you want to run (one of the subdirectories within the `samples` subdirectory of your WebLogic RFID Edge Server installation).
3. Run the "build" script (`build.sh` or `build.bat` depending on your platform) from the command line. This script compiles the sample program.
4. Run the "run" script (`run.sh` or `run.bat` depending on your platform) from the command line. This script runs the sample program you just compiled.

Some samples require additional command line arguments to the "run" script:

- `SubscribeSample`, see SubscribeSample: Exploring Asynchronous Event Cycle Delivery. The sample program connects to your Edge Server, carries out its task, and then exits.
- `ImmediateProgramSample`, see ImmediateProgramSample: Writing Tags. You need to provide information about the EPC value you want to write to the tag.
- `ProgrammingSample`, see ProgrammingSample: Exploring Programming Cycles and EPC Caches. This sample shows you how to manipulate programming cycles and EPC caches.

For tutorial walk throughs of the samples, see:

- ImmediateSample: Getting Started Reading Tags
- ImmediateSample: Event Cycles and Reliability
- ImmediateSample: Reading from Different Readers
- SubscribeSample: Exploring Asynchronous Event Cycle Delivery
- ImmediateProgramSample: Writing Tags
- ProgrammingSample: Exploring Programming Cycles and EPC Caches

## ImmediateSample: Getting Started Reading Tags

The `ImmediateSample` program shows how to use the XML serializer and deserializer, and the ALE `immediate` method. The sample program reads an `ECSpec` from an XML file, activates it for one event cycle using the ALE `immediate` method, and displays the results in XML to the console.

In the following description, it is assumed that you are using the Reader Simulator provided with WebLogic RFID Edge Server. However, if you have an actual reader and tags, you can use them.

The sample program reads an `ECSpec` from the file `ECSpec.xml`, which is shown in the following example, without the comments that are in the real file. After you become familiar with the sample program, you are encouraged to experiment by changing this file to see what happens.

    <?xml version="1.0" encoding="UTF-8"?>
    <ale:ECSpec xmlns:ale="urn:epcglobal:ale:xsd:1"
        xmlns:aleext="http://schemas.connecterra.com/EPCglobal-extensions/ale"
        creationDate="2004-11-15T16:18:43.500Z"
        schemaVersion="1.0"
        includeSpecInReports="false" >

        <logicalReaders>
            <logicalReader>ConnecTerra1</logicalReader>
        </logicalReaders>

        <boundarySpec>
          <aleext:durationReadCycles>1</aleext:durationReadCycles>
        </boundarySpec>

        <reportSpecs>
          <reportSpec reportName="ImmediateSample Report">
            <reportSet set="CURRENT" />
          </reportSpec>
        </reportSpecs>

        <aleext:applicationData>Application specific data can go here
        </aleext:applicationData>
    </ale:ECSpec>

The logical reader is specified as `ConnecTerra1`, which is mapped to "Antenna 1" in the Reader Simulator by default. (If you installed your own reader, modify the `ECSpec` to refer to one of your logical readers.) The event cycle is exactly one read cycle — this is far smaller than you are likely to use in any real situation, but it will illustrate how the ALE interface works. The final section defines a report specification, which will return both a count and a list of all the `CURRENT` tags visible to logical reader `ConnecTerra1`.

Now, run the sample following the instructions in Compiling and Running the Samples. You should see output similar to the following:

    Immediate Sample, XML-based
    sending request to Edge Server...
       ...received response.

    Received the following ECReports:

    <ale:ECReports ALEID="EdgeServerID" creationDate="2005-01-06T17:01:09.093Z" date="2005-01-06T17:01:09.093Z" schemaURL="http://schemas.connecterra.com/EPCglobal/ale-1_0.xsd" schemaVersion="1" specName="$immediate=10" terminationCondition="DURATION" totalMilliseconds="234" xmlns:ale="urn:epcglobal:ale:xsd:1" xmlns:aleext="http://schemas.connecterra.com/EPCglobal-extensions/ale">

     <reports>
      <report reportName="ImmediateSample Report">
       <group>
        <groupList>
         <member>
          <tag>urn:epc:tag:gid-64-i:10.50.5</tag>
         </member>
         <member>
          <tag>urn:epc:tag:gid-64-i:10.40.4</tag>
         </member>
         <member>
          <tag>urn:epc:tag:gid-64-i:10.10.1</tag>
         </member>
         <member>
          <tag>urn:epc:tag:gid-64-i:10.30.3</tag>
         </member>
         <member>
          <tag>urn:epc:tag:gid-64-i:10.70.7</tag>
         </member>
         <member>
          <tag>urn:epc:tag:gid-64-i:10.20.2</tag>
         </member>
         <member>
          <tag>urn:epc:tag:gid-64-i:10.60.6</tag>
         </member>
        </groupList>
        <groupCount>
         <count>7</count>
        </groupCount>
       </group>
      </report>
     </reports>
     <aleext:applicationData>application-specific data here
     </aleext:applicationData>
     <aleext:failedLogicalReaders/>
     <aleext:physicalReaders>
      <aleext:physicalReader>SimReadr</aleext:physicalReader>
     </aleext:physicalReaders>
     <aleext:totalReadCycles>1</aleext:totalReadCycles>
    </ale:ECReports>Press any key to continue . . .

The number of `epc` elements in the list report should be equal to the number of tags you have checked under "Antenna 1" in the Reader Simulator. (If you are using a real reader, you might not see all the tags you have placed near your antenna.)

### Using ImmediateSample with the Administration Console

If you are running the Administration Console, you might want to run `ImmediateSample` again, as follows:

1. Set up your desktop so you can see both the Administration Console and the `ImmediateSample` console window at the same time.
2. In the Administration Console, click SimReadr in the device browser on the left, then click the Telemetry tab in the right pane.

Keep your eye on the `uhfAntenna1.readCycles` display; `uhfAntenna1` corresponds to the logical reader `ConnecTerra1` that was specified in the sample `ECSpec.xml`. Looking at this display shows you when the `ImmediateSample` program activates the antenna for one event cycle, using the ALE `immediate` method

3. Run the sample using the instructions in Compiling and Running the Samples.

You see that `uhfAntenna1` (logical reader `ConnecTerra1`) is activated for exactly one read cycle — which is exactly what was specified for a `boundarySpec` in `ECSpec.xml`:

    <boundarySpec>
            <durationReadCycles>1</durationReadCycles>
    </boundarySpec>

## ImmediateSample: Event Cycles and Reliability

The ImmediateSample application illustrates several aspects of event cycles and how they can be used to address situations where not every tag can be read in a single read cycle. This is a very common situation, and can arise either because of the inherently unreliable nature of RFID tags, or because the business situation simply implies that not all tags for an application level event are in front of the antenna at the same time (for example, because a large pallet is moving slowly past an antenna).

To simulate this situation, this example uses the "reliability" field provided as part of the Reader Simulator. Change the Reliability field in the Reader Simulator to 50%. This tells the Reader Simulator to report each selected tag with only 50% probability in any given read cycle. Now run ImmediateSample as you did in ImmediateSample: Getting Started Reading Tags. In all likelihood, you will see fewer tags in the report than you did previously.

In the following procedure, you see how the event cycle combines tags from multiple read cycles into a single report, and how this counteracts the limitations of dealing with read cycles individually.

1. Open the file `ECSpec.xml` in a text editor.
2. Change the line that reads:

    <aleext:durationReadCycles>1</aleext:durationReadCycles>

so that it reads:

    <aleext:durationReadCycles>3</aleext:durationReadCycles>

3. Save the file.
4. Leave the reliability on the Reader Simulator set to 50%.
5. Run the sample again. This time you should see most, if not all, of the tags.

It is usually difficult to guess how many read cycles are required to read all tags of interest. In some cases, external events dictate which read cycles should be grouped into an event cycle — the `startTrigger` and `stopTrigger` features of the ALE interface (see ECBoundarySpec) can be used for this purpose. In other cases, you want an event cycle to continue as long as needed until all tags have been read. In such cases, you can use the `stableSetInterval` feature of the ALE interface.

## ImmediateSample: Reading from Different Readers

The ALE interface makes it very easy to select different readers without altering application code, even changing the number of readers. To illustrate, follow these steps:

1. Open the file `ECSpec.xml` in a text editor.
2. Immediately after the line that reads:

    <logicalReaderName>ConnecTerra1</logicalReaderName>

add a second line so that together they look like this:

    <logicalReaderName>ConnecTerra1</logicalReaderName>
    <logicalReaderName>ConnecTerra2</logicalReaderName>

3. Save the file.
4. Run `ImmediateSample` again. In the report, you will see tags read from both readers.

## SubscribeSample: Exploring Asynchronous Event Cycle Delivery

The `SubscribeSample` program shows how to use the ALE `subscribe` and `unsubscribe` methods, as well as several other administrative methods within the ALE API. The sample provides a simple command line interface that lets you define ECSpec instances from XML files; subscribe a delivery address to a previously defined `ECSpec`; unsubscribe a delivery address; and list existing `ECSpec` instances and subscriptions. As well as illustrating the use of several ALE methods, this sample serves as a useful command line utility program in its own right.

The `SubscribeSample` works with XML files to define event cycle specifications, as does the `ImmediateSample`. However, `SubscribeSample` differs from `ImmediateSample` in several respects:

- Any number of event cycle specifications can be defined, each with their own name. You invoke the `SubscribeSample` program with the `define` command for each event cycle you want to define.
- To obtain event cycle reports, you add one or more subscribers for the event cycle(s) you have defined, by invoking the `SubscribeSample` program with the `subscribe` command.
- Once you define event cycle(s) and add one or more subscriptions, the Edge Server executes event cycles and sends reports to the subscribers. This takes place asynchronously, even when the `SubscribeSample` program is not running.

Here are step-by-step instructions for working with the SubscribeSample program.

1. From the `./bin` subdirectory of your WebLogic RFID Edge Server installation, run the following scripts in this order:

`RunReaderSim` (if you are using the Reader Simulator)

`RunEdgeServer` (required)

`RunAdminConsole` (optional, but strongly suggested for this tutorial)

These files end with the suffix `.sh` or `.bat`, depending on your platform.

2. Find the console window for the Edge Server and leave it open on your desktop. Later you will be looking at console subscriber output sent to this window.
3. Go to the `SubscribeSample` directory:

    ./samples/SubscribeSample

4. In a shell, type:

    ./run.sh define mycmdlinespec ECSpec.xml

(On Windows, type `run.bat` instead of `run.sh`. Do this replacement for the rest of the examples in this section.)

You will see some output messages from the `SubscribeSample` program indicating that an event cycle specification has been defined. At this point, the `ECSpec` is defined but is not active, because there are no subscribers.

Note: | You can define as many different `ECSpec` instances as you want, as long as you give them distinct names. The name `mycmdlinespec` is used here.

5. If you are running the Administration Console, set up your desktop so you can see both the Administration Console and the `SubscribeSample` shell at same time.

In the Administration Console, click ECSpecs in the device browser. Note that the `ECSpec` you just defined, `mycmdlinespec`, is listed in the right pane.

Note: | Defining an `ECSpec` is not the same as activating it. You have not yet told a reader to read any tags, or done anything else with the `ECSpec` yet. You have simply defined a set of actions (read cycles, delivery activities, and so on) that can take place some time in the future, after the `ECSpec` is activated by a method such as `immediate`, `poll`, or, in this example, `subscribe`.

6. To prove that defining and activating an ECSpec are different, display the telemetry tab for the Reader Simulator, and then define a second `ECSpec` in the `SubscribeSample` shell:

    ./run.sh define myspec2 ECSpec.xml

Keep your eye on the `uhfAntenna1.readCycles` telemetry trace. You will not see any read cycles take place. (This `uhfAntenna1.readCycles` trace corresponds to the logical reader that `ECSpec.xml` is referencing.)

7. To demonstrate some other features of `SubscribeSample`, return to the `SubscribeSample` shell and type:

    ./run.sh list-specs

This prints a list of the names of the `ECSpec` instances that are currently defined in the Edge Server. You should see `mycmdlinespec` and any other event cycle specifications you have defined.

8. In the shell, type:

    ./run.sh subscribe mycmdlinespec console:test

Look in the Edge Server window — the Edge Server is now printing event cycle reports to the console.

Also, take a look at the Administration Console telemetry display:

As you can see, the `subscribe` method that you invoked when you ran `SubscribeSample` this last time has activated the Reader Simulator, and it is now performing read cycles as specified in the `ECSpec` called `mycmdlinespec`.

9. To experiment with a different kind of event delivery driver, first create a new directory in a file system that is accessible to the Edge Server. For example:

    mkdir /tmp/ale

On the Windows platform, the equivalent command would be, for example:

    mkdir c:\temp\ale

10. In the shell, type:

    ./run.sh subscribe mycmdlinespec file:///tmp/ale

or on the Windows platform, type:

    .\run.bat subscribe mycmdlinespec file:///c:/temp/ale

11. Use a file system tool to examine the contents of the `/tmp/ale` (or `c:\temp\ale`) directory. You will see that the Edge Server is creating XML files, each containing a single event cycle report. Alternately, if the subscription URI were to refer to a file (as opposed to a directory), then the successive event cycle reports would be appended to that file.
12. In the shell, type:

    ./run.sh list-subs mycmdlinespec

This prints a list of the URIs that have been subscribed to the `ECSpec` named `mycmdlinespec`.

13. In the shell, type:

    ./run.sh unsubscribe mycmdlinespec console:test

Look in the Edge Server window — the Edge Server is no longer printing event cycle reports to its console. But look in the temporary directory you created earlier — the Edge Server is still writing XML report files into this directory, because the other subscription is still active.

### SubscribeSample Command Line Options

For information about `SubscribeSample's` command line options, you can navigate to the `SubscribeSample` directory and type `run`. This displays the command help shown below. Note that the help distinguishes EPCglobal functions from WebLogic RFID Edge Server extensions (which are listed as RFTagAware extensions in this release).

    Usage:

    EPCglobal ALE 1.0 commands

    	define <specName> <ecSpecFilename>
    or   undefine <specName>
    or   getECSpec <specName>
    or   getECSpecNames
    or   subscribe <specName> <notificationURI>
    or   unsubscribe <specName> <notificationURI>
    or   getSubscribers <specName>
    or   poll <specName>
    or   immediate <ecSpecFilename>
    or   getStandardVersion
    or   getVendorVersion

    RFTagAware extensions:
    get-spec-info <specName>
    or   redefine <specName> <ecSpecFilename>
    or   suspend <specName>
    or   unsuspend <specName>
    or   stop <specName>

## ImmediateProgramSample: Writing Tags

This sample shows how to use the ALE API to program an Electronic Product Code (EPC) value into a tag by using a specified logical reader. The programming cycle specification is read from an XML file, and the programming cycle reports are printed as XML. You can run this sample with the simulator, or with any of the printers or readers for which WebLogic RFID Edge Server supports tag writing. See the supported RFID readers section of the RFID Reader Reference manual for this information.

If you plan to run this sample with the simulator, see Using ImmediateProgramSample with the Reader Simulator.

Here are step-by-step instructions for working with the ImmediateProgramSample program.

1. From the RFID_EDGE_HOME/bin directory of your WebLogic RFID Edge Server installation, run the following scripts in this order:

- RunReaderSim (if you are using the simulator)
- RunEdgeServer (required)
- RunAdminConsole (optional)

These files end with the suffix .sh or .bat, depending on your platform.

Important: If you are using the simulator, be sure to read the section Using ImmediateProgramSample with the Reader Simulator.

2. Find the console window for the Edge Server and leave it open on your desktop. Later you will be looking at output that this sample program sends to this window.
3. Go to the WebLogic RFID Edge Server directory:

    ./samples/ImmediateProgramSample

This sample uses the file PCSpec.xml as part of its input. This file defines the programming cycle (see PCSpec). Part of the file is reproduced here — you can take a look at the complete file in the samples directory:

    <?xml version="1.0" encoding="UTF-8"?>
    <PCSpec xmlns="http://schemas.connecterra.com/alepc">
        <applicationData>application specific data can go<        here</applicationData>
        <logicalReaders>
            <logicalReader>ConnecTerra1</logicalReader>
        </logicalReaders>

        <boundarySpec>
            <trials>1</trials>
            <duration>4000</duration>
        </boundarySpec>
    </PCSpec>

4. In a shell, type:

    ./run.sh epcValue

where `epcValue` is the EPC to write to the tag, for example:

     urn:epc:tag:gid-64-i:1.4.10

(On Windows, type `run.bat` instead of `run.sh`. Do this replacement for the rest of the examples in this section.)

5. In the console window, you should see output similar to the following:

    # ./run.sh urn:epc:tag:gid-64-i:1.4.10

    Immediate Program Sample, XML-based
      sending request to Edge Server...
      ...received response.

    Received the following PCWriteReport:
    <PCWriteReport date="2006-03-02T13:45:50.199Z" savantID="EdgeServerID"
     specName="$immediate=2" total Milliseconds="800" totalTrials="0"
     xmlns="http://schemas.connecterra.com/alepc">
     <applicationData>application specific data can go    here</applicationData>
     <wasSuccessful>true</wasSuccessful>
     <status>SUCCESSFUL</status>
     <physicalReaders>
      <physicalReader>SimReadr</physicalReader>
     </physicalReaders>
     <failedLogicalReaders/>
     <cacheSize>0</cacheSize>
     <epc>urn:epc:tag:gid-64-i:1.4.10</epc>
    </PCWriteReport>

The console output includes a `PCWriteReport`, expressed in XML. (See PCWriteReport.) `PCWriteReport` describes the programming cycle's tag writing operation.

First, the `<applicationData>` element displays the information that the originating `PCSpec.xml` included in its `<applicationData>` element.

In this example, the `<wasSuccessful>` element (set to `true`) indicates that this programming cycle was successful. The `<status>` element is correspondingly set to `SUCCESSFUL`.

If the programming cycle had encountered problems, the `<status>` element would have provided diagnostic information about the termination status of programming cycle (for example: `CACHE_EMPTY` or `READER_ERROR`; for the complete list of status codes, see PCStatus.)

Note: | If you are using the Reader Simulator and see a `MULTIPLE_IN_FIELD` status message, you probably have more that one active tag in the simulator. Make sure that you only have one active tag, and that the value of the tag is the same as the one you specify when invoking run.sh. Refer to Using ImmediateProgramSample with the Reader Simulator for information on configuring the reader simulator for use with this example.

The `<physicalReaders>` element indicates which physical readers were involved in this tag writing operation, in this case just one physical reader, `SimReadr`.

The `<failedLogicalReaders>` element is empty, because no logical readers failed during this programming cycle. The `<cacheSize>` is set to zero — in this simple example, you passed in an EPC value as a parameter to the sample program, the programming cycle used this value, and there are no other values available. In other situations `<cacheSize>` will tell you how many EPC values are left in the EPC cache associated with the originating `PCSpec`. (See EPCCacheSpec.)

The `<epc>` element contains the EPC value that was written to the tag, in this case:

    urn:epc:tag:gid-64-i:1.4.10

### Using ImmediateProgramSample with the Reader Simulator

You can use the Reader Simulator to simulate tag writes with the `ImmediateProgramSample` application. This section contains a short procedure on how to run the sample application using the Reader Simulator, followed by additional information on which tag types are recognized by the simulator:

1. Start the Reader Simulator and go to the Reader Simulator GUI.
2. Turn off (uncheck) all the tags for Antenna 2.
3. Turn off (uncheck) all but one of the tags for Antenna 1 (only one tag can be active in order for the sample program to run successfully).
4. Make the value of the remaining tag the same as the tag you will supply as an argument to `run.sh`, for example: `gid-64-i:1.4.10`.
5. Run the example using the tag defined in the previous step. For example:

    $ ./run.sh urn:epc:tag:gid-64-i:1.4.10

You should see output similar to that shown in ImmediateProgramSample: Writing Tags.

The Reader Simulator provides support for writing the following tag types:

gid-64-i | sgln-64 | sgtin-96 | sgln-96 | usdod-64
sgtin-64 | giai-64 | sscc-96 | giai-96 | usdod-96
sscc-64 | grai-64 | gid-96 | grai-96 |

The Reader Simulator needs access to a valid Company Prefix Index Table to process SGTIN-64 and SSCC-64 tags. This file can be specified in the .`/bin/RunReaderSim` (`.bat` | `.sh`) script as one of the command parameters to the Java invocation:

    -epcIndexTableURL http://onsepc.com/ManagerTranslation.xml

This file must be the same as the value of the `com.connecterra.ale.epcIndexTable` property in the `./etc/edge.props` file. If the two files are different, unpredictable results can occur.

As with a real RFID reader, there must be only one tag to be written in range of the antenna. With the Reader Simulator, you must unselect all but one of the tags checked in the GUI. Otherwise the tag write will fail with a `MULTIPLE_IN_FIELD` error.

GID-64-i tags are outside the EPCglobal Tag Data Standard. For standard tags, there are strict definitions of what are valid data in the various fields of the tag. This is one area where leading zeros are considered important. The following non-normative descriptions are provided for guidance — the document referenced above is definitive.

An SGTIN-64 tag is made up of a Filter field, a Company Prefix, an Item Reference code and a Serial Number. The Company Prefix and the Item Reference together must total 13 decimal digits. So this is a valid tag:

    urn:epc:tag:sgtin-64:1.5413149.000001.1

while this is an invalid tag:

    urn:epc:tag:sgtin-64:1.5413149.1.1

An SSCC-64 tag is made up of a Filter field, a Company Prefix and a Serial Reference. The Company Prefix and the Serial Reference together must total 17 decimal digits. So this is a valid tag:

    urn:epc:tag:sscc-64:1.0353265.0000010000

while this is an invalid tag:

    urn:epc:tag:sscc-64:1.0353265.100000

When using the sample code, any attempt to write a poorly formatted tag might generate a non-specific j`ava.net.URISyntax` exception with the (example) detail:

    non valid uri syntax for epc tag: null: urn:epc:tag:sscc-64:1.0353265.100000

## ProgrammingSample: Exploring Programming Cycles and EPC Caches

The `ProgrammingSample` program shows how to use the ALEPC methods to manipulate Programming Cycles and EPC Caches. The sample provides a simple command line interface that lets you define `PCSpec` instances from XML files, subscribe or unsubscribe a delivery address to a previously defined `PCSpec` to receive `PCWriteReport` instances, and list existing `PCSpec` instances and subscriptions. In addition, you can define `EPCCacheSpec` instances from XML files, subscribe or unsubscribe for `EPCCacheReport` instances, and replenish or deplete defined EPC caches.

As well as illustrating the use of several ALEPC methods, this sample serves as a useful command line utility program in its own right.

Like the `ImmediateProgramSample`, the `ProgrammingSample` works with XML files to define programming cycle specifications. However, `ProgrammingSample` differs from `ImmediateProgramSample` in several respects:

- The `ProgrammingSample` uses EPC caches to obtain EPC values to be programmed to tags. You invoke the `ProgrammingSample` program with the `define-cache` command for each EPC cache you want to define, and use the `replenish` command to load an EPC cache with EPC patterns that define its contents.
- Any number of programming cycle specifications can be defined, each with its own name. You invoke the `ProgrammingSample` program with the `define` command for each programming cycle you want to define.
- To obtain programming cycle write reports, you add one or more subscribers for the programming cycle(s) you have defined, by invoking the `ProgrammingSample` program with the `subscribe` command.
- To obtain cache-low reports, you add one or more subscribers for the EPC cache(s) you have defined, by invoking the `ProgrammingSample` program with the `subscribe-cache` command.
- Once you have defined programming cycle(s), EPC cache(s), and added one or more subscriptions, you invoke the `ProgrammingSample` program with the `poll` command to cause a programming cycle to commence. The `PCSpec` you poll will obtain an EPC value from its associated EPC cache and perform a tag programming operation using that EPC value.

Here are step-by-step instructions for working with the `ProgrammingSample` program.

1. Configure the Edge Server to use the Reader Simulator or any of the printers or readers for which WebLogic RFID Edge Server supports tag writing. See the supported RFID readers section of the RFID Reader Reference for information.

Assign this reader the logical reader name `ConnecTerra1`, which is the logical reader name specified in the `ProgrammingSample's PCSpec.xml` file that we will use later. Alternately, you can pick a different logical reader name, as long as you edit `edge.props` and `PCSpec.xml` to both reflect the logical reader name you chose. If you are using the Reader Simulator, please read the section Using ImmediateProgramSample with the Reader Simulator to understand the constraints of the simulator.

2. From the `./bin` subdirectory of your WebLogic RFID Edge Server installation, run the following scripts in this order:

`RunReaderSim` (if you are using the simulator)

`RunEdgeServer` (required)

`RunAdminConsole` (optional)

These files end with the suffix `.sh` or `.bat`, depending on your platform.

3. Find the console window for the Edge Server and leave it open on your desktop. Later you will be looking at console subscriber output sent to this window.
4. Go to the WebLogic RFID Edge Server directory:

    ./samples/ProgrammingSample

5. In a shell, type:

    ./run.sh define-cache mycache CacheSpec.xml

(On Windows, type `run.bat` instead of `run.sh`. Do this replacement for the rest of the examples in this section.)

You will see an output message from the `ProgrammingSample` indicating that an EPC cache has been defined.

Note: | You can define as many different EPC caches as you want, as long as you give them distinct names. In the command line above, we gave the name `mycache` for the EPC cache we defined; we will shortly be defining a `PCSpec` that refers to this cache.

6. In a shell, type:

    ./run.sh list-caches

This prints a list of the names of the EPC caches that are currently defined in the Edge Server. You should see `mycache` and any other EPC caches you have defined.

7. In a shell, type:

    ./run.sh subscribe-cache mycache console:test

Look at the console window for the Edge Server (not the Administration Console). A low-cache report has been issued to the subscription you just created:

    <!-- test -->
    <EPCCacheReport date="2006-03-16T16:38:01.734Z" savantID="EdgeServerID" xmlns="http://schemas.connecterra.com/alepc">
     <cacheName>mycache</cacheName>
     <applicationData>application specific data can go here
     </applicationData>
     <cacheSize>0</cacheSize>
     <cacheContent/>
     <threshold>10</threshold>
    </EPCCacheReport>

A low-cache report was issued because the cache we defined does not yet have any EPCs, and so is below the low-cache reporting threshold (10) defined in `CacheSpec.xml`. Whenever a cache is below its reporting threshold, it issues low-cache reports to its subscribers. In this case, such a report was issued as soon as a new subscriber was defined.

8. In a shell, type:

    ./run.sh replenish-cache mycache urn:epc:pat:gid-64-i:1.5.[1-15]

This stocks `mycache` with a range of 15 EPC values.

9. In a shell, type:

    ./run.sh cache-info mycache

The ProgrammingSample prints:

    Programming Sample
    info for EPC cache mycache: Received the following EPCCacheSpecInfo:
    <EPCCacheSpecInfo xmlns="http://schemas.connecterra.com/alepc">
     <subscriberCount>1</subscriberCount>
     <pcSpecs/>
     <activationCount>0</activationCount>
     <replenishCount>1</replenishCount>
     <lastReplenished>2006-03-16T16:39:05.097Z</lastReplenished>
     <lastReported>2006-03-16T16:38:01.734Z</lastReported>
     <cacheSize>15</cacheSize>
     <cacheContent>
      <pattern>urn:epc:pat:gid-64-i:1.5.[1-15]</pattern>
     </cacheContent>
    </EPCCacheSpecInfo>

We can see that the EPC cache we defined has one subscriber, no `PCSpec` instances using it (yet), has been replenished once but never activated (used to write tags), and is currently stocked with 15 EPCs from a single range pattern.

10. In a shell, type:

    ./run.sh define myspec PCSpec.xml

You will see an output message from the `ProgrammingSample` indicating that a PCSpec has been defined.

Note: | You can define as many different `PCSpec` instances as you want, as long as you give them distinct names. In the command line above, the name `myspec` is given to the `PCSpec` you defined.

11. In a shell, type:

    ./run.sh cache-info mycache

The ProgrammingSample prints information about `mycache`, similar to what was printed earlier. The important difference is that the empty `<pcSpecs/>` element has been replaced with:

    <pcSpecs>
     <pcSpec>myspec</pcSpec>
    </pcSpecs>

This indicates that the `PCSpec` we just defined is using the `mycache` EPC cache we defined earlier. Whenever `myspec` performs a tag programming operation, it will obtain an EPC value from `mycache`.

12. Place a single writable RFID tag in the field of the RFID reader you configured the Edge Server to use.
13. In a shell, type:

    ./run.sh poll myspec

The ProgrammingSample performs a tag programming operation and, if successful, prints a `PCWriteReport` similar to:

    Programming Sample
    polling myspec...
      ...received response.

    Received the following PCWriteReport:

    <PCWriteReport date="2006-03-16T16:42:15.454Z" savantID="EdgeServerID" specName="myspec" totalMilliseconds="540" totalTrials="0" xmlns="http://schemas.connecterra.com/alepc">

     <applicationData>application specific data can go here
     </applicationData>
     <wasSuccessful>true</wasSuccessful>
     <status>SUCCESSFUL</status>
     <physicalReaders>
      <physicalReader>SimReadr</physicalReader>
     </physicalReaders>
     <failedLogicalReaders/>
     <cacheName>mycache</cacheName>
     <cacheSize>14</cacheSize>
     <epc>urn:epc:tag:gid-64-i:1.5.1</epc>
    </PCWriteReport>

The report indicates the status of the tag programming operation, and if successful (as in the example above), contains the EPC value that was written to the tag, and also indicates how many EPC values remain in the EPC cache. In this example, note that the EPC cache, which previously had 15 EPC values, now has only 14 EPC values remaining.

14. Repeat the `poll` command several more times, and watch the Edge Server's console window. At some point, the number of EPC values remaining in the cache will drop to the reporting threshold (10), and a low-cache report will be issued to the console subscriber you defined earlier. Each subsequent poll operation will cause a further low-cache report to be issued, unless you first use the replenish command to re-stock the EPC cache.
15. Keep repeating the poll command until the EPC cache is empty, as indicated in the `PCWriteReport` indicating a tag programming failure:

    polling myspec...
        ...received response.

    Received the following PCWriteReport:

    <PCWriteReport date="2006-03-16T16:53:16.758Z" savantID="EdgeServerID-bea" specName="myspec" totalMilliseconds="300" totalTrials="0" xmlns="http://schemas.connecterra.com/alepc">

     <applicationData>application specific data can go here
     </applicationData>
     <wasSuccessful>false</wasSuccessful>
     <status>CACHE_EMPTY</status>
     <physicalReaders>
      <physicalReader>SimReadr</physicalReader>
     </physicalReaders>
     <failedLogicalReaders>
      <logicalReader>ConnecTerra1</logicalReader>
     </failedLogicalReaders>
     <cacheName>mycache</cacheName>
     <cacheSize>0</cacheSize>
     <failureInfo>EPC cache 'mycache' empty for PCSpec myspec</failureInfo>
     <terminationCondition>FAILURE</terminationCondition>

## JMS Samples

The samples in this section show how to configure JMS options and naming properties on the WebLogic RFID Edge Server for vendor-specific JNDI (Java Naming and Directory Interface) providers and JMS servers. The samples also provide deployment units to be deployed into J2EE application servers in enterprise systems and provides sample message receiving programs for message queue servers.

For vendor-specific J2EE application servers, a `JMSTest.ear` enterprise archive file is available for deployment. The enterprise archive file contains a Message Driven Bean (`JMSTestMDB`) which receives JMS messages from specified queues and prints them out to the console.

For message queue servers (WebSphere MQ and TIBCO Enterprise for JMS), sample message receiver programs are provided to receive JMS messages from specified queues and to print them out to the console.

To run the sample JMSTest enterprise program within a BEA WebLogic Server deployment, perform the following steps:

1. Configure the JNDI provider and JMS server.
2. Configure the WebLogic RFID Edge Server:

- Copy the sample `jms.options` and `naming.props` files from the `./samples/JMSSamples/BEA/etc` directory into the `./etc` directory of the installation directory.
- Modify the `jms.options` file in the `./etc` directory of the installation directory with the appropriate paths for the specified environment variables.
- Modify the `naming.props` file in the `./etc` directory of the installation directory with the appropriate values for the `java.naming.provider.url` property.
- Modify the `edge.props` file in the `./etc` directory of the installation directory to set the following property to the fully qualified name for `naming.props`:

    com.connecterra.ale.notificationDriver.jms.default.namingPropertiesFile

- (Only if you are running the Edge Server as a Windows Service) Modify the `edge.wrapper.conf` file in the `./etc` directory of the installation directory to point to ALL the relevant `JMS_LIB` `.jar` files listed in `jms.options`. You can use either fully qualified or relative pathnames. Specify one `.jar` file per line, using the format shown below.

For example, assume that `InstallRoot` is the root of the application server, or path to the top directory of the application server. If you are using a fully qualified pathname, you might add an entry like the following one to `edge.wrapper.conf`:

    wrapper.java.classpath.31=c:\InstallRoot\AppServer\lib\someJarFile.jar

You can also use a relative pathname. For example, assume the `.jar` files are in a folder called `AppServerLib`, located directly under the installation directory. In this case you might add an entry like this to`edge.wrapper.conf`:

    wrapper.java.classpath.31=../AppServerLib/someJarFile.jar

Create separate `wrapper.java.classpath` entries for each `JMS_LIB` `.jar` file listed in `jms.options`.

3. Build the sample JMSTest enterprise archive by invoking `build.bat` or `build.sh` (set the environment variables appropriate to the build environment).
4. Using the `startWeblogic` script provided by BEA, start the WebLogic Server from a console window.
5. From a Web browser, log in to the WebLogic Server Administration Console:

    http://localhost:7001/console

6. From the WebLogic Server Administration Console, deploy the `JMSTest.ear` file, which is located in the `RFID_EDGE_HOME/samples/JMSSamples/BEA/deploy` directory. (For information on deploying applications, see the WebLogic Server documentation at http://www.oracle.com/technology/documentation/index.html.)
7. Start the RFID Edge Server.
8. Define an `ECSpec` to the Edge Server. For example, use the `SubscribeSample` to define `myECSpec`:

    run define myECSpec ECSpec.xml

9. Set a JMS subscriber to the defined ECSpec. For example, set a JMS subscriber for `myECSpec` reports with the following command (shown as two lines here, but entered as one line):

    run subscribe myECSpec jms:/queue/weblogic.jms.ConnectionFactory/jms%2FTestQ)

Note: | BEA provides `weblogic.jms.ConnectionFactory` and `weblogic.jms.XAConnectionFactory` as default connection factories.

10. View `JMSTest` `MDB` messages showing `ECReports` for the defined `ECSpec` in the console corresponding to the startWebLogic command.

## Workflow Sample XML Files

The `RFID_EDGE_HOME/samples/Workflow` directory contains three sample directories whose contents are XML files that define workflows. The three sample directories are:

- `DirectionalPortal`
- `ObservePortal`
- `PalletPortal`

For information on how to define workflows and import files, see the RFID Workflow Reference manual.