The JCPN file

This page has been updated on the 12 May 2010.

Introduction

The creation of a Java component (a .jcpn file) is the first step when starting a new Mobile Devices project. It defines the very basic structure of the project (initial class for instance). It also declares the required interfaces and events for the project, the exported interfaces and events as well as all the parameters.

When the .jcpn file is saved, some code will be generated. This code will be the starting point for developing advanced features within the component.

At the top of the window, you can edit the package for your component and its version number. Below, a tree view provides an overview of the component’s elements.

Add button is used to add an element according to your selection.

Remove button removes the selected item.

Up and Down button are used to change the item order.

Initial

Initials are the classes launched at the startup of the component; this is the point of entry of the code part.
All these classes implement the com.mdi.tools.cpn.Initial interface.
This interface contains two methods :

  • start() method : this method is called at startup, so you must be careful to make it a NON blocking method.
    If you want to create a loop or a blocking method, launch a thread and let it start and end normally.
    If the start method blocks, other Initial classes won’t be able to run and in some cases other components won’t launch.
    This blocking triggers a watchdog in the ComponentLoader.
  • shutdown() method : this method is not called automatically at shutdown of the device, so if you want to use it you must manage the shutdownEvent(link) and call it at a specific level.

In order to create a new initial class, click on Initial and press the Add button.
Then, give it a name and press the Create button. An eclipse class creation wizard will show up. In most cases, you can click on Finish without checking parameters. Please notice that the generated class is placed in the src package not in the generated package, it will not be modified automatically when saving the .jcpn file.

The generated class just declares the start() and shutdown() methods. The programmer must fill these classes.


package com.test1.test;

import com.mdi.tools.cpn.Initial;

public class Initial1 implements Initial {

public void shutdown() {
// TODO Auto-generated method stub }

public void start() {
// TODO Auto-generated method stub } }

If the singleton toggle was checked, the initial class will conform to the singleton design pattern (more about singleton design pattern can be found here: Singleton Design Pattern ). Remember that if the initial class is defined as singleton, the class must contain a getInstance() method that returns the class instance.


package com.test1.test;

import com.mdi.tools.mui.MuiCommand;
import com.mdi.tools.std.BuffRef;

public class Initial implements com.mdi.tools.cpn.Initial {

private static Initial _instance = new Initial();

public void shutdown() {
// TODO Auto-generated method stub
}

public void start() {
MuiCommand muiCommand = Component.getInstance().getMuiCommand();
if (muiCommand != null)
muiCommand.register(new BuffRef("com.test1.test"));
}

private Initial() {
// TODO Auto-generated method stub
}

static Initial getInstance() {
return _instance;
} }

Provided elements

Provided elements are interfaces or events shared with other Mobile Devices components. By sharing elements, components can send data and interact with each others. Components can use a provided element by adding it into the required element part of the component model editor.

Be careful, when saving the .jcpn file, interface and event class will be generated. Be sure to check values before saving…

Provided interfaces

Provided Interfaces are the interfaces you give to other components; it can contain attributes and methods.
This part generates a file with the same name as the interface which contains an abstract class with the defined attributes and methods.
This abstract class must be implemented in the src folder.
e.g.: the provided interface testComponent generates the file testComponent.java in the folder generated which must be implemented in the src folder in the testComponent_impl.java file.

In order to create a new provided interface, click on ProvidedInterfaces and press the Add button.

You can set the name of the interface, the package where the class will be generated and a comment to describe the interface. You can also define the interface as a singleton (refer to the Initial part for further informations). The Create button generate an implemented class for the interface in which the interface behaviour is defined.

It is possible to add and edit the attributes of the interface. Press the Add button to add an attribute. The new attribute is provided with default parameters. The name, type ( String , int or boolean ) and initial value can be changed. A comment to describe this attribute is editable.

Up and Down button changes the attribute order.

Operation

An interface can contains methods (it is mandatory for the interface to be used by external component).

In order to create a new method for the interface, click on ProvidedInterfacesYourInterface and press the Add button.

The method prototype only has to be defined as the function corpse must be hard coded in the implemented class. You have to provide the name of the method, the return type ( void , boolean or int ) and an optional comment describing the method.

Now that your method has a name and a return type, adding some parameter is possible (not mandatory of course). Simply press the Add button. You can change the name, type ( String , int or boolean ) and kind of the parameter. The kind defines the access rights for the parameter (only for user convenience, generated code will be the same with [in] and with [out]). You can as usual comment on the parameter.

Provided events

Provided Events are the events you send to other components, it can contain attributes.
This part generates two files per event, one with the same name as the event and the other with the name concatenated with “Data”.
A method to launch this event is generated in Component.java; this method is called evtXXXX_set().
e.g.: the provided event TestEvent generates the file TestEvent.java and TestEventData.java in the folder generated and the method to launch it is evtTestEvent_set()

In order to create a new provided event, click on ProvidedEvents and press the Add button.

An event will be generated as a Java class so you need to provide a name and a package for it. Comments can also be added.

An event will also have attributes representing data shared with the external component. The Add button will add an attribute and you can change its name and type ( String , int or boolean ).

Required elements

Required elements represents elements defined in another component as provided elements. Adding a required element implies that your project will use the interface/event from the other component.

Required interfaces

Required Interfaces are the interface you retrieve from other components.
The interfaces are provided by the framework or by other components.
Two methods to retrieve this interface are generated in _component.java; these methods are called getXXXX() and getXXXXNE().
e.g.: the required interface DataRecorder generates the method getDataRecorder() and getDataRecorderNE() in the file Component.java

In order to create a new method for the interface, click on RequiredInterfaces and press the Add button. A wizard will open to select an interface from all know component interfaces in the workbench.

If you have selected the interface from the wizard, package entry will not be editable. The only parameter to provide is the modifier. It describes the expected quantity of element you expect to use:

  • Exactly one () : Mandatory single usage
  • Zero or more (*) : Multiple and optional usage
  • One or more (+) : Multiple and mandatory usage
  • Zero or one (?) : Optional single usage

Required events

Required Events are the events you catch from other components.
The events are provided by the framework or by other components.
A method to retrieve this interface is generated in Component.java; this method is called getXXXX().
e.g.: the required event ConfigChangeEvent generates the method getConfigChangeEvent() in the file Component.java

In order to create a new method for the interface, click on RequiredEvents and press the Add button. A wizard will open to select an event from all know component event in the workbench.

If you have selected the event from the wizard, package entry will not be editable. The only parameter to provide is the modifier. It describes the expected quantity of element you expect to use:

  • Exactly one () : Mandatory single usage
  • Zero or more (*) : Multiple and optional usage
  • One or more (+) : Multiple and mandatory usage
  • Zero or one (?) : Optional single usage

Parameters

This part describes the different parameters of the component.
These parameters can be a single value or table value of Integers, Strings or booleans. The framework does not provide the possibility to make other types or classes.
A method to retrieve these parameters is generated in Component.java; this method is called param_XXXX.
e.g.: the parameter portNumber can be retrieved by the method param_portNumber() in the file Component.java

In order to create a new method for the interface, click on Parameter and press the Add button.

A parameter have a name, a type ( String , int or boolean ) and a level. The level will change the visibility and the accessibility of the parameter:

  • Low level (0) : invisible and inaccessible
  • Hidden (1) : invisible but accessible
  • Unused (2) : unused parameter
  • Public (3) : visible and accessible

If the toggle Fetch parameter value only once is on the data will be fetch only once (saves resources). If off it will be fetched every time (default).

Your parameter can be a single value (just type the value then) or a table of values to store multiple values. The Add button will allow you to add the value your have entered inside the box at the left of the Table values toggle.

DB Variables

This part allows to easily manage DB variables.
Note that the DB is an independent component and that a DB variable can be used everywhere; it is not necessary to link them like parameters.
Depending on the parameter, two methods can be created to manage DB variables, getDB_XXXX() and setDB_XXXX().
e.g.: the DB variable MDI_DATA1 can be managed by the method getDB_MDI_DATA1() and setDB_MDI_DATA1() in the file Component.java

Generated Files

The JCPN file generates the file Component.java in the generated folder and some other files for Interfaces or Events as seen before.

Warning : the files are re-generated each time you save the file.

Format

This XML file uses the format described here : JCPN XML Description