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 stop and restart 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 or Undeploying Applications

• Managing Applications

• Managing Data Sources

• Deploying or Undeploying Connectors

Note: The OC4J web-site-related options (accessible with the -site command) that were provided in the admin.jar utility in previous releases are no longer available. For information on how to create and manage OC4J web site configurations, see Chapter 13, "Managing Web Sites in OC4J".

Overview of admin.jar Usage

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

OC4J must be started before this utility can be used, except for converting data sources, as "Converting Existing Data Sources to the New Configuration" describes. Also, the utility cannot be used to start OC4J, although it can be used to stop and then restart an instance, as "Stopping and Restarting OC4J in a Standalone Environment" describes.

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 

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 number for 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 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 and 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: 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 or Undeploying Applications

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

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. The optional -keepFiles subswitch is deprecated in OC4J 10g (10.1.3.1.0).

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, or Restarting an Application

• Updating an EJB Module Within an Application

Starting, Stopping, or Restarting an Application

You can use admin.jar to start, stop, or 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 a development environment.

Note: Incremental redeployment may be more efficient than redeploying the entire application for CMP or BMP entity beans but not for session beans, message-driven beans, or EJB 3.0 JPA entities. For details about whether to use this feature, see "Incremental Redeployment of Updated EJB Modules" in the Oracle Containers for J2EE Deployment Guide.

The syntax 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 $ORACLE_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 Data Sources

Use admin.jar to create, remove, list or test data sources for a specific application. You can also convert a pre-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-7 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 oracle.jdbc.pool.OracleDataSource. -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-8 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 OC4J 10g (10.1.3.1.0) implementation understands the 10.1.3 and the pre-10.1.3 (10.1.2 and 9.0.4) formats of the data-sources.xml file. For an application that was previously used in a pre-10.1.3 OC4J implementation and contains its own data-sources.xml file, the OC4J 10g (10.1.3.1.0) implementation automatically converts the data-sources.xml file from the pre-10.1.3 format to the 10.1.3 format when you use the Application Server Control Console to change anything in the data-sources.xml file, such as modifying an existing data source or creating or deleting a data source.

Convert a data-sources.xml File with Standalone OC4J Running or Not Running

The -convertDataSourceConfiguration option of the admin.jar command converts a pre-10.1.3 data-sources.xml file to the new file format.

With an active OC4J instance in a standalone environment, you can use admin.jar with the following syntax to manually convert a pre-10.1.3 data-sources.xml file to the 10.1.3 format.

java -jar admin.jar ormi://oc4jHost:oc4jOrmiPort adminId adminPassword 
-convertDataSourceConfiguration old-data-sources.xml new-data-sources.xml

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 might be needed for reference. After the new file has been generated, copy it into the directory containing the legacy file.

In the syntax, the ORMI URL is optional. You can specify an ORMI URL only when OC4J is running.

You can also convert a data-sources.xml file before deployment, without a running OC4J instance. The syntax for this offline conversion is as follows:

java -jar admin.jar -convertDataSourceConfiguration 
old-data-sources.xml new-data-sources.xml

Notes: If you include the ORMI port, then OC4J must be running. When OC4J is not running, you must omit the ORMI URL from the admin.jar command line. If you do not include the ORMI port, then the admin.jar command will work either way; that is, with OC4J running or with OC4J not running. The admin.jar utility works only in a standalone OC4J environment. This utility is installed in the Oracle Application Server environment but does not work in an OPMN-managed environment. The newer admin_client.jar utility works in both environments, standalone and managed Oracle Application Server. However, the admin_client.jar utility does not convert data-sources.xml files.

Check Consistency Between the Application and the New data-sources.xml File

After conversion, whether manual or automatic, visually inspect the new data-sources.xml file to confirm that there is consistency between your application and the new file regarding the JNDI location used to refer to a data source.

This consistency check is advisable because the new file may contain data source definitions that are not used, which happens because the old format uses multiple location attributes (such as location, ejb-location, and xa-location). The conversion to the new 10.1.3 format creates a separate data source in the new data-sources.xml file corresponding to each location attribute specified in the old data-sources.xml file. In most cases, client applications will use only the data source defined by either the location or ejb-location attribute. The converted data-sources.xml file may have definitions that are not used by the applications and can be removed from the file.

For examples of the new data-sources.xml format, see the "Data Sources" chapter of the Oracle Containers for J2EE Services Guide.

Deploying or 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-9 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. Undeploying a standalone RAR does not require a restart of the default application.