# Programming with the ALE and ALEPC APIs

# Asynchronous Notification Mechanisms

The following sections describe the asynchronous notification mechanisms WebLogic RFID Edge Server uses to deliver reports to client applications:

- Overview of Asynchronous Notification Mechanisms
- Encoded XML Through HTTP POST
- Encoded XML Through TCP Socket
- Encoded XML in JMS Message
- XML Written to a File
- XML Displayed on the Edge Server Console
- XML Sent to a Workflow Module

## Overview of Asynchronous Notification Mechanisms

You can define specifications (ECSpec, PCSpec, and EPCCacheSpec) for your applications and later subscribe the application to asynchronous delivery of corresponding reports (ECReports, PCWriteReport, EPCCacheReport). WebLogic RFID Edge Server provides a number of ways to deliver asynchronous reports. A subscription specifies a delivery address in the form of a Uniform Resource Identifier (URI). The URI specifies a particular method of notification delivery, and provides parameters that further identify the receiver.

In addition to out-of-the-box event delivery drivers that are applicable in a wide range of circumstances, the WebLogic RFID Edge Server provides an extensible mechanism for adding new delivery mechanisms. The following sections define the delivery mechanisms supported out-of-the-box by BEA, and describe how to construct the URIs to provide to the subscribe method of the ALE interface in order to use them.

All of the notification delivery mechanisms described below encode reports into XML. For additional information, see:

- XML Representations (for `ECSpec` and `ECReports` objects)
- XML Representations (for `PCSpec`, `PCWriteReport`, `EPCCacheSpec`, and `EPCCacheReport` objects)

## Encoded XML Through HTTP POST

The RFID Edge Server can deliver reports by sending an HTTP POST request, where the payload is the report instance encoded in XML. The general form of the subscription URI is:

    http://host:port/remainder-of-URL

Table 3-1 Report Delivery Format: Encoded XML Through HTTP Post

`host` | The DNS name or IP address of the host where the receiver is listening for incoming HTTP connections.
`port` | The TCP port on which the receiver is listening for incoming HTTP connections. The port and the preceding colon character can be omitted, in which case the port defaults to 80.
`remainder-of-URL` | The URL path to which the HTTP POST operation will be directed.

The notification payload is the XML-encoded report instance (ECReports, PCWriteReport, EPCCacheReport) for the subscribed event or programming cycle.

The response code returned by the HTTP server is used to determine whether the notification succeeded or not. A response code of 200 through 299 indicates success; any other response code indicates failure.

## Encoded XML Through TCP Socket

The Edge Server can deliver reports by opening a TCP socket to a designated receiver, sending an XML report, then closing the connection. The general form of the subscription URI is:

    tcp://host:port

Table 3-2 Report Delivery Format:

`host` | The DNS name or IP address of the host where the receiver listens for incoming TCP socket connections.
`port` | The TCP port on which the receiver is listening for incoming TCP socket connections.

Encoded XML Through TCP Socket

The notification payload is the XML-encoded report instance (ECReports, PCWriteReport, EPCCacheReport) for the subscribed event or programming cycle.

## Encoded XML in JMS Message

The Edge Server can deliver event cycle reports by sending a JMS Message to a JMS Topic or a JMS Queue where the message is a `javax.jms.TextMessage` that contains the `ECReports` instance encoded using XML.

The general form of the URI is:

    jms:/topic/conn_factory/topic_name[?queryParams]
    jms:/queue/conn_factory/queue_name[?queryParams]

Optional segments are enclosed in square brackets [].

Table 3-3

URI Segment | Optional or Required | Description
`topic` | `queue` | Required | Indicates whether the JMS notification driver adds messages to a queue or publishes messages to a topic.
`conn_factory` | Required | The JNDI name of the connection factory for obtaining a topic or queue connection.
`topic_name`| `queue_name` | Required | The name of the topic or queue to which the JMS notification driver sends its messages.
`queryParams` | Optional | Specify additional URI query parameters if necessary. To specify just one query parameter, append a string formatted as `?param1=value1` to the URI string. When you need to specify more than one parameter, append a string formatted as: `?param1=value1&param2=value2&param3=value3` Use the following query parameters: `username` The user name that you specified when you created a JMS topic connection or queue connection. Also see the password query parameter, below. `password` The password of the user specified in the URI. `ackMode` The acknowledgment mode that is used when the queue or topic session is created. Recognized values are: `auto client dups_ok` If you do not specify `ackMode`, a default value of `auto` is used. Query parameters whose names start with `jndi:` are added to the `javax.naming.Context` environment when one is constructed to access a naming service to perform the necessary JNDI lookups. If `javax.naming.Context` properties are specified in the URI as well as being configured on the Edge Server, then those properties that are specified in the URI will override the ones configured on the Edge Server. If you specify any other parameters, they will be added to the `javax.jms.TextMessage` as `String` properties, where the query parameter name is the property name and the query parameter value is the property value

Report Format: Encoded XML in JMS Message

The RFID Server also adds three additional properties to the `TextMessage`.

Table 3-4

`specName` | The name of the `ECSpec` associated with this `ECReport`.
`savantID` | The RFID Edge Server ID that is originating this `ECReport`.
`date` | The date of the `ECReport`. A time in milliseconds, as returned from `System.currentTimeMillis()`.

Text Message Properties Added by RFID Edge Server

The driver sends JMS messages in a non-transactional context.

Note: | All string values in the various segments of the URI have to be properly URI escaped. For example, to specify a forward slash (/) character in the URI, where that character is part of either the JNDI name or the connection factory, or the JNDI name of the queue or the topic, you need to use `%2F` instead of the forward slash character. For more information, see RFC 2396 at http://www.ietf.org/rfc/rfc2396.txt.

### Examples of Report Delivery by Using XML with JMS

In the following example the Edge Server is instructed to send XML reports through JMS to a queue named `MyECReportSpecQueue`. The JNDI service is accessed using `iiop` at `jms.example.com` through port `1099`. The JNDI name of the connection factory to be used is `ConnectionFactory`.

    jms:/queue/ConnectionFactory/MyECReportSpecQueue?jndi:java.naming.provider.url=iiop://jms.example.com:1099

In the following example the Edge Server is instructed to send XML reports through JMS to a topic named `MyECReportSpecTopic`. The JNDI service is accessed using `iiop` at `jms.example.com` via port 1099. The JNDI name of the connection factory to be used is called `ConnectionFactory`.

    jms:/topic/ConnectionFactory/MyECReportSpecTopic?jndi:java.naming.provider.url=iiop://jms.example.com:1099

The following example is more complex. This example incorporates JMS security as well as JNDI service security while using a queue. It uses the `jndi:` query parameters to set a security principal and security credential of `guest/PasswordForGuest` to access the JNDI service, and uses the username and password combination of b`ob/PasswordForBob` to open a connection to the queue.

    jms:/queue/ConnectionFactory/MyECReportSpecQueue?username=bob&password=PasswordForBob&
    jndi:java.naming.provider.url=iiop://jms.example.com:1099&
    jndi:java.naming.security.principal=guest&
    jndi:java.naming.security.credentials=PasswordForGuest

The following example uses all the elements of the previous example while overriding the default naming context factory class being used by the JMS driver. The class `org.jnp.interfaces.NamingContextFactory` will be used instead of the one the driver is configured with when performing JNDI lookups.

    jms:/queue/ConnectionFactory/MyECReportSpecQueue?username=bob&password=PasswordForBob&secPrincipal=guest&jndi:java.naming.provider.url=iiop://jms.example.com:1099&jndi:java.naming.security.principal=guest&jndi:java.naming.security.credentials=PasswordForGuest&jndi:java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory

The following example adds additional query parameters, `field1` and `field2` that will be added onto the JMS text message.

    jms:/queue/ConnectionFactory/MyECReportSpecQueue?username=bob&password=PasswordForBob&secPrincipal=guest&jndi:java.naming.provider.url=iiop://jms.example.com:1099&jndi:java.naming.security.principal=guest&jndi:java.naming.security.credentials=PasswordForGuest&jndi:java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory&field1=value1&field2=value2

## XML Written to a File

The Edge Server can deliver event or programming cycle reports by creating or appending XML to files in the Edge Server's local file system. The general form of the subscription URI is:

    file:///filename

where `filename` is either the name of a file, a directory, or a pattern as described below.

If `filename` names a specific file that already exists, the ECReports, PCWriteReport, or EPCCacheReport instance is encoded as XML and appended to the file. If more than one cycle completes, the resulting file is not a well-formed XML document, but a concatenation of XML documents.

If `filename` does not name an existing file but the directory portion names an existing directory, then the file is created, and the ECReports, PCWriteReport, or EPCCacheReport instance is encoded as XML and written to the file. If another cycle completes, the prior case applies and the file will be a concatenation of XML documents.

If `filename` names a directory, then the ECReports, PCWriteReport, or EPCCacheReport instance is written as a new file in that directory with a unique name of the form:

    specName-yyyyMMddhhmmssSSS.xml

where `specName` is the name of the `ECSpec`, `PCSpec`, or `EPCCacheSpec` that defined the cycle, and `yyyyMMddhhmmssSSS` is the timestamp in the `ECReports`, `PCWriteReport`, or `EPCCacheReport` instance, in the local timezone (`SSS` is the millisecond, which helps ensure the uniqueness of the filename even if several reports are generated per second).

If `filename` contains parentheses, the text within the parentheses is considered to be a pattern string for the timestamp, and the resulting filename after substitution is treated as above. For example, given this subscription URI:

    file:///mydir/myprefix-(yyyy-MM-dd).xml

then all reports generated on December 28, 2005 would be appended to the file

    /mydir/myprefix-2005-12-28.xml

In all cases, the XML is as described in:

- XML Representations (for `ECSpec` and `ECReports` objects)
- XML Representations (for `PCSpec`, `PCWriteReport`, `EPCCacheSpec`, and `EPCCacheReport` objects)

## XML Displayed on the Edge Server Console

The WebLogic RFID Edge Server can deliver event cycle reports by displaying XML in the console window where the Edge Server was started. This is typically useful only in debugging situations. The general form of the subscription URI is:

    console:heading

where heading is an arbitrary text string conforming to URI syntax restrictions. The heading is printed prior to each report instance: `ECReports`, `PCWriteReport`, or `EPCCacheReport`. This might be useful to distinguish reports arising from different subscriptions. URI syntax restrictions prohibit the heading from being empty.

## XML Sent to a Workflow Module

A workflow is a series of actions triggered by the observation of an EPC. The WebLogic RFID Edge Server can deliver ECReport data to workflow modules. Because the current release does not expose the workflow configuration APIs, use the Edge Server Administration Console for that purpose.