Getting Started with Janus
This page describes a simple and fast way to get your first Janus-based MultiAgent System up and running.
Contents |
Introduction
Janus is developed using Maven to manage all its official module. So we will discuss in this documentation how to create a simple Janus application using Maven.
The Janus platform is actually implemented as set of OSGi bundles. However it uses a different terminology to enforce the fact that when we develop a Janus application you are in fact developing a MultiAgent System (MAS) Application.
Even more Janus is an Holonic Organizational Platform. However, these concepts are outside of the scope of this page.
So lets get to business!
Creating your first Janus Application
To create our application we will use the an archetype provided by the Janus project. For further details please refer to the Janus application archetype.
To create your application run the following command :
$ mvn archetype:generate -DarchetypeCatalog=http://www.janus-project.org/maven/
You can also do this directly from eclipse, see Maven:Development for details.
Maven will ask you to select the archetype you want to use. Select crio-basic-app-archetype,
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Default Project
[INFO] task-segment: [archetype:generate] (aggregator-style)
[INFO] ------------------------------------------------------------------------
[INFO] Preparing archetype:generate
[INFO] No goals needed for project - skipping
[INFO] Setting property: classpath.resource.loader.class => 'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'.
[INFO] Setting property: velocimacro.messages.on => 'false'.
[INFO] Setting property: resource.loader => 'classpath'.
[INFO] Setting property: resource.manager.logwhenfound => 'false'.
[INFO] [archetype:generate {execution: default-cli}]
[INFO] Generating project in Interactive mode
[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
Choose archetype:
1: http://www.janus-project.org/maven/ -> crio-basic-app-archetype (Creates a simple Janus Application based on the CRIO meta-model)
Choose a number: (1): 1
[INFO] snapshot org.janus-project.maven:crio-basic-app-archetype:0.3-SNAPSHOT: checking for updates from crio-basic-app-archetype-repo
Downloading: http://devmas-set.utbm.fr/janus/maven/org/janus-project/maven/crio-basic-app-archetype/0.3-SNAPSHOT/crio-basic-app-archetype-0.3-SNAPSHOT.jar
10K downloaded (crio-basic-app-archetype-0.3-SNAPSHOT.jar)
Define value for groupId: : mygroup
Define value for artifactId: : myartifact
Define value for version: 1.0-SNAPSHOT: :
Define value for package: mygroup: :
Confirm properties configuration:
groupId: mygroup
artifactId: myartifact
version: 1.0-SNAPSHOT
package: mygroup
Y: : y
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 16 seconds
[INFO] Finished at: Fri Jun 18 13:16:41 ART 2010
[INFO] Final Memory: 17M/618M
[INFO] ------------------------------------------------------------------------
If you examine the created project, you will find the following structure:
$ cd myartifact
$ tree
.
├── pom.xml
└── src
└── main
├── janus
│ └── application
│ └── conf
│ ├── felix.japp.properties
│ └── janus.japp.properties
└── java
└── mygroup
├── Activator.java
├── agent
│ ├── ProviderAgent.java
│ └── RequestingAgent.java
├── Application.java
└── organization
├── DateMessage.java
├── DateProviderOrganization.java
├── DateProviderRole.java
└── RequesterRole.java
If fact the archetype has created a running MAS demo. ;). You can test the application using the command:
$ mvn clean install janus:run
The "janus:run" goal in the command line requests the Janus Maven Plugin to start an OSGi implementation with the janus kernel and your application. The created application uses the Apache Felix OSGi implementation. Janus is OSGi compliant so it will run on any implementation (e.g. Eclipse Equinox)
The output should look like to something like the following :
$ mvn clean install janus:run
[INFO] Scanning for projects...
[INFO] Repository 'org.janus-project.maven' will be blacklisted
[INFO] ------------------------------------------------------------------------
[INFO] Building Janus Simple CRIO based Application
[INFO] task-segment: [clean, install, janus:run]
[INFO] ------------------------------------------------------------------------
[INFO] [clean:clean {execution: default-clean}]
[INFO] [resources:resources {execution: default-resources}]
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory /tmp/janus/myartifact/src/main/resources
[INFO] [compiler:compile {execution: default-compile}]
[INFO] Compiling 8 source files to /tmp/janus/myartifact/target/classes
[INFO] [resources:testResources {execution: default-testResources}]
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory /tmp/janus/myartifact/src/test/resources
[INFO] [compiler:testCompile {execution: default-testCompile}]
[INFO] No sources to compile
[INFO] [surefire:test {execution: default-test}]
[INFO] No tests to run.
[INFO] [bundle:bundle {execution: default-bundle}]
[INFO] [install:install {execution: default-install}]
[INFO] Installing /tmp/janus/myartifact/target/myartifact-1.0-SNAPSHOT.jar to /home/sebastian/.m2/repository/mygroup/myartifact/1.0-SNAPSHOT/myartifact-1.0-SNAPSHOT.jar
[INFO] [bundle:install {execution: default-install}]
[INFO] Installing mygroup/myartifact/1.0-SNAPSHOT/myartifact-1.0-SNAPSHOT.jar
[INFO] Writing OBR metadata
[INFO] Preparing janus:run
[INFO] [janus:preparedist {execution: preparedist}]
[INFO] Found following OSGi bundles : [/home/sebastian/.m2/repository/org/janus-project/kernel/osgi/0.3-SNAPSHOT/osgi-0.3-SNAPSHOT.jar, /home/sebastian/.m2/repository/org/apache/felix/org.apache.felix.bundlerepository/1.6.2/org.apache.felix.bundlerepository-1.6.2.jar, /home/sebastian/.m2/repository/org/osgi/org.osgi.core/4.1.0/org.osgi.core-4.1.0.jar, /home/sebastian/.m2/repository/org/janus-project/kernel/kernel/0.3-SNAPSHOT/kernel-0.3-SNAPSHOT.jar, /home/sebastian/.m2/repository/org/arakhne/afc/arakhneVmutils/5.0-SNAPSHOT/arakhneVmutils-5.0-SNAPSHOT.jar, /home/sebastian/.m2/repository/org/janus-project/kernel/network/0.3-SNAPSHOT/network-0.3-SNAPSHOT.jar, /tmp/janus/myartifact/target/myartifact-1.0-SNAPSHOT.jar]
[INFO] adding dep : /home/sebastian/.m2/repository/org/janus-project/kernel/osgi/0.3-SNAPSHOT/osgi-0.3-SNAPSHOT.jar
[INFO] adding dep : /home/sebastian/.m2/repository/org/apache/felix/org.apache.felix.bundlerepository/1.6.2/org.apache.felix.bundlerepository-1.6.2.jar
[INFO] adding dep : /home/sebastian/.m2/repository/org/osgi/org.osgi.core/4.1.0/org.osgi.core-4.1.0.jar
[INFO] adding dep : /home/sebastian/.m2/repository/org/janus-project/kernel/kernel/0.3-SNAPSHOT/kernel-0.3-SNAPSHOT.jar
[INFO] adding dep : /home/sebastian/.m2/repository/org/arakhne/afc/arakhneVmutils/5.0-SNAPSHOT/arakhneVmutils-5.0-SNAPSHOT.jar
[INFO] adding dep : /home/sebastian/.m2/repository/org/janus-project/kernel/network/0.3-SNAPSHOT/network-0.3-SNAPSHOT.jar
[INFO] adding dep : /tmp/janus/myartifact/target/myartifact-1.0-SNAPSHOT.jar
[INFO] [janus:run {execution: default-cli}]
[INFO] binDirPath bin
[INFO] Running command [java,-jar,bin/org.apache.felix.main-3.0.0.jar,] on dir /tmp/janus/myartifact/target/janus-dist
========================================
Start Applicaton
========================================
[INFO] No config.properties found.
[INFO] Jul 6, 2010 8:28:14 PM org.janusproject.kernel.agent.KernelAgent <clinit>
[INFO] WARNING: No default configuration found for logging system
[INFO] Jul 6, 2010 8:28:14 PM org.janusproject.kernel.agent.KernelAgent <init>
[INFO] INFO:
[INFO] **********************************************
[INFO] * JANUS Platform *
[INFO] * Copyright: the Janus development Team *
[INFO] * Holinicly Yours *
[INFO] * Report any bug to: *
[INFO] * Bugs.. there are no bugs in my code.. *
[INFO] * That's certainly Nico that coded it (Seb). *
[INFO] * If there is effectively no bug, *
[INFO] * no doubt : Nico has corrected it (Nico). *
[INFO] * That's a piece of art...since my *
[INFO] * insectiside code was included, *
[INFO] * isn't it (Steph). *
[INFO] * Just kidding : *
[INFO] * https://devmas-set.utbm.fr/jira/ *
[INFO] * Thank you for helping us improve JANUS *
[INFO] **********************************************
[INFO] Jul 28, 2010 12:32:46 PM org.janusproject.kernel.logger.LoggerUtil loadDefaultConfiguration
[INFO] WARNING: No default configuration found for logging system
[INFO] Jul 28, 2010 12:32:46 PM org.janusproject.kernel.logger.LoggerUtil loadDefaultConfiguration
[INFO] WARNING: No default configuration found for logging system
[INFO] Jul 28, 2010 12:32:46 PM org.janusproject.kernel.logger.LoggerUtil loadDefaultConfiguration
[INFO] WARNING: No default configuration found for logging system
[INFO] Jul 28, 2010 12:32:46 PM | Agent<,231ea04d-3848-445a-8da3-90113d1127ab> on role RequesterRole | INFO : Requesting date...
[INFO] Jul 28, 2010 12:32:46 PM | Agent<,263d3d71-b926-4fbc-9111-f96d52b8f19f> | INFO : Done activation of ProviderAgent
[INFO] Jul 28, 2010 12:32:46 PM | Agent<,231ea04d-3848-445a-8da3-90113d1127ab> on role RequesterRole | INFO : Requesting date...
[INFO] Jul 28, 2010 12:32:46 PM | Agent<,231ea04d-3848-445a-8da3-90113d1127ab> on role RequesterRole | INFO : Current date is Wed Jul 28 12:32:46 ART 2010
[INFO] Jul 28, 2010 12:32:46 PM | Agent<,231ea04d-3848-445a-8da3-90113d1127ab> on role RequesterRole | INFO : Requesting date...
[INFO] Jul 28, 2010 12:32:46 PM | Agent<,231ea04d-3848-445a-8da3-90113d1127ab> on role RequesterRole | INFO : Current date is Wed Jul 28 12:32:46 ART 2010
[INFO] Jul 28, 2010 12:32:46 PM | Agent<,231ea04d-3848-445a-8da3-90113d1127ab> on role RequesterRole | INFO : Requesting date...
[INFO] Jul 28, 2010 12:32:46 PM | Agent<,231ea04d-3848-445a-8da3-90113d1127ab> on role RequesterRole | INFO : Current date is Wed Jul 28 12:32:46 ART 2010
[INFO] Jul 28, 2010 12:32:46 PM | Agent<,231ea04d-3848-445a-8da3-90113d1127ab> on role RequesterRole | INFO : Requesting date...
[INFO] Jul 28, 2010 12:32:46 PM | Agent<,231ea04d-3848-445a-8da3-90113d1127ab> on role RequesterRole | INFO : Current date is Wed Jul 28 12:32:46 ART 2010
[INFO] Jul 28, 2010 12:32:46 PM | Agent<,231ea04d-3848-445a-8da3-90113d1127ab> on role RequesterRole | INFO : Requesting date...
[INFO] Jul 28, 2010 12:32:46 PM | Agent<,231ea04d-3848-445a-8da3-90113d1127ab> on role RequesterRole | INFO : Current date is Wed Jul 28 12:32:46 ART 2010
[INFO] Jul 28, 2010 12:32:46 PM | Agent<,231ea04d-3848-445a-8da3-90113d1127ab> on role RequesterRole | INFO : Current date is Wed Jul 28 12:32:46 ART 2010
[INFO] Jul 28, 2010 12:32:46 PM | Agent<,263d3d71-b926-4fbc-9111-f96d52b8f19f> | INFO : ProviderAgent end.
[INFO] Jul 28, 2010 12:32:46 PM | Agent<,231ea04d-3848-445a-8da3-90113d1127ab> | INFO : RequestingAgent end.
[INFO] Jul 28, 2010 12:32:46 PM | Kernel<974fc756-0200-4213-8b52-e4345ad06138> | INFO : JANUS Kernel is stopped.
[INFO] Jul 28, 2010 12:32:46 PM org.janusproject.kernel.mmf.osgi.Activator stop
[INFO] INFO: null
[INFO] Jul 28, 2010 12:32:46 PM org.janusproject.kernel.mmf.osgi.Activator stop
[INFO] INFO: Stopping OSGi Framework.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 7 seconds
[INFO] Finished at: Tue Jul 06 20:28:14 ART 2010
[INFO] Final Memory: 35M/618M
[INFO] ------------------------------------------------------------------------
The application is a simple Date Provider demo, where one agent requests the current date 5 times.
Lets now tackle the application itself.
Understanding the application structure
Janus Application
Janus Applications are actually OSGi bundles. They are able to launch agents by registering themselves in the BundleContext.
As a module is an OSGi bundle you will have to make you maven project compatible with OSGi. In order to do so you can use the Apache Felix Bundle Plugin.
Here is the generated pom.xml
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>mygroup</groupId> <artifactId>myartifact</artifactId> <name>Janus Simple CRIO based Application</name> <version>1.0-SNAPSHOT</version> <packaging>bundle</packaging> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>1.6 < / source> <target>1.6</target> </configuration> </plugin> <plugin> <groupId>org.apache.felix</groupId> <artifactId>maven-bundle-plugin</artifactId> <extensions>true</extensions> <configuration> <instructions> <Bundle-Activator>mygroup.Activator</Bundle-Activator> </instructions> </configuration> </plugin> <plugin> <groupId>org.janus-project.maven</groupId> <artifactId>maven-janus-plugin</artifactId> <version>${janus.verion}</version> <configuration> <layout>felix</layout> <!-- The launcher will instantiate a OSGi Platform --> <launcher> <groupId>org.apache.felix</groupId> <artifactId>org.apache.felix.main</artifactId> <version>${felix.main.version}</version> </launcher> </configuration> </plugin> </plugins> </build> <repositories> <repository> <id>org.janus-project.maven</id> <name>Janus Project Snapshots</name> <url>https://devmas-set.utbm.fr/janus/maven/</url> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>org.janus-project.maven</id> <name>Janus Project Snapshots</name> <url>https://devmas-set.utbm.fr/janus/maven/</url> </pluginRepository> </pluginRepositories> <dependencies> <dependency> <groupId>org.janus-project.kernel</groupId> <artifactId>osgi</artifactId> <version>${janus.verion}</version> </dependency> <dependency> <groupId>org.janus-project.kernel</groupId> <artifactId>network</artifactId> <version>${janus.verion}</version> </dependency> <!-- Uncomment these dependencies if you what to use the osgi shell. Remember that if you include them they will be included in you final application distribution zip, then increasing your application footprint. --> <!-- <dependency> <groupId>org.apache.felix</groupId> <artifactId>org.apache.felix.gogo.command</artifactId> <version>${felix.gogo.version}</version> </dependency> <dependency> <groupId>org.apache.felix</groupId> <artifactId>org.apache.felix.gogo.shell</artifactId> <version>${felix.gogo.version}</version> </dependency> --> <dependency> <groupId>org.apache.felix</groupId> <artifactId>org.apache.felix.main</artifactId> <version>${felix.main.version}</version> <scope>provided</scope> </dependency> </dependencies> <properties> <janus.verion>0.3-SNAPSHOT</janus.verion> <felix.main.version>3.0.0</felix.main.version> <felix.gogo.version>0.6.0</felix.gogo.version> </properties> </project>
BundleActivator
The bundle Activator should look something like this:
public class Activator implements BundleActivator{ private JanusApplication application = null; /* * (non-Javadoc) * * @see * org.osgi.framework.BundleActivator#start(org.osgi.framework.BundleContext * ) */ public void start(BundleContext context) throws Exception { application = new Application(context); context.registerService(JanusApplication.class.getName(),application , null); } /* * (non-Javadoc) * * @see * org.osgi.framework.BundleActivator#stop(org.osgi.framework.BundleContext) */ public void stop(BundleContext context) throws Exception { } }
In fact, all the work is done by the Application class which implements the JanusApplication interface :
public class Application implements JanusApplication { private BundleContext context = null; public Application(BundleContext context) { this.context = context; } /* * (non-Javadoc) * * @see * org.janusproject.kernel.mmf.JanusModule#start(org.janusproject.kernel * .mmf.IKernelService) */ @Override public Status start(IKernelService kernel) { kernel.launchHeavyAgent(new ProviderAgent()); kernel.launchHeavyAgent(new RequestingAgent()); return StatusFactory.ok(this); } /* * (non-Javadoc) * * @see org.janusproject.kernel.mmf.JanusApplication#getKernelAgentFactory() */ @Override public KernelAgentFactory getKernelAgentFactory() { //Use this if you want to enable networking. //return new NetworkingKernelAgentFactory(context); //Use this if you want a stand-alone kernel. return null; } /* * (non-Javadoc) * * @see org.janusproject.kernel.mmf.JanusApplication#getKernelAuthority() */ @Override public IKernelAuthority getKernelAuthority() { // All operations are approved. return null; } /* * (non-Javadoc) * * @see * org.janusproject.kernel.mmf.JanusApplication#isAutoStartJanusModules() */ @Override public boolean isAutoStartJanusModules() { // All modules registered will be started automatically. return false; } /* (non-Javadoc) * @see org.janusproject.kernel.mmf.JanusModule#stop(org.janusproject.kernel.mmf.IKernelService) */ @Override public Status stop(IKernelService kernel) { return StatusFactory.ok(this); } }
A couple of things to notice here :
- Agents are launched using the start method
- The KernelAgentFactory allows you to configure which type of kernel you what to use. For the moment Janus offers two types of kernel. Stand-alone (i.e no network) connectivity and a network enabled Kernel.
- If you return true in the isAutoStartJanusModules() all module registered will be launched automatically.
- If you do not provide a IKernelAuthority, ALL operation request are automatically approved. This can be great when prototyping but be care in you final app.
Creating a distributable zip for your application
If you want to obtain a zip that you can distribute simply run the following command:
$mvn clean install janus:zip
In the target directory (or your maven output directory if you changed it) you will find a mygroup-myartifact-1.0-SNAPSHOT.zip. This file contains all your OSGi dependencies. In fact you will find ONLY your OSGi dependencies. If you have other "regular" jar dependencies, you can use the maven-bundle-plugin to include you dependencies in you janus module OSGi bundle.
Now you can unzip the zip and run you application using:
$java -jar bin/org.apache.felix.main-3.0.0.jar
Go ahead! Give it a try! Nice... right?
