7 Using the admin.jar Utility

OC4J provides a command-line utility called admin.jar that can be used to perform operations on an active OC4J instance in a standalone OC4J installation. Among other things, you can use this utility to restart and stop OC4J, deploy applications and gather information on current resource usage.

This chapter includes the following topics:

• Overview of admin.jar Usage

• Managing a Standalone OC4J Instance

• Deploying/Undeploying Applications

• Managing Applications

• Managing Web Sites

• Managing Data Sources

• Deploying/Undeploying Connectors

Overview of admin.jar Usage

The admin.jar utility is installed by default in ORACLE_HOME/j2ee/home in a standalone OC4J instance.

Note that OC4J must be started before this utility can be used. Also note that the utility cannot be used to start OC4J, although it can be used to stop and then restart an instance.

This section covers the following topics:

• Understanding the admin.jar Syntax

• Printing Help to the Console

Note: The admin.jar utility can be used only to manage a single OC4J instance in a standalone OC4J installation. Use Oracle Process Manager and Notification Server (OPMN) to manage OC4J instances running as components of Oracle Application Server. Due to its more advanced capabilities, the admin_client.jar utility should be used instead of admin.jar. See Chapter 6, "Using the admin_client.jar Utility" for details on using this utility.

Understanding the admin.jar Syntax

The admin.jar utility uses the following syntax. The parameters are described in Table 7-1.

java -jar admin.jar ormi://oc4jHost:oc4jOrmiPort adminId     adminPassword options

As an example, the following command will force a graceful shutdown of the OC4J server. The value supplied for oc4jOrmiPort is the default, 23791. The user name supplied for adminId is the user name for the default administrator account, oc4jadmin.

java -jar admin.jar ormi://localhost:23791 oc4jadmin password -shutdown 

Note that some of these commands include an -application switch that takes the name of the application to affect. The value is the name of the specific application to affect, as defined within the appropriate <application> element in the server.xml configuration file.

Table 7-1 Setting the Host and Login Information

Parameter	Description
oc4jHost:oc4jOrmiPort	The host name and port of the OC4J server on which you are invoking admin.jar. The admin.jar tool uses the OC4J Remote Method Invocation (ORMI) protocol to communicate with the OC4J server. Therefore, the host name and port identified by these variables are defined in the rmi.xml file for the OC4J server to which you are directing the request. The OC4J default port for the ORMI protocol is 23791. This value can be omitted if not changed. Configure both the host name and port number - if not using the default - in the rmi.xml file in the <rmi-server> element, as follows: <rmi-server port="oc4jOrmiPort" host="oc4jHost" />
adminId adminPassword	The OC4J administration user name and password. The user name for the default administrator account is oc4jadmin.

Printing Help to the Console

To print the online help text for the admin.jar commands to the console, simply type -help after oc4jHost:oc4jOrmiPort adminId adminPassword. For example:

java -jar admin.jar ormi://localhost:23791 oc4jadmin password -help 

Managing a Standalone OC4J Instance

This section outlines the functionality provided by admin.jar for managing an OC4J server. It includes the following sections:

• Stopping and Restarting OC4J in a Standalone Environment

• Forcing OC4J to Check for Modified Files

Stopping and Restarting OC4J in a Standalone Environment

You can use admin.jar to shut down a standalone instance of the OC4J server and then restart it.

The following command forces a shutdown of the OC4J server, which terminates all threads immediately. The string entered as the reason for the shutdown is written to the server log file, ORACLE_HOME/j2ee/home/log/server.log.

java -jar admin.jar ormi://localhost:23791 oc4jadmin password -shutdown force 
  need_to_reboot_host_machine

Table 7-2 Options for OC4J Server Shutdown/Restart

Option	Description
-shutdown	Shuts down the OC4J server. [ordinary|force]: The type of shutdown. The default is ordinary, which allows each thread to terminate normally. The force option terminates all threads immediately. [reason]: You can optionally specify a reason for the shutdown as a string that is written to the ORACLE_HOME/j2ee/home/log/server.log file. Spaces are not allowed in the string.
-restart	Restarts the OC4J server. The container must have been started with oc4j.jar. [reason]: You can optionally specify a reason for the restart as a string that is written to the ORACLE_HOME/j2ee/home/log/server.log file. Spaces are not allowed in the string.
-version	Prints the installed version of OC4J to the console, then exits.

Forcing OC4J to Check for Modified Files

You can force OC4J to check the server directory structure for modified files and reload any that have changed, using the -updateConfig option.

Note that the value of the checkForUpdates flag must be set to either all or adminClientOnly (the default setting) to use this feature. See Oracle Containers for J2EE Deployment Guide for details on the checkForUpdates flag.

Table 7-3 Option for Checking for Updated Files

Option	Description
-updateConfig	Forces OC4J to check files for changes and reload any files that have been modified.

Deploying/Undeploying Applications

You can use admin.jar to deploy or undeploy J2EE applications to or from a standalone OC4J instance.

Usage Notes: admin.jar cannot be used to deploy applications to an OPMN-managed OC4J instance. admin.jar supports deployment of EAR files only. It does not allow deployment of standalone modules, such as a Web module packaged in a WAR file. admin.jar does not accept a deployment plan. Any archive deployed using this utility must include the required OC4J-specific deployment descriptor files, such as orion-application.xml or orion-web.xml.

Deploying an application is a two-step process: You must first deploy the archive into OC4J, then bind the Web module to the Web site that will be used to access the application.

The -deploy command is first used to deploy the application:

java -jar admin.jar ormi://oc4jHost:oc4jOrmiPort adminId     adminPassword -deploy -file path/filename    -deploymentName appName -targetPath deploy_dir

Once the archive is deployed, the -bindWebApp command is used to bind a Web application to the Web site it will be accessed through:

java -jar admin.jar ormi://oc4jHost:oc4jOrmiPort adminId    adminPassword -bindWebApp appName webAppName    webSiteName contextRoot

For example, the following command deploys the utility application into OC4J:

java -jar admin.jar ormi://localhost:23791 oc4jadmin password -deploy -file utility.ear -deploymentName utility 

Next, the following example binds the utility application and its utility-web Web module to the default OC4J Web site:

java -jar admin.jar ormi://localhost:23791 oc4jadmin password -bindwebapp utility utility-web default-web-site /utility 

Table 7-4 Options for Application Deployment

Option	Description
-deploy	Deploys an application. Supply relevant information using the following subswitches: -file filename: Required. The path and filename of the EAR file to deploy. -deploymentName appName: Required. The user-defined application deployment name. This same name is used to identify the application within OC4J. It is also provided when you want to undeploy the application. -targetPath path: Optional. The path on the server node to deploy the EAR to. If not specified, the EAR is deployed to the ORACLE_HOME/j2ee/instance/applications/ directory by default. The deployed EAR file is also copied to this directory. Each successive deployment will cause this EAR file to be overwritten. -parent appName: Optional. The parent application of this application. When deployed, any method within the child application can invoke any method within the parent application. In no parent is specified, the default application serves as the default parent. -deploymentDirectory path: Optional. The directory containing the OC4J-specific deployment descriptors and generated files, such as compiled JSP classes and EJB wrapper classes. The default directory is ORACLE_HOME/j2ee/instance/application-deployments/. -iiopClientJar path/filename: Optional. Include to generate IIOP stubs for the home, remote and local interfaces packaged within each EJB JAR included in the EAR. You can optionally specify the path and filename of the JAR to output the generated stubs to. Otherwise, copies of the stubs will be output to an archive named _iiopClient.jar in a new subdirectory with the same name as the deployed EJB JAR in ORACLE_HOME/j2ee/homeapp-name/application-deployments/. Note that the GenerateIIOP system property must be enabled at OC4J startup to use this feature. For example: java -DGenerateIIOP=true -jar oc4j.jar
-bindWebApp	Binds a Web application to the specified Web site and root. appName: The application name, which is the same name set as the value for -deploymentName in the -deploy option. webAppName: The name of the Web module. This should be the name of the WAR file contained within the EAR file, without the .WAR extension. webSiteName: The name of the name_web-site.xml file that denotes the Web site that this Web application should be bound to. contextRoot: The root context for the Web module. This will be appended to the URL used to access the application through a Web browser; for example http://localhost:8888/utility. This option creates an entry in the name-web-site.xml configuration file that was denoted in the web_site_name variable.
-undeploy appName	Removes the deployed J2EE application from the OC4J instance. The value of appName is the name of the application within OC4J, as defined in an application element within ORACLE_HOME/j2ee/home/config/server.xml. Undeploying an application results in the following: The application is removed from the OC4J runtime and the server.xml file. Bindings for all the application's Web modules are removed from all the Web sites to which the Web modules were bound. Application files are removed from both the applications and application-deployments directories. -keepFiles: This optional subswitch is deprecated in OC4J 10g (10.1.3).

Managing Applications

This section outlines the functionality provided by admin.jar for managing applications in a standalone OC4J instance. It includes the following sections:

• Starting/Stopping/Restarting an Application

• Updating an EJB Module Within an Application

Starting/Stopping/Restarting an Application

You can use admin.jar to start, stop and restart an application that has been stopped in a standalone OC4J instance.

The following example restarts a specific application running on OC4J. If a file within the application has been modified, the application or module will be automatically redeployed.

java -jar admin.jar ormi://localhost:23791 oc4jadmin password -application
   myapplication -restart

Table 7-5 Options for Application Restart

Option	Description
-application appName -start	Starts the specified application and any child applications.
-application appName -stop	Stops the specified application and any child applications.
-application appName -restart	Restarts the specified application and any child applications. If OC4J polling is enabled and a file within the application has been modified, the application will be redeployed.

Updating an EJB Module Within an Application

The admin.jar utility includes an -updateEJBModule option that allows incremental or partial redeployment of EJB modules within an application running in an OC4J instance. This option is primarily intended to be used by an application developer to redeploy the JAR file directly from his/her development environment.

The syntax is as follows:

java -jar admin.jar ormi://oc4jHost:oc4jOrmiPort adminId    adminPassword -application appName -updateEJBModule relativePath      [-file path/ejbJarName] 

For example, the following commands can be used to update the customerEjb.jar module of the petstore application. Assume the following directory structure on the developer's machine:

/work
  /src    - application source code
  /build  - compiled class files
  /dist   - assembled EAR and JAR files

If the updated EJB JAR is in the /dist directory, in a location matching the relative path defined in the application's application.xml J2EE standard deployment descriptor, the following command could be issued from the /dist directory:

java -jar $OC4J_HOME/admin.jar ormi://myoc4jserver:23791 oc4jadmin password     -application petstore -updateEJBModule customerEjb.jar 

If the updated file is located within the /build directory, the following command specifying the JAR location in the -file option can be issued from the /dist directory:

java -jar admin.jar ormi://myoc4jserver:23791 oc4jadmin password     -application petstore -updateEJBModule customerEjb.jar      -file build/customerEjb.jar

Table 7-6 Options for Updating an EJB Module

Option	Description
-application appName -updateEJBModule	Updates the specified EJB module with new EJBs. relativePath: The relative path to the EJB JAR containing the updated beans as defined in the application's application.xml J2EE deployment descriptor. -file path: The path and file name of the updated EJB JAR if the file's location does not match the relative path specified in the application.xml deployment descriptor.

Managing Web Sites

The -site option enables you to configure new Web sites, including secure sites, for use by applications deployed into OC4J. You can also retrieve a list of existing sites; test existing sites; and update or remove existing sites.

The syntax of the -add option, which configures a new site, is as follows:

java -jar admin.jar ormi://oc4jHost:oc4jOrmiPort adminId    adminPassword -site -add [-host hostName] -port port -display-name name [-virtual-hosts hostNames] [-secure [true|false]] [-factory class] [-keystore path] [-storepass password] [-provider class] [-needs-client-auth [true|false]]

For example, the following command structure configures a new Web site on port 8899 with two virtual hosts:

java -jar admin.jar ormi://localhost:23791 oc4jadmin password -site -add -host www1.acme.com -port 8899 -display-name MyServer -virtual-hosts MyServer.com,MyServer2.com

The next example configures a secure Web site to receive HTTPS requests on port 4443. See "Configuring a Secure Web Site in OC4J" for instructions on creating secure Web sites.

java -jar admin.jar ormi://localhost:23791 oc4jadmin password -site -add 
-host www1.acme.com -port 8899 -display-name MySecureSite -secure 
true -factory com.evermind.ssl.JSSESSLServerSocketFactorykeystore 
-keystore ../../server.keystore -storepass password 
-provider com.sun.net.ssl.internal.ssl.Provider -needs-client-auth true

Table 7-7 Options for Web Site Administration

-site options	Description
-site -add	Installs a new Web site. Supply information with the following subswitches: -host hostName: The name of the host or the IP address hosting the Web site. Optional. -port port: The Web site port. Required. -display-name name: A user-friendly "displayable" name of the Web site. -virtual-hosts hostNames: One or more virtual Web sites sharing the same IP address. The value is a comma-delimited list of host names tied to this Web site. Optional. -secure [true|false]: The value is true if the Web site is secure. The default is false. -factory className: The name of the class extending SSLServerSocketFactory if you are not using Java Secure Socket Extension (JSSE). Optional. -keystore path: The relative or absolute path to a keystore. Optional. -storepass password: The keystore password. Optional. -provider provider: The security provider to use if not using JSSE. If not specified, the Sun Microsystems implementation - com.sun.net.ssl.internal.ssl.Provider - is used by default. The JSSE defines a provider interface that other security providers can implement. Optional. -needs-client-auth [true|false]: If set to true, a client that wants to access the Web site must identify itself with a digital certificate. The default is false.
-site -remove	Removes an existing Web site. Supply the host and port of this Web site in the following subswitches: -host hostName: The Web site host to be removed. -port port: The Web site port to be removed.
-site -test	Tests an existing Web site. Supply the host and port of the Web site to be tested, in the following subswitches: -host hostName: The Web site host to be tested. -port port: The Web site port to be tested.
-site -list	Lists all existing Web sites configured within the OC4J instance.
-site -update	Updates an existing Web site. Supply information with the following subswitches: -oldHost hostName: The name of the host or the IP address of the current Web site host. -oldPort port: The current port. -newHost hostName: The hostName or IP address of the new Web site host. -newPort port: The new port. -display-name name: A user-friendly "displayable" name of the Web site. -virtual-hosts hostNames: One or more virtual Web sites sharing the same IP address. The value is a comma-delimited list of host names tied to this Web site. Optional. -secure [true|false]: The value is true if the Web site is secure. The default is false. -factory className: The name of the class extending SSLServerSocketFactory if you are not using Java Secure Socket Extension (JSSE). Optional. -keystore path: The relative or absolute path to a keystore. Optional. -storepass password: The keystore password. Optional. -provider provider: The security provider to use if not using JSSE. If not specified, the Sun Microsystems implementation - com.sun.net.ssl.internal.ssl.Provider - is used by default. The JSSE defines a provider interface that other security providers can implement. Optional. -needs-client-auth [true|false]: If set to true, a client that wants to access the Web site must identify itself with a digital certificate. The default is false.

Managing Data Sources

Use admin.jar to create, remove, list or test data sources for a specific application. You can also convert a pre-Oracle Application Server 10g Release 3 (10.1.3) data-sources.xml file to the new file format.

Creating an Application-Specific Data Source

The syntax of the -installDataSource option, which configures a new application-specific data source, is as follows:

java -jar admin.jar ormi://oc4jHost:oc4jOrmiPort adminId adminPassword -application appName -installDataSource -jar path
-url url -location jndiName [-pooledLocation jndiName]
[-xaLocation jndiName] [-ejbLocation jndiName] -username name
-password password [-connectionDriver className] -className className
[-sourceLocation jndiName][-xaSourceLocation jndiName]

An example follows.

java -jar admin.jar ormi://localhost:23791 oc4jadmin password -application myapp 
-installDataSource -jar C:/jdbc/lib/ojdbc14dms.jar 
-url jdbc:oracle:thin:@dev2:1521:main -location jdbc/OracleUddi
-username dbuser -password dbpw -className oracle.jdbc.pool.OracleDataSource 

Table 7-8 Options for Data Source Management

Option

Description

-application appName -installDataSource

Installs a new data source for the specified application. Supply data source information within the following subswitches: -jar path: Required. The path to the JAR file containing the JDBC driver that is to be added to the OC4J server. -url url: Required. The JDBC database URL. -location jndiName: Required. The JNDI name for the raw data source. For example, "jdbc/DefaultPooledDS". -pooledLocation jndiName: Optional. The JNDI name for the pooled data source. For example, "jdbc/DefaultPooledDS". -xaLocation jndiName: Optional. The JNDI name for the XA source. For example, "jdbc/xa/DefaultXADS". Required if -ejbLocation is specified. -ejbLocation jndiName: Optional. The JNDI name for the container-managed transactional data source. This is the only data source that can perform global JTA transactions. For example, "jdbc/DefaultDS". -username name: Required. The user name to log in to the database. -password password: Required. The password to log in to the database. -connectionDriver className: Optional. The JDBC database driver class. -className classNameRequired. The data source class name, such as com.evermind.sql.DriverManagerDataSource. -sourceLocation jndiName: Optional. The JNDI name of the underlying data source of this specialized data source. -xaSourceLocation jndiName: Optional. The JNDI name of the underlying XA data source of this specialized data source.

Listing/Testing/Removing Existing Data Sources

You can use admin.jar to list, test or even delete data sources tied to a specific application.

Table 7-9 Options for Application and Data Source Management

Option	Description
-application appName -listDataSource	Retrieves the statically configured information about each installed data source object.
-application appName -testDataSource	Tests an existing data source. Supply information with the following subswitches: -location jndiName: The namespace location for the data source. For example, jdbc/DefaultDS. Required. -username name: The user name you use to log in along with a password. Optional. -password password: The password to log in with. Optional.
-application appName -removeDataSource	Removes an existing data source. Supply information with the following subswitch: -location jndiName: The namespace location for the data source. For example, jdbc/DefaultDS. Required.

Converting Existing Data Sources to the New Configuration

The -convertDataSourceConfiguration option converts a pre-Release 3 (10.1.3) data-sources.xml file to the new file format.

The syntax is as follows:

java -jar admin.jar ormi://oc4jHost:oc4jOrmiPort adminId    adminPassword -convertDataSourceConfiguration legacyFileName convertedFileName

For example, the following command converts an existing configuration and writes it to a new file:

java -jar admin.jar ormi://localhost:23791 oc4jadmin password -convertDataSourceConfiguration C:\oc4j\j2ee\home\config\data-sources.xml C:\new\data-sources.xml

Ideally, you should rename the "old" data-sources.xml after the conversion, rather than delete it, as it contains information that may be needed for reference. After the "new" file has been generated, copy it into the directory containing the legacy file.

Note that the generated data-sources.xml file may include JNDI entries that are not needed but are transferred from the legacy file. Edit the file to remove these entries.

Table 7-10 Options for Data Source File Conversion

Arguments	Description
legacyFileName	The fully qualified path to the "old" data-sources.xml file you want to convert.
convertedFileName	The fully qualified path to the "new" data-sources.xml file containing the converted configuration.

Deploying/Undeploying Connectors

You can use one of the following commands to deploy or undeploy a Java Connector Architecture-compliant resource adapter packaged in a RAR file.

Table 7-11 Options for Application Deployment

Option	Description
-deployconnector	Deploys a connector. Supply application information in the following subswitches: -file path: Required. The path and filename of the RAR file to deploy. -name name: The name of the resource adapter. -nativeLibPath path: The path to the directory containing native libraries (such as DLLs) within the RAR file. -grantAllPermissions: Include to grant all runtime permissions requested by the resource adapter, if required.
-undeployconnector	Undeploys the specified connector. name name: The name of the connector to undeploy. Note that if you are undeploying a standalone RAR, the default application must be restarted.