Contributor's Guide

This page is too big, it should be splitted up in 2 parts.
Some clean-up for XWiki Syntax v2.0 is also required

Role description

This material is prepared for "JOnAS code contributors" and "JOnAS application developers" who are not working with JOnAS team members in France. JOnAS team is a mature team, so there are not enough materials for newcomers; this guide will be helpful and can lead them to the right way.

  • Role JOnAS code contributor means developer who checks JOnAS source code, make some change and commit to JOnAS source code repository. They need the right to commit their changes.
  • Role JOnAS application developer means developer who only needs to run JOnAS, develop applications, deploy them on JOnAS and test them. They do not need to check JOnAS source code, neither the right to commit.


Join OW2 community

Browse the home page of OW2, create a new account.

Subscribe JOnAS mail listings

TO communite with JOnAS developers, you can subscribe JOnAS mail listings. JOnAS has a lot of mail listings, the most important is JOnAS-team list, you can browse this page to subscribe those mail listings:

Use Pidgin for IM

Besides mail listings, OW2 also provides a server for instance message, you can use pidgin to log in and communicate with others, and the steps to use it is like following:

  • Download the client program: pidgin
  • Configure the right server address
    1. The protocol is XMPP
    2. Domain is
    3. The account and password are the same as OW2 community
    4. The port is 5222, and the proxy for file transfer is

Check out JOnAS source code

The address to check out JOnAS is:

{id} is your account you created in OW2 community, if you are using windows as your platform, you can use TortoiseSVN and some other third party tools to simplify your operations.

Directory architecture of JOnAS

Use JOnAS 5.1.1 as the example, after check out the source, you will get the JOnAS source code directory architecture

  • Important directories:
    assemblies:Configurations, examples, output
     -binaries:Executable files in the generated bin directory
     -profiles:Output directory for JOnAS
    eclipse-settings:Code convention
    modules:Source code of JOnAS project
    -apis:public interfaces
    -client:client container
    -client-bootstrap: about client container
    -ee-components: jonas admin,etc.
    -generators: generators for JOnAS
    -itests: some tests for JOnAS
    -libraries: function module implementation
    -services: function module implementation
    -tools: launcher, etc.
  • Module architecture:
    Architecture of each module is like this:
    Java:Source code
    .bnd 文件:Describe type dependency (import/export)
    metadata.xml:Describe service dependency, used for ipojo to manage runtime service instance
    pom.xml:Used for maven build
  • Module architecture:
    Pom file
    .bnd file:Describe type dependency; translate to MF file when maven builds
    MANIFEST.MF:Describe type dependency
    metadata.xml:Describe service dependency

Maven build JOnAS

Environment: jdk 1.5
             Maven 2.x(latest best)
             Subversion (used when maven build)
Configuration for maven:

  1. Add maven to system env variable path.
  2. Edit /conf/setting.xml localrepository, change it to some shorter absolute path if your platform is windows.
    To maven build JOnAS, go to root path of JOnAS source code, and run “mvn”.
    To accelerate maven build, you can consider using artifactory or nexus to create a local mirror of maven remote repository, and add it to JOnAS repository or Maven repository:
          <id>Your repository’s id</id>
          <name>Your repository’s name</name>
          <url>Your repository’s url</url>

    Explanation of the JOnAS root directory pom file:
    <dependency>:Dependency on third party tools
    <repository>:Remote repository that JOnAS depends on
    <pluginManagement>:plugins management
    maven-jbuilding-plugin:to build java source code
    <scm>:Source code management
    When maven build, you may meet some problems,
    one error is :
    <table width="100%" cellspacing="0" cellpadding="0">
    #note("Provider message:</br>The svn command failed.</br>Command output:</br>")
    That means the maven build called command "svn", but you didn't install one, you should install one to solve this problem, you can download here for windows platform:
    Another common error is :
    <table width="100%" cellspacing="0" cellpadding="0">
    #note("FATAL ERROR</br>- - - - - - - - -</br>Java heap space</br>- - - - - - - - -</br>Trace</br>java.lang.OutOfMemoryError: Java heap space")

    To solve this problem, you have two methods:
  1. Add an environment variable “MAVEN_OPTS”, its value is “-Xms64m -Xmx1024m”.
  2. Edit mvn.bat, add “set MAVEN_OPTS= -Xms64m -Xmx1024m” on the top.
    The settings above will tell system to allocate a larger memory for maven, so that maven will not fail because of memory constraint.
    Maven build may fail or stop when the network is not good, it cannot get jar files from remote repository, you should stop maven build and run “mvn clean install” again to get them again, and sometimes it will be ok after some repeats.


Run JOnAS in command line

Set env variable: JONAS_ROOT and JONAS_BASE, use JOnAS 5.1.1 as example, after maven build, you can set them to /assemblies/profiles/full/target/jonas-full-5.1.1-bin.dir/jonas-full-5.1.1
To start JOnAS, you can go to bin directory and run “jonas start” to start JOnAS, you can also run “jonas stop” to stop JOnAS

Run JOnAS in Eclipse

The main class to run JOnAS:org.ow2.jonas.launcher.felix.JOnAS
<img src="$xwiki.getAttachmentURL("Tutorials.WebHome", "arg-1.jpg")" title="arg-1" alt="arg-1">
Set program argument:
Set VM arguments:
you should replace "{JONAS_ROOT}" with the absolute path of JOnAS
<img src="$xwiki.getAttachmentURL("Tutorials.WebHome", "arg-2.jpg")" title="arg-2" alt="arg-2">

Main arguments:
jonas.felix.gui.enabeld: whether start felix gui console</br>
m2.repository: the absolute path of local maven repository
Besides, you should add "{jonas_root}/conf" and {jonas_root}/lib/bootstrap/*.jar into the classpath.
<img src="$xwiki.getAttachmentURL("Tutorials.WebHome", "arg-3.jpg")" title="arg-3" alt="arg-3">
Then you can run jonas in Eclipse.

JOnAS configuration

Here is a very brief introduction to JOnAS configuration, if you need to learn about the details, you can browse this page and get more:

 When you are developing in JOnAS, you may need to configure JOnAS behavior. JOnAS use configure files to let developers configure it.
 Most configuration files are in the directory : {JONAS_ROOT}/conf.
 You can see ””, “”, “”, “tomcat6-server.xml”, etc. They are all important configuration files for JOnAS.
 The most often used configuration file is “”, it is the key file for configuring JOnAS, it is used for:

  1. setting some global properties for the JOnAS instance
  2. choosing the list of JOnAS services to be launched at startup
  3. customizing each services

Global properties

#Name of the JOnAS server</br>
#default value is "jonas"</br>    jonas</br>
#Name of the JOnAS domain</br>
#default value is "jonas"</br>    jonas</br>
#Enable the Security context propagation (for jrmp)</br>    true</br>
#Enable the Security manager</br>
#default value is true (if not set)</br>
#Setting this to false implies a collocated registry and setting in </br></br>
#carol.jvm.rmi.local.registry=true</br>    false</br>
#Enable csiv2</br>
  jonas.csiv2.propagation    true</br>
#Enable the Transaction context propagation</br>
  jonas.transaction.propagation    true</br>
#Set the name of log configuration file</br>
  jonas.log.configfile    trace</br>
#Set to true if the server is a master</br>
  jonas.master    false</br>
#Set to true in order to execute the JOnAS Server in development mode.</br>
#WAR archive deployment case in development mode (for single or EAR packaged WARs):</br>
#Each modified WAR archive will be unpacked in the working directory of the JOnAS Server</br>
#in a different folder to avoid file locks. This is especially useful in a Windows environment.</br>
  jonas.development    true</br>
Here you can set global properties to a customized value.
Here is the list of default services activated at starting time:
<p/>    jtm, db, security, resource, ejb3, jaxws, web, ear, depmonitor

  • cmi
    • this service provides support for the clustering of RMI objects.
  • db
    • this service is used for launching a Java database implementation. By default, HSQLDB java database is used.
  • dbm
    • this service is needed by application components that require access to one or several relational databases. It may be an alternative to the usage of a JDBC resource adapter via the resource service.
  • depmonitor
    • this service is used to control the application's deployment process in JOnAS.
  • discovery

Service startup policies

The picture below describes mandatory dependencies beetwen JOnAS services. A link between two services means that a service requires another one. Note on the right side services without dependency links.
<img src="$xwiki.getAttachmentURL("Tutorials.WebHome", "servicedependency.jpg")" title="service dependency" alt="service dependency"/>

Example(Add a customized module in JOnAS)

When we are developing in JOnAS, we may need to add services into JOnAS to provide new functions. One module may contain more than one service. Here we give an example to tell how to add a new module. In this example, we add a new module called “Axis2”, its function is to run as an optional webservice engine in JOnAS, it’s a sub module of webservices.
You need these steps to add this module:

  • Build a directory architecture according maven standard.
  • Write pom.xml for this module in the root directory.
    <img src="$xwiki.getAttachmentURL("Tutorials.WebHome", "directoryarchitecture.JPG")" title="directory architecture" alt="directory architecture"/>

After these two steps, you will be able to maven build this module as a sub module of “webservices”.
You need other steps to finish your work:

  • Write your service classes: this class should implement a service interface. It will then be exposed as a service in JOnAS.
    <img src="$xwiki.getAttachmentURL("Tutorials.WebHome", "serviceclass.JPG")" title="service class" alt="service class"/>
  • Write other subsidiary classes.
  • Write bnd file: each module in JOnAS has a bnd file, its name is “{artifactId}.bnd”, the {artifactId} is the value of “artifactId” in pom.xml. Bnd file contains “Export”, ”Import” and other code/type dependency, it is translated into MF file when maven build.
    Import-Package  org.apache.neethi, </br>
    Embed-Dependency axiom-api, </br>
    Embed-Transitive true</br>
  • Write metadata.xml: each module in JOnAS has a metadata.xml; it is used to describe the run-time information about services in this module. Each service It describes which interface this service implements, and which service instance this service need in run time, it also describes callback functions this service provides.
    <font color="blue">
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;</br> &lt;ipojo xmlns:xsi="" xmlns="org.apache.felix.ipojo" xsi:schemaLocation="org.apache.felix.ipojo" &gt;</br> &lt;component classname="" name="EasyBeans-Extension/Axis2" public="false" immediate="true"&gt;</br> &lt;provides specifications="org.ow2.easybeans.api.EZBConfigurationExtension" /&gt;</br> &lt;!-- Required dependencies --&gt;</br> &lt;requires optional="false"&gt;</br> &lt;callback type="bind" method="bindWebDeployer" /&gt;</br> &lt;/requires&gt;</br> &lt;/component&gt;</br> &lt;!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --&gt;</br> &lt;!-- Axis2Service --&gt;</br> &lt;!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --&gt;</br> &lt;component classname="" immediate="false"&gt;</br> &lt;provides specifications=""/&gt;</br> &lt;requires optional="false" specification=""&gt;</br> &lt;!-- @specification is required here because only the abstract JOnAS service reference that class, and iPOJO cannot introspect bytecode of that class that is not inside this bundle --&gt;</br> &lt;callback type="bind" method="setServerProperties" /&gt;</br> &lt;/requires&gt;</br> &lt;!-- "Inherited" from JAXWSService --&gt;</br> &lt;requires optional="false" specification="org.ow2.jonas.jmx.JmxService"&gt;</br> &lt;callback type="bind" method="setJmxService" /&gt;</br> &lt;/requires&gt;</br> &lt;requires optional="false"&gt;</br> &lt;callback method="bindEventService" type="bind" /&gt;</br> &lt;callback method="unbindEventService" type="unbind" /&gt;</br> &lt;/requires&gt;</br> &lt;!-- LifeCycle Callbacks --&gt;</br> &lt;callback transition="validate" method="start"/&gt;</br> &lt;callback transition="invalidate" method="stop"/&gt;</br> &lt;properties propagation="true"/&gt;</br> &lt;/component&gt;</br> &lt;instance component="EasyBeans-Extension/Axis2" /&gt;</br> &lt;/ipojo&gt;</br>
    In our example, we exposed two services, and each service is described as a component in metadata.xml, and metadata.xml is processed by iPojo at JOnAS run time.</br>
    After these steps above, we can package this module into a ipojo jar file, and install it into JOnAS. We may need some more changes to other modules related to this module.</br>
    If we want JOnAS to auto start your module at run time, you should first edit {jonas_root}/assemblies/profiles/pom.xml to add a deploymentplan for this module. It will create a xml file in {jonas_root}/assemblies/profiles/full/target/jonas-full-5.2.0-M1-SNAPSHOT-bin.dir/jonas-full-5.2.0-M1-SNAPSHOT/repositories/url-internal which describe the dependency of this bundle.</br>
    You need to add your service into {jonas_root}/assemblies/profiles/full/target/jonas-full-5.2.0-M1-SNAPSHOT-bin.dir/jonas-full-5.2.0-M1-SNAPSHOT/conf/</br>
    <p/>    jtm,db,dbm,security,resource,ejb3,jaxws2,web,ear,depmonitor</br>
    Then JOnAS will start your service when starts.</br>

Guide for JOnAS-based application developer

Download JOnAS

You can download JOnAS from this


Environment: jdk 1.5</br>
Env variable: JONAS_ROOT and JONAS_BASE set to JOnAS work directory</br>
To start JOnAS, you can go to bin directory and run “jonas start” to start JOnAS, you can also run “jonas stop” to stop JOnAS</br>

Directory architecture of JOnAS

  • Bin
    • Executable files of JOnAS
    • Jonas.bat: used to start and stop JOnAS on windows
  • Conf
    • Configuration files of JOnAS
  • Deploy
    • Deploy directory of JOnAS
  • Example
    • Examples of JOnAS
  • Lib
    • Libraries of JOnAS
  • Repository
    • All ipojo jars and third party jars of JOnAS
  • Templates
    • Temporary directory

Run JOnAS Admin

JOnAS Admin is a default application which is auto deployed when JOnAS starts, then you can use JOnAS Admin to monitor and manage JOnAS server.
~~URL: http://localhost:9000/jonasAdmin~~
User name/password: jonas/jonas
You can use this account to log in JOnAS Admin tool and use it.
<img src="$xwiki.getAttachmentURL("Tutorials.WebHome", "jonasadmin.JPG")" title="jonas admin" alt="jonas admin"/>

You can view all common services and deployed applications in JOnAS.
<img src="$xwiki.getAttachmentURL("Tutorials.WebHome", "jonasadmin2.JPG")" title="jonas admin2" alt="jonas admin2"/>

<img src="$xwiki.getAttachmentURL("Tutorials.WebHome", "jonasadmin3.JPG")" title="jonas admin3" alt="jonas admin3"/>

Deploy applications on JOnAS

You have two ways to deploy applications on JOnAS:

  • JOnAS Admin
    You can update your archives and deploy them on JOnAS using JOnAS Admin tools.
    <img src="$xwiki.getAttachmentURL("Tutorials.WebHome", "jonasadmin4.JPG")" title="jonas admin4" alt="jonas admin4"/>
  • Auto deploy
    You can also just put your archives into JOnAS_ROOT/deploy, and JOnAS will auto deploy your applications.



Remote interface:

<font color="blue">
package org.ow2.jonas.helloworld;</br> public interface HelloWorldRemote {</br> public String say(String s);</br> }</br>

Stateless Session Bean:

<font color="blue">
package org.ow2.jonas.helloworld;</br> import javax.ejb.Remote;</br> import javax.ejb.Stateful;</br> import javax.ejb.Stateless;</br> @Stateless</br> @Remote(HelloWorldRemote.class)</br> public class HelloWorldBean implements HelloWorldRemote</br> {</br> public String say(String s) {</br> System.out.println(m);</br> return m+" reached!";</br> }</br> }</br>


<font color="blue">
package org.ow2.jonas.helloworld;</br> import java.util.Properties;</br> import javax.naming.Context;</br> import javax.naming.InitialContext;</br> public final class Client {</br> private static final String JNDI_NAME =</br> "org.ow2.jonas.helloworld.HelloWorldBean"</br> + "_" + HelloWorldRemote.class.getName()</br> + "@Remote";</br> public static void main(final String[] args) </br> throws Exception {</br> Properties props = new Properties();</br> props.setProperty("java.naming.factory.initial",</br> "org.ow2.carol.jndi.spi.MultiOrbInitialContextFactory");</br> Context initialContext = new InitialContext(props);</br> HelloWorldRemote businessItf =</br> (HelloWorldRemote) initialContext.lookup(JNDI_NAME);</br> System.out.println("Calling helloWorld method...");</br> System.out.println(businessItf.say("123"));</br> }</br> }</br>
<font color="red">

  1. To run the client,classpath should contain the client.jar which is under the folder {JONAS_ROOT}/lib.
  2. The jndi property java.naming.factory.initial should be set as org.ow2.carol.jndi.spi.MultiOrbInitialContextFactory
  3. Remember the jndi name format: BeanName_RemoteInterfaceName@Remote


&nbsp&nbsp&nbsp&nbspJOnAS can support webservice, it has two optional JAXWS webservice engine: CXF and Axis2. Here we have one simple example. JOnAS can support two kind of webservice, one is EJB webservice, and another is pojo webserice.</br>
&nbsp&nbsp&nbsp&nbspTo develop a webservice on JOnAS, you should first write a webservice application according to JAXWS specifications, then deploy it on JOnAS.</br>
&nbsp&nbsp&nbsp&nbspIn this example, we wrote a Hello interface and HelloWorld bean:</br>

Hello bean:

<font color="blue>
import javax.jws.WebMethod;</br>
import javax.jws.WebService;</br>
import javax.jws.soap.SOAPBinding;</br>
public class SimpleService implements SimpleServiceInterface {</br>
    private static final long serialVersionUID = 1L;</br>
    public String greetMe(String str) {</br>
        System.out.println("Hello World: " + str);</br>
        return "hello world" + str;</br>

Hello interface:

import javax.jws.WebMethod;</br>
public interface SimpleServiceInterface {</br>
    public String greetMe(String str);</br>
&nbsp&nbsp&nbsp&nbspIts function is to receive a string, and return “hello world” added with this string. We used annotations here to tell JOnAS webservice engine this is a webservice. We also provide the wsdl for this application, but this is optional.
&nbsp&nbsp&nbsp&nbspBesides, we write web.xml and jonas-web.xml, they tell JOnAS web container to create a context root for this webservice. Then we can compile and package them into a jar file.
&nbsp&nbsp&nbsp&nbspAfter deploy it, we can browse the url of this ws to get wsdl for it and invoke it:
<img src="$xwiki.getAttachmentURL("Tutorials.WebHome", "wsdl.JPG")" title="wsdl" alt="wsdl"/>

&nbsp&nbsp&nbsp&nbspWe can invoke this ws by writing a ws client program, here we use soapui as the ws client to invoke our application:
<img src="$xwiki.getAttachmentURL("Tutorials.WebHome", "soapui.JPG")" title="soapui" alt="soapui"/>

Related resources

OW2 Forge:</br>
Mainly used as a platform for developer’s communication and project management.
<img src="$xwiki.getAttachmentURL("Tutorials.WebHome", "forge.JPG")" title="forge" alt="forge"/>
A bug tracking system, assign bug to developers, and discuss about bugs, you can also see detailed svn records.
<img src="$xwiki.getAttachmentURL("Tutorials.WebHome", "jira.JPG")" title="jira" alt="jira"/>

JOnAS Wiki

&nbsp&nbsp&nbsp&nbspJOnAS wiki is a home page for JOnAS project; it contains the latest news and information about JOnAS. You can download the latest stable version of JOnAS. You can also get JOnAS’s detailed documents and examples here.
Here gives an outline of JOnAS project and introduces involved organizations, here also gives a very brief introduction to JOnAS’s characteristic of on-demand and support for SOA.
<img src="$xwiki.getAttachmentURL("Tutorials.WebHome", "wiki.JPG")" title="wiki" alt="wiki"/>

JOnAS document:</br></br>
You can find most JOnAS 4 & JOnAS 5 document here, including configuration</br>
manual, user manual, technical white paper, etc. This is very useful for freshman in developing JOnAS.</br>
JOnAS Java doc:</br></br></br>
You can look up java doc of JOnAS 4 & JOnAS 5 here.</br>

JOnAS document:

&nbsp&nbsp&nbsp&nbspJOnAS supplied a document for beginners in developing applications on JOnAS, you can get some detailed information here:</br>