4 Managing Extensions

This chapter, through the following sections, describes the extensions for the Oracle Sensor Edge Server's driver, filters, and dispatchers.

Section 4.1, "Overview of Extensions"
Section 4.2, "Extension Archive Files"
Section 4.3, "Uploading Extensions"
Section 4.4, "Extension Class Hierarchy"
Section 4.5, "Implementing Extensions"
Section 4.6, "Managing the Parameters of an Instance"

4.1 Overview of Extensions

An extension is a custom-built driver, dispatcher or filter which you upload to the Oracle Sensor Edge Server by packaging the component in an Extension Archive file. The Extension Archive file is a JAR file containing all of the class files and native binaries for the driver, filter, or dispatcher, as well as properties files or static data files. In addition, the Extension Archive includes the Extension Archive Descriptor file, an XML file containing instructions for the Oracle Sensor Edge Server on loading and managing the extension.

Note:

Setting the element content of <IsExtensionMonitorEnabled> to true enables an extension to be dynamically uploaded to the Oracle Sensor Edge Server. You do not have have to restart the Oracle Sensor Edge Server. However, for the Oracle Edge Sensor Server to use the instances created from an extension, you must restart the Oracle Edge Sensor Server as described in Section 1.3.1..

For information on the packaging an Extension Archive and the Device Management API, refer to the Oracle Application Server Wireless Developer's Guide.

4.2 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
classes
lib

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 4-1 illustrates an Extension Archive Descriptor file (ext.xml) for a filter extension called Loop Back Filter.

Example 4-1 The Extension Archive Descriptor File for a Filter Extension

<?xml version="1.0"?>
<Extension>
<name>Loop Back Filter</name>
<version>1.0</version>
<className>oracle.edge.impl.filter.LoopBackFilter</className>
<type>Filter</type>
<Parameters>
        <Parameter name="TagID" defaultValue="" description="The Invalid Tag ID">
            <valueType type="string"/>
        </Parameter>
        <Parameter name="LightStackName" defaultValue="stack1" description="The Light Stack Instance Name">
            <valueType type="string"/>
        </Parameter>
    </Parameters>

Example 4-2 describes a simplified version of the DTD for ext.xml; Table 4-1 describes this DTD's elements.

Example 4-2 The DTD for the Extension Archive Descriptor File

<?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 4-1 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.
`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`	(Parent of the <Parameter> element.)	The parameters that users can edit after an extension has been uploaded.
`Parameter`	Attributes include: `name` `displayName` `defaultValue` `encrypted` `isClearText` `required`	`name` -- The name of the parameter. `displayName` -- The display name of the parameter. `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 (which can be one of the following): `int` -- if the parameter is a 32-bit signed integer. `string` -- for a string of variable length. `double` -- for a double precision number. `boolean` -- for a boolean value (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 4-3 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 4-3 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

4.2.1 Packaging an Extension Archive File

To package an Extension Archive file:

Build a sandbox directory. Use this directory as the JAR source directory.
At the top of this directory, create the META-INF and classes directories.
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.

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 upload test.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.xml
0 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 the JAR prevents the Oracle Sensor Edge Server from locating the Extension Archive Descriptor file or the classes. As a result, the extension cannot be deployed.

4.3 Uploading Extensions

To upload an extension:

Package the driver, filter, or dispatcher in an Extension Archive File as described in Section 4.2.1.
Copy this JAR file to:

ORACLE_HOME/edge/extensions
Restart the Oracle Sensor Edge Server by restarting the OC4J Instance.

Tip:

If the <IsExtensionMonitorEnabled> element has been set to true in edgeserver.xml, then you only need to copy the JAR file to ORACLE_HOME/edge/extensions. The running Oracle Sensor Edge Server then picks up the extension automatically and does not need to be stopped and then restarted. Because this method of adding an extension slows performance, it is recommended only for development instances.

4.4 Extension Class Hierarchy

All of the extensions of the Oracle Sensor Edge Server are arranged as:

EdgeObject—The basic root class, which contains a unique identifier

AbstractEdgeExtensionImpl—Implements the EdgeExtension interface.
- AbstractDispatcher—An abstract class that defines a base for a filter extension.
- AbstractFilter—A basic filter.
- AbstractDevice—A basic device.
  - AbstractEventDevice—A common sensor or indicator device.
  - AbstractSocketDevice—A network-based device driver.

Note:

Extend from AbstractDispatcher, AbstractFilter, AbstractDevice (or from a descendant class) when you create an extension.

4.5 Implementing Extensions

The doInit() method implements extensions, as this call initializes the instance of an extension at runtime.

4.5.1 Extension Context

When the instance of an extension is created at runtime, the corresponding Context is created that enables the extension to:

Set (or retrieve) the runtime Context data.
Locate and communicate with other extensions of the Oracle Edge Sensor Server.
Access the system facilities of the Oracle Edge Sensor Server.
Retrieve information about the instance itself (described in Section 4.5.1.1).

4.5.1.1 Retrieving Information About the Instance

The base class, EdgeExtension, provides utility functions for an instance to retrieve information about itself. These methods include:

getContext()

Returns the runtime context.
getName()

Returns the name of the extension.
getDescription()

Returns the description of the extension.
getVersion()

Returns the version string of the extension.

4.5.1.2 Accessing the Runtime Context of an Instance

To retrieve the instance's Context object, use

EdgeExtensionContext context = super.getContext();

The method call, getContext(), returns the Context object of the current instance.

4.6 Managing the Parameters of an Instance

An instance of an extension does not hold its own persistent data or configuration; configuration data is passed in at runtime when the instance is initialized. The configuration data is defined as parameters, which are composed of name/value pairs. Each parameter has a unique name and an optional value.

Note:

This release of the Oracle Sensor Edge Server does not directly support trees or arrays of values. You are responsible for un-marshalling the data when forming non-scalar type data.

4.6.1 Exposing Custom Parameters

Extensions often have specific configurations. For example, a driver might include such configuration parameters as serial port name, baud rate, IP address, port number, login and password. These parameters must be defined to enable the driver to communicate with the device.

To expose parameters for a driver implementation, you must modify the Extension Archive Descriptor file. Example 4-4 illustrates a device that has two parameters that can be configured: serial port name and baud rate, defined within the <Parameter> extract tags.

Example 4-4 An Extension Archive Descriptor File with Exposed Parameters

<Extension>
         <name>My Driver</name>
         <type>Device</type>
         <className>my.testdriver</className>
         <Parameters>
                   <Parameter name="port" displayName="Serial Port">
                          <valueType type="string"/>
                   </Parameter>
                   <Parameter name="baud" displayName="Baud Rate">
                         <valueType type="int"/>
                   </Parameter>
         </Parameters>
</Extension>

4.6.2 Retrieving Parameter Values

Once you have defined the Extension Archive Descriptor file's <Parameter> tags, you can fetch the values for the parameters using the EdgeExtensionConfigInfo object. The values defined within the <Parameter> tags are retrieved using the Context object (illustrated in Example 4-5).

Example 4-5 Retrieving Parameter Values Using the Context Object

EdgeExtensionContext context = super.getContext();
ConfigParameter filenameParam = ct.getParameter( fileName );

The getParameter() method returns a ConfigParameter object. The getParameter() method returns the value for a parameter. (In Example 4-5, the ConfigParamter object is called filenameParam and the getParameter() method returns the value for a parameter called fileName.)The name of the target parameter must be passed to the ConfigParameter object. Further, the name of this parameter must match the name given to the name attribute of the <Parameter> element of the Extension Archive Descriptor file. Once you obtain the ConfigParameter object, you can get the value of the parameter (illustrated in Example 4-6).

Example 4-6 Retrieving the Value of a Parameter

m_fileName = filenameParam.getStringValue();

Note:

The getStringValue()method returns the string value of the parameter. If the value for the parameter is an int, call the getIntegerValue() method, which returns an Integer object.