# 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
newjb
  Build a new JONAS_BASE for the conformance tests
newjc
  Build a cluster configuration
probeJgroups
  Search the JGroups members on the network
jonasctl
  Wrapper around jonas.sh script for production usage
createjb
  Creates a new JONAS_BASE (based on newjb)

## jonas

### Synopsis

> `jonas start [-fg | -bg | -win] [-n name] [-target server]`
>   start a JOnAS server
> `jonas stop [-n name] [-target server]`
>   stop a JOnAS server
> `jonas admin [-n name] [admin_options] [-target server]`
>   administrate a JOnAS server
> `jonas check`
>   check JOnAS environment
> `jonas version`
>   print JOnAS version

### Description

> The jonas 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 subcommands, 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 subcommands. 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.
> -ping [-timeout seconds]
>   Used for admin only. Waits until the JOnAS server is available.
> -target server
>   Used for start, stop, or admin only. This allows the user to start/stop or admin another server in the cluster. The command asks the master server to perform the operation on the target sever. The target can also be a cluster. In that case, the command is applied to all servers belonging to this cluster.
> 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 (i.e., 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 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
>   This 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.
>   **Note: With a 1.0 Resource Adapter, this is a mandatory option. With a 1.5 Resource Adapter, this option is ignored since there are multiple jndinames that can be specified and the user is required to update the jonas-ra.xml with the correct values.
> -NEW
>   Create a new jonas-ra.xml file instead of just extracting it, if one already exists in the specified rar file.
> -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 -path . MyRA.rar`
  > Generates the `jonas-ra.xml` file from the ra.xml file or extracts the `jonas-ra.xml` file if it already exists in the rar 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

>   the JOnAS instances of the cluster (set of new JONAS_BASE directories prefixed by default with 'jb').
>   the mod_jk/director configuration files ('conf/jk' directory).
>   a cluster daemon configuration which can be used for controlling remotely the cluster instances through JMX ('cd' directory).
>   a JOnAS instance dedicated to the database when an HSQL database is configured ('db' directory).
>   a JOnAS instance dedicated to the master node for managing the domain/cluster from a single jonasAdmin console ('master' directory).
>   a script for starting/stopping the entire cluster and deploying the sampleCluster2 application (jcl4sc2).

> 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', etc.
>   - 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 for defining the cluster instances is provided in the $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.

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

> A default configuration file for defining the instance dedicated to the management (master node) is provided in the $JONAS_ROOT/examples/sampleCluster2/newjc/build-master.properties.

> A default configuration file for defining the instance dedicated to the database is provided in the $JONAS_ROOT/examples/sampleCluster2/newjc/build-db.properties.

> 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 also be 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

## jonasctl

### Synopsis

> jonasctl start/stop/... [usual jonas' options]

### Description

> This tool is a wrapper around the `jonas` script. It is intended to be used in production mode, with JONAS_BASEs produced by createjb.
> This script is based on the JONAS_BASE value. It will load the environment linked to the JOnAS base by sourcing the JONAS_BASE/conf/env.sh.include.
> Loading the environment means that some environment variables will be set:

> - `JONAS_ROOT`: The JOnAS installation directory linked to this JONAS_BASE (this hard-links the JOnAS config with a given JOnAS version).
> - `SERVER_NAME`: The JOnAS server name associated with this configuration.
> - `ANT_HOME` and `JAVA_HOME`: The Java and Ant version to be used to run this configuration of JOnAS.
> - `JAVA_OPTS`: The particular Java options (-D, -X, ...) associated to that JOnAS instance.
> - `CLASSPATH`: Available if it is really necessary to add a jar into the CLASSPATH, but its usage is not recommended.
> After loading the "global" environment customization, `jonasctl` will override the config with command specific customizations. If `jonasctl start` is called, the `JONAS_BASE/conf/env.start.sh.include` will be sourced (like env.sh.include).
> Only the `start` command specialization is provided in JOnAS, but this is applicable for all of the commands of the `jonas` launching script.
> The administrator can put any code he wants in these included scripts.

## createjb

### Synopsis

> createjb

### Description

> This tool is only a wrapper around new jb (for now), but it's aiming to offer more features.
> Currently, it simply creates a new JONAS_BASE using the usual Ant tasks (like newjb). But it's used to copy and change the JONAS_BASE/conf/env.*.sh.include scripts processed by `jonasctl`.