J2EETM SDK Tools
This page is an appendix from the J2EETM Tutorial, which is available online at:
The J2EETM 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
- runclient Script
- Accessing a Remote Server
- Preventing the User Name and Password Prompts
- Verifier Tool
- Command-Line Verifier
- Stand-Alone GUI Verifier
J2EE Administration Tool
j2eeadmintool is a command-line script that enables you to add and remove these resources: JDBCTM drivers and data sources, JMS destinations and connection factories, and resource adapter connection factories.
Table 2 j2eeadmin tool Options Option
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
-propsflag, 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.
Adds the JDBC driver specified by its fullyqualified <class-name>. You must also update the
J2EE_CLASSPATHenvironment variable in the file
bin\userconfig.bat. Then you must restart the J2EE server.
Adds the JDBC
DataSourcewith the specified <jndi-name> and <url>.
Adds the JDBC
XADataSourcewith the specified <jndi-name> and fully-qualified <class-name>. Optionally, a user name and password for the
DataSourcemay be specified. Also optional is the
-propsflag, followed by one or more name-value pairs that specify properties for this
Adds a JMS destination with the specified <jndi-name> and declares the destination as either a
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.
Lists resources of the specified <resource-type>, either
JmsFactory. There is no space between
Removes the resource of the specified <resource-type> and <jndi-name>. (See the description of
-listfor the allowed <resource-type> elements.)
Removes all resources of the specified <resource-type>. (See the description of
-listfor the allowed <resource-type> elements.)
cleanuptool 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!
The examples in this manual have been tested with the Cloudscape DBMS, which is included in the J2EE SDK.
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
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
ijtool 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
orderstable, 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
orderstable: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
deploytoolto 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
ijtool, 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
cloudscapedirectory of your J2EE SDK installation. The
CloudscapeDBdatabase will be created automatically the first time it is accessed. The driver for the Cloudscape server is already configured in the
config/default.propertiesfile. No further changes by you are necessary.
deploytoolutility has two versions: GUI and command line. The GUI version enables you to package components and to deploy applications. If you run the
deploytoolscript 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
Table 3 deploytool Options Option
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>.
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>.
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
noOverWriteoption is specified, then existing SQL statements are not overwritten.
Lists the J2EE applications that are deployed on the J2EE server running on the machine specified by <server-name>.
Lists the resource adapters that are deployed on the J2EE server running on the machine specified by <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>.
Undeploys the J2EE application whose name is <app-name> from the J2EE server running on the machine specified by <server-name>.
Runs the GUI version (default).
To launch the J2EE server, run the
j2eescript from the command-line prompt.
Table 4 j2ee Options Option
Redirects all logging output to the current shell.
Displays the version number.
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.
keytoolutility creates public and private keys and generates X.509 self-signed certificates. The J2EE SDK version of the
keytoolutility has the same options as the version distributed with the J2SE SDK. For more information, see the J2EE SDK Configuration Guide.
packagertool is a command-line script that enables you to package J2EE components. This tool is for advanced users who do not want to use
deploytoolto 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
packagertool 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
Syntaxpackager -ejbJar <root-directory> <file-list> <ejb-dd> <ejb-jar>
The following command packages the three
Helloclasses and the
hello-jar.xmldeployment descriptor into the
HelloEJB.jarfile:packager -ejbJar /home/duke/classes/ HelloHome.class:HelloEJB.class:HelloRemote.class hello-jar.xml HelloEJB.jar
Web Application WAR File
Syntaxpackager -webArchive [-classpath <root-directory> [-classFiles <file-list>]] <content-root> [-contentFiles <file-list>] <web-dd> <web-war>
The following command packages helper classes and JSPTM pages into the
bookstore2.warfile: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
Syntaxpackager -applicationClient <root-directory> <file-list> <main-class> <appclient-dd> <appclient-jar>
The following command creates the
appClient.jarfile:packager -applicationClient classes hola:hello/HelloUtil.class package.Main client.xml appClient.jar
J2EE Application EAR File
Syntaxpackager -enterpriseArchive <file-only-list> [-alternativeDescriptorEntries <file-only-list>] [-libraryJars <file-list>] <app-name> <app-ear>
In the following command, the optional
-alternativeDescriptorEntriesflag 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
-enterpriseArchiveflag 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.
Syntaxpackager -setRuntime <app-ear>|<appclient-jar> <runtime.xml> [-o <output-file>]
In the following command, the
packagerto insert the runtime deployment descriptor (
sun-j2ee-ri.xml) into the
myApp.earfile:packager -setRuntime MyApp.ear sun-j2ee-ri.xml
The following command copies
OtherApp.ear, inserts the deployment descriptor into the
OtherApp.earfile, and leaves
MyApp.earunchanged: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-dtdfile of your J2EE SDK installation.
Note: The runtime deployment descriptor (
.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
Syntaxpackager -connector <root-directory> <file-list> ra.xml myConnector.rar
In this example, the
jarcommand packages the files under the
myfiles.jar. The packager command creates a RAR file named
myra.xmldeployment descriptor:jar -cvf myadapter.jar com packager -connector . myadapter.jar myra.xml theConnector.rar
realmtoolutility is a command-line script that enables you to add and remove J2EE users and to import certificate files.
Table 5 realmtool Options Option
Lists the realm names.
Lists the users in the specified realm. This release has two realms:
Lists the groups in the
Lists the groups in the
defaultrealm to which the specified user belongs.
-add <user-name password
Adds the specified user to the
Adds a group to the
Adds a user to the
certificaterealm by importing a file containing an X.509 certificate.
Removes a user from the specified realm.
Removes a group.
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
-addflag. The following command will add a user named
robinwho is protected by the password
red, and will include
winggroups: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
-removeflag. For example, to remove a user named
sparrowfrom the default realm, you would type the following command:realmtool -remove default sparrow
To add a group to the default realm you specify the
-addGroupflag. The following command adds the
winggroup:realmtool -addGroup wing
(You cannot add a group to the certificate realm.)
To remove a group from the default realm, you specify the
-removeGroupflag:realmtool -removeGroup wing
To run a J2EE application client, you execute the
runclientscript from a command-line prompt.
Syntaxrunclient -client <appjar> [-name <name>] [-textauth] [app-args]
Table 6 runclient Options Option
The J2EE application EAR file
The display name of the J2EE application client component
Causes the client container to prompt for the user name and password are from the command line, not from a pop-up window
Any arguments required by the J2EE application
Before executing the
runclientcommand, you must set the
APPCPATHenvironment variable to the name of the client JAR stub file that is generated during deployment. The following example shows how to set
APPCPATHon a Windows machine. The
runclientcommand that follows launches a client named
FabulousClient. The J2EE application of this client resides in the
FabulousApp.earfile.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
runclientyou 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
runclientscript. 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
APPCPATHenvironment variable to the name of the client JAR stub file.
- Set the
VMARGSenvironment variable to the following value:-Dorg.omg.CORBA.ORBInitialHost=
- For example, if the remote host were named
murphy, you would set the
VMARGSvariable 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
VMARGSenvironment variable to the following value:-Dj2eelogin.name=guest -Dj2eelogin.password=guest123
verifiertool validates J2EE archive files (EAR, WAR, JAR).
You can run
verifierfrom within the
deploytoolGUI, choose Verifier from the Tools menu. The following sections explain how to run the verifier the other two ways.
verifiertool has the following syntax:verifier [options] <filename>
The filename argument is the name of a J2EE component file.
Table 7 verifier Options Syntax
Displays a verbose version of output.
Writes the results to the specified <output-file>, overriding the default
Runs the stand-alone GUI version.
Determines whether warnings or failures are reported. The <report-level> may be either
By default, only warnings and failures are reported.
Stand-Alone GUI Verifier
To run the stand-alone GUI
verifiertool, 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:
Click OK. The
verifiertool lists the details in the lower portion of the screen.