Skip Headers

Oracle® Containers for J2EE Configuration and Administration Guide 10g Release 3 (10.1.3) Part No. B14432-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 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/home` `app-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.xm`l. 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` `className`Required. 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.