# 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

### 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:

> - `C` Container-Managed Persistence
> - `B` Bean-Managed Persistence

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

> 1. JonasAdmin
> 2. JonasAdmin -n jonas-name
> 3. 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.