User Tools

Site Tools


resource_container_bundle

Resource container bundle

A bundle includes the mapping for a specific technology or virtual soft sensors.

Architecture

For developing a bundle, project skeletons are provided for C++ and Java. These skeletons include the required APIs to develop a bundle. A developer has to create custom resource type classes that deal with the mapping of OIC representation and according technology messages. The connector contains the stack of the technology and according technology specific server/client logic.

C++ Bundle APIs and Project Template

A C++ bundle is a shared object library (.so) which is dynamically loaded by the resource container. To create a C++ bundle the header files located in the resource-container/bundle-api folder have to be included by a bundle developer. A sample C++ template project is provided in resource-container/examples/HueSampleBundle. To create a bundle the header files of the bundle API need to be included. A bundle has then to provide a bundle activator and its resource definitions. A protocol bridge bundle shall further provide a connector.

Bundle configuration: The common format for the XML configuration of a bundle is given below.

<container>
  <bundle>
    <id>oic.bundle.hueSample</id>
    <path>libHueBundle.so</path>
    <activator>huesample</activator>
    <version>1.0.0</version>
    <resources>
      <resourceInfo>
        <name>light</name>
        <resourceType>oic.r.light</resourceType>
        <address>http://192.168.0.2/api/newdeveloper/lights/1</address>
      </resourceInfo>       
    </resources>
</bundle>

The root element of the configuration is the container element which contains an arbitrary number of bundle elements specifying the configuration of bundles. For configuration of the bundle an id, path, activator ,version and resources need to be configured. The identifier should be a string uniquely identifying the bundle. A hierarchical naming scheme like a domain name is desirable but an arbitraty string can be chosen. The path references the local path of the bundle location relative to the executing application. The activator holds bundle specific information of the activation code that needs to be triggered if a bundle is started. For C++ bundles, this is a name prefix of a static activation function, for Java it is a class name.

The resources element encapsulates all resource specific information. A resource element covers here the configuration of a single resource instance. The bundle contains resource type specific classes that map the interaction for a specific protocol or soft sensor. The resource element provides all instance specific configuration. A bundle can contain multiple resources, and each resource is described with the resourceInfo element. Mandatory elements of the resource configuration are name and resourceType and resourceUri. In addition to the mandatory fields, arbitrary technology specific information for the resource can be included in the configuration file. A soft sensor resource could further provide resource configuration for inputs. In this case the resource container can take care to acquire the according data from the according input resources. Output attributes can either be listed in the configuration or programmatically inside the soft sensor implementation.

<resources>
  <resourceInfo>
    <name>DiscomfortIndexSensor1</name>
    <resourceType>oic.r.sensor</resourceType>
    <outputs>
      <output>
        <name>discomfortIndex</name>
        <type>int</type>
      </output>
      <output>
        <name>humidity</name>
        <type>double</type>
      </output>
    </outputs>
  </resourceInfo>  
</resources>

Project template

A project template to create a C++ resource bundle is given in “resource-container/examples/HueSampleBundle” A resource bundle has to define an activator, a connector and resource classes.

A resource bundle should implement the BundleActivator interface to define an activator. The following external functions also need to be defined, and trigger the creation and the execution of the activator. The prefix of the external functions should be the same as the activator described in the bundle configuration file.

extern "C" void huesample_externalActivateBundle(ResourceContainerBundleAPI *resourceContainer, std::string bundleId)
{
    bundle = new HueSampleBundleActivator();
    bundle->activateBundle(resourceContainer, bundleId);
}
 
extern "C" void huesample_externalDeactivateBundle()
{
    bundle->deactivateBundle();
    delete bundle;
}
 
extern "C" void huesample_externalCreateResource(resourceInfo resourceInfo)
{
    bundle->createResource(resourceInfo);
}
 
extern "C" void huesample_externalDestroyResource(BundleResource::Ptr pBundleResource)
{
    bundle->destroyResource(pBundleResource);
}

To define resource classes, the resource bundle should implement ProtocolBridgeResource and SoftSensorResource interface to define resources for each protocol bridge and soft sensor bundle.

Build instructions

To build the bundle API and a C++ resource bundle, include the header files of the bundle-api into a new project and provide the resource container library. Scons can be used to create a resource library. The Sconscript of the resourceContainer shows how to build a resource bundle.

Java bundle APIs and project template

A Java bundle offers the capability to reuse existing Java-based communication libraries and integrate your protocols. The Java bundle mechanism can also be used in an Android environment. A Java bundle developer only needs to take care about the mapping between the OIC resource representation and the integrated technology. The required interfaces to create a Java bundle can be found in the resource-container/bundle-java-api directory. The API consists of a set of interfaces and abstract classes. Most important is the BaseActivator class, which has to be extended by a bundle provider. It offers the methods for retrieving configuration parameters and for resource registration. The second important abstract class is the BundleResource. A developer has to extend this class for concrete resource types and implement the mapping for reads and writes on the resource attributes.

Project Template

A Java example project template is provided in the folder examples/HueJavaSampleBundle/hue. To create a new Java bundle, copy this folder and modify the Maven pom.xml. Source files can be put in an arbitrary package.

Build instructions

For building the Java Bundle APIs and the bundle projects the Maven build system is used.

Note (using Maven behind firewall or proxy): 
If you are behind a firewall or proxy it might be required to ease the security settings. Provide the following parameters to your Maven commands if external dependencies are downloaded.
-Dmaven.wagon.http.ssl.insecure=true
-Dmaven.wagon.http.ssl.allowall=true
-Dmaven.wagon.http.ssl.ignore.validity.dates=true

Bundle API

First step is to build the Java Bundle API.

resource-container/bundle-java-api> mvn compile
resource-container/bundle-java-api> mvn install

This compiles the bundle api and installs it in the local maven repository. All bundle projects can use the library then. A project can include declare a dependency on the Java bundle API. An example pom.xml can be found in the resource-container/examples/HueJavaSampleBundle folder.

Java resource bundle

To build a Java bundle all dependencies need to be included. In order to package all dependencies the assembly plugin is used.

resource_container_bundle.txt · Last modified: 2016/05/16 07:33 by Markus Jung