Skip Headers

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

Previous | Next |

# 12 Deploying to Standalone OC4J with admin.jar

Note: The `admin_client.jar` utility is the recommended option for all deployment and management operations, and should be used in place of `admin.jar`.

The following chapter provides instruction on using the `admin.jar` command-line utility provided with OC4J, which can be used to deploy or undeploy J2EE applications to a standalone OC4J instance. The following topics are covered:

- Understanding the admin.jar Syntax

- Deploying/Redeploying an Application

- Undeploying an Application

- Updating an EJB Module Within a Deployed Application

- Deploying/Redeploying a Standalone Connector

- Undeploying a Standalone Connector

Note that only those `admin.jar` options for deployment and undeployment are documented in this chapter. See the Oracle Containers for J2EE Configuration and Administration Guide for complete instructions on using the `admin.jar` utility.

Notes: `admin.jar` cannot be used to deploy 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`.

## Understanding the admin.jar Syntax

The `admin.jar` utility uses the following syntax. The variables are described in Table 12-1.

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

For example, the following command will print the admin.jar help to the console. 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 -help

Table 12-1 Setting the Host and Login Information

Variable | 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 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`.

## Deploying/Redeploying an Application

The `-deploy` option is used to deploy or redeploy a J2EE application packaged in an EAR file into an OC4J instance. Note that OC4J must already be running before `admin.jar` can be used.

1. Open a command console and change to the J2EE_HOME directory.

2. Deploy the archive into OC4J. The syntax is as follows:

       java -jar admin.jar ormi://oc4jHost:oc4jOrmiPort adminId      adminPassword -deploy -file path/filename    -deploymentName appName [-targetPath path] [-parent appName]    [-deploymentDirectory path] [-iiopClientJar path/filename]

   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

   The following table provides details on the`-deploy` subswitches:

   Table 12-2 -deploy Command Subswitches

   Subswitch | Description
   --- | ---
   `-file` | Required. The path and file name of the EAR file to deploy.
   `-deploymentName` | Required. The user-defined application deployment name, used to identify the application within OC4J.
   `-targetPath` | Optional. The directory 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` | Optional The parent application of this application. The default is the global or `default` application.
   `-deploymentDirectory` | 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` | 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 file name 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`/`instance``/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

3. Next, bind the application to the Web site that will be used to access it. The syntax is:

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

   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 admin password -bindwebapp utility utility-web default-web-site /utility

Table 12-3 -bindWebApp Command Parameters

Parameter | Description
--- | ---
`appName` | The user-defined name of the application, which is the same name used 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 context root 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`.

## Undeploying an Application

The following command removes an application from the OC4J runtime and removes bindings from any Web sites to which the application's Web modules were bound.

1. Open a command console and change to the `ORACLE_HOME` directory.

2. Undeploy the application. The syntax is as follows:

       java -jar admin.jar ormi://oc4jHost:oc4jOrmiPort adminId adminpassword
          -undeploy appname

   - `appName` is the application name, which must match the value specified for `-deploymentName` on the `-deploy` option.

   Note: The optional `-keepFiles` subswitch, which could be used to prevent files from being removed from the installed directories, has been deprecated. All files are now removed during undeployment.

   For example, the following undeploys the `utility` application:

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

## Updating an EJB Module Within a Deployed Application

The `admin.jar` command-line utility provided with OC4J includes an `-updateEJBModule` option that allows an updated EJB JAR to be redeployed to an application running within an OC4J instance. Only those beans that have changed within the EJB JAR will be deployed.

This option is intended to be used by an application developer to redeploy the JAR file directly from his/her development environment. For more information on using `admin.jar`, see the Oracle Containers for J2EE Configuration and Administration Guide.

The syntax for `-updateEJBModule` is as follows:

    java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin_id    admin_password -application appName -updateEJBModule ejbJarName     [-file path/ejbJarName]

Usage notes:

- Specify the application the EJB is a component of as the value for `appName`. This name must match the name specified at deployment.

- If the updated EJB JAR file is in the working directory, and its location matches the relative module path defined in the application's `application.xml` J2EE deployment descriptor, you only need to specify the EJB JAR file name as the value for `ejbJarName`.

- If the updated EJB JAR is not in the working directory, or is in a subdirectory that does not match the relative module path defined in `application.xml`, specify the JAR file's location using the optional `[-file]` subswitch.

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 at the root level of the `/dist` directory and the relative path defined in `application.xml` is Ò`customerEjb.jar`", the following command could be issued from the `/dist` directory:

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

However, if the updated file is located within the `/build` directory, the optional `-file` subswitch can be used to specify this location:

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

Notes: The examples assume that a `J2EE_HOME` environment variable pointing to the `oc4j_installed_dir/j2ee/home` directory within the target OC4J host exists on the developer's machine. An error will occur if the EJB module name is missing or invalid, of if the updated EJB JAR cannot be found.

## Deploying/Redeploying a Standalone Connector

Use the `-deployconnector` command to deploy or redeploy a standalone Java Connector Architecture-compliant resource adapter packaged in a RAR file. Note that redeploying a standalone resource adapter requires a restart of the `default` application.

During redeployment of a resource adapter packaged within a RAR file, all existing application components will continue to obtain connection factories from the existing version of the resource adapter. New components, however, will obtain connection factories from the newly deployed resource adapter.

Existing JCA connections will remain open until closed by the application; new connections will be created from the original resource adapter instance.

The syntax is as follows:

    java -jar admin.jar ormi://oc4jHost:oc4jOrmiPort adminId     adminPassword -deployconnector -file path -name connectorName
        [-nativeLibPath path] [-grantAllPermissions]

Table 12-4 -deployconnector Command Subswitches

Subswitch | Description
--- | ---
`-file` | Required. The path and file name of the RAR file to deploy.
`-deploymentName` | Required. The user-defined connector name, used to identify the connector within OC4J.
`-nativeLibPath` | Optional. The path to the directory containing native libraries (such as DLLs) within the RAR file.
`-grantAllPermissions` | Optional. Include to grant all runtime permissions requested by the resource adapter, if required.

## Undeploying a Standalone Connector

Use `-undeployconnector` to remove a standalone connector from the OC4J runtime. The `default` application must be restarted after a standalone resource adapter is undeployed.

The syntax is as follows. Note that the connector name must be supplied.

    java -jar admin.jar ormi://oc4jHost:oc4jOrmiPort adminId     adminPassword -undeployconnector -name connectorName