What is a module in the Sentinel Express SDK?

The word “module” is used to describe both an on-disk directory and an Ivy module. Each module on disk has a one-to-one relationship with an Ivy module.

Modules on disk hold source code and documentation source. The build system that is part of the Sentinel Express SDK publishes them as Ivy modules.

Modules depend on other modules, as specified in the dependencies section of their ivy.xml file.

Common types of modules

Below are some common types of modules.

Note These are representative of a standard set of modules a developer will encounter, but the list is not exhaustive.
Type of module What it contains

JSLEE library

The source code for a single JSLEE library component. Publishes a single JSLEE library jar component into the slee-component Ivy configuration.

May contain documentation.

Profile

The source code for a single profile component. Publishes a single profile specification jar component into the slee-component Ivy configuration.

May contain documentation.

POJO feature

The source code for a single Sentinel POJO feature. Publishes a single SBB part component jar into the slee-component Ivy configuration.

Typically POJO feature modules depend on one or more library and profile modules.

SBB feature

The source code for a single Sentinel SBB feature. Publishes a single deployable unit jar into the du Ivy configuration.

The deployable unit jar contains both the SBB itself and a build-generated SBB part component jar.

Group

May not contain any source code. Used to group together related modules, through Ivy dependencies on the related modules. Its on-disk structure often includes sub-directories that are themselves modules.

Many feature modules are also group modules. This is typical for features that have a single configuration profile. In such a case, the module is referred to as both a feature module and a group module, where the feature is the group.

Group modules from OpenCloud are tagged with group in Artifact indexes. Group modules can depend on other group modules.

Deployment

Typically exists to deploy and configure other modules; a specialisation of a group module.

A deployment module generally includes configuration source, so that particular configuration can be applied by the configurer.

Deployment modules from OpenCloud are tagged with service-deploy in Artifact indexes.

Deployable unit

Modules that publish a single deployable unit. Typically, they contain source code. SBB feature modules are deployable unit modules.

Deployment script

Includes Ant script files that the deployer invokes.

Often used for deploying resource adaptors or other modules that do not conform to the deployer’s publication conventions.

Note For more about the deployer, see Deploying modules in Rhino

Module on disk

Modules are directories under the sentinel-express-sdk directory. At minimum, a module contains the following files:

File What it’s for

build.xml

contains build targets

ivy.xml

contains Ivy module definition, dependencies, and publications

.sdk.root

points to the location of the build infrastructure; required for the module to build

module.properties

contains various build variables, and per-module constants used in the module build
Tip Modules can be placed as subdirectories of other modules. This means you can use a “tree” of directories if you want. It is often convenient to group related modules into a particular directory structure.

Any source code for a module is in the src subdirectory of the module directory.

Unit testing code for a module is in the test subdirectory of the module directory.

Modules that are part of your SDK (as opposed to those made available by OpenCloud) can be listed using the list-sdk-modules command in the sdkadm tool:

> help list-sdk-modules
"list-sdk-modules": Lists all modules contained within this SDK.
    Usage: list-sdk-modules
    Example: list-sdk-modules

Building and publishing modules

Here are procedures for building and publishing modules:

To…​ Do this:

build and publish a single module

use the publish-local target with the modules directory as your current working directory:

cd module-directory
ant publish-local

build and publish all modules in the current directory and all if its subdirectories

use the publish-local-branch:

cd directory
ant publish-local-branch

remove any build artifacts and generated files

use the clean and clean-branch targets:

  • clean removes build artifacts and generated files from the current directory.

  • clean-branch removes build artifacts and generated files from the current directory and all of its subdirectories.

view all available targets

use the ant -p command inside a module

cd module-dir
ant -p

(Targets differ depending on the current working directory.)

Default build

The SDK includes default build behaviour, which will build most module types without requiring any modification to the build.xml file.

Module types that require changes to the default build.xml file include:

  • SBB feature modules

  • deployable unit modules

  • deployment script modules.

When creating a module from a module pack (using the sdkadm create-module command), a suitable build.xml file is placed into the created module’s directory.

When creating an SBB feature, use an existing module-pack SBB feature as the input to create-module.

Artifact snapshots, milestones, and releases

There are three "`grades" of artifact:

Artifact grade Commands that produce them What they’re used for

snapshot

publish-local
publish-local-branch

Typical every day builds. In many continuous integration environments, snapshot artifacts are deleted after a period of time to reclaim disk use.

milestone

publish-milestone
publish-milestone-branch

Often aligned with end-of-sprint builds, or other milestone points in a project.

release

publish-release
publish-release-branch

Typically used for more major milestones in a project, such as Early Access, Release Candidate, and General Availability builds.

Dependencies in ivy.xml files may use a latest keyword, which specifies what to check and then resolve the most recent artifact revisions.

Use this keyword To check…​

latest.integration

snapshots, milestones, and releases

latest.milestone

milestones and releases

latest.release

releases only

It often considered good practice to have milestone builds only depending on other modules milestone or releases, and release builds only depending on other module releases.

Users may also want to "pin" particular revisions in place. This is often done through use of variables in a deps.properties file.

Multi-threaded builds

The SDK supports building modules in parallel using multiple threads. This can reduce build time by as much as half in projects with a large number of modules.

This feature must be explicitly enabled by either:

  • passing -Dbuild.multithreaded=true to an Ant command. For example:

ant clean publish-local -Dbuild.multithreaded=true

  • or, setting build.multithreaded=true in sdk.local.properties (applies to a single SDK project) or in ~/.build.properties (applies globally).

By default, the build will use as many threads as available cores on your machine. To override this, you can set the build.maxthreads property to the maximum number of threads the build should use.
For example:

ant clean publish-local -Dbuild.multithreaded=true -Dbuild.maxthreads=6

When enabled, the multi-threaded builder will sort the Ivy modules in dependency order and start assigning them to be built as sub-projects to a pool of executors. Module build jobs will only be submitted when all local modules they depend on have finished building.

If running in a terminal, the default Ant console output will be suppressed and replaced by a status view of the currently building modules. The per-module Ant output will instead be written to build.log in each module. If a module build fails, all unstarted module builds will be cancelled and any modules currently building in other threads will be terminated. When running without a terminal (in Jenkins for instance) the build output of modules will be written to standard out, interleaved on a per-line basis.

Some caveats:

  • multi-threaded builds are incompatible with Ivy symlinks (ivy.symlinks=true) – the SDK will enforce that these options are not used together. Multi-threaded builds require file locking of the local repository cache, but symlinks bypass the locks, causing the builds to fail unpredictably.

  • projects that have multiple modules binding to the same port or otherwise using some unshareable system resource in their unit tests can’t be built using the multi-threaded builder – these must first be updated to use unique ports/resources.

  • the CPU and memory requirements of builds using multiple threads are higher. If the CPU use is high enough to render your machine unusable, you can limit the threads using the build.maxthreads property. For the memory use, you may need to increase the max memory arguments set for Ant.

Modules in Ivy

After a module that is part of an SDK has been published, its artifacts are stored in the local filesystem-based repository. This repository is located under the ~/.ivy2/opencloud-local directory.

OpenCloud-provided modules are served from an online repository.

For more information, see Using Ivy with the SDK.

Tip Before artifacts get published in Ivy, they are created in the module’s target/artifacts directory. It can often be useful to view the content of this directory during development.

Module packs

There is a special type of publication called a “module pack”. Module packs from OpenCloud are tagged with module-pack in Artifact indexes.

A module pack is a zip file that contains files in one or more modules.

Module packs are used as a mechanism for distributing example source and as a template for creating new modules, in concert with the sdkadm create-module command.

For more detailed information about module packs see: Module Packs.

Module indexes

Module indexes are a listing of available modules in the OpenCloud repository. You can view the index content with the list-modules command in the sdkadm tool:

> help list-modules
"list-modules": Lists available modules of the specified type.
    Usage: list-modules [-v|--verbose] [--show-all-versions] [[+tag1] -tag2,
        ...] [pagination#]
    Example: list-modules +sip +feature - 15

Module tags

Different types of modules in the index are tagged with attributes, so that they are searchable when using the list-modules command.

Note Tags are merely text strings. Modules may have multiple tags.

Below is a current list of frequently used tags. As OpenCloud updates its product repositories, the index gets updated.

Tag Used by

service-deploy

Sentinel Service deployment modules

module-pack

modules that publish a module pack

sip

modules that contain SIP protocol behaviour

ss7

modules that contain SS7 protocol behaviour

diameter

modules that contain Diameter protocol behaviour

feature

modules that contain a feature

sbb

modules that publish an SBB

sbb-part

modules that publish an SBB part

library

modules that publish a library

profile

modules that publish a profile

mmtel

modules that are part of MMTel

scc

modules that are part of SCC

volte

modules that are part of Sentinel VoLTE

Creating and deleting modules

Below are procedures to create a module, create a deployment module, and delete a module.

Creating a module

Modules can be created in the SDK either manually or with the sdkadm tool’s create-module command.

create-module works by downloading a module-pack and extracting it, substituting various parameters. Substitutions can be passed into the command; otherwise the command prompts for parameters.

This command offers tab completion for module packs that are available in the index. Here’s its command-line help:

> help create-module
"create-module": Creates a module or set of modules at the specified location.
        During the module creation process, values which need to be renamed
        will be prompted for interactively. These values can alternatively be
        supplied as arguments in the form <oldvalue:newvalue> as additional
        args. If the optional "defaults" argument is supplied, values that do
        not have an explicit rename argument will use their default values
        without prompting.
    Usage: create-module <directory> <module-pack> [defaults]
        [<oldvalue1:newvalue1> [<oldname2:newname2> [...]]]
    Example: create-module my-features-modules/new-feature
        opencloud#sentinel-template-feature#sentinel-core/trunk;latest.integr-
        ation

Once a module has been created in the SDK, the module name will be included in the output of the list-sdk-modules command.

Creating a deployment module

Deployment modules can be created in the SDK either manually or with the sdkadm tool create-deployment-module command.

The create-deployment-module command works by creating a module that depends on the specified module.

The configuration from the specified module is copied into the newly created module, so that all configuration is available to the user in a single module. Here’s its command-line help:

> help create-deployment-module
"create-deployment-module": Creates a deployment module suitable for deploying
        slee-components contained in other modules.
    Usage: create-deployment-module <directory> <module-name>
        (<dependency-name> [...])
    Example: create-deployment-module my/target/directory deploy-module-name
        opencloud#sentinel-sip-example;latest.integration
        opencloud#sentinel-sip-service;1.0
        opencloud#sentinel-ss7-service#1.0.0;1.0

Once a deployment module has been created in the SDK, the module name will be included in the output of the list-sdk-modules command.

Deleting a module

Modules can be deleted manually. The process is the same regardless of the type of module:

1

If the module is bound, unbind it in Rhino.

2

If the module is deployed, undeploy it in Rhino.

3

Delete the module directory on disk.

4

If the module is under source control, remove it from source control.

5

Delete the artifacts from the local disk-based repository.

6

Clean the Ivy cache, using ant ivy-cleancache.

7

Remove all references to the module from the ivy.xml files in the SDK.

8

Remove all references to the module from the SDK’s deps.properties file.
Previous page Next page