Programming with the BEA WebLogic RFID Edge Mobile SDK APIs

Sample C# Application

The following sections describe how to use the sample C# application provided with the SDK. The sample application is free for you to use and modify for your own purposes. You can use this application as a starting point for developing your own applications.

Overview of Sample C# Applications

The following sample is provided with BEA WebLogic RFID Edge Mobile SDK:

BEAMobileTagRead — Shows how to use the BEA WebLogic RFID Edge Mobile SDK API for tag reading with EPCIS capture (send an EPCIS ObjectEvent for one or more EPC reads).

Setting Up Your Development Environment

To compile and run the sample application, you need to install the Microsoft Visual Studio .NET 2003 or Microsoft Visual Studio 2005, and the BEA WebLogic RFID Edge Mobile SDK software.

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

Compiling and Running the Samples

Use Microsoft Visual Studio to open the sample solution and associated projects to build the sample application.

For example, for the BEA Mobile Tag Read sample application, perform the following:

Use the Windows File Explorer to go to the following directory:

BEA_MOBILE_SDK_HOME\samples\BEAMobileTagRead

Double-click on the BEAMobileTagRead.sln solution file to bring up the BEA Mobile Tag Read solution, associated project, and source code files in Microsoft Visual Studio.
Make the desired changes to the source code.
In the main menu of Microsoft Visual Studio, select Build -> Rebuild Solution to compile the BEA Mobile Tag Read sample application.

For details on running the BEAMobileTagRead sample application, see Configuring and Running the BEA Mobile Tag Read Sample Application in Installing BEA WebLogic RFID Edge Mobile SDK.

For a tutorial walk through of a sample, see:

BEAMobileTagRead: UML Diagrams

Class Diagrams

Figure 4-1 illustrates the relationships among the classes of the BEA Mobile Tag Read sample application.

Figure 4-1 BEA Mobile Tag Read Sample Application UML Diagram

com.bea.mobile.rfid.samples.tagread.BEAMobileTagReadForm Class

The BEAMobileTagReadForm class is the main application class supporting the user interface and application logic. This class contains the following methods:

BEAMobileTagReadForm

BEAMobileTagReadForm() // Default constructor

Main() : void // Main program method

BEAMobileTagReadForm_Load(sender:Object, eventArgs:EventArgs) : void

// Processes BEAMobileTagReadForm load event

ReaderTimer_Tick(sender:Object, eventArgs:EventArgs) : void

// Processes timer tick event

OnClosing(CancelEventArgs:EventArgs) : void // Processes cancel event

Dispose(disposing:boolean) : void // Frees up resources

initApp() : void // Initializes the application

ExitMenu_Click(sender:Object, eventArgs:EventArgs) : void

// Processes Exit menu event

AboutMenu_Click(sender:Object, eventArgs:EventArgs) : void

// Processes About menu event

SendPersistedMenu_Click(sender:Object, eventArgs:EventArgs) : void

// Processes Send Persisted menu event

ClearDisplayedMenu_Click(sender:Object, eventArgs:EventArgs) : void

// Processes Clear Displayed menu event

ClearPersistedMenu_Click(sender:Object, eventArgs:EventArgs) : void

// Processes Clear Persisted menu event

EditConfigMenu_Click(sender:Object, eventArgs:EventArgs) : void

// Processes Edit Config menu event

ReadImmediatelyMenu_Click(sender:Object, eventArgs:EventArgs) : void

// Processes Read Immediately menu event

DisplayMenuBox(text:String, caption:String) : void

// Displays menu box with specified text

com.bea.mobile.rfid.samples.tagread.BEAMobileTagReadForm.MobileTagReadWorkflow Nested Class

The BEAMobileTagReadForm.MobileTagReadWorkflow nested class provides the concrete implementation of the AbstractWorkflow class and encapsulates the business logic for the tag read workflow. This class contains the following methods:

BEAMobileTagReadForm.MobileTagReadWorkflow

MobileTagReadWorkflow(form:BEAMobileTagReadForm, physicalReader:PhysicalReader) // Constructor with form and physical

// reader parameters

initialize(configManager:ConfigManager) : void // Initializes the

// workflow based on specified ConfigManager

start() : void // Starts the workflow

stop() : void // Stops the workflow

shutdown() : void // Shuts down the workflow

reset() : void // Resets the workflow

terminateReader() : void // Terminates the reader

handleEvent(sender:Object, eventArgs:EventArgs) : void

// Processes the event

handleTimerEvent(args:WorkflowEventArgs) : void

// Processes the timer event

handleClearPersistenceEvent(args:WorkflowEventArgs) : void

// Processes the clear persistence event

handleReadPersistenceEvent(args:WorkflowEventArgs) : void

// Processes the read persistence event

handleChangeConfigurationEvent(args:WorkflowEventArgs) : void

// Processes the change configuration event

handleTriggerPressedEvent(sender:Object, eventArgs:EventArgs) : void

// Processes the trigger pressed event

handleTriggerReleasedEvent(sender:Object, eventArgs:EventArgs) : void

// Processes the trigger released event

handleReadEvent(sender:Object, eventArgs:EventArgs) : void

// Processes the read event

enableReadEventHandler() : void // Enables the read event handler

enableTriggerEventHandlers() : void // Enables the trigger event handlers

disableReadEventHandler() : void // Disables the read event handler

disableTriggerEventHandlers() : void // Disables the trigger event

// handlers

initFilters(filterClassNames:List, configMgr:ConfigManager, persistenceMgr:PersistenceManager) : void // Initializes the configured

// filters

com.bea.mobile.rfid.samples.tagread.ConfigForm Class

The ConfigForm class provides support for the Edit Config dialog. This class contains the following methods:

ConfigForm

ConfigForm(wc:WorkflowConfig, rc:ReaderConfig, pc:PersistenceConfig, ecc:EPCISCaptureConfig)     // Constructor with config parameters

Dispose(disposing:boolean) : void // Cleans up any resources being used

ConfigForm_Load(sender:Object, eventArgs:EventArgs) : void

// Processes ConfigForm load event

ButtonOK_Click(sender:Object, eventArgs:EventArgs) : void

// Processes OK click event

ButtonCancel_Click(sender:Object, eventArgs:EventArgs) : void

// Processes Cancel click event

Sequence Diagram

Figure 4-2 illustrates the messages involved from workflow initialization to tag read processing in the BEA Mobile Tag Read sample application.

Figure 4-2 BEA Mobile Tag Read Sample Application - Sequence Diagram

In the above sequence diagram, the BEA Mobile Tag Read sample application creates the device specific physical reader and the applicable workflow instance. The application calls initialize() on the workflow instance to perform initialization. The application calls start() on the workflow instance to enable the mobile device and setup the appropriate event handlers. The application processes events (read events, trigger events) and displays the desired data and status in the user interface.

BEAMobileTagRead: How to Use the BEA WebLogic RFID Edge Mobile SDK APIs to Read Tags and Send EPCIS Events

The BEAMobileTagRead sample application shows how to do the following:

Use the Tag Reading API to create a reader, listen for trigger press and release events, obtain tag read data, and close a reader.
Use the Workflow API to manage the lifecycle (creation, start, stop) of the application workflow.
Use the Filter API to filter tag reads based on configured criteria.
Use the Persistence API to persist EPCIS capture events to a configured persistence store.
Use the Configuration API to process static configuration and dynamic configuration for specific sets of configuration data.
Use the ALE EPC API to perform EPC processing.
Use the EPCIS Capture API to construct EPCIS event messages (ObjectEvent) and send the EPCIS event messages to configured destinations.

Tag Reading API Usage

The MobileTagReadWorkflow in the BEAMobileTagRead sample application uses read event and trigger event handlers to start, process, and stop tag reads. In MobileTagReadWorkflow.initialize(), the following C# lines of code instantiate the required event handlers:

// Create handler for read event notifications

m_readEventHandler = new EventHandler(handleReadEvent);

// Create handler for trigger pressed event notifications

m_triggerPressedEventHandler = new EventHandler(handleTriggerPressedEvent);

// Create handler for trigger released event notifications

m_triggerReleasedEventHandler = new EventHandler(handleTriggerReleasedEvent);

MobileTagReadWorkflow.start() enables the event handlers via LogicalReader.subscribe() for the specific event type and event handler. MobileTagReadWorkflow.stop() disables the event handlers via LogicalReader.unsubscribe() for the specific event type and event handler.

When the trigger is pressed on the mobile device, the MobileTagReadWorkflow.handleTriggerPressedEvent() method is invoked, which then starts tag reads via MobileTagReadWorkflow.startRead(). The internal implementation of MobileTagReadWorkflow.startRead() publishes a ReadEvent event.

The MobileTagReadWorkflow.handleReadEvent() method is invoked to handle the ReadEvent. The implementation of MobileTagReadWorkflow.handleReadEvent() obtains the read buffer via the LogicalReader.ReadBuffer property and displays the EPC-formatted tag reads in the main UI. A beep is played for each tag read via PhysicalReader.playBeep().

When the trigger is released on the mobile device, the MobileTagReadWorkflow.handleTriggerReleasedEvent() method is invoked, which then disables the tag reads.

Workflow API Usage

In BEAMobileTagReadForm.initApp(), the MobileTagReadWorkflow is instantiated, initialized and started by the following C# lines of code:

// Create workflow

m_workflow = new MobileTagReadWorkflow(this, physicalReader);

// Initialize workflow

m_workflow.initialize(ConfigManagerImpl.Instance);

// Start workflow

m_workflow.start();

Events are handled in BEAMobileTagReadForm through delegation to the workflow. For example, when the user selects "Send Persisted Events" on the main UI, the BEAMobileTagReadForm.SendPersistedMenu_Click() method is invoked, which then processes the event via Workflow.handleEvent().

The BEAMobileTagReadForm.OnClosing() method is called when the application is closing. The implementation of BEAMobileTagReadForm.OnClosing()calls Workflow.stop() and Workflow.shutdown() to stop and shutdown the workflow, respectively.

Filter API Usage

In MobileTagReadWorkflow.initFilters(), each configured filter is created, initialized, and added to the filter list by the following C# lines of code:

foreach (string filterClassName in filterClassNames)

    // Create filter

    Filter filter = WorkflowConfig.createFilterClassInstance( filterClassName);

    // Initialize filter

       filter.initialize(configManager, persistenceManager, null);

       m_filters.Add(filter);

};

In MobileTagReadWorkflow.applyFilters(), the configured filters are applied to the specified ObjectEvent by the following lines:

IList objectEvents = new ArrayList();

objectEvents.Add(objectEvent);

foreach (Filter filter in m_filters)

    objectEvents = filter.execute(objectEvents);

Persistence API Usage

In MobileTagReadWorkflow.processReadData(), each ObjectEvent is persisted to the configured persistence store by using the PersistenceManager class as follows:

m_persistenceManager.persist(objectEvent);

To process a "Send Persisted Reads" action from the main UI, the MobileTagReadWorkflow.handleReadPersistenceEvent() method is invoked to read persisted EPCIS events into memory and send them to configured EPCIS capture destinations via the following C# lines of code:

IList epcisEvents = m_persistenceManager.Data;

foreach (EPCISEvent epcisEvent in epcisEvents)

try

        // Send EPCIS capture event

        m_epcisCapture.capture(epcisEvent);

    catch(EPCISCaptureException ece)

...

};

Configuration API Usage

In MobileTagReadWorkflow.initialize(), workflow-specific configuration data is obtained by using the ConfigManagerImpl class as illustrated in the following C# lines of code:

// Get workflow config data

IList workflowNames = configManagerImpl.WorkflowConfig.getWorkflowNames();

m_workflowConfigData = configManagerImpl.WorkflowConfig.getWorkflowConfigData((string)workflowNames[0]);

ALE EPC API Usage

In MobileTagReadWorkflow.processReadData(), the EPC tag URI string is obtained by using the EPC class as follows in C#:

tagReport.EPC.TagURI.ToString();

EPCIS Capture API Usage

In MobileTagReadWorkflow.createObjectEvent(), an ObjectEvent instance is created by the following C# lines of code:

EPCISEventData.ObjectEventData objectEventData = new EPCISEventData.ObjectEventData();

// Set event time

objectEventData.m_eventTime = ((TagReport)tagReports[0]).Timestamp;

// Create list of EPC URIs

IList epcURIs = new ArrayList();

for (int i=0; i<tagReports.Count; i++)

    TagReport tagReport = (TagReport)tagReports[i];

    epcURIs.Add(tagReport.EPC.TagURI);

objectEventData.m_epcURIs = epcURIs;

// Set EPCIS data

EPCISEventData.EPCISData epcisData = new EPCISEventData.EPCISData();

epcisData.m_action = m_epcisCaptureConfig.EPCISAction;

epcisData.m_readPointURI = m_epcisCaptureConfig.CurrentReadPointURI;

epcisData.m_businessLocationURI = m_epcisCaptureConfig.CurrentBusinessLocationURI;

epcisData.m_businessStepURI = m_epcisCaptureConfig.CurrentBusinessStepURI;

epcisData.m_dispositionURI = m_epcisCaptureConfig.CurrentDispositionURI;

// Set business transaction data

IList businessTransactions = null;

if (m_epcisCaptureConfig.CurrentBusinessTransactions != null)

    businessTransactions = new ArrayList();

    businessTransactions.Add(m_epcisCaptureConfig. CurrentBusinessTrasnaction);

epcisData.m_businessTransactions = businessTransactions;

objectEventData.m_epcisData = epcisData;

return m_epcisCapture.createObjectEvent(objectEventData);

In MobileTagReadWorkflow.processReadData(), an EPCIS event is sent to configured destinations using the EPCISCapture interface as follows in C#:

try

    // Send EPCIS capture event

    m_epcisCapture.capture(epcisEvent);

catch(EPCISCaptureException ece)

...