J2EE(TM) SDK Tools

J2EE^TM SDK Tools

This page is an appendix from the J2EE^TM Tutorial, which is available online at:
http://java.sun.com/j2ee/tutorial/index.html

The J2EE^TM SDK includes a number of tools, which are described in this appendix.

In This Appendix

J2EE Administration Tool
Cleanup Tool
Cloudscape Server

Starting Cloudscape
Stopping Cloudscape
Running the Interactive SQL Tool
Cloudscape Server Configuration

Deployment Tool
J2EE Server
Key Tool
Packager Tool

EJB JAR File
Web Application WAR File
Application Client JAR File
J2EE Application EAR File
Specifying the Runtime Deployment Descriptor
Resource Adapter RAR File

Realm Tool

Examples

runclient Script

Syntax
Example
Accessing a Remote Server
Preventing the User Name and Password Prompts

Verifier Tool

Command-Line Verifier
Stand-Alone GUI Verifier

J2EE Administration Tool

The j2eeadmin tool is a command-line script that enables you to add and remove these resources: JDBC^TM drivers and data sources, JMS destinations and connection factories, and resource adapter connection factories.

Table 2 j2eeadmin tool Options
Option
Description

-addConnectorFactory
<jndi-name>
[<app-name>:]
<rar-filename>
[<xa-user-name>
<xa-password>]
[-props
(<name>=<value>)+]
Adds a connection factory with the specified <jndi-name>. The connection factory is contained in the RAR file specified by <rar-filename>. The <rar-filename> must be the base name of the file; it cannot include any prefix ending in / (UNIX) or \ (Windows). If the RAR file is contained in an EAR file, then the name of the J2EE application name must be specified by <app-name>, followed by a colon. Optionally, a user name and password for the factory may be specified. Also optional is the -props flag, followed by one or more name-value pairs that specify properties for this factory. To prevent the shell from interpreting characters in the values, enclose the values in single or double quotes.

-addJdbcDriver
<class-name>
Adds the JDBC driver specified by its fullyqualified <class-name>. You must also update the J2EE_CLASSPATH environment variable in the file bin\userconfig.bat. Then you must restart the J2EE server.

-addJdbcDatasource
<jndi-name> <url>
Adds the JDBC DataSource with the specified <jndi-name> and <url>.

-addJdbcXADatasource
<jndi-name>
<class-name>
[<xa-user-name>
<xa-password>]
[-props
<name>=<value>)+]
Adds the JDBC XADataSource with the specified <jndi-name> and fully-qualified <class-name>. Optionally, a user name and password for the DataSource may be specified. Also optional is the -props flag, followed by one or more name-value pairs that specify properties for this DataSource.

-addJmsDestination
<jndi-name>
(queue|topic)
Adds a JMS destination with the specified <jndi-name> and declares the destination as either a queue or topic.

-addJmsFactory
<jndi-name>
(queue|topic)
[-props
(<name>=<value>)+]
Adds a JMS connection factory with the specified <jndi-name> and destination type, either queue or topic. Optionally, one or more properties may be specified with name-value pairs.

-list<resource-type>
Lists resources of the specified <resource-type>, either ConnectorFactory, JdbcDriver, JdbcDatasource, JdbcXADatasource, JmsDestination, or JmsFactory. There is no space between -list and <resource-type>.

-remove<resource-type>
<jndi-name>
Removes the resource of the specified <resource-type> and <jndi-name>. (See the description of -list for the allowed <resource-type> elements.)

-removeAll<resource-type>
Removes all resources of the specified <resource-type>. (See the description of -list for the allowed <resource-type> elements.)

Cleanup Tool

The cleanup tool is a command-line script that removes all deployed applications from your J2EE server. It will not delete the component files (JAR, WAR, EAR).

Note: Use this utility with care!

Cloudscape Server

The examples in this manual have been tested with the Cloudscape DBMS, which is included in the J2EE SDK.

Starting Cloudscape

Before your enterprise beans can access a Cloudscape database, you must run the Cloudscape server from the command line:
cloudscape -start
 
You should see output similar to the following:
Mon Aug 09 11:50:30 PDT 1999: [RmiJdbc]

COM.cloudscape.core.JDBCDriver registered in DriverManager

Mon Aug 09 11:50:30 PDT 1999: [RmiJdbc] Binding . . ..

Mon Aug 09 11:50:30 PDT 1999: [RmiJdbc] No installation of

RMI Security Manager...

Mon Aug 09 11:50:31 PDT 1999: [RmiJdbc] RmiJdbcServer

bound in rmi registry 
 
Stopping Cloudscape

To stop the server type the following command:
cloudscape -stop
 
You should see output similar to the following:
Attempting to shutdown RmiJdbc server

RmiJdbc Server RmiAddr is: //buzz/RmiJdbcServer

WARNING: Shutdown was successful! 
 
Note: If you stop the server with Control-c, files will not be closed properly. When the server is started the next time, it must perform recovery by rolling back noncommitted transactions and possibly applying the forward log.

Running the Interactive SQL Tool

The Cloudscape product includes a text-based, interactive tool called ij. (This tool is not supported by Sun Microsystems, Inc.) You can run the ij tool by typing this command:
cloudscape -isql
 
Within the tool, each command you type must end in a semicolon. The commands in the next example display all rows from the orders table, execute a SQL script named myscript.sql, and end the tool session:
ij> select * from orders;

ij> run 'myscript.sql';

ij> exit;
 
The following example runs a SQL script from the command line:
cloudscape -isql < myscript.sql
 
This command lists the names of all user tables in the database:
ij> select tablename from sys.systables

    where tabletype = 'T';
 
The next example displays the column names of the orders table:
ij> select columnname from sys.syscolumns

    where referenceid =

          (select tableid from sys.systables

           where tablename = 'orders');
 
Before you deploy an entity bean with container-managed persistence, you use deploytool to generate the bean's SQL statements. Because the table names in these SQL statements are case sensitive, you must enclose them in double quotes:
ij> select * from "TeamBeanTable";
 
For more information on the ij tool, please refer to the online documentation on the Cloudscape Web site:
http://www.cloudscape.com
 
Cloudscape Server Configuration

The default database used by the Cloudscape server is named CloudscapeDB. This database will reside in the cloudscape directory of your J2EE SDK installation. The CloudscapeDB database will be created automatically the first time it is accessed. The driver for the Cloudscape server is already configured in the config/default.properties file. No further changes by you are necessary.

Deployment Tool

The deploytool utility has two versions: GUI and command line. The GUI version enables you to package components and to deploy applications. If you run the deploytool script with no options, the GUI version is launched.

The GUI version includes online help information that is context sensitive. To access a help topic for a particular dialog box or tab , press F1.

The command-line version of the tool enables you to deploy and undeploy applications. To package components from the command line, use the packager tool.

Table 3 deploytool Options
Option
Description

-deploy
<ear-filename>
<server-name>
[<client-stub-jar>]
Deploys the J2EE application contained in the EAR file specified by <ear-filename> onto the J2EE server running on the machine specified by <server-name>. Optionally, a JAR file for a stand-alone Java application client may be created by specifying <client-stub-jar>.

-deployConnector
<rar-filename>
<server-name>
Deploys the resource adapter contained in the RAR file specified by <rar-filename> onto the J2EE server running on the machine specified by <server-name>.

-generateSQL
<ear-filename>
<server-name>
[noOverWrite]

Generates SQL statements for all entity beans with container-managed persistence. These beans are in the EAR file specified by <ear-filename> that has been deployed on the J2EE server running on the machine specified by <server-name>. If the noOverWrite option is specified, then existing SQL statements are not overwritten.

-listApps
<server-name>
Lists the J2EE applications that are deployed on the J2EE server running on the machine specified by <server-name>.

-listConnectors
<server-name>
Lists the resource adapters that are deployed on the J2EE server running on the machine specified by <server-name>.

-undeployConnector
<rar-filename>
<server-name>
Undeploys the resource adapter contained in the file specified by <rar-filename> from the J2EE server running on the machine specified by <server-name>.

-uninstall
<app-name>
<server-name>
Undeploys the J2EE application whose name is <app-name> from the J2EE server running on the machine specified by <server-name>.

-help
Displays options.

-ui
Runs the GUI version (default).

J2EE Server

To launch the J2EE server, run the j2ee script from the command-line prompt.

Table 4 j2ee Options
Option
Description

-verbose
Redirects all logging output to the current shell.

-version
Displays the version number.

-stop
Stops the J2EE server.

To run the HTTPS service of the J2EE server, you must install a server certificate. For instructions, see the Security chapter of the J2EE Tutorial.

Key Tool

The keytool utility creates public and private keys and generates X.509 self-signed certificates. The J2EE SDK version of the keytool utility has the same options as the version distributed with the J2SE SDK. For more information, see the J2EE SDK Configuration Guide.

Packager Tool

The packager tool is a command-line script that enables you to package J2EE components. This tool is for advanced users who do not want to use deploytool to package J2EE components. With packager, you can create the following component packages:

EJB JAR file
Web application WAR file
Application client JAR file
J2EE application EAR file
Resource adapter RAR file

The packager tool also enables you to set the runtime deployment information of an application EAR file.

Note: To make them easier to read, the examples that follow contain line breaks within the commands. When typing these commands, do not include the line breaks.

EJB JAR File

Syntax
packager -ejbJar <root-directory> <file-list> 

<ejb-dd> <ejb-jar>
 
Example

The following command packages the three Hello classes and the hello-jar.xml deployment descriptor into the HelloEJB.jar file:
packager -ejbJar /home/duke/classes/

HelloHome.class:HelloEJB.class:HelloRemote.class

hello-jar.xml HelloEJB.jar 
 
Web Application WAR File

Syntax
packager -webArchive 

[-classpath <root-directory> [-classFiles <file-list>]] 

<content-root> [-contentFiles <file-list>] <web-dd> <web-war>
 
Example

The following command packages helper classes and JSP^TM pages into the bookstore2.war file:
packager -webArchive -classpath .

-classFiles

   cart\ShoppingCart.class:cart\ShoppingCartItem.class:

   database\BookDB.class:util\Currency.class

.

-contentFiles

   banner.jsp:bookdetails.jsp:bookstore.jsp:cashier.jsp:

   catalog.jsp:DigitalClock.class:duke.books.gif:

   errorpage.jsp:initdestroy.jsp:receipt.jsp:showcart.jsp

web.xml bookstore2.war
 
Application Client JAR File

Syntax
packager -applicationClient <root-directory> <file-list>

<main-class> <appclient-dd> <appclient-jar>
 
Example

The following command creates the appClient.jar file:
packager  -applicationClient classes 

hola:hello/HelloUtil.class 

package.Main client.xml appClient.jar
 
J2EE Application EAR File

Syntax
packager -enterpriseArchive <file-only-list> 

[-alternativeDescriptorEntries <file-only-list>]

[-libraryJars <file-list>] <app-name> <app-ear>
 
Example

In the following command, the optional -alternativeDescriptorEntries flag allows you to specify the external descriptor entry name of each component as you wish it to appear in the EAR file:
packager -enterpriseArchive

myWeb.war:myEJB.jar:appClient.ear 

-alternativeDescriptorEntries 

myWeb/web.xml:myEjb/myEjb.xml:client/client.xml 

myAppName myApp.ear 
 
Specifying the Runtime Deployment Descriptor

The preceding example specified the -enterpriseArchive flag to create a portable J2EE application EAR file. This file is portable because you can import it into any J2EE environment that conforms to the J2EE Specification. Although you can import the file into the deploytool, you cannot deploy it on the J2EE server until it contains a runtime deployment descriptor. This deployment descriptor is an XML file that contains information such as the JNDI names of the application's enterprise beans.

Syntax
packager -setRuntime <app-ear>|<appclient-jar> <runtime.xml> 

[-o <output-file>]
 
Example

In the following command, the -setRuntime flag instructs packager to insert the runtime deployment descriptor (sun-j2ee-ri.xml) into the myApp.ear file:
packager -setRuntime MyApp.ear sun-j2ee-ri.xml
 
The following command copies MyApp.ear to OtherApp.ear, inserts the deployment descriptor into the OtherApp.ear file, and leaves MyApp.ear unchanged:
packager -setRuntime MyApp.ear sun-j2ee-ri.xml -o OtherApp.ear
 
To obtain an example of the runtime deployment descriptor, extract it from an EAR file that you've already deployed:
jar -xvf SomeApp.ear
 
The DTD of the runtime deployment descriptor is in the lib/dtds/sun-j2ee-ri-dtd file of your J2EE SDK installation.

Note: The runtime deployment descriptor (sun-j2ee-ri-<version>.xml) is not required by the J2EE Specification. This descriptor is unique to the J2EE SDK and may change in future releases.

Resource Adapter RAR File

Syntax
packager -connector <root-directory> <file-list> 

ra.xml myConnector.rar
 
Example

In this example, the jar command packages the files under the com directory into myfiles.jar. The packager command creates a RAR file named theConnector.rar that contains myfiles.jar and the myra.xml deployment descriptor:
jar -cvf myadapter.jar com

packager -connector . myadapter.jar myra.xml theConnector.rar
 
Realm Tool

The realmtool utility is a command-line script that enables you to add and remove J2EE users and to import certificate files.

Table 5 realmtool Options
Option
Description

-show
Lists the realm names.

-list <realm-name>
Lists the users in the specified realm. This release has two realms: default and certificate.

-listGroups
Lists the groups in the default realm.

-userGroups <user-name>
Lists the groups in the default realm to which the specified user belongs.

-add <user-name password
group[,group]>
Adds the specified user to the default realm.

-addGroup <group>
Adds a group to the default realm.

-import <certificate-file>
Adds a user to the certificate realm by importing a file containing an X.509 certificate.

-remove <realm-name user-name>
Removes a user from the specified realm.

-removeGroup <group>
Removes a group.

Examples

To display all users in the default realm, type this command:
realmtool -list default
 
To add a user to the default realm you specify the -add flag. The following command will add a user named robin who is protected by the password red, and will include robin in the bird and wing groups:
realmtool -add robin red bird,wing
 
To add a user to the certificate realm, you import a file containing the X.509 certificate that identifies the user:
realmtool -import certificate-file
 
To remove a user, you specify the -remove flag. For example, to remove a user named sparrow from the default realm, you would type the following command:
realmtool -remove default sparrow
 
To add a group to the default realm you specify the -addGroup flag. The following command adds the wing group:
realmtool -addGroup wing
 
(You cannot add a group to the certificate realm.)

To remove a group from the default realm, you specify the -removeGroup flag:
realmtool -removeGroup wing
 
runclient Script

To run a J2EE application client, you execute the runclient script from a command-line prompt.

Syntax
runclient -client <appjar> [-name <name>]

[-textauth] [app-args]
 
Table 6 runclient Options
Option
Description

-client <appjar>
The J2EE application EAR file

-name <name>
The display name of the J2EE application client component

-textauth
Causes the client container to prompt for the user name and password are from the command line, not from a pop-up window

<app-args>
Any arguments required by the J2EE application

Example

Before executing the runclient command, you must set the APPCPATH environment variable to the name of the client JAR stub file that is generated during deployment. The following example shows how to set APPCPATH on a Windows machine. The runclient command that follows launches a client named FabulousClient. The J2EE application of this client resides in the FabulousApp.ear file.
set APPCPATH=FabulousAppClient.jar

runclient -client FabulousApp.ear -name FabulousClient
 
Accessing a Remote Server

If the J2EE application client will reside on a different machine than the J2EE server, before executing runclient you must do the following:
Install the J2EE SDK on the remote client's machine. The SDK must be on the client's machine so that you can run its runclient script. You do not need to start the J2EE server on the client's machine.
Copy the EAR file to the remote client's machine.
Copy the client JAR stub file to the remote client's machine.
Set the APPCPATH environment variable to the name of the client JAR stub file.
Set the VMARGS environment variable to the following value:
-Dorg.omg.CORBA.ORBInitialHost=<remote-host>
 
For example, if the remote host were named murphy, you would set the VMARGS variable on a Windows machine as follows:
set VMARGS=-Dorg.omg.CORBA.ORBInitialHost=murphy
 
Preventing the User Name and Password Prompts

During iterative development, you may find it convenient to prevent the client container from prompting for the user name and password. To prevent these prompts, set the VMARGS environment variable to the following value:
-Dj2eelogin.name=guest -Dj2eelogin.password=guest123
 
Verifier Tool

The verifier tool validates J2EE archive files (EAR, WAR, JAR).

You can run verifier three ways:

From within the deploytool GUI
As a command-line utility
As a stand-alone GUI utility

To run verifier from within the deploytool GUI, choose Verifier from the Tools menu. The following sections explain how to run the verifier the other two ways.

Command-Line Verifier

The command-line verifier tool has the following syntax:
verifier [options] <filename>
 
The filename argument is the name of a J2EE component file.

Table 7 verifier Options
Syntax
Description

-v
Displays a verbose version of output.

-o <output-file>
Writes the results to the specified <output-file>, overriding the default Results.txt file.

-u
Runs the stand-alone GUI version.

-<report-level>
Determines whether warnings or failures are reported. The <report-level> may be either a, w, or f:
a (all results)
w (warnings only)
f (failures only)
By default, only warnings and failures are reported.

Stand-Alone GUI Verifier

To run the stand-alone GUI verifier tool, follow these steps:
From the command-line prompt, type:
verifier -u
 
To select a file for verification, click Add.
Select the radio button to indicate the report level:

All Results
Failures Only
Failures and Warnings Only

Click OK.
The verifier tool lists the details in the lower portion of the screen.

Option	Description
`-addConnectorFactory` <jndi-name> `[`<app-name>`:]` <rar-filename> `[`<xa-user-name> <xa-password>`]` `[-props` `(`<name>`=`<value>`)+]`	Adds a connection factory with the specified <jndi-name>. The connection factory is contained in the RAR file specified by <rar-filename>. The <rar-filename> must be the base name of the file; it cannot include any prefix ending in / (UNIX) or \ (Windows). If the RAR file is contained in an EAR file, then the name of the J2EE application name must be specified by <app-name>, followed by a colon. Optionally, a user name and password for the factory may be specified. Also optional is the `-props` flag, followed by one or more name-value pairs that specify properties for this factory. To prevent the shell from interpreting characters in the values, enclose the values in single or double quotes.
`-addJdbcDriver` <class-name>	Adds the JDBC driver specified by its fullyqualified <class-name>. You must also update the `J2EE_CLASSPATH` environment variable in the file `bin\userconfig.bat`. Then you must restart the J2EE server.
`-addJdbcDatasource` <jndi-name> <url>	Adds the JDBC `DataSource` with the specified <jndi-name> and <url>.
`-addJdbcXADatasource` <jndi-name> <class-name> `[`<xa-user-name> <xa-password>`]` `[-props` <name>`=`<value>`)+]`	Adds the JDBC `XADataSource` with the specified <jndi-name> and fully-qualified <class-name>. Optionally, a user name and password for the `DataSource` may be specified. Also optional is the `-props` flag, followed by one or more name-value pairs that specify properties for this `DataSource`.
`-addJmsDestination` <jndi-name> `(queue\|topic)`	Adds a JMS destination with the specified <jndi-name> and declares the destination as either a `queue` or `topic`.
`-addJmsFactory` <jndi-name> `(queue\|topic)` `[-props` `(`<name>`=`<value>`)+]`	Adds a JMS connection factory with the specified <jndi-name> and destination type, either queue or topic. Optionally, one or more properties may be specified with name-value pairs.
`-list`<resource-type>	Lists resources of the specified <resource-type>, either `ConnectorFactory`, `JdbcDriver`, `JdbcDatasource`, `JdbcXADatasource`, `JmsDestination`, or `JmsFactory`. There is no space between `-list` and <resource-type>.
`-remove`<resource-type> <jndi-name>	Removes the resource of the specified <resource-type> and <jndi-name>. (See the description of `-list` for the allowed <resource-type> elements.)
`-removeAll`<resource-type>	Removes all resources of the specified <resource-type>. (See the description of `-list` for the allowed <resource-type> elements.)

Option	Description
`-deploy` <ear-filename> <server-name> `[`<client-stub-jar>`]`	Deploys the J2EE application contained in the EAR file specified by <ear-filename> onto the J2EE server running on the machine specified by <server-name>. Optionally, a JAR file for a stand-alone Java application client may be created by specifying <client-stub-jar>.
`-deployConnector` <rar-filename> <server-name>	Deploys the resource adapter contained in the RAR file specified by <rar-filename> onto the J2EE server running on the machine specified by <server-name>.
`-generateSQL` <ear-filename> <server-name> `[noOverWrite]`	Generates SQL statements for all entity beans with container-managed persistence. These beans are in the EAR file specified by <ear-filename> that has been deployed on the J2EE server running on the machine specified by <server-name>. If the `noOverWrite` option is specified, then existing SQL statements are not overwritten.
`-listApps` <server-name>	Lists the J2EE applications that are deployed on the J2EE server running on the machine specified by <server-name>.
`-listConnectors` <server-name>	Lists the resource adapters that are deployed on the J2EE server running on the machine specified by <server-name>.
`-undeployConnector` <rar-filename> <server-name>	Undeploys the resource adapter contained in the file specified by <rar-filename> from the J2EE server running on the machine specified by <server-name>.
`-uninstall` <app-name> <server-name>	Undeploys the J2EE application whose name is <app-name> from the J2EE server running on the machine specified by <server-name>.
`-help`	Displays options.
`-ui`	Runs the GUI version (default).

Option	Description
`-verbose`	Redirects all logging output to the current shell.
`-version`	Displays the version number.
`-stop`	Stops the J2EE server.

Option	Description
`-show`	Lists the realm names.
`-list` <realm-name>	Lists the users in the specified realm. This release has two realms: `default` and `certificate`.
`-listGroups`	Lists the groups in the `default` realm.
`-userGroups` <user-name>	Lists the groups in the `default` realm to which the specified user belongs.
`-add <`user-name password group`[,`group`]>`	Adds the specified user to the `default` realm.
`-addGroup` <group>	Adds a group to the `default` realm.
`-import` <certificate-file>	Adds a user to the `certificate` realm by importing a file containing an X.509 certificate.
`-remove` <realm-name user-name>	Removes a user from the specified realm.
`-removeGroup` <group>	Removes a group.

Option	Description
`-client` <appjar>	The J2EE application EAR file
`-name` <name>	The display name of the J2EE application client component
`-textauth`	Causes the client container to prompt for the user name and password are from the command line, not from a pop-up window
<app-args>	Any arguments required by the J2EE application

Syntax	Description
`-v`	Displays a verbose version of output.
`-o` <output-file>	Writes the results to the specified <output-file>, overriding the default `Results.txt` file.
`-u`	Runs the stand-alone GUI version.
`-`<report-level>	Determines whether warnings or failures are reported. The <report-level> may be either `a`, `w`, or `f`: `a` (all results) `w` (warnings only) `f` (failures only) By default, only warnings and failures are reported.

J2EETM SDK Tools

In This Appendix

J2EE Administration Tool

Cleanup Tool

Cloudscape Server

Starting Cloudscape

Stopping Cloudscape

Running the Interactive SQL Tool

Cloudscape Server Configuration

Deployment Tool

J2EE Server

Key Tool

Packager Tool

EJB JAR File

Syntax

Example

Web Application WAR File

Syntax

Example

Application Client JAR File

Syntax

Example

J2EE Application EAR File

Syntax

Example

Specifying the Runtime Deployment Descriptor

Syntax

Example

Resource Adapter RAR File

Syntax

Example

Realm Tool

Examples

runclient Script

Syntax

Example

Accessing a Remote Server

Preventing the User Name and Password Prompts

Verifier Tool

Command-Line Verifier

Stand-Alone GUI Verifier

J2EE^TM SDK Tools