how_to_use

Table Of Contents

• Table Of Contents
• About this page
• Building OsMoSes
• Deploying OsMoSes
  • Required Directory Hierarchy
    • Base directory
    • Service bundles
    • Service JAR files
    • Agents bundles
• Launching OsMoSes
  • The Simplest Way
  • The Personalized Way
  • Starting Agents
• Configuring OsMoSes

About this page

In this page you will find all the information about how to build, install and use OsMoSes.

Building OsMoSes

Refer to the page about building OsMoSes to find information about how to build the components of the project.

Deploying OsMoSes

After building OsMoSes, you can deploy it simply by uncompressing the generated deploy file. The result (referred in here as the deployed directory) will contain all necessary files to run JADE using OsMoSes.

Required Directory Hierarchy

To launch JADE using OsMoSes you should have (at least) the following directories:

• Base directory
• Service bundles
• Service JAR files
• Agents bundles

Base directory

This is the directory used as base for all the resources OsMoSes generates during its work. In particular, OSGi framework cache information and received bundles (by means of agent migrations) will be written in there.

OsMoSes requires read and write access in this directory.

By default this directory is looked for under current (at execution time) directory with the name "osgi_ms". However the path to use can be specified using the configuration property osmoses_base_path.

Service bundles

Contains all the bundles that conform OsMoSes.

OsMoSes requires read access in this directory.

By default this directory is looked for under current (at execution time) directory with the name "svc_bundles". However the path to use can be specified using the configuration property osmoses_svc_bundles_path.

These bundles are:

• logger
• repository_helper
• resolver_consumer
• resolver_producer
• rtp_common
• rtp_requester
• rtp_sender

Service JAR files

Contains the JAR files with the classes that are part of OsMoSes but don't run in an OSGi framework (aren't bundles).
This directory is not automatically detected or used by OsMoSes, however, their associated JAR files must be available in the classpath.

These JAR files are:

• jade_imtp_transport_svc
• jade_osgi_ms
• jade_transport_connection

All these JARs and also the external dependencies are placed under the directory "jars" in the distribution file (generated by the build process).

Agents bundles

Contains the bundles that define agents.

Bundles in this directory are loaded at JADE startup (particularly when the OsMoSes mobility service is initiated) and allows OSGi based agents to be launched.

OsMoSes requires read access in this directory.

By default this directory is looked for under current (at execution time) directory with the name "bundles". However the path to use can be specified using the configuration property osmoses_src_bundles_path.

Launching OsMoSes

These sections describe how to launch OsMoSes. It assumes some knowledge about launching JADE. For further details about launching JADE refer to its documentation (particularly to its administrators guide ).

The examples assume that there is a sub-directory called "jars" with all JAR dependencies (external dependencies and service JARs) and that the default required directories paths are valid. If you launch JADE standing in the deployed directory you are good to go.

Also, the command lines shown use the syntax for Linux/Unix, in Windows you will need to adjust them as necessary (e.g. change slashes '/' to back slashes '\' for paths).

The Simplest Way

The simplest way of launching JADE with OsMoSes requires only to specify the use of OsMoSes mobility service as a service for JADE and to activate the jade_imtp_transport_svc so it can be used as communication channel.

java -cp "jars/*" jade.Boot -services ar.uba.fi.mism.jade.transport.connection.imtp.ImtpConnectionTransportService\;ar.uba.fi.mism.jade.core.mobility.OsgiAgentMobilityService 

Note: as described in the JADE's administration guide, launching JADE this way will make the Notification
Service not enabled (is active by default but not if the option -services is specified). To enable it just add the extra service "jade.core.event.NotificationService" to the list.

The Personalized Way

OsMoSes can be configured to use different paths and to use different implementations for communication. For configuration options, you can refer to the Configuring OsMoSes section. Here it is explained how to launch OsMoSes with a different communication implementation.

Currently there are two implementations for transmitting OsMoSes related information between JADE containers. The default one is by using the same channel all other JADE services use (IMTP) and was the one presented in The Simplest Way section. Alternatively you can use an implementation based on "raw" TCP channel, this one should be more efficient (less data transmission overhead) but is a little more difficult to configure/use.

If you only want to start JADE containers in different hosts, then using TCP based communication is as easy as telling OsMoSes mobility service to do so. Here is how it is done:

java -cp "jars/*" jade.Boot -services ar.uba.fi.mism.jade.core.mobility.OsgiAgentMobilityService \
-osmoses_cont_conn_mgr_class ar.uba.fi.osmoses.jade.transport.connection.imtp.ImtpContainerConnector 

Note that in this case there is no need to start the jade_imtp_transport_svc. However, its associated JAR file must be in the classpath.
Refer to the configuration property osmoses_cont_conn_mgr_class for more information about it.

That was simple! but (as always, there is a but), if you need/want to launch different containers in the same host (but in different instances of JADE) you will need to choose different ports for the communication channel in each container (see jade_transport_connection tcp implementation for more details).
The ports to use by each container are specified by means of the configuration property tcp_container_connection_manager_port_specification.
Then, if you want to launch two containers "c1" and "c2" in the same hosts and assign the port 1660 to the first one and 1661 to the second one, the command line will be as follows:

java -cp "jars/*" jade.Boot -services ar.uba.fi.mism.jade.core.mobility.OsgiAgentMobilityService \
-osmoses_cont_conn_mgr_class ar.uba.fi.osmoses.jade.transport.connection.imtp.ImtpContainerConnector \
-tcp_container_connection_manager_port_specification "c1=1660,c2=1661" \
-container-name "c1"

Note: As the JADE's configuration option "container-name" indicates, the previous command line is for launching the container "c1". To use it for container "c2" just replace "c1" by "c2".

It is important to note that because you are setting non-default ports, if you want to be able to migrate agents from/to "c1" or "c2" to other's hosts containers, you will need to specify (using the configuration property tcp_container_connection_manager_port_specification) in those other hosts the port to use for migrations to that container ("c1" and/or "c2").

Starting Agents

In OSGi a class name is not sufficient to identify a class, you also need to indicate to which bundle the class belongs to. The way to identify a bundle that was chosen by OsMoSes is the pair [symbolic name, version], so, to specify the class for an agent, you will need to tell the class name, the bundle symbolic name and the bundle version.
OsMoSes takes advantage of a mechanism implemented in JADE to add properties associated to class names, and uses it to specify the bundle that class belongs to. So it defines two properties:

1. bundle_sn: to indicate the bundle symbolic name
2. bundle_v: to indicate the bundle version

Then, to tell you want to use the class "ClassA" from the bundle with symbolic name "BundleSnA" and version "1.0.0", you would use a "decorated" class name like the following:

ClassA[bundle_sn=BundleSnA,bundle_v=1.0.0]

Then, the simple way's command line would be:

java -cp "jars/*" jade.Boot -services ar.uba.fi.mism.jade.transport.connection.imtp.ImtpConnectionTransportService\;ar.uba.fi.mism.jade.core.mobility.OsgiAgentMobilityService "myAgent:ClassA[bundle_sn=BundleSnA,bundle_v=1.0.0]"

Which means "launch a JADE instance with OsMoSes (the simple way) and start up an agent called myAgent associated to the class ClassA from the bundle with symbolic name BundleSnA and version 1.0.0".

This way of launching an agent is no different from the one defined in JADE (see its administrators guide) except for the fact that, instead of specifying only the class name for the agent, you are indicating also the bundle that class belongs to.

Configuring OsMoSes

Currently there exists configuration properties to personalize the execution of the jade_osgi_ms and the jade_transport_connection tcp implementation. Refer to those pages for the details.