J2EE TM SDK Tools

The J2EE TM SDK includes the following tools:

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
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
Remote Access
Verifier
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 43 j2eeadmintool 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 fully-qualified <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 enterprise code 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 non-committed 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 commmands 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 the 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 tabbed pane, 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 44 deploytool Options 
Option Description
-deploy
<ear-filename>
<server-name>
[<client-stub-jar>]
Deploys the J2EE application contained in the EAR file specified by <ear-filenamme> 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>.
-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 GUI version (default).


J2EE Server

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

 

Table 45 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.

Key Tool

The keytool utility creates public and private keys and generates X509 self-signed certificates. The J2EE SDK version of the keytool utility has the same options as the version distributed with the J2SE SDK. However, the J2EE version programatically adds a Java Cryptographic Extension provider that has implementations of RSA algorithms (licensed from RSA Data Security). For more information, see the Security chapter.

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 the deploytool to package J2EE components. With the 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

-setRuntime <app-ear>|<appclient-jar> <runtime.xml> 
[-o <output-file>]  
          

        

Example

In the following command, the -setRuntime flag instructs the 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 next commmand copies MyApp.ear to OtherApp.ear, inserts the deployment descriptor into 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.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> file1:file2 
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 46 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.
-add <username password
group[,group]>
Adds the specified user to the default realm.
-addGroup <group> Adds a group to the default realm.
-import <certificate-file>
-alias <alias>
Adds a user to the certificate realm by importing a file containing an X509 certificate.
-remove <realm-name username> 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 X509 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]
[-Dj2eelogin.name=guest -Dj2eelogin.password=guest123]
[app-args]
          


<table>
  <caption>
                                         Table 47    runclient Options                         </caption>
  <tr>
    <th>
          
             
            
Option


          </th>
    <th>
          
             
            
Description


          </th>
  </tr>
  <tr>
    <td>
          
             
            
                -client <appjar>
            

          </td>
    <td>
          
             
            
The J2EE application EAR file.


          </td>
  </tr>
  <tr>
    <td>
          
             
            
                -name <name>
            

          </td>
    <td>
          
             
            
The display name of the J2EE application client component.


          </td>
  </tr>
  <tr>
    <td>
          
             
            
-textauth 


          </td>
    <td>
          
             
            
Causes the client container to prompt for the user name and password are from the command line, not from a pop-up window. 


          </td>
  </tr>
  <tr>
    <td>
          
             
            
-Dj2eelogin.name=guest
-Dj2eelogin.password=guest123


          </td>
    <td>
          
             
            
Prevents the client container from prompting for the user name and password.


          </td>
  </tr>
  <tr>
    <td>
          
             
            
                <app-args>
            

          </td>
    <td>
          
             
            
Any arguments required by the J2EE application.


          </td>
  </tr>
</table>



  
          

        

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  
          

        

Remote Access

If the J2EE application client will reside on a different machine than the J2EE server, before executing runclient you must do the following:

  •  
  • 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  
              

            

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 has the following syntax:

verifier [options] <filename>  
          

        

The filename argument is the name of a J2EE component file. The following table lists the options.

 

Table 48 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, follow these steps:

  1.  
  2. From the command-line prompt, type:
    verifier -u  
                  
    
                
  3. To select a file for verification, click Add.
  4. Select the radio button to indicate the report level:
    •  
    • All Results
    • Failures Only
    • Failures and Warnings Only
  5. Click OK.
  6. The verifier lists the details in the lower portion of the screen.
Left Curve
Java SDKs and Tools
Right Curve
Left Curve
Java Resources
Right Curve

Java 8 banner (182)

Virtual Technology Summit 07.09.14 Banner

Java One 2014 RHS Banner

Duke's Choice RHS Banner