Installing WebLogic RFID Edge Server

Configuring WebLogic RFID Edge Server

You can configure an WebLogic RFID Edge Server by editing the edge.props file or by using the Administration Console. As installed, the default is to use the Administration Console.

The edge.props file is a configuration properties file for the Edge Server. It is located in RFID_EDGE_HOME/etc, where RFID_EDGE_HOME is the directory in which you installed the RFID Edge Server software.

This file is formatted as a Java properties file, where each line defines a configuration parameter. Lines beginning with a pound sign (#) character are comments and are ignored by WebLogic RFID Edge Server during processing. The file is self-documenting in that each property or set of properties is described by the comments preceding it.

The installation program writes initial configuration settings to this file.

Some setup tasks you might want to perform include:

Configuring Readers

The following sections provide information related to configuring the readers that will interact with the RFID Edge Server:

Two Approaches to Configuring Readers: edge.props or Administration Console

You can configure WebLogic RFID Edge Server to communicate with supported readers, printers, filters, and a workflow configuration in one of two ways:

The default behavior is controlled by a property in the edge.props file called com.connecterra.ale.dynamicConfig.enabled. The default setting for this property is true:

com.connecterra.ale.dynamicConfig.enabled = true

This means that you can, for example, configure logical and composite readers using the Administration Console. If you want to add and configure readers by editing the edge.props file, set this property to false.

Important: One group of options is configured only through edge.props, and a second group of options (those mentioned earlier: readers, printers, filters, and workflow configuration) can be configured either through edge.props or through the Administration Console. For this second group of configuration options, if you choose to use:

You can think of the dynamicConfig.enabled property as a single big switch: everything in the second group of properties is configured either through edge.props, or through the console, but not both. Therefore you should change the setting of dynamicConfig.enabled to false only after careful consideration of these implications. (The dynamicConfig.enabled property itself is part of the first group, edge.props only.)

RFID Reader Reference provides detailed information about the physical reader driver parameters, acceptable values, and defaults for readers recognized by WebLogic RFID Edge Server.

Comparing Physical Readers and Logical Readers

In specifying an event cycle or programming cycle, an application names one or more readers of interest. This is necessary because a single Edge Server may manage many readers that are used for unrelated purposes. For example, in a large warehouse, there may be 10 doors, with three readers at each door (a total of 30 readers). In such a case, a typical ALE request may be directed at the three readers for a particular door, but it is unlikely that an application tracking the flow of goods into trucks would want the reads from all 30 readers to be combined into a single event cycle.

This raises the question of how applications specify which readers are to be used for a given cycle. One possibility is to use identities associated with the readers themselves; for example, a unique name, serial number, IP address, etc. This is undesirable for several reasons:

To avoid these problems, ALE introduces the notion of a "logical reader." Logical readers are abstract names that an application uses to refer to one or more readers that have a single logical purpose; for example, readers positioned around a door might be called DockDoor42. Logical readers may be usefully thought of as being equivalent to "locations." Within the Edge Server, an association is maintained between logical names such as DockDoor42 and the physical readers assigned to fulfill that purpose. Any event cycle or programming cycle specification that refers to DockDoor42 is understood by the Edge Server to refer to the physical reader (or readers) associated with that name.

In many cases, a single RFID reader may support the use of more than one antenna, with the ability to treat each antenna independently. The Edge Server permits such readers to be configured so that each antenna is exposed through ALE as a separate logical reader. This gives flexibility to applications to use antennas independently or in concert, by simply specifying one or more logical readers in an ECSpec.

Adding Additional Physical Readers

If you decide to configure readers through the RFID Devices pane on the Administration Console, see Using the RFID Edge Server Administration Console for full instructions on configuring readers, and refer to the RFID Reader Reference for details on each reader's properties.

The remainder of this section describes the reader configuration parameters used to configure additional readers in edge.props.

Within the edge.props file, each reader is configured by including several related lines of parameter definitions. Every physical reader configuration includes a line having the following form:

com.connecterra.ale.reader.<deviceID>.class = <className>

Accompanying each instance of a reader configuration is a block of additional properties that are specific to that particular reader. The properties for a given physical reader are identified by sharing a common <deviceID> within their property names. The properties required within each configuration block depend on the reader make and model - the particular properties required by each reader type are listed in the RFID Reader Reference.

Each provisioned physical reader has one or more logical readers associated with it, one logical reader for each operational antenna. The definition of a logical reader specifies the logical reader's name, which is used when identifying the logical reader within an event cycle specification.

Each reader configuration line in edge.props looks like this:

com.connecterra.ale.reader.<deviceID>.<prop1>=<prop1value>

The <deviceID> is the same for all properties corresponding to a particular physical reader, <prop1> is the name of a property, and <prop1value> is the value assigned to that property. If a property is identified as optional, you can omit the corresponding line in the edge.props file and the default value will be used instead.

See Reader Simulator Configuration for an example of the as-shipped configuration for the Reader Simulator in edge.props.

Using Composite Readers

You specify names for logical readers when defining physical readers. You can create additional logical readers by combining existing logical readers. A logical reader created in this way is called a composite reader. By defining composite readers, you can decouple applications from decisions you take at deployment time about how many readers are needed to cover a single location.

For example, suppose that today, you have four logical readers covering a location called LoadingDock23:

You specify these reader names in each ECSpec that you create for LoadingDock23.

Then suppose you discover that you really need five readers to cover LoadingDock23. If you specified single logical reader names in each ECSpec, then you would need to:

Changing every ECSpec is undesirable, especially if some applications generate ECSpec instances for LoadingDock23 on the fly.

The alternative is to define a composite reader called LoadingDock23. Initially, this composite reader is configured to contain LoadingDock23_Reader1 through LoadingDock23_Reader4. Applications that want to read from Loading Dock 23 simply specify LoadingDock23 as the sole logical reader in their ECSpec instances.

Then, when you add your fifth reader, all you have to do is:

For information on how to define composite readers, see Defining Composite Readers.

Defining Composite Readers

If you have chosen to configure composite readers through the Composite Readers pane on the Administration Console, see Using the RFID Edge Server Administration Console for full instructions on configuring readers. The remainder of this section describes how to define composite readers in edge.props.

Use the following lines in edge.props to define composite readers:

Adding a Transient Filter

You can apply a transient (tag) filter to any logical reader that you configure in edge.props. Different logical readers may share the same filter settings, or have different settings.

For each transient filter you add, three parameters that control its operation:

These parameters control the filter in the following way. A tag is considered "soft" until it has been read minReads times, with no more than firmInterval milliseconds passing between each of those reads. A "soft" tag is not included in the filter's output, and therefore will not be considered by any active event cycles. If a "soft" tag is not read for more than firmInterval milliseconds, the count starts over again the next time the tag is read.

When the count reaches minReads, the tag becomes "firm." A "firm" tag is included in the filter's output, and will be considered by any active event cycles that use this logical reader. A "firm" tag remains "firm" even if the tag is not read in every read cycle, until it is not read for expiredInterval milliseconds. When that happens the tag is considered "expired." The next time the tag is read, it will be considered "soft", and the filter process starts again.

Setting firmInterval to -1 means that the count for a given tag will continue to increase towards minReads regardless of the time between reads, until the filter is reset. Setting expiredInterval to -1 causes any "firm" tag to remain "firm" until the filter is reset.

When choosing values for firmInterval and expiredInterval, you must be aware of the rate at which the logical reader performs read cycles. For most physical reader types, this is the defaultRate parameter times the number of active logical readers. If the firmInterval is less than this, tags will never become "firm" and no tags will be reported to any event cycle. Likewise, if the expiredInterval is less than the defaultRate parameter times the number of active logical readers, then it is equivalent to specifying an expiredInterval of zero.

To add a transient filter to a logical reader, add the following settings in the edge.props file. First, add the following lines to define a named filter (in the example, the filter is named myfilter1):

com.connecterra.ale.filter.myfilter1.class=
  com.connecterra.ale.filtertypes.TransientFilterFactory
com.connecterra.ale.filter.myfilter1.minReads = 3
com.connecterra.ale.filter.myfilter1.firmInterval = 1400
com.connecterra.ale.filter.myfilter1.expiredInterval = 1400

Then, for each logical reader to which you want to add the filter, add a line like this (in the example, the logical reader is named myreader):

com.connecterra.ale.logicalReader.myreader.filters = myfilter1

To apply the same filter parameters to more than one logical reader, you may specify the same filter name for more than one reader. Even though more than one logical reader refers to the same filter name, each logical reader is processed by a different filter instance.

Using 64-bit Tags

WebLogic RFID Edge Server supports the following 64-bit tag formats as defined by the EPCglobal Tag Data Standards Version 1.1:

When encoded onto 64-bit tags, these tag formats require an external translation table to translate the EPC Company Prefix Index field of the tag into an EAN.UCC Company Prefix. EPCGlobal supplies a translation table at this URL (that WebLogic RFID Edge Server uses by default):

http://www.onsepc.com/ManagerTranslation.xml

Alternatively, you can specify a local file as the source of the translation table by changing the value of com.connecterra.ale.epcIndexTableURL in edge.props to file:///c:mydir/myfile.xml, where myfile.xml has the general form:

<GEPC64Table>
<entry index="1" companyPrefix="0037000"/>
<entry index="2" companyPrefix="0041333"/>
...
<entry index="16383" companyPrefix="0614141"/>
</GEPC64Table>

If a file name is specified without an absolute path, the path given is assumed to be relative to WebLogic RFID Edge Server's ./etc directory. You may also specify a list of URLs, separated by spaces:

com.connecterra.ale.epcIndexTableURL = http://www.onsepc.com/ManagerTranslation.xml file:///c:/mydir/myfile.xml

The Edge Server will try each URL in turn, from left to right, until it successfully reads from one of the URLs. You can use this syntax to specify the EPCglobal table as the primary source, and use the local file syntax as a backup in case the EPCglobal site is unreachable.

Using 96-bit Tags

WebLogic RFID Edge Server supports the following 96-bit tag formats as defined by the EPCglobal Tag Data Standards Version 1.1. These tag formats do not require an external translation table.

Reader Simulator Configuration

The Reader Simulator provides a minimal simulation of a ThingMagic Mercury4 reader with two antennas running on your local system on port 5050. To modify the default Reader Simulator configuration using the Administration Console, you can enter properties into the Reader Configuration dialog box; for information on how to do this, see Using the RFID Edge Server Administration Console.

If you are using edge.props for reader configuration, the following properties are the as-shipped defaults for the Reader Simulator:

com.connecterra.ale.reader.SimReadr.class = 
  com.connecterra.ale.readertypes.ThingMagicMercury4PhysicalReader

com.connecterra.ale.reader.SimReadr.hostname = localhost
com.connecterra.ale.reader.SimReadr.port = 5050
com.connecterra.ale.reader.SimReadr.defaultRate = 0
com.connecterra.ale.reader.SimReadr.uhf2LogicalReaderName = ConnecTerra2
com.connecterra.ale.reader.SimReadr.uhf1LogicalReaderName = ConnecTerra1

See Two Approaches to Configuring Readers: edge.props or Administration Console for a discussion of these reader-configuration mechanisms.

With minor modifications to the command that starts the Reader Simulator in the RunReaderSim script, the simulator can provide a minimal simulation of a Printronix printer. For information on configuring and using the Reader Simulator, see Using the Reader Simulator.

Specifying State Data Persistence

You can configure the Edge Server to either keep or discard state data each time you stop and start the Edge Server. "State data" means:

You configure how you want to handle state data by editing edge.props, as described below.

The Edge Server also includes a utility that removes all state data. For information on how to use this utility, see Using ClearEdgeServerState to Delete State Data.

Editing edge.props to Configure State Data

Table 10-1 describes the edge.props properties that define how the Edge Server handles state data:

Using ClearEdgeServerState to Delete State Data

The ClearEdgeServerState utility removes all state data that you are storing in your state data directory. After you run ClearEdgeServerState, your Edge Server will start with no ECSpec instances defined. This ClearEdgeServerState utility also removes all dynamic configuration data. Be sure that you want the Edge Server in a newly installed stated before you the use this utility.

To run ClearEdgeServerState:

Configuring the HTTP Notification Driver

To configure the HTTP notification driver, you can use the edge.props timeout values shown in Table 10-2.

For example:

com.connecterra.ale.notificationDriver.http.class =
  com.connecterra.ale.notifytypes.HTTPNotificationDriver
com.connecterra.ale.notificationDriver.http.connectTimeout = 5000
com.connecterra.ale.notificationDriver.http.readTimeout = 10000

Enabling the SNMP Log Handler

WebLogic RFID Edge Server installations support an SNMP Log Handler, which creates SNMP traps from WebLogic RFID Edge Server log event messages and sends them to one or more configured destinations (called trap sinks). Typically, these destinations are SNMP-based Network Management Systems.

The default installation of WebLogic RFID Edge Server does not enable the SNMP Log Handler. To enable it, use the following instructions to edit the etc/logging.props.edge file. This file contains Java property definitions that control which log messages are forwarded to which handlers.

The MIB files can be found under share/mibs in the WebLogic RFID Edge Server installation directory.

Setting Up the JMS Notification Driver

To use the JMS notification driver, you edit various WebLogic RFID Edge Server configuration files to include JMS specifications, which is covered in this section. In addition, you set up a Java Naming and Directory Interface (JNDI) provider and JMS server, which is covered in Setting Up the JNDI Provider and JMS Server.

To use the JMS notification driver, edit the following Edge Server configuration files:

edge.props

Find the notification driver properties, and under the property com.connecterra.ale.notificationDriver (shortened to ND in the following example), edit the JMS notification driver properties as follows.

jms.options

Edit the JMS_LIB environment variable to indicate the location of the JAR and ZIP files provided by your JMS vendor that provide the naming context factory class (as you previously specified in edge.props) and all other classes required by JMS clients for your JMS vendor's implementation. Vendor-specific samples of JMS options are in samples/JMSSamples. A sample of jms.options is installed in the RFID_EDGE_HOME/bin directory.

The exact convention for setting this environment variable depends on your operating system and shell environment.

WebLogic Server 9.2

JMS_LIB must contain the location of two client jars. For instance, use this format where JMS_ROOT=WL_HOME\server\lib:

set JMS_LIB=%JMS_ROOT%\wljmsclient.jar;%JMS_ROOT%\wlclient.jar

This gets added to the Edge Server classpath at runtime via RunEdgeServer.bat, which automatically picks up the JMS_LIB at startup.

Note: Earlier versions of WebLogic Server also used the thin client jars, wljmsclient.jar and wlclient.jar, as well as the optional weblogic.jar.

Requirement for SAF (Store and Forward) client: weblogic.jar is required on the client.

WebLogic Server 10.0

For WebLogic Server 10.0, there are new options available for client configuration. The following example shows the use of these options:

naming.props

The naming properties file is used to initialize the instance of the javax.naming.Context class. The names and values of the properties specified in the file are used as Context environment properties, as with, for example, the properties from the BEA naming.props file:

java.naming.provider.url=t3://localhost:7001
java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory

A naming.props file resides in the RFID_EDGE_HOME/etc directory. You can copy other sample files from vendor-specific examples located in:

RFID_EDGE_HOME/samples/JMSSamples/<vendor_name>/etc

A Non-SAF example is available:

java.naming.provider.url=t3://localhost:7001
java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory

For a SAF example, refer to the default contents of the naming.props file. For configuration, you must point to the local SAF client xml file to find the object used to initialize the context. For information on configuring SAF clients, see refer to Using the WebLogic JMS Store-and-Forward (SAF) Client.

To create a naming properties file:

Setting Up the JNDI Provider and JMS Server

To use WebLogic RFID Edge Server's JMS notification driver, you need to set up the following components in your environment:

The following sections include configuration instructions for the following vendors:

BEA WebLogic Server 8.1 Configuration

Use the BEA WebLogic Server Administration Console (for example, http://<wlhost>:7001/console) to configure the JNDI provider and JMS server.

For example, use the following Administration Console page flows:

For additional information, see the WebLogic Server System Administration Documentation:

BEA WebLogic Server 9.2 and 10.0 Configuration

For WebLogic Server 9.2 and 10.0, you must create a JMS Module as well as a JMS Server. You must also create the destinations (queues or topics) as members of the JMS Module. The JMS Module and JMS Server must be targeted to the correct server, and destinations must reference a sub-deployment object.

Use the BEA WebLogic Server Administration Console (http://<wlhost>:7001/console) to configure the JNDI provider and JMS server. The following steps describe this configuration procedure using the WebLogic Administration Console:

If a JMS exception occurs after you completed the creation of the server objects, you can correct the problem by performing the following steps:

IBM WebSphere Configuration

WebSphere Application Server with Embedded Messaging Configuration

Use the WebSphere Application Server Administration Console (for example: http://<was_host>:9090/admin) to configure the Internal JMS Server and to configure a listener port.

For example, use the following Administration Console page flows:

WebSphere Application Server with Full WebSphere MQ Configuration

Use the WebSphere Application Server Administration Console (for example: http://<was_host>:9090/admin) to configure a listener port.

For example, use the following Administration Console page flows:

WebSphere MQ Stand-alone Configuration

Use the WebSphere MQ Explorer to create a queue manager (for example: QM_host1) and to create a queue (for example: MQ_JMS_Q) under the queue manager.

Use the JMSAdmin tool to define connection factories and queues.

For example, use the JMSAdmin tool to define a connection factory with JNDI name of jms/MQTestQCF and a queue with JNDI name of jms/MQTestQ as follows:

InitCtx> define qcf(jms/MQTestQCF) qmgr(QM_host1)

InitCtx> define q(jms/MQTestQ) qmgr(QM_host1) queue(MQ_JMS_Q)

Additional IBM Product Information

For additional information, see the IBM Product Publications:

http://www.ibm.com/support/publications/us/

The following publications are recommended:

JBoss Application Server Configuration

JBoss provides a default connection factory (with JNDI name of ConnectionFactory) which can be leveraged without any additional JNDI configuration.

For EJBs (Message Driven Beans configured to receive JMS messages) deployed in the JBoss application server, the JBoss-specific EJB deployment descriptor (jboss.xml) contains the destination JNDI name (example: TestQ) to be configured. Note that JBoss automatically configures the destination JNDI name in the "queue" JNDI context for queues (example: queue/TestQ) or "topic" JNDI context for topics (example: topic/TestTopic).

For more advanced JMS or JNDI configurations, use the JBoss JMX administrative console (example: http://<jboss_host>:8080/jmx-console) to configure the JMS server and JNDI provider.

For more information, see the JBoss Administration and Development Documentation:

http://jboss.org/docs/index

Sun Java System Application Server Configuration

Use the Application Server Admin Console (example: http://<sun_host>:4848/asadmin) to configure the JNDI provider and JMS server.

For example, use the following Administration Console page flows:

For additional information, see the Sun Java System Application Server Administration Guide. The Platform Edition 8.2 manual is available at:

http://docs.sun.com/app/docs/doc/819-4712

TIBCO Enterprise for JMS Configuration

Use the JMS Administration Tool to create JMS connection factories and queues.

For example, after starting the JMS Server, use the JMS Administration Tool to define a connection factory with JNDI name of TestQCF and a queue with JNDI name of TestQ as follows:

> connect host1:7222

tcp://host1:7222> create factory TestQCF queue
tcp://host1:7222> create queue TestQ

For additional information, see the TIBCO Enterprise for JMS User's Guide, located in the installation directory of TIBCO Enterprise for JMS:

JMS/doc/pdf/tib_jms_users_guide.pdf

Using the WebLogic JMS Store-and-Forward (SAF) Client

The WebLogic 10.0 JMS SAF Client feature provides a store-and-forward mechanism whereby stand-alone JMS clients can reliably send messages to server-side JMS destinations, even when a JMS client cannot temporarily reach a destination (for example, due to a temporary network connection failure). While disconnected from the server, messages sent by a JMS SAF client are stored locally on the client file system and are forwarded to server-side JMS destinations when the client reconnects.

For detailed information, see Reliably Sending Messages Using the JMS SAF Client in Programming Stand-alone Clients and Messaging (JMS) for BEA WebLogic Server® 10.0.

Configuring the Edge Server To Use Client-Side JMS SAF

These interoperability guidelines apply when configuring a JMS SAF client:

In the event that you cannot use the thick-client you may alternatively use the thin-client jars found in WLS10.0\server\lib: wls-api.jar, wljmsclient.jar, wlclient.jar and wlsafclient.jar. These files can be located in any directory that is accessible by the Edge Server, and will also need to be set in the jms.options file.

Prerequisites—Before configuring the Edge Server to use client-side JMS SAF:

Follow these steps to configure the Edge Server to use client-side SAF JMS Notifications:

What's Next: Developing Applications

You can now start your own application development using the ALE API and creating Edge Flow modules. For complete reference information, sample applications, and code walkthroughs, see: