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