J2EETM SDK Tools
This page is an appendix from the J2EETM Tutorial, which is available online at:
http://java.sun.com/j2ee/tutorial/index.html
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
- 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: JDBCTM drivers and data sources, JMS destinations and connection factories, and resource adapter connection factories.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 -startYou 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 registryStopping Cloudscape
To stop the server type the following command:
cloudscape -stopYou 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 theij
tool by typing this command:cloudscape -isqlWithin 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 namedmyscript.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.sqlThis 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.comCloudscape Server Configuration
The default database used by the Cloudscape server is named
CloudscapeDB
. This database will reside in thecloudscape
directory of your J2EE SDK installation. TheCloudscapeDB
database will be created automatically the first time it is accessed. The driver for the Cloudscape server is already configured in theconfig/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 thedeploytool
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.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 thekeytool
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 usedeploytool
to package J2EE components. Withpackager
, 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 thehello-jar.xml
deployment descriptor into theHelloEJB.jar
file:packager -ejbJar /home/duke/classes/ HelloHome.class:HelloEJB.class:HelloRemote.class hello-jar.xml HelloEJB.jarWeb 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 JSPTM 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.warApplication 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.jarJ2EE 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.earSpecifying 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 thedeploytool
, 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 instructspackager
to insert the runtime deployment descriptor (sun-j2ee-ri.xml
) into themyApp.ear
file:packager -setRuntime MyApp.ear sun-j2ee-ri.xmlThe following command copies
MyApp.ear
toOtherApp.ear
, inserts the deployment descriptor into theOtherApp.ear
file, and leavesMyApp.ear
unchanged:packager -setRuntime MyApp.ear sun-j2ee-ri.xml -o OtherApp.earTo obtain an example of the runtime deployment descriptor, extract it from an EAR file that you've already deployed:
jar -xvf SomeApp.earThe 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.rarExample
In this example, the
jar
command packages the files under thecom
directory intomyfiles.jar
. The packager command creates a RAR file namedtheConnector.rar
that containsmyfiles.jar
and themyra.xml
deployment descriptor:jar -cvf myadapter.jar com packager -connector . myadapter.jar myra.xml theConnector.rarRealm Tool
The
realmtool
utility is a command-line script that enables you to add and remove J2EE users and to import certificate files.Examples
To display all users in the default realm, type this command:
realmtool -list defaultTo add a user to the default realm you specify the
-add
flag. The following command will add a user namedrobin
who is protected by the passwordred
, and will includerobin
in thebird
andwing
groups:realmtool -add robin red bird,wingTo add a user to the certificate realm, you import a file containing the X.509 certificate that identifies the user:
realmtool -import certificate-fileTo remove a user, you specify the
-remove
flag. For example, to remove a user namedsparrow
from the default realm, you would type the following command:realmtool -remove default sparrowTo add a group to the default realm you specify the
-addGroup
flag. The following command adds thewing
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 wingrunclient 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]
Example
Before executing the
runclient
command, you must set theAPPCPATH
environment variable to the name of the client JAR stub file that is generated during deployment. The following example shows how to setAPPCPATH
on a Windows machine. Therunclient
command that follows launches a client namedFabulousClient
. The J2EE application of this client resides in theFabulousApp.ear
file.set APPCPATH=FabulousAppClient.jar runclient -client FabulousApp.ear -name FabulousClientAccessing 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 theVMARGS
variable on a Windows machine as follows:set VMARGS=-Dorg.omg.CORBA.ORBInitialHost=murphyPreventing 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=guest123Verifier Tool
The
verifier
tool validates J2EE archive files (EAR, WAR, JAR).You can run
verifier
three ways:To run
verifier
from within thedeploytool
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.
Stand-Alone GUI Verifier
To run the stand-alone GUI
verifier
tool, follow these steps: