Recent News
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.
Guide for JOnAS code contributor
Browse the home page of OW2 community：
http://forge.ow2.org, 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:
http://jonas.ow2.org/wws/info/jonas-team
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:
- The protocol is “XMPP”
- Domain is “jabber.objectweb.org”
- The account and password are the same as OW2 community
- Resource is “Home”
- The port is 5222, and the proxy for file transfer is proxy.jabber.org:7777
Check out JOnAS source code
The address to check out JOnAS is:
svn+ssh://{id}@svn.forge.objectweb.org/svnroot/jonas/jonas/trunk/jonas
{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
assemblies：Configurations, examples, output
-binaries：Executable files in the generated bin directory
-configuration：Configurations
-example：Examples
-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.
Architecture of each module is like this:
Java：Source code
Resources
META-INF
.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
META-INF
Maven
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:
- Add maven to system env variable path.
- 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:
Your repository’s id
Your repository’s name
Your repository’s url
true
false
Explanation of the JOnAS root directory pom file:
：Dependency on third party tools
：Remote repository that JOnAS depends on
：plugins management
maven-jbuilding-plugin：to build java source code
：Source code managementWhen maven build, you may meet some problems,
one error is :
|
Provider message:The svn command failed.Command output: |
|
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: http://www.sliksvn.com/en/download
Another common error is :
|
|
FATAL ERROR- - - - - - - - -Java heap space- - - - - - - - -Tracejava.lang.OutOfMemoryError: Java heap space |
|
To solve this problem, you have two methods:
- Add an environment variable “MAVEN_OPTS”, its value is “-Xms64m -Xmx1024m”.
- 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
Run JOnAS in command line
Environment：Jdk-1.5
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
Set program argument:
-startSet VM arguments:-Djonas.root=${JONAS_ROOT}
-Djonas.base=${JONAS_BASE}
-Djava.security.policy=${JONAS_BASE}confjava.policy
-Dorg.omg.CORBA.ORBClass=org.jacorb.orb.ORB
-Djonas.developer=true
-Djonas.cache.clean=true
-Djonas.felix.gui.enabled=false
-Djonas.felix.tui.enabled=true
-Dorg.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingleton
-Dorg.omg.PortableInterceptor.ORBInitializerClass.standard_init=org.jacorb.orb.standardInterceptors.IORInterceptorInitializer
-Djavax.rmi.CORBA.PortableRemoteObjectClass=org.ow2.carol.rmi.multi.MultiPRODelegate
-Djava.naming.factory.initial=org.ow2.carol.jndi.spi.MultiOrbInitialContextFactory
-Djavax.rmi.CORBA.UtilClass=org.ow2.carol.util.delegate.UtilDelegateImpl
-Djava.security.auth.login.config=${JONAS_BASE}confjaas.config
-Djava.endorsed.dirs=${JONAS_ROOT}libendorsed
-DConfigHome=${JONAS_ROOT}conf
-Dm2.repository=F:repositoryyou should replace "{JONAS_ROOT}" with the absolute path of JOnAS
Main arguments：
jonas.felix.gui.enabeld: whether start felix gui console
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.
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:http://jonas.ow2.org/JONAS_5_1_1/doc/doc-en/html/configuration_guide.html 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 ”carol.properties”, “db2.properties”, “jonas.properties”, “tomcat6-server.xml”, etc. They are all important configuration files for JOnAS. The most often used configuration file is “jonas.properties”, it is the key file for configuring JOnAS, it is used for:
- setting some global properties for the JOnAS instance
- choosing the list of JOnAS services to be launched at startup
- customizing each services
Global properties
#Name of the JOnAS server
#default value is "jonas"
jonas.name jonas#Name of the JOnAS domain
#default value is "jonas"
domain.name jonas#Enable the Security context propagation (for jrmp)
jonas.security.propagation true#Enable the Security manager
#default value is true (if not set)
#Setting this to false implies a collocated registry and setting in
#carol.properties:
#carol.jvm.rmi.local.registry=true
jonas.security.manager false#Enable csiv2
jonas.csiv2.propagation true#Enable the Transaction context propagation
jonas.transaction.propagation true#Set the name of log configuration file
jonas.log.configfile trace#Set to true if the server is a master
jonas.master false#Set to true in order to execute the JOnAS Server in development mode.#WAR archive deployment case in development mode (for single or EAR packaged WARs):
#Each modified WAR archive will be unpacked in the working directory of the JOnAS Server
#in a different folder to avoid file locks. This is especially useful in a Windows environment.
jonas.development trueHere you can set global properties to a customized value.Here is the list of default services activated at starting time:jonas.services 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
- this service allows dynamic administration of management domains.
You can see more detailed introduction to each service on
http://jonas.ow2.org/JONAS_5_1_1/doc/doc-en/html/configuration_guide.html
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.
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.
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.
- 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,
Private-Package org.ow2.jonas.ws.axis2.
Embed-Dependency axiom-api,
xbean-reflect
Embed-Transitive true
- 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.
<?xml version="1.0" encoding="UTF-8"?>
<ipojo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="org.apache.felix.ipojo"
xsi:schemaLocation="org.apache.felix.ipojo http://felix.apache.org/ipojo/schemas/1.4.0/core.xsd" >
<component classname="org.ow2.jonas.ws.axis2.easybeans.ext.Axis2ConfigurationExtension"
name="EasyBeans-Extension/Axis2"
public="false"
immediate="true">
<provides specifications="org.ow2.easybeans.api.EZBConfigurationExtension" />
<!-- Required dependencies -->
<requires optional="false">
<callback type="bind" method="bindWebDeployer" />
</requires>
</component>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<!-- Axis2Service -->
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<component classname="org.ow2.jonas.ws.axis2.Axis2Service"
immediate="false">
<provides specifications="org.ow2.jonas.ws.jaxws.IJAXWSService"/>
<requires optional="false"
specification="org.ow2.jonas.properties.ServerProperties">
<!-- @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 -->
<callback type="bind" method="setServerProperties" />
</requires>
<!-- "Inherited" from JAXWSService -->
<requires optional="false"
specification="org.ow2.jonas.jmx.JmxService">
<callback type="bind" method="setJmxService" />
</requires>
<requires optional="false">
<callback method="bindEventService" type="bind" />
<callback method="unbindEventService" type="unbind" />
</requires>
<!-- LifeCycle Callbacks -->
<callback transition="validate" method="start"/>
<callback transition="invalidate" method="stop"/>
<properties propagation="true"/>
</component>
<instance component="EasyBeans-Extension/Axis2" />
</ipojo>
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.
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.
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.
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/jonas.properties:
jonas.services jtm,db,dbm,security,resource,ejb3,jaxws2,web,ear,depmonitor
jonas.service.jaxws2.class org.ow2.jonas.ws.axis2.Axis2Service
Then JOnAS will start your service when starts.
Guide for JOnAS-based application developer
Download JOnAS
You can download JOnAS from this URL：http://wiki.jonas.ow2.org/xwiki/bin/view/Main/Downloads
Run JOnAS
Environment: jdk 1.5
Env variable: JONAS_ROOT and JONAS_BASE set to JOnAS work directory
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
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
- Lib
- Repository
- All ipojo jars and third party jars of JOnAS
- Templates
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.
You can view all common services and deployed applications in JOnAS.
Deploy applications on JOnAS
You have two ways to deploy applications on JOnAS:
You can update your archives and deploy them on JOnAS using JOnAS Admin tools.
You can also just put your archives into JOnAS_ROOT/deploy, and JOnAS will auto deploy your applications.
Examples
HelloWorld(EJB3)
Remote interface:
package org.ow2.jonas.helloworld;
public interface HelloWorldRemote {
public String say(String s);
}
Stateless Session Bean:
package org.ow2.jonas.helloworld;
import javax.ejb.Remote;
import javax.ejb.Stateful;
import javax.ejb.Stateless;
@Stateless
@Remote(HelloWorldRemote.class)
public class HelloWorldBean implements HelloWorldRemote
{
public String say(String s) {
System.out.println(m);
return m+" reached!";
}
}
Client:
package org.ow2.jonas.helloworld;
import java.util.Properties;
import javax.naming.Context;
import javax.naming.InitialContext;
public final class Client {
private static final String JNDI_NAME =
"org.ow2.jonas.helloworld.HelloWorldBean"
+ "_" + HelloWorldRemote.class.getName()
+ "@Remote";
public static void main(final String[] args)
throws Exception {
Properties props = new Properties();
props.setProperty("java.naming.factory.initial",
"org.ow2.carol.jndi.spi.MultiOrbInitialContextFactory");
Context initialContext = new InitialContext(props);
HelloWorldRemote businessItf =
(HelloWorldRemote) initialContext.lookup(JNDI_NAME);
System.out.println("Calling helloWorld method...");
System.out.println(businessItf.say("123"));
}
}
Notes:
- To run the client,classpath should contain the client.jar which is under the folder {JONAS_ROOT}/lib.
- The jndi property java.naming.factory.initial should be set as org.ow2.carol.jndi.spi.MultiOrbInitialContextFactory
- Remember the jndi name format: BeanName_RemoteInterfaceName@Remote
HelloWolrd(Webservice)
JOnAS 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.
To develop a webservice on JOnAS, you should first write a webservice application according to JAXWS specifications, then deploy it on JOnAS.
In this example, we wrote a Hello interface and HelloWorld bean:
Hello bean:
@SOAPBinding(parameterStyle=SOAPBinding.ParameterStyle.BARE)
public class SimpleService implements SimpleServiceInterface {
private static final long serialVersionUID = 1L;
@WebMethod(exclude=false)
public String greetMe(String str) {
System.out.println("Hello World: " + str);
return "hello world" + str;
}
}
Hello interface:
package org.ow2.jonas.ws.jaxws.test.pojo;
import javax.jws.WebMethod;
public interface SimpleServiceInterface {
@WebMethod(exclude=false)
public String greetMe(String str);
}
Its 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.
Besides, 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.
After deploy it, we can browse the url of this ws to get wsdl for it and invoke it:
We can invoke this ws by writing a ws client program, here we use soapui as the ws client to invoke our application:
Related resources
OW2 Forge:
http://forge.ow2.org/projects/jonas
Mainly used as a platform for developer’s communication and project management.
http://jira.ow2.org/browse/JONAS
A bug tracking system, assign bug to developers, and discuss about bugs, you can also see detailed svn records.
JOnAS Wiki
JOnAS 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.http://wiki.jonas.ow2.org/xwiki/bin/view/Main/WebHome
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.
JOnAS document：
http://wiki.jonas.ow2.org/xwiki/bin/view/Main/Documentation
You can find most JOnAS 4 & JOnAS 5 document here, including configuration
manual, user manual, technical white paper, etc. This is very useful for freshman in developing JOnAS.JOnAS Java doc：
http://jonas.ow2.org/JONAS_5_1_0/apidocs/index.html
http://jonas.ow2.org/JONAS_4_9_2/jdoc/index.html
You can look up java doc of JOnAS 4 & JOnAS 5 here.
JOnAS document:
JOnAS supplied a document for beginners in developing applications on JOnAS, you can get some detailed information here:
http://jonas.ow2.org/JONAS_5_1_1/doc/doc-en/html/getting_started_guide.html
