Skip Headers
Oracle® Application Server Wireless Developer's Guide
10g Release 2 (10.1.2)
B13819-02
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

13 Oracle Sensor Edge Server

Each section of this document presents a different topic. These sections include:

13.1 Introducing Oracle Sensor Edge Server

Oracle Sensor Edge Server is a middle tier component that integrates sensors and other types of command or response indication equipment with applications.


Note:

For more information on the use and management of Oracle Sensor Edge Server, see Oracle Application Server Administrator's Guide.

13.1.1 Oracle Sensor Edge Server Concepts

Oracle Sensor Edge Server integrates sensor data (from Sensors) and applications. Sensors are hardware or software end points that make observations of certain changes of state, such as RFID, laser diodes, temperature sensors, and others.

13.1.1.1 RFID Basics

RFID is the use of small transponders with embedded Electronic Serial Numbers (ESN) or memory, which transmit identifiers across one or more frequencies. A transponder can carry other information in its memory, and can be read or written to at a distance, without the need for line-of-sight contact.

Here are some useful terms for understanding the technology:

  • Tag—a single unit that contains a chip, one or more antennae, and a power source. If the tag has its own power source (such as a battery or electrical connection), the tag is an Active Tag. If the power source is inductive-based, which means that it relies on photoelectric effect to generate power from remotely generated radio waves, the tag is a Passive Tag.

  • Chip—a silicon chip, with embedded memory, is used in a tag. The chip is where the information is stored. It implements the wireless protocol and access functions to its embedded memory. Note that in active tags, this is not a single chip but a whole board.

  • Antenna—there is one or more antennae on each tag. On the other side of the communication link, the reader must also have an antenna. Some readers can drive multiple antennae at the same time. Depending on the protocol, frequency and application, these antennae vary from thin strips of metal laid across a surface, to a portal doorway antenna that is meters tall.

  • Reader—reads from, and writes to tags. Readers usually have serial interfaces used to communicate with a host computer. There is no widely-accepted standard for this protocol.

  • Device—an end point of a sensor-based architecture. A device can be an RFID reader, a dry contact, a laser diode, carousel, robotic pickers, and so on.

  • Oracle Sensor Edge Server—the middle tier that resides between all the readers and the applications. It is responsible for interfacing with all the readers and sending normalized data back to the application server.

13.1.2 Overview of Oracle Sensor Server Architecture

This section describes the highlights of Oracle Sensor Edge Server architecture. Figure 13-1 shows Oracle Sensor Edge Server architecture as part of an enterprise installation.

Figure 13-1 Oracle Sensor Edge Server Architecture

Description of Figure 13-1  follows
Description of "Figure 13-1 Oracle Sensor Edge Server Architecture"

13.1.2.1 Device Drivers

Device Drivers communicate with sensors, and normalize incoming data into standard format. Device Drivers can be customized or built to suit your needs.

13.1.2.2 Device Groups

Device Groups are used by administrators to group devices logically, and manage them more efficiently. An Oracle Sensor Edge Server can have one or many Device Groups instantiated. Each Device Group is responsible for the Device Drivers that it manages.

13.1.2.3 Filter Rules

Filter Rules remove unwanted or low-level events. Filter Rules can be used to sort incoming data. They can be applied to individual Devices, or to Device Groups.

13.1.2.4 Event Processor

Event Processor is the central processing engine for event delivery. It loads the rest of the components, which include the Driver Manager and (on start up) the Event Dispatcher. Internally, it reads the configuration to find out which Event Dispatcher to load. The process is started on startup.

13.1.2.5 Driver Manager

Driver Manager loads and manages the life cycle of the Device Groups and Device Drivers. There is only one instance of a Driver Manager for each Oracle Sensor Edge Server.Driver Manager provides an accessible context to device drivers so they can retrieve configuration information. It then loads the Device Groups, and binds them to the Device Drivers. The Driver Manager does not hold any thread internally, but an instance of it is held by the Event Processor instance as long as the server is up and running.

There is one Event Processor and one Driver Manager in each Oracle Sensor Edge Server. Each Driver Manager loads a number of Device Groups. In turn, each Device Group can have any number of Device Drivers. But, one Device Driver can only belong to one Device Group.

13.1.3 Edge Dispatcher

Dispatchers are plug-ins that enable two-way communication with applications. The main output of the Oracle Sensor Edge Server is filtered data events. These data events are provided already minimized and normalized. They can be delivered in one of the out-of-the-box supported methods:

  • Streams/AQ

  • JMS

  • Web Services

  • HTTP Post

  • Other forwarding methods can be supported by writing a Custom Event Dispatcher.


Note:

For more information on managing Sensor Services, see OracleAS Wireless Administrator's Guide.

13.1.3.1 Streams/AQ

Oracle Sensor Edge Server supports forwarding data to Oracle Streams as the distribution mechanism to applications and agents. Dispatching through Streams provides the most robust and flexible method of forwarding data. This is the only dispatching method that fully supports rule-based processes and agents-based technologies.

Unlike other dispatcher methods mentioned (in which events are mostly transient and sent directly to an entry point), the Streams Dispatcher supports a much more sophisticated model in which arriving events are not directly mapped to event consumer entry points (that is, applications).

Events are data that is dropped into a Staging Area. The Oracle Sensor Edge Server defines various ways to aggregate data for different consumers. Interpretation of events is not done by either the Oracle Sensor Edge Server or the applications; it is done by the Sensor Data Hub in the database. This layer provides a rules-based process that defines the content and timing of notification.

Once events are staged, data can be archived, transformed and managed independently of the application and the Oracle Sensor Edge Server. This allows the Oracle Sensor Edge Server to be application and sensor neutral, providing far better quality and detail of data for goal-based and business intelligence models to process.

The Streams Dispatcher passes events to the staging area. Once data is in the staging area, the data can be processed in different ways.

The Rules Evaluation Job takes events from the staging area and runs them against the Oracle Sensor Edge Server ruleset. Each rule in the ruleset has an action, which is executed if the rule's predicate becomes relevant.

Actions defined can perform various operations, such as calling a PL/SQL callback, or propagating to other queues (which could then be consumed by other applications).

Applications needing to receive raw events before the rules evaluation phase can connect directly to the staging area by using AQ notification, AQ propagation, or JMS.

To summarize, the following are the ways an application can be invoked:

  • PL/SQL Callback (rules-based)

  • Queue propagation (rules-based)

  • Mining the Sensor Data Hub

  • Direct raw events by connecting to the staging area

13.1.3.1.1 Configuration

If the Streams/AQ dispatch method is selected, the client must provide the connection information to the Streams staging area (this is in the schema that username refers to). The Streams/AQ connection parameters are listed in Table 13-1.

Table 13-1 Streams/AQ Connection Parameters

Parameter Format Description

url

Text (URL)

The connection string to the database where the staging area resides. Administrators should point to an application database where events and observations can best be accessed and archived.

username

Text

Name to be used to connect to the database connection provided (Must be edge in this release.).

password

Text

Password of the user.



Note:

Oracle Sensor Edge Server runs in enterprise and standalone (Java) modes. If you are developing applications to run in both modes, ensure that all parameter names are composed of one word, and do not contain other characters (such as apostrophes, special characters).

13.1.3.1.2 Event ADT

The EDG_EVENT ADT (Advanced Data Type) is a custom defined data type to represent an event. An event can be an observation, or an instruction to a device. The following table shows the fields inside the EDG_EVENT type.

Table 13-2 EDG_EVENT type fields

Column Type

TYPE

NUMBER

SUBTYPE

NUMBER

ID

CLOB

SITENAME

VARCHAR2

DEVICENAME

VARCHAR2

DATA

CLOB

TIME

TIMESTAMP

SOURCENAME

VARCHAR2

CORRELATIONID

VARCHAR2


See Table 13-16, "Event Format" for a detailed description on how these fields are used.

13.1.3.1.3 Queues

During installation, the EDGE schema contains two internal queues:

  • EDG_EVENT_Q—the internal ADT AQ. The payload uses the Event ADT type. You can attach to this queue, and dequeue from it without disrupting the Rules jobs. This technique is useful if you want to read all events that are coming in from Oracle Sensor Edge Server.

  • EDG_INSTR_IN_Q—used by applications to send event instructions back to Oracle Sensor Edge Server. It is also an ADT AQ based on the type Event ADT.

13.1.3.1.4 Rules

Rules can be defined any time. You can add as many rules as you need. See Oracle DBMS documentation for details on using Rulesets.

The rules are defined in the Streams database using the standard dbm_rule package. The ruleset name used for the Oracle Sensor Edge Server is EDG_RULESET. Each rule contains the following elements:

  • Name—a name of the rule, which must be unique across all rules in the ruleset (for example: EDG_RULESET).

  • Condition—the evaluation expression. If the result is true, the rule will be applied. The expression is a SQL WHERE clause (without the WHERE keyword). The edg_event can be accessed through tab.user_data.

  • Action_Context—defines what the Oracle Sensor Edge Server does when the rule becomes valid. Action_Context instructs the Oracle Sensor Edge Server what to execute when the associating rule becomes valid.

  • Evaluation Context (optional)—for advanced Rules package users. Evaluation context provides a way for developers to alias tables in other schemas. Use a PL/SQL callout which has access to the requisite objects. If Evaluation Context is specified, the Edge User must have evaluate privileges on this object. The context is a list of name value pairs which contain the following names:

Table 13-3 Action_Context Rules

Name Format Description

TYPE

Text

A string that tells the evaluation engine what command to execute. The following commands are supported:"call"—calls a PL/SQL callback. The name of the callback is defined in the param field."queue"—propagates to another queue. The name of the other queue is defined in the param field

PARAM

Text

Parameter for the command; the format varies according to the command used.


Here is an example of how to add a Rule using the edg_utl.add_rule procedure:

Example 13-1 Adding a Rule using edg_utl.add_rule procedure

begin
edg_utl.add_rule(     
    ruleName => 'my_callback',
    condition => 'tab.user_data.type = 0 AND tab.user_data.subtype = 2',
    param => 'my_schema.my_package.my_callback',
    command => 'call');
end;
/

This registers a callback that is called when the incoming edg_event has a type of 0 and subtype of 2 (this is an error message in the system). The rules engine calls the my_callback pl/sql procedure in the my_package pl/sql package in the my_schema schema.

Here is an example of how to remove a rule using the edg_utl.remove_rule procedure:

Example 13-2 Removing a Rule using edg_utl.remove_rule procedure

begin
edg_utl.remove_rule(     
    ruleName => 'my_callback')
end;
/

This removes the my_callback rule from the rulset.

13.1.3.1.5 Rules Action Types

By using Streams, client applications can receive events in various ways. These action types are supported:

  • PL/SQL Callback—the parameter is the name of the PL/SQL procedure to call qualified schema names.

  • Queue Propagation—the parameter is the name of the queue to propagate to for qualified schema names.

13.1.3.1.6 PL/SQL Callback

If the client is called using a PL/SQL callback, the PL/SQL will have a parameter that is passed in. The parameter is defined with an ADT type named EDG_EVENT.

Here is a callback example:

Example 13-3 Callback Example

PROCEDURE my_callback(ev IN EDGE.EDG_EVENT) IS
BEGIN

.... your code here ....

END my_callback;

my_callback is the name of your callback. Note that the owner of the edge schema must have execute privileges on this PL/SQL procedure.

13.1.3.1.7 Queue Propagation

If the defined rule uses queue propagation, when the rule becomes valid, the relevant event is copied to the designated queue. The destination, for this release, must be defined as an ADT queue, using the type EDG_EVENT. The application can then read off this custom queue for data relevant to it.


Note:

The owner of the edge schema must have enqueue privileges on your queue. For more information, see your database documentation.

13.1.3.1.8 Default Rules

By default, the following Rules are added to the Rules Set. They are all optional, and can be removed if you prefer not to do these types of archiving. There are no system jobs that will purge these archives for you; you must purge them manually is desired.

  • sdh_callback—inserts and archives all incoming events into the table SDH_EVENTS. If you do not want all events to be archived, remove this default rule.

  • sdh_perf_callback—inserts all performance-related events into the SDH_FILTER_PERF table.sdh_error_callback—inserts all events that are related to reporting error conditions into the SDH_DEVICEFAILURE table. Events that are related to check tag error (meaning using the CheckTag filter), are inserted into the SDH_CHECKTAG_ERROR table.

13.1.3.1.9 Sensor Data Archive

The Sensor Data Archive is a set of tables that store relevant sensor data required by Oracle Sensor Edge Server. The administrator can customize which data types to archive by changing or adding rules in the Edge Ruleset. The administrator can change the default rule to customize which conditions will be archived, but changing the default rule is not recommended. Changing the rule can make getting support for the product very difficult.

There are four tables: sdh_events (Table 13-4), sdh_checktag_error (Table 13-5), sdh_devicefailure (Table 13-6), and sdh_filter_perf (Table 13-7).

  • sdh_events is an archive of all of the collected events. The format is: create table sdh_events

    Table 13-4 sdh_events table

    Column Type

    type

    number

    subtype

    number

    id

    clob

    sitename

    varchar2 (100)

    devicename

    varchar2 (100)

    data

    clob

    time

    timestamp

    sourcename

    varchar2 (100)

    correlationid

    varchar2 (100)


  • sdh_checktag_error lists errors in the check tag filter. The format is: create table sdh_checktag_error

    Table 13-5 sdh_checktag_error table

    Column Type

    filtername

    varchar2 (100)

    tagid

    clob

    sitename

    varchar2 (100)

    text

    clob

    time

    timestamp


  • sdh_devicefailure lists device failures. The format is: create table sdh_devicefailure

    Table 13-6 sdh_device failure table

    Column Type

    devicename

    varchar2 (100)

    sitename

    varchar2 (100)

    error

    clob

    time

    timestamp


  • sdh_filter_perf displays filter performance. The format is: create table sdh_filter_perf

    Table 13-7 sdh_filter_perf table

    Column Type

    filtername

    varchar2 (100)

    diff_count

    clob

    sitename

    varchar2 (100)

    time

    timestamp


13.1.3.1.10 Sending Instructions

On reacting to an event (or at any point in time), if an application needs to send an instruction to a device (for example, to light up a light stack), the application posts an event into the ADT queue named edg_instr_q_in.

Table 13-8 Sending Instructions

Field Description

correlationld

Unique message ID for threading

siteName

The target site

deviceName

The target device

time

Time the message was sourced

type

Set to 100

subtype

Subtype code:

0 - Report status

1 - Turn on

2 - Turn off

All other subtype codes are custom types

id

Minor device number or name

data

Device-specific parameters

sourceName

Name of source


13.1.3.1.11 Route and Instructions Mapping

In order for an application to know where to return alerts and instructions upon receiving an event or some other condition, an extra layer of abstraction is provided to map the event source to a list of destinations.

The destinations may be light stacks, or message boards that may be physically close to the source of the events. It is possible to send alerts to other (remote) devices such as phones other devices. This type of remote notification requires separate development work.

The application can also map a custom condition to a series of operations.

13.1.3.1.12 Route Mapping

A Route Map is a map of a certain criteria to a list of destinations. The criteria is defined by the following elements:

  • SITE_NAME

  • DEVICE_NAME

  • CONDITION_NAME

  • PRIORITY

By providing the SITE_NAME, DEVICE_NAME, a custom CONDITION_NAME and a PRIORITY, the edg_utl's route_map_fire_instruction procedure forwards predetermined instructions to various devices in response to a given condition. For example, sensor observations by one device determines whether another (target) device is on or off. By putting an instruction into a mapping table and calling a procedure, instruction(s) can be sent when a given condition is met.Each relevant destination can also have a priority associated to it for Instruction Ordering. Once the destinations are resolved from the Route Map, Instructions that have already been associated with the SITE_NAME/DEVICE_NAME/CONDITION_NAME combination are sent to the appropriate destinations in the given priority.Here is an example of how to use this API:

Example 13-4 edg_utl.route_map_fire_instruction example

begin
    edg_utl.route_map_fire_instruction(
device_name => 'device',
site_name => 'sitename',
cond => 'name of the condition');
end;
/ 

13.1.3.2 edg_utl Package

The edg_utl PL/SQL package contains utility functions that simplify common tasks required for accessing the Sensor Data Hub. The package is created under the EDGE user schema. The following table lists all the functions exposed in the edg_utl package.

Table 13-9 edg_utl functions

Function Parameters Description

ADD_RULE

RULENAME: Name of rule

CONDITION: Rule condition

EVAL_CTX: Context (null usually)

ACT_CTX: Action context (null usually)

PARAM: Parameter for action

ACTION: Action

Create a new rule with the name RULENAME. For details on the EVAL_CTX and ACT_CTX, please refer to the Streams documentation.

ACTION can be either 'call' or 'queue'

REMOVE_RULE

RULENAME: Name of rule

EVAL_CTX: Evaluation context (null usually)

Remove a rule previously created with the name defined in "RULENAME"

CHECK_DISPATCH_JOB_EXIT

None

Returns true if the automatic evaluation job is terminated. This is an error condition; the job should be running under normal conditions. This function is mostly for internal use.

SET_LOG_LEVEL

LEVEL: Current log level

Set the current logging level to "LEVEL". If set to 0, there will be no logging

SENDTOEDGE

TYPE: Type of event

SUBTYPE: Sub type of event

ID: Identifier list

SITENAME: Name of site to send to

DEVICENAME: Name of device to send data to

DATA: data payload of the event

TIME: time event was first generated

SOURCENAME: name of sender

CORELATIONID: Correlation ID

Send an event to the Edge Server. This function is used for sending instruction events to the devices in the Edge Server.

SENDTOSTAGE

TYPE: Type of event

SUBTYPE: Sub type of event

ID: Identifier list

SITENAME: Source siteName

DEVICENAME: Source device

DATA: Data payload of the event

TIME: Time event was first generated

SOURCENAME: Name of sender

CORRELATIONID: Correlation ID

Send an event to the Streams staging area. This is useful for testing your rules without the need to set up an Edge Server and simulator. Any event sent to the staging area will be evaluated by the ruleset.

CHECKDEVICE

SITENAME: Site name where device resides

DEVICENAME: Name of device to check

Verifies device is still up and running. The device sends back a message with the same correlation ID, stating in the data payload whether it is "UP" or "DOWN"

STARTDEVICE

SITENAME: Name of site where device resides

DEVICENAME: Device to start


STOPDEVICE

SITENAME: Name of site where device resides

DEVICENAME: Device to stop

Stop a device

ROUTE_MAP_FIRE_INSTRUCTION

DEVICENAME: Name of device

SITENAME: Site device resides

COND: Condition to look for

MSG: Message to display

Send groups of instructions to devices if the specified condition met


For example, to send an event to a device called MyLight, with type 105, subtype 2, you could write:

Example 13-5 edg_utl to send an event

SQL> edg_utl.sendToEdge( 105, 2, 'MySite', 'MyLight', 'dummyData', CURRENT_TIMESTAMP, '', '' );

To start a device called MyLight:

Example 13-6 edg_utl to start a device

SQL> edg_utl.startDevice( 'MySite', 'MyLight' );

13.1.3.3 Java Messaging Services

The Java Messaging Services (JMS) is a standard messaging API that J2EE components use to communicate. The Oracle Sensor Edge Server provides a JMS Dispatcher to enable users to relay events to JMS topics.

13.1.3.3.1 Configuration

In order for the JMS Dispatcher to connect to the queue to which it posts events, the administrator must provide the configuration parameters listed in the following table:

Table 13-10 JMS Parameters

Parameter Format Description

provider

Text(URI)

The URI used to connect to the OC4J instance where the topic is stored. This URI is used internally by oc4j ormi to connect to the server. For example: ormi://oc4j.us.oracle.com

password

Text

Password for using the OC4J instance

username

Text

Username for using the OC4J instance

ack

Text

Values (optional) are set to auto or client; default is auto.

enterprise_mode

Text

Signals (to the JMS parameter) if it is running as part of an enterprise, or as standalone. Default is false.



Note:

Oracle Sensor Edge Server runs in enterprise and standalone (Java) modes. If you are developing applications to run in both modes, ensure that all parameter names are composed of one word, and do not contain other characters (such as apostrophes, special characters).

To set up the JMS queue, the administrator must configure a JMS topic named 'edgeTopic' and make it accessible by the Oracle Sensor Edge Server components. The administrator must also confingure a JMS TopicConnectionFactory (named 'edgeEventsConnectionFactory'). This is done by configuring the jms.xml file under the oc4j container. See the OC4J documentation for details on how to configure a JMS queue.

The JMS Dispatcher (at startup) looks for the JMS topic named edgeTopic using JNDI from the container. If this resource is not found, the Dispatcher returns an error and exits.

13.1.3.3.2 Client Interface

The JMS Dispatcher posts new events to the OC4J JMS queue topic.

A JMS Listener can subscribe to these queues in the JMS Server. When events arrive, the fields of the event are specified in message properties. The keys to these properties are defined in a the java class oracle.edge.rt.RTConstants. In the enterprise version, you can find this class in ORACLE_HOME/wireless/lib/wireless.jar. In the standalone version, you can find this class in ORACLE_HOME/j2ee/home/applications/edge/edge-web/WEB-INF/lib/edge.jar.

Table 13-11 specifies the keys and types of these message properties.

Table 13-11 Message properties keys

Key Type

RTConstants.DISPATCH_PROPERTY_TYPE

string

RTConstants.DISPATCH_PROPERTY_SUBTYPE

string

RTConstants.DISPATCH_PROPERTY_ID

string

RTConstants.DISPATCH_PROPERTY_SITENAME

string

RTConstants.DISPATCH_PROPERTY_DEVICENAME

string

RTConstants.DISPATCH_PROPERTY_DATA

string

RTConstants.DISPATCH_PROPERTY_TIME

long (milliseconds)

RTConstants.DISPATCH_PROPERTY_SOURCENAME

string

RTConstants.DISPATCH_PROPERTY_CORRELATIONID

string


13.1.3.3.3 Sending Instructions

This release of the Oracle Sensor Edge Server does not support applications sending instructions back to devices using the JMS Dispatcher. This functionality is only supported for the Streams Dispatcher.

13.1.3.4 Web Services

Another method supported by the Oracle Sensor Edge Server to distribute events is through Web Services, or more specifically SOAP calls.

A client can register a SOAP call which the server can invoke when a new message must be delivered. The following parameters must be provided by the client:

WebService EndPoint URL—this URL points to the WebService's EndPoint.

13.1.3.4.1 Configuration

If the Web Service dispatch method is selected, the client must instruct the Oracle Sensor Edge Server how to call it when an event is received. The parameters in the following table are required; they are stored under the Configuration Framework.

Table 13-12 Web Services Parameters

Parameter Format Description

url

text(URL)

The URL that points to the WSDL file that describes the client call. The WSDL file must contain the Port Type EdgeClientCallback, and within it, the call processEvent.



Note:

Oracle Sensor Edge Server runs in enterprise and standalone (Java) modes. If you are developing applications to run in both modes, ensure that all parameter names are composed of one word, and do not contain other characters (such as apostrophes, special characters).

13.1.3.4.2 Callback Interface

When an event is received, the Web Service Dispatcher calls the method processEvent the WebService that is specified in the URL parameter. The WebService has the following signature:

public void processEvent( long type, long subtype, String tagid, String siteName, String deviceName, String data, Date time )

Table 13-13 Callback Interface Parameters

Part (or Parameter Name) Format Description

sitename

Text

Name of the site that read this tag

devicename

Text

Name of the device that read this tag

time

Time

Date and time the observation was made

type

Long

Type of event. See Table 13-16, "Event Format" for more information.

subtype

Long

Values vary, depending on the custom drivers and filters used.

data

Text

Optional data read from the tag (in base64 format)


13.1.3.4.3 Sending Instructions

This release of the Oracle Sensor Edge Server does not support applications sending instructions back to devices using the Web Services Dispatcher. This functionality is currently only supported for the Streams Dispatcher.

13.1.3.5 HTTP Interface

When HTTP client interface is chosen, the server uses standard HTTP 1.0 protocol to communicate with the client.

The client must provide a URL to which the Oracle Sensor Edge Server will post. When an event is received, the Oracle Sensor Edge Server initiates an HTTP Post command to the provided URL. The data is provided in the Post data. Note that each event is a separate post. All posts are performed sequentially, so if one post is blocked, other posts will not go through.

13.1.3.5.1 Configuration

If the HTTP dispatch method is selected, the client must tell the Oracle Sensor Edge Server where to post data when an event is received. The following parameters are required and are stored under the Configuration Framework:

Table 13-14 HTTP Interface parameters

Parameter Format Description

url

Text(URL)

The URL that points to the client application. The Oracle Sensor Edge Server posts to this URL whenever a new event is to be dispatched.



Note:

Oracle Sensor Edge Server runs in enterprise and standalone (Java) modes. If you are developing applications to run in both modes, ensure that all parameter names are composed of one word, and do not contain other characters (such as apostrophes, special characters).

13.1.3.5.2 Callback Interface

If the HTTP dispatch method is selected, the Sensor Edge Server calls the url listed in the parameters with a post of the following parameters:

Table 13-15 Callback Interface Parameters

Part (or Parameter Name) Format Description

siteName

Text

Site ID where this tag was originally read

deviceName

Text

Device ID where this tag was originally read

time

Text (alphanumeric)

Return the timestamp of the point when the tag is read. The value is the difference, in milliseconds, between the current time and January 1, 1970.

type

Text(Numeric)

A numeric text that defines the type of the event.

subType

Text(Numeric)

A numeric text that defines the type of the event.

id

Text(hex)

This is the identifier of the tag read in hexadecimal.

data

Text

Optional data that is read together with the tag ID.


13.1.3.5.3 Sending Instructions

This release of the Oracle Sensor Edge Server does not support applications sending instructions back to devices using HTTP. This functionality is only supported for the Streams Dispatcher.

13.1.3.6 Custom Event Dispatcher

The Oracle Sensor Edge Server allows custom dispatchers to be loaded at runtime. The configurations for these dispatchers must be provided in an xml file and loaded into the Oracle Sensor Edge Server. The dispatcher must implement certain functions to provide the ability to send Events and also receive Instructions and other commands. To implement a dispatcher, see Oracle Application Server Administrator's Guide.

13.1.3.7 Sensor Data Hub

The term Sensor Data Hub (SDH) refers to a collection of standard out-of-the-box supported views and data objects. The constructs provide common functions used by most applications to shorten application development time.

13.1.3.8 Event

In all the client interfaces described, you will see the class or type Event being mentioned. This section describes the format and details usage of the fields in the Event type.

The Event type is a representation of a message that is sent from one component to another. An event is fixed-format but is extensible by mapping the existing fields to different meanings, depending on the type of event.

The following table shows the generic format of an Event:

Table 13-16 Event Format

Section Field Format Description

Routing Headers

sourceName

Text

(optional) Identifies who originally created the event.


correlationId

Text

(optional, client-generated) Correlates a response to the instruction.

Message Headers

siteName

Text

Site from which this message originated.


deviceName

Text

Device (or application) from which this message was generated.


time

Time

Date and time the observation or message was created.

Type Info

type

Long

Type of event.


subtype

Long

Subtype of the event.

Payload

id

Text

Identifier of a read or target to an instruction.


data

Text

Optional data.


The Event is split into the following sections:

Header—contains delivery information only. The header section contains these fields:

  • correlationId—provided by the client; used for message responses to a particular client. It is up to the client to set it. Any message sent back in response to a client will have the same Id.sourceName—typically set to the name of the client for more efficient routing. The dispatch method may or may not use it to provide routing depending on this ID. It is up to the client to set it.

Type Info—information about how this Event's payload section is formatted. The type field of Event Type Info define the type of the message you are sending or receiving. The type field is assigned in a range depending of the type of the message:

  • 0-99—System Messages

  • 100-199—Instructions/Commands

  • 200-299—Observations

More types can be defined, but currently the following types are available:

  • 0: Unknown—If a event is set with type 0, it is either a bad event, or it is a system internal event. It should be ignored

  • 1: Message Event—The message is a confirmation message, which is usually the return result code of a corresponding instruction requested

  • 100: General Instructions—General instructions for controlling devices

  • 101: RFID Instructions—Instructions to RFID devices

  • 200: RFID Observation—The message is an RFID observation

  • 201: RTLS

  • 202: Physical Contact—(laser diode, dry contacts, and others)

  • 203: Temperature

  • 204: Humidity

  • 205: Weight

  • 206: Tampering

  • 207: Audio

  • 208: Message Board

EventPayload—Event-specific section with a specific data format (depending on the type of event or instruction).

  • 102: Printer Instructions

  • 103: Light Stack Instructions

13.1.3.8.1 System Events

System Events are messages that the system reports to various layers. These messages can be informational, warning and error messages. By trapping or writing rules against these events, applications can report or provide better error recovery and handling.

13.1.3.8.2 Message Events

A message event is one that is sent to report a state, error condition, or a confirmation. The following table shows the usage of the fields in the Event data type:

Table 13-17 Event Data Type Fields

Field Description

type

Set to 1

subType

Codes:

0 - Successful (confirmation)

1 - Error (confirmation)

2 - Error report

3 - Function not supported

4 - Edge Server startup

5 - Edge Server shutdown

6 - Dispatcher connection failed

7 - Dispatcher connection online again

8 - Dispatcher stopping

9 - Dispatcher starting

10 - Notification

id

Error or success code.

data

Error of status message text.


13.1.3.8.3 Instruction Events

An Instruction Event is usually sent by an application to tell a specific device to perform some operation.

General Instruction Event—The following table shows the usage of the fields in the General Instruction Event data type:

Table 13-18 General Instruction Event Data Types

Field Description

type

Set to 100

subtype

Codes:

0 - Get status

1 - Turn on

2 - Turn off

id

Minor device number or name

data

Device-specific parameters


RFID Instruction Event—An RFID Instruction Event is sent by an application to tell it to print out a label. The following table shows the usage of the fields in the RFID Instruction Event data type:

Table 13-19 RFID Instruction Event Data Types

Field Description

type

Set to 101

subtype

Codes:

0 - Write to tag

1 - Destroy tag

2 - Get field strength

3 - Read tag payload

id

Tag id

data

Device-specific parameters


Print Instruction Event—sent by an application to tell the system to print out a label. The following table shows the usage of the fields in a Print Instruction Event data type:

Table 13-20 Print Instruction Event Data Types

Field Description

type

Set to 102

subtype

0 - Print by template

1 - Print direct

id

Template name

data

XML or print data file


The print data is an XML file that contains all the fields to be printed, or the actual print raw data file (depending on the subtype code) The XML data file specifies a list of name value pairs. These fields are mapped to the actual printer descriptor fields based on the label type and meta data in the EDG_PRINTCAP table.

The EDG_PRINTCAP table has the following format:

Table 13-21 EDG_PRINTCAP table fields

Field Description

TYPE

Print label type

SOURCEVAR

Name of the source tag

TARGETVAR

Target tag name


Light Stack Instruction—A Light Stack Instruction is sent by an application to tell the system to do something with a light stack. Table 13-22 shows the usage of the fields in the Event Data Type:

Table 13-22 Light Stack Instruction Event Data Types

Field Description

type

Set to 103

subtype

1 - Light Stack command

data

XML


13.1.3.8.4 Observation Events

Observation events are events generated by sensors when they observe the presence (or stage changes) for tagged items.

RFID Observation Event—sent when an RFID reader reads a new tag (assuming it passed through all of the filters). The following tables shows the usage of the fields in the Event Data Type:

Table 13-23 Event Data Types for RFID Observation Events

Field Description

subtype

Codes:

0 - Unknown or bad message

1 - In Field Event

2 - Out Field Event

3 - Pass Thru Event

4 - Pallet In Field Event

5 - Pallet Out Field Event

6 - Pallet Pass Thru Event

7 - Container Event

id

RFID Tag ID of the tag read, in hexadecimal. This may be a list of IDs, which are comma-separated.

data

If the tag has extra payload (extra memory), it is stored here.


13.2 Tutorial: Writing Sensor-based Applications Using Streams

This tutorial demonstrates how you can build your own custom applications. Other tutorials for Oracle Sensor Edge Server are posted on Oracle Technology Network.

13.2.1 Overview of the Tutorial

This tutorial describes how to use Oracle Database Streams technologies with the Oracle Sensor Edge Server to build applications and Rule-based Agents.

13.2.1.1 Requirements

The following components are required before you can use this sample project:

  • J2SE 1.4.x

  • JDeveloper (10g)

  • Oracle Sensor Edge Server

  • Oracle Database 9.2 or later

13.2.2 Understanding Streams and Oracle Sensor Edge Server Integration

Before beginning, here is some background information about how the Oracle Sensor Edge Server works with Oracle Streams.

13.2.2.1 What is Streams?

Oracle Streams enables the propagation and management of data, transactions and events in a data stream in one database, or across multiple databases. It enables you to manage and transform large amounts of data flowing through your Streams database. Sensor data is a data source that can be managed through Streams.

There are three stages to Streams:

  • Capturing—taking in data from various sources to upload to a staging area for processing. The staging area is either an Advanced Queue or simply a table.

  • Staging—once data and events are captured, events are placed in a staging area, this is the Staging Phase. Subscribers examine the contents of the staging area and then determine what to do with the events.

  • Consumption—the events and data are applied to the database. You can build your own custom Streams for handling your data.

13.2.2.2 Oracle Sensor Edge Server and Streams

Oracle Sensor Edge Server supports using Streams as a distribution method; Streams is the recommended model because it provides the most flexibility, robustness and features.

When events are read in the devices, they are normalized by the drivers and sent out for filtering. After the data is cleansed and filtered, they are passed to the dispatchers to distribution.

Streams does not communicate directly with the application; it uses the Streams Dispatcher to hand off the events into a Streams Staging area (See the following diagram).

Figure 13-2 Architecture of Streams Dispatcher

The Streams Dispatcher hands off events to Streams Staging Areas.
Description of "Figure 13-2 Architecture of Streams Dispatcher"

Once the events are put into the Staging Area (which is an internal queue), the Oracle Sensor Edge Server's job is done. The rest of the process is handled by the database.

If you have installed the post installation scripts from the Oracle Sensor Edge Server for supporting Streams, you will gain extra functionality described below.

13.2.2.3 What Happens to the Events in the Database?

After events are deposited into the staging area, a background job picks them up and evaluates them against a set of rules. The rules are conditions that an event can either match or not. If the condition is satisfied for this event, an action will be taken. These actions, like the conditions, are user defined.

13.2.2.4 Rules and Actions

Each event that is staged is evaluated against the rules in the system. If any of them comes back positive, the action that is associated with the rule is executed. Rules are comprised of:

  • Name

  • Condition

  • Command

  • Parameter

Name is a unique rule name provided by the caller who created the rule. After creation, the rule name can be searched, changed, or deleted.

Condition is like a WHERE clause, but without the WHERE keyword. For example, if you want to match all tags with tag ID that starts with 159, you can use the condition tab.user_data.tagid LIKE '159%'. The prefix tab.user_data tells it to use the current event as the context.

Once the condition is met, the associated action is taken. Each action, is further broken down into:

  • Command

  • Parameter

Command gives the command (such as call to call a PL/SQL procedure, or queue to push the event to another queue).

Parameter is the parameter for the command. Call is the PL/SQL name; queue is the queue name.

13.2.3 Running the Tutorial

First, decide which interface model you want; here are the choices:

  • PL/SQL Procedure Callback—If you want to write a PL/SQL procedure that will be called whenever an event comes in or a condition is met that is of interest to you, choose this model.

  • Queue Propagation—The Oracle Sensor Edge Server can propagate events to various queues based on different conditions, then your application can be driven off these queues.

  • Querying the Sensor Data Archive—For traditional pull and query-based applications, you can query events and data off the Sensor Data Archive.

If your application is asynchronous or event-driven, meaning that it is more reactive to certain conditions or as events are received, then you need to decided between Queue Propagation or PL/SQL callback.

If your application is PL/SQL based and does not require long processing time, use PL/SQL callback; it is simple and easy to debug.

If you need to do time-consuming processing, and are concerned with keeping up with the data rate, you should use Queue Propagation.

If you are writing your application in Java, you should use Queue Propagation and then process the events by using JMS directly, or build your component as a MDB. For more information, see the JMS tutorial on Oracle Technology Network.

Choosing the model to use is easy. If your application is user interface-based, or batch processing-based, most likely you will need a pull model.

In this tutorial each of these models will be used, and you will see their advantages and disadvantages. However, no matter which model you choose, you must do some basic post-installation setups.

13.2.4 Setting Up Streams Support and Sensor Data Archive

Before you can use the Streams Dispatcher, you must set up a database instance to hold the Streams staging area, the rules, queues, Sensor Data Archive, and other related data. Once the schema is ready, you can point the Dispatcher of the Oracle Sensor Edge Servers to it to start collecting data.

13.2.4.1 Setting up the Database Instance

Set up a database instance. You can either use the Standard or Enterprise Edition of the Database, but it must be 9.0.2 or later. Once you have the instance, make sure you note the GDN (Global Data Name), and the administrator's user name and password.


Note:

The database that your Streams Dispatcher points to must be running Oracle Database 9i Release 2 or later; this is because the Streams Dispatcher relies on the Streams packages of the database that were introduced in Oracle Database 9i Release 2.

If the database instance is on a separate machine (from Oracle Sensor Edge Server), you must edit ORACLE_HOME/network/admin/tnsnames.ora on the Oracle Sensor Edge Server machine to add the GDN to it.

13.2.4.2 Post-Installation

After setting up the database instance, set up the schema that the Streams Dispatcher will use. To do so, follow these steps (from the command line; all of the scripts mentioned here are in the \wireless\repository\sql directory.):

  1. Go to ORACLE_HOME\wireless\repository\sql.

  2. Start SQL*Plus, and use it to connect to your database instance as the administrator (user dba).

  3. Run create_edg_user.sql to create the necessary user permision.This script will prompt your for the password for the user EDGE. Enter any password you like, but note it for your reference.

  4. Log out of SQL*Plus.

  5. Log in to SQL*Plus again, this time as the user EDGE. For example, if your GDN name is SDH, run sqlplus edge@sdh.

  6. Run the script edg_create_streams.sql to create the internal queues, ruleset, and other streams-related data and schema.

  7. Run the script edg_create_sdh.sql to create the Sensor Data Hub schema. If you do not need the Sensor Data Hub, omit this step.

Once you have executed the scripts, you will have a user in your database called EDGE. Under that user, all the necessary schemas and data will be created. The background jobs are also started automatically. For example, if your database is named mydb, your Sensor Edge Server is installed in C:/oracle/edge, and administrator password is manager, you can run the following commands to set up the database:

Example 13-7 Commands used to set up the database

C:/> cd /oracle/edge
C:/oracle/edge> sqlplus system/manager@mydb @create_edg_usr.sql
SQL> password: edge <-- Enter your password, here we will use "edge"
SQL> exit
 
C:/oracle/edge> sqlplus edge/edge@mydb 
SQL> @edg_create_streams.sql
....
SQL> @edg_create_sdh.sql
....
SQL> exit
 
C:/oracle/edge>

Once you have done this, you are able to see the schema. Do a select * from sdh_events table to verify.

13.2.4.3 Configuring the Streams Dispatcher

Now that your database is prepared, you can begin sending it sensor observations.


Note:

For information on switching to, or setting up the Streams Dispatcher, see Oracle Application Server Wireless Administrator's Guide.

To configure the Streams Dispatcher:

  1. With a web browser, connect to the Sensor Services tab within the Wireless webtool.

  2. Click Manage Edge Dispatchers.

  3. From the drop-down list select StreamDispatcher.

  4. Change the password for the edge user in the password parameter.

  5. Change the parameter url to point to your database instance.

  1. Click OK.

  2. Restart the Sensor Edge Server. If the Sensor Edge Server is attached to simulators or real devices, you will begin to see the events coming into the database.

To verify that the dispatcher is connected properly, see wireless\logs\log.xml. You should see the following lines:

Tue Sep 14 19:06:15 PDT 2004: StreamsDispatcher: Attempting to create Q connectionsTue Sep 14 19:06:15 PDT 2004: StreamsDispatcher: Creating topic connectionTue Sep 14 19:06:21 PDT 2004: StreamsDispatcher: Creating topic sessionTue Sep 14 19:06:22 PDT 2004: StreamsDispatcher: Creating topic publisherTue Sep 14 19:06:22 PDT 2004: StreamsDispatcher: Creating topic subscriberTue Sep 14 19:06:26 PDT 2004: StreamsDispatcher: Finished initialization

If you see that initialization failed, your connection string or password is probably wrong, or the database is not seeded properly.

To test incoming events, from SQL*Plus, login as EDGE user, and execute: SELECT * FROM SDH_EVENTS. This is where all the observation events are archived. You should see it grow. If not, run the simulator and make sure the events are piping through.

Now that the Oracle Sensor Edge Server is ready, you can begin to code.

13.2.4.4 Adding Rules

To add Rules to the instance, follow these steps:

  1. Connect to the database as user EDGE, for example: sqlplus edge/edge@mydb.

  2. Run the following PL/SQL procedure: call edg_utl.add_rule( 'RuleName', 'Condition', NULL, NULL, 'Parameter', 'Command' );

    Where:

    'RuleName' is a unique name for the rule'Condition' is the rule condition'Parameters' is the parameter for the rule 'Command' is the command to invoke if the condition is satisfied

13.2.4.5 Testing Your Rules

You can test your Rules, even with the Sensor Edge Server running.

To test your Rule:

  1. Connect to your database as user EDGE, for example: sqlplus edge/edge@sdh.

  2. Call the utility function as follows: call edg_utl.sendToStage( type, subtype, id, siteName, deviceName, data, time, sourceName, correlId );

  3. If the event matches one of your Rules, your callback will be called, or the event will be propagated to your queue (depending on the command you used).

  4. To check for execution errors: select message from edg_log order by msg_time;

The utility function edg_util.sendToStage() sends an event directly to the staging area, which is evaluated by the Rules.

The EDG_LOG table stores any errors it encounters during execution.

13.2.4.6 Defining Conditions

A Rule's action is executed when the Condition clause is satisfied.

Condition is basically the WHERE clause of a SQL statement, with some distinctions. The event being evaluated is defined in the context tab.user_data (for details, see the DBMS Streams documentation for this construct). To see the fields in the event, execute desc edg_event, which will show you the definition of the EDG_EVENT ADT type. For example, if you want to look for any event that has a type value of 203, and an ID that begins with epc:, use the condition:

tab.user_data.type.type = 203 AND tab.user_data.id LIKE 'epc:%'

For more complex rules (such as joins with other lookup tables and so on), you can create PL/SQL functions, or better yet, use Streams context (see DBMS Streams documentation for more information).

13.2.4.7 Commands and Parameters

Once you have defined the condition, you must instruct the Oracle Sensor Edge Server as to what to do when the condition is met. This is specified in the command and parameters field.

There are two types of commands supported in this release:

'call' which calls a PL/SQL callback

'queue' which propagate the event to another queue

If the command is a 'call', the parameter field should be set to:

'schema.package.procedure'

For example, if a procedure is defined in the schema 'edge', in package name 'my_pkg', called 'testproc', then the parameter is:

'edge.my_pkg.testproc'

If the command is 'queue', then the parameter is set to the name of the queue you want to propagate to. Note that this queue must be created based on EDG_EVENT ADT type (future releases will support marshalling to different queue formats).

13.2.4.8 Creating Your Own Instances

If you want to clear out the instance and re-initialize it to start over, you can do so by dropping the edge user from the Oracle Sensor Edge Server. Note that all data and PL/SQL built in the edge user will also be cleared; back up any data you need before following these steps:

  1. Log in, for example: sqlplus edge/edge@sdh.

  2. Run exec edg_utl.deschedule_job.

  3. Log out.

  4. Connect to the database as administrator, for example: sqlplus edge/edge@sdh.

  5. Run the SQL command to drop the user as follows: drop user edge cascade;

  6. Exit from SQL*Plus.

Upon completion, you can re-initialize the instance.

13.3 Tutorial: Using Streams to Propagate Sensor Events to AQ

This tutorial demonstrates how to define Rules to propagate events to your applications AQ. Other tutorials for Oracle Sensor Edge Server are posted on Oracle Technology Network.


Note:

The SiteName displayed for any events (including simulated events) is the SiteName that was set using Enterprise Manager. For security reasons, Site names are always overwritten with the Enterprise Manager's SiteName; others are ignored.

13.3.1 Overview

This tutorial describes how to define Rules to propagate events to your applications AQ. Ensure that you have completed the set up tutorial before completing this tutorial.

13.3.1.1 Requirements

The following components are required before you can use this sample project:

  • J2SE 1.4.x (downloadable from Sun's web site (http://www.javasoft.com)

  • Oracle Sensor Edge Server

  • Oracle Database 9.2 or later

13.3.2 Getting Started

Decide on the development model you want to use. By using the Streams Dispatcher, you have a few options:

  • PL/SQL Procedure Callback—If you want to write a PL/SQL procedure that will be called whenever an event arrives, or a condition is met that is of interest, choose this model.

  • Queues Propagation—Sensor Edge Server can propagate events to various queues based on different conditions, then your application can be driven off these queues.

  • Querying the Sensor Data Archive—For traditional pull and query-based applications; you can query events and data off the Sensor Data Archive.

This tutorial shows how to define rules to propagate to different queues.

13.3.3 Creating Queues

You must first create a queue to receive the events. The following code creates a queue named my_q. Connect to the database (as user EDGE) to run these:

EXECUTE DBMS_AQADM.CREATE_QUEUE_TABLE( queue_table => 'my_q_table', queue_payload_type => 'EDG_EVENT' ); EXECUTE DBMS_AQADM.CREATE_QUEUE(

queue_name => 'my_q', queue_table => 'my_q_table' ); EXECUTE DBMS_AQADM.START_QUEUE( queue_name =>'my_q' );

Now that you have created the queue, you are ready to set up rule(s) to propagate to it.

13.3.4 Creating Rules

To create a Rule to retrieve all events with IDs starting with epc, follow these steps:

  1. Connect to your database, for example: sqlplus edge/edge@sdh.

  2. Run this command: call edg_utl.add_rule( 'MyTestRule3', 'tab.user_data.id LIKE ''epc:%'' ', NULL, NULL, 'my_q', 'queue' );

Now that the rule is set, you can test it.

13.3.5 Test Run

Send a simulated event from your simulator. You can even send it without using Sensor Edge Server:

  1. Connect to your database using SQL*Plus.

  2. Run the command: call edg_utl.sendToStage( 1, 1, 'epc:12345', 'MySite', 'MyDevice', 'data', sysdate, 'src', 'cor' );

The procedure generates and sends out a dummy event with the ID set to 456. To verify that it worked, look at your Sensor Data Archive. This event should be there: SELECT id FROM SDH_EVENTS;

If you run SELECT from your queue table or deque from it, you should see the events coming in.

13.4 Tutorial: Writing Sensor-based Applications with PL/SQL Callbacks

This tutorial demonstrates how to write applications in the database that can react to observations or generate events to edge devices. Other tutorials for Oracle Sensor Edge Server are posted on Oracle Technology Network.

13.4.1 Overview

This tutorial describes how to write applications in the database that can react to observations or generate events to edge devices. Ensure that you have completed the Streams set up tutorial before completing this tutorial.

13.4.1.1 Requirements

The following components are required before you can use this sample project:

  • J2SE 1.4.x (J2DK is downloadable from Sun's web site (http://www.javasoft.com)

  • Oracle Sensor Edge Server

  • Oracle Database 9.2 or later

13.4.2 Getting Started

Decide on the development model you want to use. By using the Streams Dispatcher, you have a few options:

  • PL/SQL Procedure Callback—If you want to write a PL/SQL procedure that will be called whenever an event arrives, or a condition is met that is of interest, choose this model.

  • Queues Propagation—Sensor Edge Server can propagate events to various queues based on different conditions, then your application can be driven off these queues.

  • Querying the Sensor Data Archive—For traditional pull and query-based applications; you can query events and data off the Sensor Data Archive.

Here's how to choose which model to use:

  • If your application is user interface-based, or batch processing-based (mostly query information about the items being sensed) most likely you will need a Pull model, which is Querying the Sensor Data Archive.If your application is more asynchronous or event-driven, meaning that it is more reactive to certain conditions, or as events are received, you can use either Queue Propagation or PL/SQL callback.

    To distinguish between these two: if your application is PL/SQL-based and does not require long processing time, use the PL/SQL callback. It is simple and easy to debug. However, if you need to do time-consuming processing, and you are worried about not being able to keep up with the data rate, use Queue Propagation.

    Lastly, if you are writing your application in Java, you should use Queue Propagation, and then process the events by using JMS directly or build your component as a Message Driver Bean. Please note that if you are using Streams, you cannot use Message Driven Beans. Message Driven Beans will work with the OC4J JMS only. For more information on this, please refer to the JMS tutorial available on Oracle Technology Network.

13.4.3 Source Code

The source code, configuration files and project files are included with this tutorial. You can download the files at: http://www.oracle.com/technology/products/iaswe/edge_server/tutorials.html.

13.4.4 Writing the Application

This tutorial demonstrates how to write a simple application that defines a rule for detecting a simple theft condition, and calls your PL/SQL code when that condition is met.

The first step is to define a theft condition. To do so, use a simple lookup table such as:

create table lookup ( id varchar2(128), state number );

The column lookup.id is the tag item of the item, and lookup.state is set to 0 if the item is paid for. If an event comes in from a gate that says it has detected a certain item and if that tag ID is in this table and it's state is not 0, then it is theft, in this simple case, at least.When this condition is met, make it call the callback procedure.

13.4.5 The PL/SQL Package

The PL/SQL package will have two functions: isTheft which returns true when a theft condition is met, and myCallBack which is the callback function.

Create the lookup table, and feed it some data, as in Example 13-8.

Example 13-8 Creating a lookup table

-- Create lookup table
DROP TABLE lookup;
CREATE TABLE lookup( id varchar2(128), state NUMBER );
 
-- Seed lookup table
INSERT INTO lookup values ( '123', 0 );
INSERT INTO lookup values ( '456', 1 );
INSERT INTO lookup values ( '789', 1 );
 
-- Create table to store theft info
DROP TABLE stolen;
CREATE TABLE stolen ( ev EDG_EVENT );
 
commit;
/
 
In this case, 123 is paid for, but 456 and 789 are not.
The following package interface defines these procedures:
-- Create Package
CREATE OR REPLACE
PACKAGE test_pkg 
 Authid Current_User IS
 
 FUNCTION  isTheft ( l_id IN VARCHAR2 ) RETURN NUMBER;
 PROCEDURE myCallBack ( ev IN EDG_EVENT );
 
end test_pkg;
/

This defines two required functions, shown in Example 13-9 .

Example 13-9 Required functions

-- Create Package
CREATE OR REPLACE
PACKAGE test_pkg 
 Authid Current_User IS
 
 FUNCTION  isTheft ( l_id IN VARCHAR2 ) RETURN NUMBER;
 PROCEDURE myCallBack ( ev IN EDG_EVENT ); 
 
end test_pkg;
/
 
-- Now the Body
CREATE OR REPLACE PACKAGE BODY test_pkg IS
 -- Returns 1 if it is stolen
 FUNCTION  isTheft ( l_id IN VARCHAR2 ) RETURN NUMBER
 IS
    TYPE num_tab      IS TABLE OF NUMBER;  
    states                  num_tab;
 begin
 
-- See if id is in lookup table
SELECT id BULK COLLECT INTO states FROM lookup WHERE id = l_id AND state <> 0;     
 
IF SQL%ROWCOUNT > 0 
THEN
        RETURN 1;
ELSE
        RETURN 0;
END IF;
end;
 
PROCEDURE myCallBack ( ev IN EDG_EVENT )
IS
BEGIN
   DBMS_OUTPUT.PUT_LINE( 'Got Event!' );
   INSERT INTO stolen values ( ev );
END;
 
end test_pkg;
/

Once you have applied them to your database using SQL*Plus, you can test it. To test the function, run this command to see it 123 is stolen:

SQL> select test_pkg.ISTHEFT('456') from dual;

This should return 1, meaning that the item is not paid for. Next, you will create a Rule.

13.4.6 Creating the Rule

The condition is relatively simple because more of the work is done inside the function isTheft(). Follow these steps to create the rule:

  1. Connect to the database, for example: sqlplus edge/edge@mydb.

  2. Run this command: call edg_utl.add_rule( 'MyTestRule2', 'test_pkg.isTheft(tab.user_data.id) = 1', NULL, NULL, 'test_pkg.myCallBack', 'call' );

When this is done, you can test.

13.4.7 Test Run

Send a simulated event from your simulator. You can even send it without using Sensor Edge Server:

  1. Connect to your database using SQL*Plus.

  2. Run the command: call edg_utl.sendToStage( 1, 1, '456', 'MySite', 'MyDevice', 'data', sysdate, 'src', 'cor' );

The procedure generates and sends out a dummy event with the ID set to 456. To verify that it worked, look at your Sensor Data Archive. This event should be there: SELECT id FROM SDH_EVENTS;

Now look at the stolen table to see if the callback was invoked: SELECT*FROM stolen;

The event should appear.

13.5 Filters and Driver Interfaces

Oracle Sensor Edge Server includes an interface for you to develop your drivers from the ground up. You can also extend some of the existing driver classes provided in the product. You can save development time by modifying only the classes that you need to change; building on our foundation.


Note:

It is important to note the following concerning Oracle Sensor Edge Server and upgrades. Extensions are automatically uploaded in a standard Enterprise installation, but not during a release 9.0.4 to 10.1.2 upgrade. To preserve your existing extensions:
  • In an Enterprise installation, after the infrastructure and middle tiers are upgraded, you can upload the extensions (which are included in the 10.1.2 release) through the webtool (from ORACLE_HOME/wireless/lib/edgeobjects on any middle tier). Each one must be uploaded manually.

  • In a standalone installation, extensions must be deployed by putting them into edge/extensions


Figure 13-3 Driver Extension Class Map

Description of Figure 13-3  follows
Description of "Figure 13-3 Driver Extension Class Map"

Filter types

Table 13-24 The Pre-Seeded Filters of the Oracle Sensor Edge Server

Filter Name Function Applied to Device Group? (Supports Group-Level Filtering) Applied to Devices? (Supports Device-Level Filtering)

Check Tag ID Filter

A diagnostic tool that checks if a device is reading tags during a specified interval.

No

Yes

Cross-Reader Redundant Filter

Blocks redundant events that are sent from the devices of a device group.

Yes

No

Debug Filter

Tracks events, and then writes these events to a log file.

No

Yes

Pass Filter

Notifies applications that a tag has passed through a device's gateway or range or transmission. This filter also blocks events, so that only one event, rather than a series of events, are generated when a tag is detected by a device.

No

Yes

Shelf Filter

Signals that an item has entered, or exited the field or gateway of a device reader.

No

Yes

Pallet Pass-Thru Filter

Enables you to see all of the tag IDs for items held in a container or on a pallet, and eliminates duplicate reads.

No

Yes

Pallet Shelf Filter

Sends events that signal new containers or pallets entering or exiting the field or gateway of a device reader.

No

Yes


13.5.1 Device Interface

Oracle Sensor Edge Server provides a Device interface used to implement a device driver. The interface covers the aspects of uniquely identifying each device instance, initialization with configurable parameters, receiving asynchronous events, sending instructions with returned instruction-processing results and self cleanup. This interface does not restrict any particular communication channel between a device and an Oracle Sensor Edge Server. A device can work with an Oracle Sensor Edge Server through TCP socket, HTTP or event serial communication.Oracle Sensor Edge Server provides an interface for filtering. Each filter object can implement three levels of filtering: pre-device filtering, post-device filtering and device group filtering. Pre-device filtering provides filtering against a batch of pass-in events before they are routed to the device. Post-device filtering provides filtering against events before they are merged up to device group level. Device group filtering provides filtering against the events before they are delivered to an Edge Client. The following graphic shows filter placement.

Figure 13-4 Device Filter placement

Description of Figure 13-4  follows
Description of "Figure 13-4 Device Filter placement"

The Device interface is the main interface used for writing a Device Driver.

Table 13-25 Device Driver Interfaces

Method Description

getName()

Returns a unique name of a device instance.

getDescription()

Returns a longer description of the driver itself. This information is not instance-specific.

getVersion()

Returns the version number of the driver implementation.

doInit()

Part of life cycle management - This method is called by the Driver Manager when it is loaded.

start()

Part of life cycle management – This method is called by the Driver Manager when the device is enabled.

stop()

Part of life cycle management – This method is called by the Driver Manager when the Oracle Sensor Edge Server is requested to stop the device.

destroy()

Clean up upon destroy of the device.

isAlive()

Reports on the operational status of the device.

processInstruction()

Process each incoming instruction event.


Table 13-26 Filter Interface Methods

Method Description

getName()

Returns the name of the filter.

getDescription()

Returns a longer description of the driver. This information is not instance-specific.

getVersion()

Returns the version number of the filter implementation.

doInit()

Part of life cycle management; this method is called by the Device Manager when the filter is loaded.

preFilterDeviceEvents()

Filters against a batch of pass-in events before they are stored into the event buffer of a device; used for device-level filtering.

postFilterDeviceEvents()

Filters against events stored in a device buffer just before they are merged with other collected device buffer events inside a device group; used for device-level filtering.

filterDeviceGroupEvents()

Filters against events collected by a Device Group just before they are delivered to the Dispatcher.

start()

Start the filter.

stop()

Stop the filter.

destroy()

Clean up upon destroy of the device.


13.6 Extension Archive Files

Before you can upload a custom extension, such as a driver, dispatcher, or filter, you must package the extension files into an Extension Archive. An Extension Archive contains all of the extension's binaries, startup data, and configuration information. Each Extension Archive contains only one extension implementation, which is loaded at runtime. The Extension Archive contains the following directories:

Meta-INF

This directory contains any meta information about the archive. This directory must include the Extension Archive Descriptor file. The Extension Archive Descriptor file is an XML file located in the META-INF directory that contains the information needed by the Oracle Sensor Edge Server to load and manage the extension. The Extension Archive Descriptor file is called ext.xml. Example 13-10 describes a simplified version of the DTD for ext.xml. Table 13-27 describes this DTD's elements.

Example 13-10 DTD of the Extension Archive Descriptor File (ext.xml)

<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT Extension (name, version, className,  type, Parameters)>
 
<!ELEMENT name (#PCDATA)>
<!ELEMENT version (#PCDATA)>
<!ELEMENT className (#PCDATA)>
<!ELEMENT type (#PCDATA)>
 
<!ELEMENT Parameters (Parameter+)>
 
<!ELEMENT Parameter (valueType)>
<!ATTLIST Parameter
  name CDATA #REQUIRED
  displayName CDATA #IMPLIED
  defaultValue CDATA #IMPLIED
  description CDATA #IMPLIED
  encrypted (true|false) #IMPLIED
  isClearText (true|false) #IMPLIED
  required (true|false) #IMPLIED>
 
<!ELEMENT valueType EMPTY>
<!ATTLIST valueType
  type (int | string | double | boolean) #REQUIRED

Table 13-27 Elements and Attributes of the DTD for the Extension Archive Descriptor File

Element Attribute or Text Description

Extension


Defines the properties of an extension.

name

#text

The name of the extension. This name displays when users select an extension for creating a filter, device, or selecting a dispatcher.

type

#text

The type of the extension, such as a driver, filter, or dispatcher. Although the match is not case-sensitive, there must be no extra spaces or special characters in the text. The reserved values are: Device, Filter, Dispatcher.

version

#text

A text representation of the version number of the extension.

className

#text

The name of the class to load and instantiate the driver. This is the entry class that implements one of the standard extension interfaces. You must include a package name to form a fully qualified class name.

Parameters


The parameters that users can edit using the Sensor Services Tool after an extension has been uploaded.

Parameter

Attributes include:

  • name

  • displayName

  • defaultValue

  • encrypted

  • isClearText

  • required

  • name -- The name of the parameter.

  • displayName -- The name that displays in the Sensor Services tool when prompting for

  • defaultValue -- The default value for the parameter.

  • encrypted -- Indicates whether the value for the parameter should be encrypted so that the value does not have to be stored in clear-text format.

  • isClearText -- Enables the default value (and the value for the parameter instance) to be reset to clear-text format. If the encrypted parameter is set to true, then the clear-text format is read and then set to encrypted format the next time the Oracle Sensor Edge Server starts.

  • required -- Indicates whether the parameter value is required.

valueType

type

The type of the parameter; one of:

int -- if the parameter is a 32-bit signed integer.

string -- for a string of variable length.

double -- for a double precision number.

boolean (true, false)


classes

This directory includes all of the classes files, native binaries, files, or static data. The classes files packaged into JAR files must be expanded on top of this directory. This release does not support loading JAR libraries.

lib

The Extension Archive file also includes the lib directory, where you specify third-party libraries. Example 13-11 illustrates an Extension Archive file for an Alien device driver, where the lib directory includes the library specific to the Alien device driver, Gateway.jar.

Example 13-11 Extension Archive File for an Alien Device Driver

meta-inf/ext.xml
meta-inf/Manifest.mf
classes/oracle/edge/impl/driver/AlienReader.class
lib/Gateway.jar

13.6.1 Packaging an Extension Archive File

To package an Extension Archive file:

  1. Build a sandbox directory. Use this directory as the JAR source directory.

  2. At the top of this directory, create the META-INF and classes directories.

  3. Copy all class files and properties files (if any) to the classes directory. In the META-INF directory, create ext.xml, the Extension Archive Descriptor file.

  4. Archive the files. You can use the JAR tool included in the JDK, or any other standard compression utility. Run the JAR tool from top-level directory of the sandbox. For example, executing jar cvMf test.jar archives the files in the sandbox directory into test.jar. You can then uploadtest.jar to the Oracle Sensor Edge Server. Do not archive the META-INF and classes directories as part of the sandbox directory. For example, the command c:/work> jar tvf test.jar displays the files in test.jar have been properly archived as follows:

    0 Thu Apr 08 14:36:56 PDT 2004 META-INF/71 Thu Apr 08 14:36:56 PDT 2004 META-INF/ext.xml0 Thu Apr 08 13:42:52 PDT 2004 classes/0 Thu Apr 08 13:42:52 PDT 2004 classes/my/0 Thu Apr 08 13:42:58 PDT 2004 classes/my/test.class
    

    Note:

    No slashes or other directory indicators appear before the META-INF and classes directories. Including the entire path in JAR prevents the Oracle Edge Sensor Server from locating the Extension Archive Descriptor file or the classes. As a result, the extension cannot be deployed.