JOnAS Commands Reference Guide

Commands provided with JOnAS are described in this chapter.

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
EJBServer: JOnAS Server (deprecated)
JonasAdmin: JOnAS Administration Server (deprecated)
CheckEnv: JOnAS configuration checker (deprecated)

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

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.

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

CheckEnv

Synopsis

CheckEnv [ Options ]

This command is deprecated. It has been replaced by jonas check.

Description

The CheckEnv tool verifies the JOnAS configuration coherence and displays the content of the configuration files that are used.

Options

-help

Displays the usage of the CheckEnv command.

Example

CheckEnv

Environment

The outcome of this command may depend on the current directory from which it is launched.
(Existence of a jonas.properties file in the current directory, or existence of the . (dot) path in the class path.)

EJBServer

Synopsis

EJBServer [ Options ]

This command is deprecated. It has been replaced by jonas start.

Description

Launch the JOnAS Server.

Options

-D<property>=<value>

All the JOnAS properties that can be defined in the jonas.properties file can also be set via this standard -D option of the java tool.

Example

The EJBServer command can normally be run in the background:

EJBServer & on Unix, or

start EJBServer on Windows.

Environment

The outcome of this command may depend on the current directory from which it is launched.
(Existence of a jonas.properties file in the current directory.)

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.

-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.

-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.

-mappernames

Comma-separated list of mapper names for which the container classes will be generated. Used for the JORM-based implementation of CMP 2.0. A mapper is used by JORM for accessing a given database. This list of mappers corresponds to the list of potential databases upon which the entity beans can be deployed.

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.

JonasAdmin

This command is deprecated. It has been replaced by jonas admin.

General Description

JonasAdmin is a tool that performs some administration tasks on a running JOnAS Server.

This tool has two modes: a command mode and an interactive one.

The command JonasAdmin without argument (or only with the option -n <jonas-name>) runs the tool in interactive mode.

The functions performed by the JonasAdmin tool are summarized in the table below:

Functionality	Command Mode	Interactive Mode
Dynamically creates a new JOnAS container and adds beans to it.	`-a fileName`	addbeans
Lists the properties of the JOnAS server.	`-e`	env
Runs the garbage collector in the JOnAS Server.	`-gc`	gc
Shows the usage of the JonasAdmin command.	`-?` or `-h`	help
Lists the registered JNDI names.	`-j`	jndinames
Lists the types of beans currently loaded by the JOnAS server.	`-l`	listbeans
Identifies a JOnAS Server.	`-n jonasName`	name
Quits JonasAdmin.	non applicable	quit
Dynamically removes a JOnAS container and all its beans.	`-r fileName`	removebeans
Stops the JOnAS server.	`-s`	stop
Synchronizes entity bean instances on the Server.	`-sync`	sync
Lists or Sets the trace level in the JOnAS Server.	`-t topic`	trace
Sets the default transaction timeout (in seconds) in the JOnAS Server.	`-tt timeout`	ttimeout

By default (without -n <jonas-name> option), JonasAdmin accesses the JOnAS Server whose name is jonas.

Detailed usage of this tool is provided in the following.

Synopsis

JonasAdmin

JonasAdmin -n jonas-name

JonasAdmin [ -n jonas-name ] [ options ]

Description

The first (1.), run JonasAdmin in interactive mode, on the JOnAS Server whose name is jonas.

The second (2.), run JonasAdmin in interactive mode, on the JOnAS Server whose name is jonas-name.

The third (3.), run JonasAdmin in command mode, the task performed depends on the selected option.

Options

addbeans <beans-file-name>

Dynamically creates a new JOnAS container.
The beans-file-name is an ejb-jar file.
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.

env

Lists the properties of the JOnAS server.

gc

Runs the garbage collector in the current JOnAS Server.

help

Gives a summary of the options.

jndinames

Lists the registered JNDI names.

listbeans

Lists the beans currently loaded by the JOnAS server.

name

Changes the default JOnAS Server on which the following commands will apply.

quit

Quits JonasAdmin.

removebeans <beans-file-name>

Dynamically removes the JOnAS container identified by beans-file-name.

stop

Stops the JOnAS server.

sync

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

trace

Lists trace filters in current JOnAS Server.

trace <topic>

Sets the topic level to DEBUG.

ttimeout <seconds>

Changes the default timeout for transactions

Examples

JonasAdmin -j

Lists the JNDI names currently registered by the JOnAS server.

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

-? 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.

-j jndiname

It is a mandatory option. 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.

-p 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.

-r 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.

-u 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.