# JOnAS Commands Reference Guide

Commands provided with JOnAS are described in this chapter.

jonas
  jonas manager
jclient
  Starting jonas client
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 allows to start, stop, or administrate JOnAS servers.

> Result of this program may depend on the directory where the command is run (Existence of a jonas.properties file in the current directory). If needed, it is possible to set system properties to the program by using the JAVA_OPTS environment variable. Notice that setting system properties with a -D option will always take precedence on the properties described in the different jonas.properties files.

> In case of problems or to get additional information, you can have a look at the following scripts, and possibly modify them :

>   jonas for UNIX systems
>   jonas.bat for WINDOWS systems
> There are 5 different sub-commands, depending on the first mandatory argument :
> jonas start
>   Start a new JOnAS server. The process can be run in foreground, in background, or in a new window. In case 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 different name than the default name.
> jonas admin
>   Administrate a JOnAS server. Use the -n option if the server was given a different name than the default name. Used without any other option, this command will prompt the user for an administrative command (interactive mode). Each administrative command exist in a non interactive mode, to be used in shell scripts or bat scripts for example. See the option list to have a description of each of them. Another way to manage JOnAS is to use the graphical tool jadmin. More or less you can have the same functionalities with jadmin than with jonas admin.
> jonas check
>   Check 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 5 different sub-commands. For example, jonas check and jonas version does not accept any option.
> -n name
>   Give a name to the JOnAS server. Default is jonas. Used for start, stop or admin.
> -fg
>   Used for start only. The server is launched in 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 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.
> -cnhost host
>   Give the hostname for COSNAMING. Default is localhost. Used only in case of DAVID orb.
> -cnport port
>   Give the port number for COSNAMING. Default is 14727. Used only in case of DAVID orb.
> -?
>   Used for admin only. Print a help with all possible options.
> -a filename
>   Used for admin only. Deploy a new application described by filename inside the JOnAS Server. The application may 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 from where the EJB server has been launched or also relative to the $JONAS_ROOT/ejbjars directory in case of ejb-jar file.
>   - a standard .war file containing a WEB Component. If the file name has a relative path, this path is relative from where the EJB server has been launched or also relative to the $JONAS_ROOT/webapps directory in case of ejb-jar file.
>   - a standard .ear file containing a complete J2EE application. If the file name has a relative path, this path is relative from where the EJB server has been launched or also relative to the $JONAS_ROOT/apps directory in case of ejb-jar file.
> -r filename
>   Used for admin only. Dynamically remove a previous -a filename command.
> -gc
>   Used for admin only. Run the garbage collector in the specified JOnAS server
> -passivate
>   Used for admin only. Passivate all entity bean instances. This concerns 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 current JOnAS server. Notice that this concerns only the instances that are not involved in a transaction.
> -debug topic
>   Used for admin only. Set topic level to DEBUG.
> -tt timeout
>   Used for admin only. Changes default timeout for transactions. timeout is in seconds.
> Each jonas admin option has its equivalent in the interactive mode. To enter the interactive mode, just type jonas admin [-n name] without any other argument. You can then have access to this list of subcommands. To exit from the 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 start easyly a "heavy" java client that will be able to reach beans in remote jonas servers and to start distributed transactions.

### Options

> -cnhost host
>   Give the hostname for COSNAMING. Default is localhost. Used only in case of DAVID orb.
> -cnport port
>   Give the port number for COSNAMING. Default is 14727. Used only in case of DAVID orb.
> -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 to start developing a bean by generating skeletons for all the necessary files to make a bean. Note that this tool only creates templates of the files. You need anyway to customize them and to write your business logic. However, the files should be compilable.

> You must just type newbean and enter a set of parameters in an interactive mode.

> After running newbean on each bean of your package, you must make a Makefile by joining all the *.mk generated files.

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

> The Bean Type must be one of the following:

> - `S` Entity bean
> - `E` Session bean
> - `MD` Message Driven bean

> The Session Type must be one of the following:

> - `L` Stateless Session Bean
> - `F` Stateful Session Bean

> The Persistance manager must be one of the following:

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

> 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 looks like the current directory.

> The Jar Name argument is the name that will be used to build the .jar file. Do not provide here the .jar extension. Usually, we take the last part of the package name.

> 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 on the current host, depending 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 EJBServer. So in this case, this tools have not to be used.

### Options

> port
>   Port number.

### Example

> The registry command may be typically 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 which are used.

### Options

> -help
>   Displays the usage of the CheckEnv command.

### Example

> `CheckEnv`

### Environment

> The result of this command may depend on the current directory from where 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 which can be defined in the jonas.properties file, may also be set by the way of this standard -D option of the java tool.

### Example

> The EJBServer command may be typically run in the background:

> - `EJBServer &` on Unix, or
> - `start EJBServer` on Windows.

### Environment

> The result of this command may depend on the current directory from where 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 a XML deployment descriptor of beans.

> The GenIC utility :

>   - firstly, generates the sources of the container classes for all the beans defined in the deployment descriptor,
>   - secondly, compiles these classes by way of the java compiler,
>   - thirdly, generates stubs and skeletons for those remote objects by way of the rmi compiler, and
>   - lastly, 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.
>   You can use this option 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 in 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 delete intermediate generated files.
> -noaddinjar
>   If the InputFile is an ejb-jar file, do not add the generated classes in the ejb-jar file.
> -nocompil
>   Do not compile the generated sources files via the java and rmi compilers.
> -rmiopts options
>   Specifies the options to pass to the rmi compiler.
> -secpropag
>   For generating stubs and skeletons that provide propagation of the Security context as well as the transaction context.
> -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, you will provide here the list of mappers corresponding to the list of potential databases upon which you will be able to deploy your entity beans.

### Example

> `GenIC -d ../../classes sb.xml`
> generates container classes of all the Entreprise JavaBeans defined in the sb.xml file. Classes are generated in the ../../classes directory respecting the classes hirarchy.

> `GenIC sb.jar`
> generates container classes of all the Entreprise JavaBeans defined in the sb.jar file and added the generated classes in this ejb-jar file.

### Environment

> If InputFile is a XML deployment descriptor, the classpath must include the paths of the directories where the Enterprise Bean's classes may be found, and 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

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

### Options

> none

### Example

> The JmsServer command may be 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 (ie EJBServer).

There are two modes to use this tool: a command mode and an interactive one.

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

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

Functionnalities | Command Mode | Interactive Mode
Dynamically creates a new JOnAS container and adds beans in it | `-a fileName` | addbeans
Lists the properties of the EJB server | `-e` | env
run the garbage collector in EJBServer | `-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 EJB server | `-l` | listbeans
Identify an EJBServer | `-n jonasName` | name
Quit JonasAdmin | non applicable | quit
Dynamically remove a JOnAS container and all its beans | `-r fileName` | removebeans
Stops the EJB server | `-s` | stop
Synchronizes entity bean instances on EJBServer | `-sync` | sync
List or Set trace level in EJBServer | `-t topic` | trace
Set default transaction timeout (in seconds) in EJBServer | `-tt timeout` | ttimeout

By default (without `-n <jonas-name>` option), JonasAdmin access to the EJBServer whose name is `jonas`
(`jonas.name` property in `jonas.properties` file)

The 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, run JonasAdmin in interactive mode, on EJBServer whose name is `jonas-name`.

> The second, run JonasAdmin in interactive mode, on EJBServer whose name is `jonas-name`.

> The third, 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 from where the EJB server has been launched or also relative to the $JONAS_ROOT/ejbjars directory in case of ejb-jar file.
> `env`
>   Lists the properties of the EJB server.
> `gc`
>   Run the garbage collector in the current EJBServer
> `help`
>   Gives the summary of the options.
> `jndinames`
>   Lists the registered JNDI names.
> `listbeans`
>   Lists the beans currently loaded by the EJB server.
> `name`
>   Change the default EJBServer on which the following commands will apply.
> `quit`
>   Quit JonasAdmin
> `removebeans <beans-file-name>`
>   Dynamically remove the JOnAS container identified by beans-file-name.
> `stop`
>   Stops the EJB server.
> `sync`
>   Synchronizes the entity bean instances on current EJBServer. Notice that this concerns only the instances that are not involved in a transaction.
> `trace`
>   List trace filters in current EJBServer.
> `trace <topic>`
>   Set topic level to DEBUG.
> `ttimeout <seconds>`
>   Changes default timeout for transactions

### Examples

> `JonasAdmin -j`

>   Lists the JNDI names currently registered by the EJB server.

> `JonasAdmin -n myserver -a myfile`

>   Make available in the EJBServer identified by the `jonas.name`, `myserver`, the EJBs indentified by the `jonas.service.ejb.descriptors` property in `myfile` file.

## RAConfig

### Synopsis

> RAConfig [ Options ] <InputFileName>

### Description

> The RAConfig utility generates a jonas specifig resource adapter configuration file `(jonas-ra.xml)` from a `ra.xml` file (Resource adapter deployment descriptor).

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

### Options

> -? or -help options
>   Gives the summary of the options.
> -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 use by the resource service for registering in JNDI the connection factory corresponding to this resource adapter.
> -r rarlink
>   Specifies the jndi name of an rar file to link with. 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, then 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, then it is the only argument executed.
> -verbose
>   verbose mode. Displays on standard `System.out` the deployment descriptor of the resource adapter .

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