> Programming with the ALE and ALEPC APIs > Asynchronous Notification Mechanisms

Programming with the ALE and ALEPC APIs

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

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

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:

 

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 bob/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 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.


  Back to Top       Previous  Next