JOnAS Commands Reference Guide

jonas

JOnAS manager

jclient

Starting a JOnASclient

newbean

Bean generator

registry

Java Remote Object Registry

GenIC

Container classes generator

JmsServer

JMS Server

RAConfig

Resource Adapter configuration tool

newjb

Build a new JONAS_BASE for the conformance tests

newjc

Build a cluster configuration

probeJgroups

Search the JGroups members on the network

jonas

Synopsis

jonas start [-fg | -bg | -win] [-n name]

start a JOnAS server

jonas stop [-n name]

stop a JOnAS server

jonas admin [-n name] [admin_options]

administrate a JOnAS server

jonas check

check JOnAS environment

jonas version

print JOnAS version

Description

This command replaces the deprecated commands EJBServer, JonasAdmin, and CheckEnv. It provides the capability to start, stop, or administrate JOnAS servers.

The outcome of this program may depend on the directory from which the command is run (existence of a jonas.properties file in the current directory). It is possible to set system properties to the program by using the JAVA_OPTS environment variable, if required. Note that setting system properties with a -D option will always take precedence over the properties described in the other jonas.properties files.

The following two scripts can be reviewed and possibly modified for assistance with problems or for obtaining additional information:

jonas for UNIX systems

jonas.bat for WINDOWS systems

There are five different sub-commands, that depend on the first mandatory argument:

jonas start

Start a new JOnAS server. The process can be run in the foreground, in the background, or in a new window. If the background option is chosen (default option), control is given back to the caller only when the server is ready. The default name is jonas. A different name can be given with the -n option.

jonas stop

Stop a running JOnAS server. Use the -n option if the server was given a name other than the default name.

jonas admin

Administrate a JOnAS server. Use the -n option if the server was given a name other than the default name. Used without any other option, this command will prompt the user for an administrative command (interactive mode). Each administrative command exists in a non-interactive mode, for use in shell scripts or bat scripts, for example. Refer to the option list for a description of each. Another way to manage JOnAS is to use the graphical tool JonasAdmin. The functionality is essentially the same for JonasAdmin as it is for jonas admin.

jonas check

Check the environment before running a JOnAS server.

jonas version

Print the current version of JOnAS.

Options

Each option may be pertinent only for a subset of the five different sub-commands. For example, jonas check and jonas version do not accept any options.

-n name

Give a name to the JOnAS server. The default is jonas. Used for start, stop, or admin.

-fg

Used for start only. The server is launched in the foreground: Control is given back to the user only at the end of the process.

-bg

Used for start only. The server is launched in the background. Control is given back to the user only when the JOnAS server is ready. This is the default mode.

-win

Used for start only. The server is launched in a new window.

-?

Used for admin only. Prints a help with all possible options.

-a filename

Used for admin only. Deploys a new application described by filename inside the JOnAS Server. The application can be one of the following:

• a standard ejb-jar file. This will lead to the creation of a new EJB Container in the JOnAS Server. If the file name has a relative path, this path is relative to where the EJB server has been launched or relative to the $JONAS_ROOT/ejbjars directory for an ejb-jar file.
• a standard .war file containing a WEB Component. If the file name has a relative path, this path is relative to where the EJB server has been launched or relative to the $JONAS_ROOT/webapps directory for a war file.
• a standard .ear file containing a complete J2EE application. If the file name has a relative path, this path is relative to where the EJB server has been launched or relative to the $JONAS_ROOT/apps directory for an ear file.

-r filename

Used for admin only. Dynamically removes a previous -a filename command.

-gc

Used for admin only. Runs the garbage collector in the specified JOnAS server.

-passivate

Used for admin only. Passivates all entity bean instances. This affects only instances outside transaction.

-e

Used for admin only. Lists the properties of the specified JOnAS server.

-j

Used for admin only. Lists the registered JNDI names, as seen by the specified JOnAS server.

-l

Used for admin only. Lists the beans currently loaded by the specified JOnAS server.

-sync

Used for admin only. Synchronizes the entity bean instances on the current JOnAS server. Note that this affects only the instances that are not involved in a transaction.

-debug topic

Used for admin only. Sets the topic level to DEBUG.

-tt timeout

Used for admin only. Changes the default timeout for transactions. timeout is in seconds.

Each jonas admin option has its equivalent in the interactive mode. To enter interactive mode and access the following list of subcommands, type jonas admin [-n name] without any other argument. To exit from interactive mode, use the exit command.

interactive command	on-line matching command
addbeans	-a fileName
env	-e
gc	-gc
help	-?
jndinames	-j
listbeans	-l
removebeans	-r fileName
sync	-sync
trace	-debug topic
ttimeout	-tt timeout
quit	exit interactive mode

Examples

jonas check

jonas start -n jonas1

jonas admin -n jonas1 -a bean1.jar

jonas stop -n jonas1

jclient

Synopsis

jclient [options] java-class [args]

Description

The jclient command allows the user to easily start a "heavy" java client that will be able to reach beans in remote JOnAS servers and start distributed transactions.

It is not the J2EE compliant way to run a java client which is to use to package the java client in a J2EE container client (refer to Client Packaging).
The jclient command may be deprecated in a future release.

Options

-cp classpath

Add an additional classpath before running the java program.

-security

Set a security manager using the policy file in $JONAS_BASE/conf/java.policy. (Used for automatic stubs downloading)

Examples

jclient package.javaclassname args

newbean

Synopsis

newbean

Description

The newbean tool helps the bean writer start developing a bean by generating skeletons for all the necessary files for making a bean. Note that this tool only creates templates of the files. These templates must then be customized and the business logic written. However, the files should be compilable.

To create these templates, type newbean and enter a set of parameters in interactive mode.

The Bean Name must start with a capital letter. Avoid the reserved names: Home, EJB, Session, Entity. This name will be used as a prefix for all filenames relative to the bean.

The Bean Type must be one of the following:

• S Session bean
• E Entity bean
• MD Message-Driven bean

The Session Type must be one of the following:

• L Stateless Session Bean
• F Stateful Session Bean

The Persistence manager must be one of the following:

• C2 Container-Managed Persistence (CMP 2.x)
• C Container-Managed Persistence (CMP 1.x)
• B Bean-Managed Persistence (BMP)

The Bean Location must be one of the following:

• R Remote Interfaces
• L Local Interfaces

The Package Name is a dot-separated string representing the package to which the bean belongs. Usually this is the same as the current directory.

The Jar Name argument is the name that will be used to build the .jar file. Do not provide the .jar extension with this argument. Typically, the last part of the package name is used.

The Primary Key class is the class representing the primary key. Only needed for entity beans. Possible values are:

• S java.lang.String
• I java.lang.Integer
• O Object (Will be chosen later)

Example

newbean
Bean Name
> MyEntity

Bean type
  S   Session bean
  E   Entity bean
  MD  Message-Driven bean
> E

Persistance manager
  C  Container
  B  Bean
> C

Bean location
  R  Remote
  L  Local
> R

Package name
> truc.machin

Jar name
> machin

Primary Key class
0  S  String
  I  Integer
  O  Object
> S

Creating bean MyEntity (type ECR) in package truc.machin
Your bean files have been created. You can now customize them.
      

registry

Synopsis

registry [ <port> ]

Description

The registry tool creates and starts a remote object registry on the specified port of the current host, based on the ORB type defined in the JOnAS configuration (RMI or Jeremie).

If the port is omitted, the registry is started on port 1099 on RMI, or on port 1234 on Jeremie.

Note that, by default, the registry is collocated in the same JVM as the JOnAS Server. In this case, it is not necessary to use this tool; the registry is automatically launched.

Options

port

Port number.

Example

The registry command can normally be run in the background:

• registry & on Unix, or
• start registry.bat on Windows

GenIC

Synopsis

GenIC [ Options ] <InputFileName>

Description

The GenIC utility generates the container classes for JOnAS from the given Enterprise Java Beans.

The InputFileName is either the file name of an ejb-jar file or the file name of an XML deployment descriptor of beans.

The GenIC utility does the following in the order listed:

1) generates the sources of the container classes for all the beans defined in the deployment descriptor,

2) compiles these classes via the java compiler,

3) generates stubs and skeletons for those remote objects via the rmi compiler, and

4) if the InputFile is an ejb-jar file, adds the generated classes in this ejb-jar file.

Options

-d directory

Specifies the root directory of the class hierarchy.

This option can be used to specify a destination directory for the generated files.

If the -d option is not used, the package hierarchy of the target class is ignored and the generated files are placed in the current directory.

If the InputFile is an ejb-jar file, the generated classes are added to the ejb-jar file, unless the -noaddinjar option is set.

-invokecmd

Invokes directly, in some cases, the method of the java class corresponding to the command. This is useful on Windows in the event of a CreateProcess Exception (this occurs when the command line is too long).

-javac options

Specifies the java compiler name to use (javac by default).

-javacopts options

Specifies the options to pass to the java compiler.

-keepgenerated

Do not immediately delete generated files.

-noaddinjar

If the InputFile is an ejb-jar file, do not add the generated classes to the ejb-jar file.

-nocompil

Do not compile the generated source files via the java and rmi compilers.

-novalidation

Remove xml validation during parsing.

-protocols

Comma-separated list of protocols (chosen within jeremie, jrmp, iiop, cmi) for which stubs should be generated. Default is jrmp,jeremie.

-rmiopts options

Specifies the options to pass to the rmi compiler.

-verbose

Displays additional information about command execution.

-nofastrmic

Disable the use of fastrmic for stubs/ties generation.

Example

GenIC -d ../../classes sb.xml
generates container classes of all the Enterprise JavaBeans defined in the sb.xml file. Classes are generated in the ../../classes directory adhering to the classes hierarchy.

GenIC sb.jar
generates container classes for all the Enterprise JavaBeans defined in the sb.jar file and adds the generated classes to this ejb-jar file.

Environment

If InputFile is an XML deployment descriptor, the classpath must include the paths of the directories in which the Enterprise Bean's classes can be found, as well as the path of the directory specified by the -d option.

If InputFile is an ejb-jar file, the classpath must include the path of the directory specified by the -d option.

JmsServer

Synopsis

JmsServer

Description

Launches the Joram Server (ie the MOM) with its default options.

Options

none

Example

The JmsServer command is typically run in the background:

• JmsServer & on Unix, or
• start JmsServer on Windows.

RAConfig

Synopsis

RAConfig [ Options ] <InputFileName> [<OutputFileName>]

Description

The RAConfig utility generates a JOnAS-specific resource adapter configuration file (jonas-ra.xml) from an ra.xml file (Resource adapter deployment descriptor).

The InputFileName is the file name of a the resource adapter.

The OutputFileName is the file name of an output resource adapter used with the -p(required) or -u(optional).

Options: Only capital letters or the full option name must be specified

-? or -HELP options

Gives a summary of the options.

-DM,-DS,-PC,-XA DriverManager, DataSource, PooledConnection, XAConnection

Specifies the rarlink value to configure, used with the -p option. If -DM is used, then the conversion will be a direct reflection of the values specified in the -p <database>.properties file. If any of the other values are specified, then the jonas-ra.xml created will reflect options from the -p <database>.properties file and the user must edit the file based on information from the database provider for the specified type of datasource. Each database provider may have different config properties that need to be set and will be included in the database provider's documentation.

-ENcrypt

Used with -SecurityFile to encrypt the specified passwords.

-Jndiname jndiname

It is a mandatory option with a 1.0 Resource Adapter. It specifies the JNDI name of the connection factory. This name corresponds to the name of the <jndi-name> element of the <jonas-resource> element in the JOnAS-specific deployment descriptor. This name is used by the resource service for registering in JNDI the connection factory corresponding to this resource adapter.

-NoValidation

Turn off the xml dtd/schema validation.

-PATH output directory for the generated jonas-ra.xml

Specifies the directory name to place the generated jonas-ra.xml file. The default value when not specified is the System attribute of java.io.tmpdir.

-Property database properties file

Specifies the name of the database.properties file to process. The result of this processing will be a jonas-ra.xml file that will update the /META-INF/jonas-ra.xml file in the output rar.

-Rarlink rarlink

Specifies the jndi name of an rar file with which to link. This option can be used when this rar file will inherit all attributes associated with the specified jndi name. If this option is specified in the jonas-ra.xml file, it is the only file needed in the rar, and the ra.xml file will be processed from the rarlink file.

-SecurityFile security property file to process

Specifies the security property file to process and add security information to jonas-ra.xml. This will map the specified principal name to the user on the EIS system. The specified file must be in the following form: principal = user::password . When used in conjunction with the -ENcrypt option, then the resulting information will be encrypted in jonas-ra.xml.

-Update inputname

Specifies the name of the XML file to process. This file will update the /META-INF/jonas-ra.xml file in the rar. If this argument is used, it is the only argument executed.

-Verbose

Verbose mode. Displays the deployment descriptor of the resource adapter on standard System.out.

Example

• RAConfig -j adapt_1 MyRA.rar
  Generates the jonas-ra.xml file from the ra.xml file.

  After the jonas-ra.xml has been configured for the MyRA rar file
  RAConfig -u jonas-ra.xml MyRA.rar
  Updates/inserts the jonas-ra.xml file into the rar file.

• RAConfig -dm -p MySQL1 $JONAS_ROOT/rars/autoload/JOnAS_jdbcDM MySQL_dm
  
  Generates the jonas-ra.xml file from the ra.xml file of the JOnAS_jdbcDM.rar and inserts the corresponding values from the MySQL1.properties file. The jonas-ra.xml file is then added/updated to the MySQL_dm.rar file. This rar file can then be deployed and will replace the configured MySQL1 datasource.

newjb

Synopsis

newjb;

Description

The newjb utility builds a new JONAS_BASE directory that allows the conformance tests to be launched. At the start, the user must choose:

- the protocol among jrmp,jeremie,iiop,cmi

- the database

- the web container among tomcat, jetty

and the tool generates the configuration automatically.

The $JONAS_BASE variable must be set before launching the tool; it specifies the path to the new directory that will be built.

The $HOME/jb.config/lib directory must be created before launching the tool. It can contain some specific user configuration (see below).

The tool relies on JOnAS's ant tasks ($JONAS_ROOT/build-jb.xml) and thus builds a configuration compatible with the JOnAS version. First, a JONAS_BASE with default values is built, and then the configuration files are modified with the values defined in the centralized configuration file of newjb (see below).

A default configuration file is provided in $JONAS_ROOT/build-jb.properties. It contains the variable parameters used by the tool, such as port number and database properties.

A user configuration can be set in the $HOME/jb.config/conf/jonas-newjb.properties file. If this file is present, the parameters it contains will override the default parameters.

By default, only the HSQL database can be configured with this tool. For other databases, the specific drivers must be stored in the $HOME/jb.config/lib directory before the run and the properties must be set in the $HOME/jb.config/conf/jonas-newjb.properties file.

The default script ($JONAS_ROOT/build-jb.xml) and its configuration ($JONAS_ROOT/build-jb.properties) can be used as an example for creating a configuration tool corresponding to a user's specific requirements.

newjc

Synopsis

cd $JONAS_ROOT/examples/sampleCluster2/newjc
newjc.sh;

Description

The newjc utility builds a new cluster configuration. Here a cluster configuration is a set of new JONAS_BASE directories and the mod_jk/director configuration files. At the start, the user must choose:

- the output directory. The default value is the $JONAS_BASE value. This is the directory where all the JONAS_BASE directories of the cluster configuration and the mod_jk/director configuration will be created.

- the prefix for the JONAS_BASE directories. By default jb is suggested and in this case, the JONAS_BASE will be 'jb1', 'jb2', and so on.

- the protocol between jrmp,jeremie,iiop,cmi

- the database

- the web container

- the cluster architecture between bothWebEjb and diffWebEjb. The first describes a cluster where all the nodes contain the same services, whereas the second one describes an architecture where the web level and the ejb level are separated.

- the number of web and ejb (diffWebEjb) or web/ejb (bothWebEjb) instances to create.

Once this is done, the tool generates the configuration automatically.

The $HOME/jc.config/lib directory must be created before launching the tool. It can contain some specific user configuration (see below).

The tool relies on JOnAS's ant tasks ($JONAS_ROOT/examples/sampleCluster2/build-jc.xml) and thus builds a configuration compatible with the JOnAS version. First, the JONAS_BASE directories with default values are built, and then the configuration files are modified with the values defined in the centralized configuration file of newjc (see below).

A default configuration file is provided in $JONAS_ROOT/examples/sampleCluster2/newjc/build-jc.properties. It contains the variable parameters used by the tool, such as port-number range and database properties.

An user configuration can be set in the $HOME/jc.config/conf/jonas-newjc.properties file. If this file is present, the parameters it contains override the default parameters.

By default, only the HSQL database can be configured with this tool. For other databases, the specific drivers must be stored in the $HOME/jc.config/lib directory before the run and the properties must be set in the $HOME/jc.config/conf/jonas-newjc.properties file.

By default, the load-balancing at the web level is implemented through the Apache mod_jk plugin. The Enhydra-director plugin can be also used by modifying the configuration file ($HOME/jc.config/conf/jonas-newjb.properties) and by storing the tomcat5.5-director.jar (http://director.objectweb.org/) file in the $HOME/jc.config/lib directory before the run.

probeJgroups

Synopsis

probeJgroups [-query jmx|-query props|...]

Description

The tool probes the network to search the JGroups members, and prints a state for each one. By default, the discovery relies on the multicast address 224.0.0.75:7500. See the JGroups documentation for further information http://www.jgroups.org/javagroupsnew/docs/index.html.

Options

- 'no parameter' : print network information for each member with the JGroups cluster identification [multicast address, multicast port, group name]

- -query jmx : print statistical information about the traffic for each member

- -query props : print configuration information such as the protocol stack parameters for each member