Control Unit Generator

The Control Unit Generator tool facilitates implementation of control units. This document provides a detailed guide for this tool usage.

Contents:

Principles of Work
User's Guide
References

Principles of Work

The Control Unit Generator is very useful when you want to create a control unit provider application and pack it in a bundle. The tool is compliant with the Control Unit Generator API (see "Control Unit Generator Support Bundle"), and given a control unit metadata XML generates a control unit model and the skeleton of a controller .

Tip: For more information about the control unit paradigm, refer to the "Control Unit Admin Bundle" document.

User's Guide

Write an XML File

The first step in using the Control Unit Generator is providing the metadata XML in accordance with the ProSyst Metatype Bundle and the control unit metadata model.

Here is an example metadata XML of a lamp control unit:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE metatype-provider SYSTEM "conf.dtd">
<metatype-provider>
  <objectclass>
    <locale>en</locale>
    <name>Sample Lamp</name>
    <id>lamp</id>
    <description>Sample Lamp</description>
    <attribute modifier="req">
	    <name>Current Status</name>
      <id>status</id>
	    <description>Current status of the lamp - ON or OFF.</description>
	    <type>&boolean;</type>
      <cardinality>0</cardinality>
      <value>
        <scalar>false</scalar>
      </value>
      <selected-pairs>
        <scalar>OFF</scalar>
        <scalar>false</scalar>
	      <scalar>ON</scalar>
        <scalar>true</scalar>
	    </selected-pairs>
    </attribute>
    <attribute modifier="req">
	    <name>Current Intensity</name>
      <id>intensity</id>
	    <description>Current intensity of the lamp - from 0 to 100%.</description>
	    <type>&int;</type>
      <cardinality>0</cardinality>
	    <key name="minValue" value="0"/>
      <key name="maxValue" value="100"/>
      <value>
        <scalar>0</scalar>
	    </value>
    </attribute>
    <objectclass>
      <locale>en</locale>
	    <name>Turn ON</name>
      <id>turnOn</id>
      <description>Turns the lamp on. No input/output arguments.</description>
    </objectclass>
    <objectclass>
      <locale>en</locale>
      <name>Turn OFF</name>
      <id>turnOff</id>
      <description>Turns the lamp off. No input/output arguments.</description>
    </objectclass>
    <objectclass>
      <locale>en</locale>
      <name>Set Intensity</name>
      <id>setIntensity</id>
      <description>Changes the lamp intensity to the given value. 
      Executed only if the lamp status is ON.</description>
      <attribute modifier="in">
  	  <name>New Intensity</name>
        <id>newIntensity</id>
	      <description>New value for intensity - from 0 to 100%.</description>
	      <type>&int;</type>
        <cardinality>0</cardinality>
	      <key name="minValue" value="0"/>
        <key name="maxValue" value="100"/>
      </attribute>
    </objectclass>
    <objectclass>
      <locale>en</locale>
      <name>Create Lamp Unit</name>
      <id>$create.</id>
      <description>Creates a new lamp control unit.</description>
    </objectclass>
  </objectclass>
</metatype-provider>

Listing 1: An example control unit metadata.

Run the Control Unit Generator

To start the generator, open a command prompt window in the tool's home directory and type the following:

cugenerator <xmlfile> <package> [<output>], where:

<xmlfile> - The metadata XML file to use as generation input. See the previous step.
<package> - The package name of generated classes.
<output> - The name of the directory where produced files will be saved.

For example:

cugenerator example_cu.xml example.cu example_cu

Fill Output Files with Custom Logic

The Control Unit Generator creates Java source files for the components of the Control Unit Generator API defined to hold custom data and logic - model and controller. In case the metadata XML contains the $create., $find. and/or $destroy actions, which are predefined for Control Unit Factories, the tool provides a Control Unit Factory implementation as well.

Produced files do not provide a complete control unit but only its skeleton. The developer should implement actions for changing the state of a control unit instance, and in the case of a Control Unit Factory - for creating, searching and destroying control units.

Model

A generated model does not need further development efforts and can be directly added to a control unit provider application. Unless explicitly specified otherwise through the model.superclass JVM system property, a model provided by the Control Unit Generator extends the org.mbs.services.cu.generator.DefaultControlUnitModel class and is named <control_unit_type>ControlUnitModel. The model implementation contains a single method, getModelInitValues, for specifying initial values of control unit's state variables.

The output model for the XML, shown in Listing 1, looks like this:

Figure 1: An example model, generated by the Control Unit Generator.

Controller

The generated controller is the control unit component, which needs additional development in order to become functional.

The controller contains Java methods for mapping control unit actions in compliance with the requirements of the Control Unit Generator API - method names start with the _cu_ prefix so that the default Managed Control Unit or Control Unit Factory implementation can locate and invoke actions correctly on user request. Controller's methods should be further implemented to execute the corresponding actions. Additionally, the Control Unit Generator is also capable of producing controllers, which subclass certain classes specified with the model.superclass JVM system property.

The Control Unit Generator names controller classes as <control_unit_type>ControlUnitController.

The output controller for the XML, shown in Listing 1, looks like this:

Figure 2: An example controller, generated by the Control Unit Generator.

Control Unit Factory

As the Control Unit Generator creates a Control Unit Factory only in case the metadata XML contains definitions of constructor, destructor and/or finder actions, developers should implement the activities behind these factory actions.

Generated Control Unit Factory extends the org.mbs.services.cu.generator.DefaultControlUnitFactory class and carries the <control_unit_type>ControlUnitFactory name. According to the factory actions in the input XML, the factory overrides the createControlUnit, findControlUnits and/or destroyControlUnit methods, leaving them empty for further development.

The output Control Unit Factory for the XML, shown in Listing 1, looks like this:

Figure 3: An example Control Unit Factory, generated by the Control Unit Generator.

Use Generated Files in a Control Unit Provider Application

Models, controllers and factories, produced by the Control Unit Generator, are not sufficient for a fully functional control unit provider. The thing that remains to be done is :

Attach the model and controller to an org.mbs.services.cu.generator.DefaultControlUnit instance and register it as a service in the OSGi framework under the org.mbs.services.cu.spi.ManagedControlUnit interface.
or
Register an org.mbs.services.cu.generator.DefaultControlUnitFactory instance as a service in the OSGi framework under the org.mbs.services.cu.spi.ControlUnitFactory interface.

For more details on achieving the operations above, refer to the Control Unit Generator API description.

Prepare and Install the Bundle JAR

Finally, compile the components of the control unit provider application and pack them in a JAR file. Note that the JAR must contain the metadata XML used as input for the generation of the control unit model, controller and factory (see the "Export Control Unit Metadata" chapter from the Control Unit Admin Bundle description).

Then, when installing your control unit provider bundle, containing files provided by the Control Unit Generator tool, make sure the Control Unit Generator Support Bundle is already running in the OSGi framework.

References

Control Unit Tools