Home

Welcome to the signaling-plane wiki!

The unit of packaging for signaling plane applications is called a "Module". A module can contain any number of (including zero) verticles and can depend on other modules (and their verticles) in turn. Creating a module with no Verticles makes sense to provide only library support for other modules

This section takes you through a short introduction on how to start building your own module (application) on the signaling plane and running this application.

1 Naming Scheme

Modules are identified by three components:

• the module owner
• the module's name
• the module's version

We impose little restrictions on either of these but it is sensible to stick to the following:

• The module owner should resemble a Java package name. Preferably the name of the package of the modules's source code (if it is implemented in Java)

Together, these components form a module's fully qualified name. For this matter, they are joined in a single string with a tilde (~) in between. Consider a module with the following:

    owner: com.acme
    name: myModule
    version: 1.0 

The fully qualified name of this module would be com.acmemyModule0.1.

2 Generate Module Skeleton

The easiest way to start your development is to use the feature to generate the skeleton of the module. This is achieve by the following:

• change directory to the module path ($OPENXSP_HOME/modules)
• execute the following command openxsp initProject [MyModule] , whereby MyModule is the name of your project. Example openxsp initProject foo-bar

This will generate a new folder in the module folder with a base structure that looks like the following.

gradle -------------------------------	maven config, build tasks
mods	--------------------------------	other dependent modules
src
main/resources	 --------------------	non-compiled resources
main/java	 ------------------------	java source code
build.gradle	-------------------------	build configuration
gradle.properties	---------------------	gradle configuration
gradlew ------------------------------	build script
mod.json -----------------------------	module descriptor
vertx_classpath.txt --------------------	list of classpaths 

3 Generate IDE project file

Create a project file for your favorite IDE. Change directory to the newly created module folder, and execute ./gradlew [short_name_of_ide]. The examples below are for eclipse and IntelliJ IDE

• ./gradlew eclipse for Eclipse ide
• ./gradlew idea for IntelliJ IDE

4 Module Dependencies

4.1 Using other Modules from a Module

This section explains how to use other Modules from a Module. If a module ever refers to another module, e.g. because it wants to use resources from it or run the module (see below) that module must be specified in the section of the depending module's mod.json. Additionally, the module must be linked into the depending module's directory structure. That happens automatically if the child module can be found in one of the configured repositories (the recommended approach). If the latter is not the case, the openxsp link command can be used to manually create a module link.

To use the openxsp link command change to the parent module's directory (the directory of the module that depends on another module) and run the following command:

openxsp link <path_to_child_module>

4.2 Using libraries in Modules

if your module directly uses other jar or zip files these should be placed in a lib directory which in the standard module layout resides under src/main/resources. Any jar or zip files in the lib directory will be added to the module classpath.

If a particular resource (i.e. jar or zip file) is used by more than one module, it makes sense to put those resources in a module of their own, and then declare that other modules includes them, instead of copying the same resources into every module that needs them. Doing this adds the classloader of the included module as a parent to the classloader of the including module, in effect meaning you can reference the resources in the included modules if they were present in the including module.

This is done by specifying an includes field in the parent module's descriptor. If the module can not be found in one of the configured repositories, it must also be linked via the openxsp link command.

Modules that only contain resources for re-use are called non-runnable modules and they don't require a main field in mod.json. It's also possible to include the resources of runnable modules into another module.

4.3 Maven Dependencies

In order to include maven dependencies to your application, modify the build.gradle file to add (maven) dependencies. The example below shows how to include the Kurento client as a dependency

dependencies {
  /*
  Add your module jar dependencies here
  E.g.
  compile "com.foo:foo-lib:1.0.1" - for compile time deps - this will end up in your module too!
  testCompile "com.foo:foo-lib:1.0.1" - for test time deps
  provided "com.foo:foo-lib:1.0.1" - if you DON'T want it to be packaged in the module zip
  */

  // If you're creating Groovy compiled verticles you may need the following dependencies
  //provided "org.codehaus.groovy:groovy-all:$groovyVersion"
  //provided "io.vertx:lang-groovy:$groovyLangModVersion@jar"
  
  compile 'org.kurento:kurento-client:5.0.4'
}

5 Building and Running Modules

To build your module, On the module directory, use the following command

./gradlew 

5.1 Runing single Module

Running the module, note that only runnable module - i.e. those that specify main in their mod.json can be executed.

To run a single module, simply change to its directory and run the following command:

openxsp runmod

This will cause openxsp to attempt to resolve any module dependencies using the configured repositories and then invoke the startup routine specified in main.json.

Optionally, you can pass a configuration file to the runmod command. This configuration is always a JSON file that contains a single JSON object with arbitrary data. To pass configuration, use the --conf option to openxsp runmod:

openxsp runmod --conf config.json

That configuration is then available inside your verticle by calling the config() method on the container member variable of the verticle:

JsonObject config = container.config();
System.out.println("Config is " + config);

5.2 Running multiple Modules as an App

Multiple modules can be contained in what we call an App. An app is simply a JSON descriptor file that resides in its own directory. This descriptor file specifies a number of modules to be run along with their configuration.

Such an app can the be run with the openxsp runapp command:

openxsp runApp app.json

The following fields are recognized in an app descriptor:

• owner: The app's owner.
• name: The app's name.
• version: The app's version.
• description: Text description of the app.
• keywords: JSON array of strings representing keywords that describe the app.
• developers: JSON array of strings representing any other developers of the app.
• modules: JSON array of module entries. Each module entry describes one module to be started.

The following fields are recognized in a module entry:

• name: The fully qualified name of the module to be run (mandatory).
• instances: Number of instances to run. Use with caution.
• config: The module's config.

An example of such an descriptor is shown here:

{ 
   "name":"openxsp_myapp",
	"owner":"org.openxsp",
	"version":"0.1",
	"modules":[
	   {
            "name":"org.openxsp~my_module~0.1",
	       "config":{
		 “config_param":“value"
	       }
	   },
	   {
             "name":"org.openxsp~foo-bar~0.1",
		 "config":{
	  	      “…":”…”
		 }
	   },
	]
}