J2EE SDK ToolJ2EE SDK Toolss

J2EE SDK Tools

j2ee

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

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, install a server certificate.

j2eeadmin

The j2eeadmin tool is a command-line script that enables you to add and remove these resources:

JDBC drivers
JDBC data sources
JMS destinations
JMS connection factories
Resource adapter connection factories.

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 app 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 fully qualified class-name. You must also update the J2EE_CLASSPATH environment variable in the file bin\userconfig.bat. Then 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.

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

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

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

cleanup

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

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, 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!

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

deploytool

The deploytool utility has two versions: GUI and command line. The GUI version enables you to package components and to deploy apps. 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 apps. To package components from the command line, use the packager tool.

Option Description

-deploy
ear-filename
server-name
[client-stub-jar] Deploys the J2EE app 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 app 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 apps 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 app 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).

keytool

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.

packager

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 app WAR file
Application client JAR file
J2EE app EAR file
Resource adapter RAR file

The packager tool also enables you to set the runtime deployment information of an app EAR file.
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 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 -appClient root-directory file-list main-class appclient-dd appclient-jar

Example

The following command creates the appClient.jar file:
packager -appClient 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 app 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 app'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.
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

realmtool

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

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

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

Syntax

runclient -client appjar [-name name] [-textauth] [app-args]

Option Description

-client appjar The J2EE app EAR file

-name name The display name of the J2EE app client component

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

app-args Any arguments required by the J2EE app

Example

Before executing the runclient command, 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 app 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 app client will reside on a different machine than the J2EE server, before executing runclient 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

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.

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
-verbose	Redirects all logging output to the current shell.
-version	Displays the version number.
-stop	Stops the J2EE server.

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 app 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 fully qualified class-name. You must also update the J2EE_CLASSPATH environment variable in the file bin\userconfig.bat. Then 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.
-listresource-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.
-removeresource-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.)
-removeAllresource-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 app 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 app 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 apps 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 app 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
-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 app EAR file
-name name	The display name of the J2EE app client component
-textauth	Causes the client container to prompt for the user name and password from the command line, not from a pop-up window
app-args	Any arguments required by the J2EE app

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.