Skip Headers
Oracle® Containers for J2EE Deployment Guide
10g (10.1.3.5.0)
E13980-01
  Go To Documentation Library
Library
Go To Product List
Product
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
 
Next
Next
 

11 Using the admin_client.jar Utility for Deployment

OC4J provides a command-line utility, admin_client.jar, for performing deployment tasks on active OC4J instances in an Oracle Application Server clustered environment as well as on a standalone OC4J server. In addition, you can use admin_client.jar to restart or stop an OC4J instance or group of instances.

The admin_client.jar utility is also part of the Administrative Client Utility for performing operations remotely, available on the companion CD or for downloading from Oracle Technology Network.

You can perform deployment operations on a specific OC4J instance or simultaneously on all OC4J instances in a group. A group is a synchronized set of OC4J instances that belong to the same cluster topology, which is two or more loosely connected Oracle Application Server nodes. With the admin_client.jar command-line utility, you can perform the following operations on an OC4J instance or group of OC4J instances:

You can perform similar operations with Application Server Control or the OC4J Ant tasks. For more information, see Chapter 9, "Using Application Server Control for Deployment," or Chapter 10, "Using OC4J Ant Tasks for Deployment.".

This chapter includes the following topics:

Preparing to Use admin_client.jar

The admin_client.jar utility is installed by default in the ORACLE_HOME/j2ee/instance directory in each OC4J instance. This is the preferred command-line tool for performing operations on OC4J. This utility is also in the Administrative Client Utility for performing operations remotely, available on the companion CD for Oracle Application Server 10g Release 3 (10.1.3.5.0) or for downloading from Oracle Technology Network.

Before this utility can perform operations on an OC4J instance, the instance must be started.

This section covers these topics:

Understanding the admin_client.jar Syntax and URI Specification

The admin_client.jar utility uses the following syntax:

java -jar admin_client.jar uri adminId adminPassword command

The key parameter passed on the command line is uri, which specifies the target for the command or commands supplied. The syntax for the URI varies depending on the instance or instances being targeted. See the following topics for the format of this URI:

The OC4J administration user name and password are also passed to the admin_client.jar utility. The user name for the default administrator account is oc4jadmin.

As an example, the following command will start the petstore application, which is installed in the OC4J instance named oc4j_2 on node1, a member of a cluster:

java -jar admin_client.jar deployer:oc4j:opmn://node1.company.com/oc4j_2
oc4jadmin password -application petstore -start

Figure 11-1 shows four processes that are configured to run from an OC4J instance named OC4J_home in one of the Oracle Application Server instances within a cluster.

Figure 11-1 OC4J Instance Running on Multiple JVMs in an Oracle Application Server Instance Within a Cluster

Description of Figure 11-1 follows
Description of "Figure 11-1 OC4J Instance Running on Multiple JVMs in an Oracle Application Server Instance Within a Cluster"


Note:

The OC4J instance named home typically cannot be configured to run with multiple processes because it hosts the Application Server Control application, which is not suitable for running in the multiple-process model.

Deploying to a Group of OC4J Instances Within a Cluster

Use the following URI to specify all OC4J instances in a group as the deployment target. A group is a synchronized set of OC4J instances that belong to the same cluster topology. You can perform deployment operations simultaneously on all OC4J instances in the group. For example, you could specify default_group as the target to perform a deployment operation simultaneously on all OC4J instances that belong to the default group (named default_group) in a cluster.

The URI utilizes the OPMN-based clustering framework, in which cluster nodes are aware of one another. You need to supply only the host name and, optionally, the OPMN request port for any Oracle Application Server node within the cluster. The application is then able to retrieve the host names and OPMN ports for all other nodes within the cluster.

The URI syntax follows:

deployer:cluster:[rmis]:opmn://opmnHost[:opmnPort]/groupName

For example:

deployer:cluster:opmn://node1.company.com/default_group

Table 11-1 URI Parameters for Targeting a Group

Parameter Description

rmis

Optional. Include if the target utilizes ORMI over SSL, or ORMIS.

opmnHost

Required. The host name of an Oracle Application Server node within a cluster. Any node can be specified; the list of other nodes in the cluster will be retrieved from this node.

opmnPort

Optional. The OPMN request port, as specified in opmn.xml. If no port is specified, the default port, 6003, will be used.

groupName

Required. The name of the group to which the OC4J instances belong, within a cluster.


Deploying to a Specific OC4J Instance

Use the following URI syntax to target a specific OPMN-managed OC4J instance, including an instance within a cluster. In the prefix, oc4j replaces cluster.

Specify the host name for the Oracle Application Server node hosting the instance. If you are not sure of the host name or port for the node, you can specify the host name for another node within the cluster, as well as the name of the Oracle Application Server instance. The application will then use the OPMN clustering framework to locate the node hosting the Oracle Application Server instance.

The URI syntax follows:

deployer:oc4j:[rmis]:opmn://host[:opmnPort]/[iASInstanceName]/oc4jInstanceName

For example:

deployer:oc4j:opmn://server.company.com:6004/instance2/home

Table 11-2 URI Parameters for Targeting a Specific Instance

Parameter Description

rmis

Optional. Include if the target utilizes ORMI over SSL, or ORMIS.

host

Required. The host name of the Oracle Application Server node to target within the cluster to use as the OPMN server.

opmnPort

Optional. The OPMN request port, as specified in opmn.xml. If no port is specified, the default port, 6003, will be used.

iASInstanceName

Optional. The name of the Oracle Application Server instance to target, if it does not reside on the node specified for host.

oc4jInstanceName

Required. The name of the target OC4J instance.


Deploying to a Standalone OC4J Server

Use one of the following URIs to target a standalone OC4J server instance.

If you are using RMI, specify the URI as follows:

deployer:oc4j:host:rmiPort

For example:

deployer:oc4j:myserver:23791

If you are using ORMI over SSL (ORMIS), specify the URI as follows:

deployer:oc4j:rmis:host:ormisPort

For example:

deployer:oc4j:rmis:myserver:23943

Table 11-3 URI Parameters for Targeting Standalone OC4J

Parameter Description

rmis

Required if the target utilizes ORMI over SSL, or ORMIS.

host

Required. The host name of an Oracle Application Server node within the cluster. Any node can be specified; the list of other nodes in the cluster will be retrieved from this node.

rmiPort

Required if RMI used. The RMI port, as specified in the instance-specific rmi.xml file.

ormisPort

Required if ORMIS is used. The SSL port, as specified in the instance-specific rmi.xml file.


Validating a URI

You can validate a URI using the -validateURI command.

java -jar admin_client.jar uri adminId adminPassword -validateURI

For example:

java -jar admin_client.jar deployer:cluster:opmn://node1.company.com/default_group 
oc4jadmin password -validateURI

Downloading and Extracting the Remote Administration Client

The Administrative Client Utility distribution contains the admin_client.jar command-line utility. This utility can connect to OC4J or Oracle Application Server targets and perform a range of life cycle, deployment, and resource configuration operations.

Consider the scenario in which a remote system needs to perform regular operations against an Oracle Application Server instance. For example, a remote system might have some automated build or test process, such as deployment operations or querying or manipulating some application-specific or server JMX MBeans for administrative purposes. Or perhaps the remote system performs a regularly scheduled test-to-production set of configuration and deployment operations. The Administrative Client Utility can be used to do this, removing the need for the remote system to have a full OC4J or Oracle Application Server installation.

The Administrative Client Utility, a separate distribution for Oracle Application Server 10g Release 3 (10.1.3.5.0), is available for downloading from Oracle Technology Network and is on the Oracle Application Server companion CD. The distribution file, oc4j_admin_client_101350.zip, contains all you need to manage an OC4J instance remotely:

  • The Java libraries required to establish remote JMX connections, using the ORMI protocol, to either an OC4J or Oracle Application Server target

  • The executable admin_client.jar utility with the libraries it requires to operate

  • The standard J2EE libraries relevant to the remote client role

To download and extract the Administrative Client Utility:

  1. Download oc4j_admin_client_101350.zip from the Oracle Technology Network:

    http://download.oracle.com/otn/java/oc4j/10131/oc4j_admin_client_101350.zip
    
  2. Extract the contents of oc4j_admin_client_101350.zip into a local directory. For example:

     >mkdir oc4j_admin_client
     >cd oc4j_admin_client
     >jar xvf d:\software\oc4j_admin_client_101350.zip
    

    The resulting directory structure looks like this:

    \j2ee
       \home
          oc4jclient.jar
          admin_client.jar
          \lib
             ejb.jar
             mail.jar
             adminclient.jar
             javax88.jar
             javax77.jar
             jmx_remote_api.jar
             jmxri.jar
    \lib
       xmlparserv2.jar
       dms.jar 
    \opmn
       \lib
       optic.jar
    \jlib
       oraclepki.jar
       ojpse.jar
    

    The following URIs use different patterns for different OC4J targets:

    • Standalone OC4J server:

      deployer:oc4j:test-cycle.oracle.com:23791
      
    • Specific OC4J instance on Oracle Application Server:

      deployer:oc4j:opmn://test-cycle.oracle.com/testunit 
      
    • Group of OC4J instances within a cluster:

      deployer:cluster:opmn://test-cycle.oracle.com/[groupName] 
      
  3. Connect admin_client.jar to a target OC4J instance or instances and test the connection. For example:

    >cd j2ee\home
    >java -jar admin_client.jar
      deployer:oc4j:opmn://test-cycle.oracle.com/testunit 
        oc4jadmin welcome1 
      –validateURI
    
    URI deployer:oc4j:opmn://test-cycle.oracle.com/testunit is valid and connected
    

Printing Usage Text to the Console

To print the online help text for the admin_client.jar commands to the console, simply type -help on the command line. For example:

java -jar admin_client.jar -help

To view detailed help for a specific command, type -usage followed by the command identifier. For example:

java -jar admin_client.jar -usage [command]

Enabling Logging

To help troubleshoot errors that occur when running admin_client.jar, you can enable Java logging when running this tool. Log messages will be output to the console.

To enable logging:

  1. Create a logging.properties file containing a single line:

    oracle.oc4j.admin.jmx.client.CoreRemoteMBeanServer.level=INFO
    

    If you create this file in a location other than ORACLE_HOME/j2ee/instance, you must include the path to the file in the following command.

  2. Set -Djava.util.logging.config.file=logging.properties on the admin_client.jar command line as follows:

    java -Djava.util.logging.config.file=logging.properties -jar admin_client.jar uri adminId adminPassword command
    

You can set the value in the logging.properties file to one of the Java log-level values in Table 11-4.

Table 11-4 Java Log Levels

Java Log Level Description
SEVERE

Log system errors requiring attention from the system administrator.

WARNING

Log actions or a conditions discovered that should be reviewed and might require action before an error occurs.

INFO

Log normal actions or events. This could be a user operation, such as login completed, or an automatic operation, such as a log file rotation.

CONFIG

Log messages or problems related to log configuration.

FINE

Log trace or debug messages used for debugging or performance monitoring. Typically contains detailed event data.

FINER

Log fairly detailed trace or debug messages.

FINEST

Log highly detailed trace or debug messages.


For example:

oracle.oc4j.admin.jmx.client.CoreRemoteMBeanServer.level=FINE

Adding Web Sites

You can use the -addWebSite command to add a Web site on a standalone OC4J instance or on an OC4J instance within a cluster. The new Web site will include the default Web application from the default Web site. See Chapter 13, "Managing Web Sites in OC4J," in the Oracle Containers for J2EE Configuration and Administration Guide for detailed information about OC4J Web sites and how to manually add Web sites.


Note:

The -addWebSite command cannot be used to create a Web site on multiple OC4J instances within a group.

The syntax for this command follows:

java -jar admin_client.jar uri adminId adminPassword -addWebSite -webSiteName
site-name -protocol protocol -port port [-keystorePath path]
[-keystorePassword password] [-sslProvider class-name]

The following example creates a new Web site called test-web-site on an OC4J standalone instance:

java -jar admin_client.jar deployer:oc4j:localhost:23791 oc4jadmin welcome1 
-addWebSite -webSiteName test-web-site.xml -protocol http -port 8899

Table 11-5 -addWebSite Command Parameters

Parameter Description

-webSiteName

Required. The name for the Web site. The name must use the form name-web-site. For example, test-web-site. In addition, the Web site name must be unique on the OC4J instance.

-protocol

Required. The protocol to be used by the Web site. The protocol can be http, https, ajp, ajps. The ajp protocol can only be used by one Web site on an OC4J instance.

-port

Required. The port number to be used by the Web site. Two Web sites can share the same port number only if they both use the http or https protocol.

-keystorePath

Optional. The filename, including the path, of the keystore file. This parameter is required when using https or ajps and should not be specified when using http or ajp.

-keystorePassword

Optional. The password of the keystore file. This parameter is required when using https or ajps and should not be specified when using http or ajp.

-sslProvider

Optional. The third-party SSLServerSocketFactory implementation. The default SSLServerSocketFactory implementation is used if no implementation is specified.


Deploying an Archive

You can use the admin_client.jar utility to deploy an application (EAR or application directory), a standalone Web module (WAR), a standalone EJB module (JAR), or a standalone resource adapter (RAR) to a specific OC4J instance or to a group of OC4J instances.

This section covers the following topics:


Note:

Deploying an archive across a group requires that all instances have the same oc4jadmin account password.

Deploying a J2EE Application (EAR)

Use the -deploy command to deploy a J2EE application that is packaged as an EAR file or a J2EE application that is in the standard enterprise application directory structure. A J2EE application's modules can be packaged or left in their directory structure as well. The syntax follows:

java -jar admin_client.jar uri adminId adminPassword -deploy -file path/filename 
-deploymentName appName [-bindAllWebApps [webSiteName]] [-targetPath path] 
[-parent appName] [-deploymentDirectory path] [sequential [waitsec]] [-enableIIOP] 
[-iiopClientJar path/filename] [-deploymentPlan path/filename] [-removeArchive]

You can include the -bindAllWebApps parameter to bind all Web modules within the application to the Web site through which they will be accessed. If no Web site is specified, modules will be bound to the default Web site.

For example, the following command deploys the utility application to all OC4J instances that belong to the group default_group within a cluster. All Web modules within the application will be bound to the default Web site.

java -jar admin_client.jar deployer:cluster:opmn://node1.company.com/default_group 
oc4jadmin password -deploy -file C:/dev/utility.ear -deploymentName utility 
-bindAllWebApps 

The application may also be assembled in a standard J2EE application directory structure. Indicate the directory using the -file parameter. The following example deploys the application located in the utility directory:

java -jar admin_client.jar deployer:cluster:opmn://node1.company.com/default_group 
oc4jadmin password -deploy -file C:/dev/utility -deploymentName utility 
-bindAllWebApps 

Table 11-6 -deploy Command Parameters for EAR Deployment

Parameter Description

-file

Required. The file path of the archive or application directory to be deployed. The application directory must be assembled in a standard J2EE application directory structure when using directory-based deployment.

-deploymentName

Required. The user-defined application deployment name, used to identify the application within OC4J.

-bindAllWebApps

Optional. Binds all Web modules in the EAR to the specified Web site or, if none is specified, to the default Web site.

You can supply a value for webSiteName, which is the name portion of the name_web-site.xml file that contains the Web site configuration.

If this parameter is not specified, you can use the -bindAllWebApps command after deployment. For more information about this command, see "Binding All Web Modules to a Single Web Site".

-targetPath

Optional. The directory to deploy the EAR to. If a directory is 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 default application or global Web application.

-deploymentPlan

Optional. The path and file name for a deployment plan to apply to the application. The plan would have been saved during a previous deployment as an XML file. The file must exist on the local host.

-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/applications.

-sequential [waitsec]

Optional. Specify to deploy the archive to each OC4J instance in a group. The deployment to each target OC4J instance must complete before deployment begins on the next target instance. Requests will not be routed to an OC4J instance while the EAR is being deployed to it.

You can use the waitsec option to specify a number of seconds to wait between deployments, as follows:

-sequential 15

For more information about the waitsec option, see "Specifying a Delay Between Sequential Redeployments in a Cluster".

If this parameter is not specified, the archive will be simultaneously deployed to all OC4J instances in the group by default.

This option is valid only in a clustered environment. It is not valid for standalone OC4J.

-enableIIOP

Optional. Specify this parameter to generate IIOP client stubs on the OC4J server.

The application-level stubs generated for all EJB modules are output to an archive named _iiopClient.jar in the ORACLE_HOME/j2ee/instance/application-deployments/appName directory. In addition, stubs for each individual EJB module are generated in an archive with the same name in the ORACLE_HOME/j2ee/instance/application-deployments/appName/ejbModuleName directory.

The GenerateIIOP system property must be enabled at OC4J startup to use this feature. This property is set as -DGenerateIIOP=true on the OC4J command line for standalone OC4J or as an oc4j-options value in opmn.xml.

-iiopClientJar

Optional. The path and file name of the JAR to output IIOP client stubs to.

The application-level stubs generated for all EJB modules are output to an archive named _iiopClient.jar in the ORACLE_HOME/j2ee/instance/application-deployments/appName directory. If a path is supplied, the archive is also set on this path.

In addition, stubs for each individual EJB module are generated in an archive with the same name in the ORACLE_HOME/j2ee/instance/application-deployments/appName/ejbModuleName directory.

The GenerateIIOP system property must be enabled at OC4J startup to use this feature. This property is set as -DGenerateIIOP=true on the OC4J command line for standalone OC4J or as an oc4j-options value in opmn.xml.

-removeArchive

Optional. Specify to delete the EAR file from the server's file system after deployment.


Deploying a J2EE Application from a Remote Client

The following example shows how to deploy an EAR from a remote client to a specific OC4J instance on Oracle Application Server:

cd j2ee/home
>java -jar admin_client.jar 
 deployer:oc4j:opmn://test-cycle.oracle.com/testunit
 oc4jadmin welcome1 
 -deploy 
 -file d:\temp\rupg\testru.ear 
 -deploymentName testru –bindAllWebApps

06/06/20 17:00:16 Notification ==>Uploading file testru.ear ...
06/06/20 17:00:18 Notification ==>Application Deployer for testru STARTS.
06/06/20 17:00:19 Notification ==>Copy the archive to /scratch/sbutton/m1_060618/j2ee/admin/applications/testru.ear
06/06/20 17:00:19 Notification ==>Initialize /scratch/sbutton/m1_060618/j2ee/admin/applications/testru.ear begins...
06/06/20 17:00:19 Notification ==>Unpacking testru.ear
06/06/20 17:00:20 Notification ==>Done unpacking testru.ear
06/06/20 17:00:20 Notification ==>Unpacking testru-web.war
06/06/20 17:00:20 Notification ==>Done unpacking testru-web.war
06/06/20 17:00:20 Notification ==>Initialize /scratch/sbutton/m1_060618/j2ee/admin/applications/testru.ear ends...
06/06/20 17:00:20 Notification ==>Starting application : testru
06/06/20 17:00:20 Notification ==>Initializing ClassLoader(s)
06/06/20 17:00:20 Notification ==>Initializing EJB container
06/06/20 17:00:20 Notification ==>Loading connector(s)
06/06/20 17:00:20 Notification ==>Starting up resource adapters
06/06/20 17:00:20 Notification ==>Initializing EJB sessions
06/06/20 17:00:20 Notification ==>Committing ClassLoader(s)06/06/20 17:00:20 Notification ==>Initialize testru-web begins...
06/06/20 17:00:20 Notification ==>Initialize testru-web ends...
06/06/20 17:00:21 Notification ==>Started application : testru
06/06/20 17:00:21 Notification ==>Binding web application(s) to site default-web-site begins...
06/06/20 17:00:21 Notification ==>Binding testru-web web-module for application testru to site default-web-site under context root /testru
06/06/20 17:00:22 Notification ==>Binding web application(s) to site default-web-site ends...
06/06/20 17:00:22 Notification ==>Application Deployer for testru COMPLETES. Operation time: 3785 msecs

Deploying a Standalone Web Module (WAR)

Use the -deploy command to deploy a standalone Web module packaged as a WAR file.


Note:

The -deploy command does not support directory-based deployment for standalone Web modules. The Web module must be packaged as a WAR file. However, directory-based deployment of a Web module is supported if the Web module directory is included within a J2EE application directory structure with a respective META-INF/application.xml file. In this case, deploy the application instead of the Web module.

The WAR-specific syntax follows:

java -jar admin_client.jar uri adminId adminPassword -deploy -file
path/filename -deploymentName appName [-bindAllWebApps [webSiteName]]
[-targetPath path] [-parent appName] [-deploymentDirectory path]
[-contextRoot context]
[-removeArchive]

The WAR can be designated a child of another deployed application that does not already contain a Web module component; otherwise, the WAR will be deployed to the default application.

A WAR cannot be deployed as the child of an application that already contains a Web module. That is, if the acme application already contains acme-web.war, an additional WAR file cannot be deployed into that application. Repackage the WAR in the application's EAR file and redeploy the application instead.

The following command deploys the standalone acme-web.war Web module to the default application in all OC4J instances that belong to default_group within the cluster of which node1 is a member. Because the -bindAllWebApps parameter is included, but a Web site to bind to is not specified, the module will be bound to the default Web site.

java -jar admin_client.jar deployer:cluster:opmn://node1.company.com/default_group 
oc4jadmin password -deploy -file C:/dev/acme-web.war -deploymentName utility 
-bindAllWebApps -parent default

Table 11-7 -deploy Command Parameters for WAR Deployment

Parameter Description

-file

Required. The path and file name of the archive to deploy.

-deploymentName

Required. The user-defined name for the Web module, used to identify it within OC4J.

-bindAllWebApps

Optional. Binds the Web module to the specified Web site or, if none is specified, to the default Web site.

You can supply a value for webSiteName, which is the name portion of the name_web-site.xml file that contains the Web site configuration.

-targetPath

Optional. The directory to deploy the archive to. If a directory is not specified, the archive is deployed to the ORACLE_HOME/j2ee/instance/applications directory by default.

The generated EAR file containing the standalone WAR file is also copied to this directory. Each successive deployment will cause this archive to be overwritten.

-parent

Optional. The parent application the module will be deployed to. The default is the default application.

-deploymentDirectory

Optional. The directory containing the OC4J-specific deployment descriptors and generated files, such as compiled JSP classes.

The default directory is ORACLE_HOME/j2ee/instance/application-deployments.

-contextRoot

Optional. The Web module context root, which will be appended to the URL used to access the application through a Web browser. If the contest root is not specified, the value passed in for -deploymentName will be used.

For example, if you supply /petstore as the context root, the module could be accessed with the following URL:

http://node1.company.com:7777/petstore

-removeArchive

Optional. Include to delete the WAR file from the server's file system after deployment.


Deploying a Standalone EJB Module (JAR)

Use the -deploy command to deploy a standalone EJB module packaged as a JAR file. The syntax follows:

java -jar admin_client.jar uri adminId adminPassword -deploy -file path/filename 
-deploymentName jarName [-targetPath path] [-parent appName] [-deploymentDirectory path] [-removeArchive]

The following command deploys the standalone acme-ejb.jar EJB module to the default application in all OC4J instances that belong to default_group within the cluster of which node1 is a member.

java -jar admin_client.jar deployer:cluster:opmn://node1.company.com/default_group 
oc4jadmin password -deploy -file C:/dev/acme-ejb.jar -deploymentName acme 

Table 11-8 -deploy Command Parameters for EJB JAR Deployment

Parameter Description

-file

Required. The path and file name of the archive to deploy.

-deploymentName

Required. The user-defined name for the EJB module, used to identify it within OC4J.

-targetPath

Optional. The directory to deploy the EJB JAR to. If a directory is not specified, the EJB JAR is deployed to the ORACLE_HOME/j2ee/instance/applications directory by default.

The deployed EJB JAR file is also copied to this directory. Each successive deployment will cause this EJB JAR file to be overwritten.

-parent

Optional. The parent application the EJB module will be deployed to. The default is the default application.

-deploymentDirectory

Optional. The directory containing the OC4J-specific deployment descriptors. The default directory is ORACLE_HOME/j2ee/instance/applications-deployments.

-removeArchive

Optional. Delete the JAR file from the server's file system after deployment.


Deploying a Standalone Resource Adapter (RAR)

Use the -deploy command to deploy or redeploy a Java Connector Architecture-compliant resource adapter packaged as a RAR file. By default, resource adapters are deployed to the ORACLE_HOME/j2ee/instance/connectors directory.

Redeploying or undeploying a standalone RAR does not require a restart of the default application.

The RAR-specific syntax follows:

java -jar admin_client.jar uri adminId adminPassword -deploy -file path/filename 
-deploymentName connectorName [-nativePathLib path] [-grantAllPermissions]
[-removeArchive]

The following command deploys the acme-rar.rar module to all OC4J instances that belong to default_group within a cluster.

java -jar admin_client.jar deployer:cluster:opmn://node1.company.com/default_group 
oc4jadmin password -deploy -file /dev/acme-rar.rar -deploymentName acme-rar 
-grantAllPermissions -removeArchive

Table 11-9 -deploy Command Parameters for RAR Deployment

Parameter 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 this parameter to grant all runtime permissions requested by the resource adapter, if required.

-removeArchive

Optional. Include this parameter to delete the RAR file from the server's file system after deployment.


For more information, see Chapter 6, "Deploying Resource Adapters."

Using a Script File for Batch Deployment

You can specify a script file that contains deployment commands on the admin_client.jar command line. If you specify a file in the -script command, admin_client.jar can do a list of commands with only one connection to the deployment manager. The syntax for batch deployment follows:

java -jar admin_client.jar uri adminId adminPassword
-script filename

The script file, filename, contains multiple lines, like the lines in this example:

-deploy -file /scratch/rpan/apps/hello-planet.ear -deploymentName hello-planet
-bindWebApp -appName hello-planet -webModuleName hello-planet-web
-stop hello-planet
-start hello-planet
-redeploy -file /scratch/rpan/apps/hello-planet.ear
-deploymentName hello-planet -bindAllWebApps
-undeploy hello-planet
-validateURI

You can convert to batch mode by looking at the script or logs from an installation and extracting the relevant lines used by an existing configuration assistant.

Managing Web Bindings

You can use the admin_client.jar utility to: bind Web modules to a Web site; unbind Web modules from a Web site; and list the current Web module bindings for a Web site. These commands can be run for a specific OC4J instance or for a group of OC4J instances in a cluster.

This section covers the following topics:

Binding Web Modules to a Web Site After Deployment

Every Web module deployed to OC4J must be bound to a Web site through which it will be accessed.

Typically, you will bind Web modules packaged as WAR files within an EAR at the time the EAR is deployed using the -bindAllWebApps parameter on the -deploy command. However, if the -bindAllWebApps parameter was not specified when the EAR was deployed, you can bind modules to a Web site after deployment, as the following topics describe:

Binding All Web Modules to a Single Web Site

Use the -bindAllWebApps command to bind all Web modules within a J2EE application to the same Web site, or to default-web-site by default. The syntax for this command follows:

java -jar admin_client.jar uri adminId adminPassword -bindAllWebApps 
-appName appName -webSiteName siteName -shared true/false -loadOnStartup 
true/false -accessLog true/false

Table 11-10 -bindAllWebApps Command Parameters

Parameter Description

-appName

Required. The name of the parent application as specified at deployment time.

-webSiteName

Optional. The Web site name to which the Web module tries to bind. The siteName is the same as the Web site XML configuration file name. For example, default-web-site.

Web modules are bound to the default Web site (default-web-site) on the target OC4J instances if this parameter is not specified.

-shared

Optional. The application is allowed to be shared between HTTP/HTTPS. The default value is false.

-loadOnStartup

Optional. The application is allowed to be loaded on startup. The default value is true.

-accessLog

Optional. The application is allowed to enable access logging. The default value is true.


Binding a Specific Web Module to a Web Site and Setting the Context Root

Use the -bindWebApp command to bind a specific Web module within a J2EE application to a Web site you specify or to the default Web site. You can also set the context root that will be used to access the Web module.

The syntax of this command follows:

java -jar admin_client.jar uri adminId adminPassword -bindWebApp
-appName appName -webModuleName moduleName -webSiteName siteName
-contextRoot contextRoot -shared true/false -loadOnStartup true/false -accessLog
true/false

Table 11-11 -bindWebApp Command Parameters

Parameter Description

-appName

Required. The name of the parent application as specified at deployment time.

-webModuleName

Required. The name of the Web module to be bound. This should be the name of the WAR file contained within the EAR file, without the .war extension.

-webSiteName

Optional. The Web site name to which the Web module tries to bind. The siteName is the same as the Web site XML configuration file name. For example, default-web-site.

Web modules are bound to the default Web site (default-web-site) on the target OC4J instances if this parameter is not specified.

-contextRoot

Optional. 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/petstore.

If a context root is not supplied, the context root specified in the parent application's application.xml deployment descriptor will be used.

-shared

Optional. The application is allowed to be shared between HTTP/HTTPS. The default value is false.

-loadOnStartup

Optional. The application is allowed to be loaded on startup. The default value is true.

-accessLog

Optional. The application is allowed to enable access logging. The default value is true.


Unbinding Web Modules from a Web Site

Web Modules can be unbound from a Web site after deployment. You can unbind all Web Modules from a Web site or you can unbind a specific Web module from a Web site.

Unbinding All Web Modules

Use the -unbindAllWebApps command to remove all Web module bindings from a Web site in an OC4J instance or in a group of OC4J instances that are part of a cluster.

The syntax of this command follows:

java -jar admin_client.jar uri adminId adminPassword -unbindAllWebApps 
-appName appname  [-webSiteName web-site-name]

The following example unbinds all Web modules belonging to the hello application from all Web sites named default-web-site in a cluster that consists of multiple OC4J instances that are listening on the OPMN request port 6003:

java -jar admin_client.jar deployer:cluster:opmn://localhost:6003/default_group 
oc4jadmin welcome1 -unbindAllWebApps -appName hello -webSiteName default-web-site

Table 11-12 -unbindAllWebApps Command Parameters

Parameter Description

-appName

Required. The name of the parent application as specified at deployment time.

-webSiteName

Optional. The Web site name from which the Web module tries to unbind. The web-site-name is the same as the Web site XML configuration file name. For example, default-web-site.

Web modules are unbound from the default Web site (default-web-site) on the target OC4J instances if this parameter is not specified.


Unbinding a Specific Web Module

Use the -unbindWebApp command to remove a specific Web module binding from a specific Web site in an OC4J instance or in a group of OC4J instances that are part of a cluster.

The syntax of this command follows:

java -jar admin_client.jar uri adminId adminPassword -unbindWebApp 
-appName appname  -webModuleName web-module-name [-webSiteName web-site-name]

The following example unbinds the Web module hello-web for the hello application from the Web site default-web-site on an OC4J standalone instance:

java -jar admin_client.jar deployer:oc4j:localhost:23971 oc4jadmin welcome1 
-unbindWebApp -appName hello -webModuleName hello-web

Table 11-13 -unbindWebApp Command Parameters

Parameter Description

-appName

Required. The name of the parent application as specified at deployment time.

-webModuleName

Required. The name of the Web module to be unbound. This should be the name of the WAR file contained within the EAR file, without the .war extension.

-webSiteName

Optional. The Web site name from which the Web module tries to unbind. The web-site-name is the same as the Web site XML configuration file name. For example, default-web-site.

The Web module is unbound from the default Web site (default-web-site) on the target OC4J instances if this parameter is not specified.


Listing Web Bindings

Use the -listWebBindings command to display the Web site bindings for each Web module in an OC4J instance or in a group of OC4J instances that are part of a cluster. The following information is listed by default: application name, module name, context root, and Web site name. For more detailed information, use the -verbose option, which is described below.

The syntax of this command follows:

java -jar admin_client.jar uri adminId adminPassword -listWebBindings [webSiteName web-site-name][-verbose]

The following example displays detailed information for the Web modules bound to all Web sites named, default-web-site, in a cluster that consists of multiple OC4J instances that are listening on the OPMN request port 6003:

java -jar admin_client.jar deployer:cluster:opmn://localhost:6003/default_group
 oc4jadmin welcome1 -listWebBindings -webSiteName default-web-site -verbose

Table 11-14 -listWebBindings Command Parameters

Parameter Description

-webSiteName

Optional. The Web site name for which to view all Web bindings. The web-site-name is the same as the Web site XML configuration file name. For example, default-web-site. All Web bindings for all Web sites are displayed if no Web site is specified.

-verbose

Optional. Displays more details. The additional details include: pre-load, shared, access log, and maximum inactivity time.


Redeploying an Archive

Use the -redeploy command to redeploy a previously deployed archive.

This operation performs a graceful redeployment because it stops the application if it is running and then undeploys the archive. It then deploys and restarts the application. Redeploying an archive with the -deploy command, in contrast, does not stop the application but simply undeploys, redeploys, and then restarts it.

The syntax of this command follows:

java -jar admin_client.jar uri adminId adminPassword -redeploy -file path/filename 
-deploymentName appName [-bindAllWebApps] [-isConnector] [-keepSettings] 
[-sequential [waitsec]] [-removeArchive]

Table 11-15 -redeploy Command Parameters

Parameter Description

-file

Required. The path and file name of an EAR, WAR, or RAR file to redeploy.

-deploymentName

Required. The user-defined application deployment name, used to identify the application within OC4J. This value must match the name of the existing application on the server.

-isConnector

Required for redeploying a standalone RAR.

-bindAllWebApps

Optional. Binds all Web modules in an EAR to the specified Web site or, if none is specified, to the default Web site.

You can supply a value for webSiteName, which is the name portion of the name_web-site.xml file that contains the Web site configuration.

Alternatively, you can bind all Web modules to a Web site later, as described in "Binding Web Modules to a Web Site After Deployment".

-keepSettings

Optional. If this parameter is specified, the redeployed application will fetch and use the deployment plan from the previous deployment. Values set in deployment descriptors packaged within the archive will be ignored.

If this parameter is not specified, values will be set to those in the deployment descriptors packaged with the archive.

-sequential [waitsec]

Optional. Specify to redeploy the archive to each OC4J instance in a group in sequence. The redeployment to each target OC4J instance must complete before redeployment begins on the next target instance. Requests will not be routed to an OC4J instance while the archive is being redeployed to it.

You can use the waitsec option to specify a number of seconds to wait between deployments, as follows:

-sequential 15

If this parameter is not specified, the archive will be simultaneously deployed to all OC4J instances in the group by default.

This option is valid only in a clustered environment. It is not valid for standalone OC4J.

-removeArchive

Optional. Specify to delete the EAR, WAR, or RAR file from the server's file system after deployment.

-failureRecovery

Optional. Enable recovery from a failed redeployment. The previous archive is redeployed if possible.


Specifying a Delay Between Sequential Redeployments in a Cluster

When an application is redeployed to a group with the -sequential parameter of the admin_client.jar -redeploy command, the redeployment operation is serialized, with redeployment done to one OC4J instance at a time so that the target application is never entirely in a stopped state. In a sequential redeployment, the deployment manager immediately commences redeployment on the next OC4J instance that is running a member of an application cluster as soon as the redeployment operation completes on the current OC4J instance. The result is that the system might not be able to stabilize itself so that the new application instance is fully active before the next redeployment commences, which introduces these possible side effects:

  • The application can become inaccessible while it is stopped on one OC4J instance and before mod_oc4j is notified that the application is available on another instance.

  • Session replication activities might not have had an opportunity to execute.

In some circumstances, the session state of an application might be lost when you redeploy an application to a cluster with the admin_client.jar -redeploy command, even if you specify the -sequential and -keepsettings parameters.

In OC4J 10g (10.1.3.5.0), you can use the waitsec option of the -sequential parameter to specify a number of seconds between redeployments to different OC4J instances that are running an application cluster. This delay can provide enough time for replication of session state.

If you specify the optional waitsec value, the deployment manager waits the specified number of seconds between redeployment operations on OC4J instances within a group. This delay enables the system to stabilize as redeployment operations occur across the group, reducing the opportunities for applications to be inaccessible or session state to be lost.

For example, the following admin_client.jar -redeploy command specifies a delay of 15 seconds between redeployments to different OC4J instances:

java -jar admin_client.jar deployer:cluster:opmn://host:port/home oc4jadmin
password -redeploy -file "myapp.ear" -deploymentName rolling -sequential 15
-keepsettings

The new waitsec option also applies to the -sequential parameter of the admin_client.jar -deploy command.

Redeploying an Application with Scheduled Jobs

If you redeploy an application that has scheduled jobs, the jobs will not run as scheduled unless you remove all the jobs before the redeployment and resubmit them after it.

To redeploy an application with scheduled jobs:

  1. Remove all scheduled jobs.

  2. Redeploy the application.

  3. Resubmit all the jobs.

Undeploying an Archive

The -undeploy command removes an application, standalone Web, standalone EJB, or standalone connector module from the target OC4J instances, as the following topics describe:

Undeploying an EAR, Standalone WAR, and Standalone EJB JAR

Undeploying an EAR, standalone Web module, or standalone EJB JAR removes it from the OC4J runtime. Existing Web site bindings are also deleted.

The syntax for undeploying an EAR, standalone WAR, or standalone EJB JAR follows. The name of the application or module must be supplied.

java -jar admin_client.jar uri adminId adminPassword -undeploy appName

Undeploying a Standalone RAR

The syntax for undeploying a standalone RAR follows. The -isConnector parameter must be included along with name of the connector.

java -jar admin_client.jar uri adminId adminPassword -undeploy connectorName 
-isConnector

Undeploying a standalone RAR does not require a restart of the default application.

Updating Modified Classes in a Deployed EJB Module

The -updateEJBModule command performs incremental or partial redeployment of EJB modules within an application running in an OC4J instance or in a group of OC4J instances. This feature makes it possible to redeploy only those beans within an EJB JAR that have changed.


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".

The syntax for updating modified classes in a deployed EJB module follows. The name of the application the EJB JAR is part of must be supplied. If updating a standalone EJB module, specify the default application.

java -jar admin_client.jar uri adminId adminPassword -updateEJBModule
-appName appName -ejbModuleName ejbJarName -file path/ejbJarName

For example:

java -jar admin_client.jar deployer:cluster:opmn://node1.company.com/default_group 
oc4jadmin password -updateEJBModule -appName petstore 
-ejbModuleName customerEjb.jar -file build/customerEjb.jar

Table 11-16 -updateEJBModule Syntax

Option Description

-appName

Required. The name of the application that the EJB module is part of. If you are updating a standalone EJB module, specify the default application.

-ejbModuleName

Required. The name of the EJB JAR file to be updated, as defined in application.xml.

-file

Required. The path and file name of the updated EJB JAR.


Creating and Managing Shared Libraries

You can use the admin_client.jar utility to create and manage shared libraries in an OC4J instance or in a group of OC4J instances, as the following topics describe:

Installing a Shared Library

You can use the -publishSharedLibrary command to create the shared library directory structure and install the binaries that compose the library within it in a specific OC4J instance or in a group of OC4J instances. The shared library will be created in the ORACLE_HOME/j2ee/instance/shared-lib directory of each OC4J instance.

The command will also declare the shared library within a <shared-library> element in the server.xml file on each OC4J instance, making it available to applications.

The syntax for installing a shared library follows. The path and file names for multiple code sources, binaries that will compose the shared library, can be specified, each separated from the next by a space.

java -jar admin_client.jar uri adminId adminPassword -publishSharedLibrary
-name libName -version libVersion [-parentName parentLibName] 
[-parentVersion parentLibVersion] [-installCodeSources path [path ...]]
[-addCodeSources path [path ...]] [-imports sharedLibName
[:min-version][,max-version] [sharedLibName ...]]

The following command deploys the acme.common:2.5 shared library to a group of OC4J instances (all the members of default_group) within a cluster.

java -jar admin_client.jar deployer:cluster:opmn://server.company.com:6004/default_group
oc4jadmin password -publishSharedLibrary -name acme.common -version 2.5 
-installCodeSources /myserver/tmp/acme-apis.jar /myserver/tmp/acmeImpl.jar

The resulting directory structure within a target OC4J server would be as follows:

ORACLE_HOME/j2ee/home/shared-lib
  /acme.common
    /2.5
      acme-apis.jar
      acmeImpl.jar

Table 11-17 -publishSharedLibrary Command Parameters

Parameter Description

-name

Required. The name of the shared library.

Where common APIs are implemented by multiple vendors, the name should include both the vendor name and the name of the technology; for example, oracle.jdbc or xerces.xml.

-version

Required. The version number of the shared library. This value should ideally reflect the code implementation version.

-parentName

Optional. The name of the parent shared library, if applicable.

-parentVersion

Optional. The version number of the parent shared library, if applicable.

-installCodeSources

The path and file names for one or more JAR or ZIP files to be uploaded to the OC4J instance or instances and installed as part of the shared library. Separate each path/file name string from the next with a space.

-addCodeSources

Optional. The path and file names for JAR or ZIP files that have already been uploaded to the OC4J instance or instances to add to the shared library. Separate each path/file name string from the next with a space.

-imports

Optional. The name of one or more existing shared libraries to import into this shared library. Separate each name string from the next with a space.

You can specify the maximum or minimum version, or both, of the library to import.


Modifying an Existing Shared Library

You can use the -modifySharedLibrary command to modify the contents of an existing shared library. The command will also update the shared library definition within the server.xml file on each OC4J instance.

The syntax for modifying an existing shared library follows. The path and file names for multiple code sources, binaries that will compose the shared library, can be specified, each separated from the next by a space.

java -jar admin_client.jar uri adminId adminPassword -modifySharedLibrary
-name libName -version libVersion [-installCodeSources path [path ...]]
[-addCodeSources path [path ...]] [-removeCodeSources path [path ...]]
[-addImports sharedLibName[:min-version][,max-version] [sharedLibName ...]] 
[-removeImports sharedLibName[:min-version][,max-version] [sharedLibName ...]]

The following command updates the acme.common:2.5 shared library.

java -jar admin_client.jar
deployer:cluster:opmn://server.company.com:6004/default_group
oc4jadmin password -modifySharedLibrary -name acme.common -version 2.5 
-addCodeSources /myserver/tmp/acme-helpers.jar

Table 11-18 -modifySharedLibrary Command Parameters

Parameter Description

-name

Required. The name of the shared library to update.

-version

Required. The version number of the shared library to update.

-installCodeSources

Optional. The path and file name to a JAR or ZIP file to be uploaded to the OC4J instance or instances and installed as part of the shared library. Separate each path/file name string from the next with a space.

-addCodeSources

Optional. The path and file name for one or more JAR or ZIP files that have already been uploaded to the OC4J instance or instances to add to the shared library. Separate each path/file name string from the next with a space.

-removeCodeSources

Optional. The path and file name for one or more JAR or ZIP files to remove from the shared library. Separate each path/file name string from the next with a space.

-addImports

Optional. The name of one or more existing shared libraries to import into this shared library. Separate each name string from the next with a space.

You can specify the maximum or minimum version, or both, of the library to import.

-removeImports

Optional. The name of one or more existing shared libraries to remove from this shared library.

You can specify the maximum or minimum version, or both, of the library to remove.


Viewing the Contents of a Shared Library

Use the -describeSharedLibrary command to view the code sources and imported shared libraries that compose the specified shared library. The syntax follows:

java -jar admin_client.jar uri adminId adminPassword -describeSharedLibrary
-name libName -version libVersion

Table 11-19 -describeSharedLibrary Command Parameters

Parameter Description

-name

Required. The name of the shared library.

-version

Required. The version number of the shared library.


Listing All Shared Libraries

Use the -listSharedLibraries command to output a list of all shared libraries defined in the target OC4J instance or instances. The syntax follows:

java -jar admin_client.jar uri adminId adminPassword -listSharedLibraries

Note:

If you are using JDK1.4, Oracle Application Server 10g Release 3 (10.1.3.5.0) does not support using the Xalan library shipped with the JDK as a shared library. To use the Xalan library, you have two alternatives:
  • Use JDK 5.0 (JDK 1.5) or JDK 6, in which the embedded Xalan library is supported as a shared library.

  • With JDK1.4, use a standalone distribution of the Xalan library instead of the embedded version.


Removing a Shared Library

Use the -removeSharedLibrary command to remove a shared library from the target OC4J instance or instances. The syntax follows:

java -jar admin_client.jar uri adminId adminPassword -removeSharedLibrary
-name libName -version libVersion

Table 11-20 -removeSharedLibrary Command Parameters

Parameter Description

-name

Required. The name of the shared library to remove.

-version

Required. The version number of the shared library to remove.


Importing an Existing Shared Library

Use the -addImportSharedLibrary command to import an existing shared library to an application's classloader. The command is equivalent to adding an <import-shared-library> element to an application's orion-application.xml descriptor. This command requires an application restart for the change to take effect. Refer to "Installing a Shared Library" for instructions on installing a shared library. The syntax follows:

java -jar admin_client.jar uri adminId adminPassword -addImportSharedLibrary
-appName application -name name -minVer MinVersion -maxVer MaxVersion

The following example imports the oracle.jdbc shared library to an application named Myapp:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 
-addImportSharedLibrary -appName Myapp -name oracle.jdbc

Table 11-21 -addImportSharedLibrary Command Parameters

Parameter Description

-appName

Required. The name of the application, as defined at deployment time, to which the shared library is imported.

-name

Required. The name of an existing shared library to add to the given application.

-minVer

Optional. The minimum version number of the library required by an application.

-maxVer

Optional. The maximum version number of the library required by an application.


Deleting an Imported Shared Library

Use the -deleteImportSharedLibrary command to delete a shared library from an application's classloader. The command is equivalent to deleting an <import-shared-library> element from an application's orion-application.xml descriptor. This command requires an application restart for the change to take effect. The syntax follows:

java -jar admin_client.jar uri adminId adminPassword -deleteImportSharedLibrary
-appName application -name name

The following example deletes the oracle.jdbc shared library from the application named Myapp:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 
-deleteImportSharedLibrary -appName Myapp -name oracle.jdbc

Table 11-22 -deleteImportSharedLibrary Command Parameters

Parameter Description

-appName

Required. The name of the application, as defined at deployment time, from which the shared library is deleted.

-name

Required. The name of the shared library to remove from the given application.


Stopping a Shared Library from being Inherited

Use the -addRemoveInheritedSharedLibrary command to stop a shared library from being inherited by an application's classloader. The command is equivalent to adding a <remove-inherited> element to an application's orion-application.xml descriptor. This command requires an application restart for the change to take effect. The syntax follows:

java -jar admin_client.jar uri adminId adminPassword -addRemoveInheritedSharedLibrary -appName application -name name

The following example stops the oracle.jdbc shared library from being inherited by the application named Myapp:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1
-addRemoveInheritedSharedLibrary -appName Myapp -name oracle.jdbc

Table 11-23 -addRemoveInheritedSharedLibrary Command Parameters

Parameter Description

-appName

Required. The name of the application, as defined at deployment time, that will not inherit the shared library.

-name

Required. The name of the shared library to stop from being inherited.


Allowing a Shared Library to be Inherited

Use the -deleteRemoveInheritedSharedLibrary command to allow a shared library to be inherited by an application's classloader. The command is equivalent to deleting a <remove-inherited> element from an application's orion-application.xml descriptor. This command requires an application restart for the change to take effect. The syntax follows:

java -jar admin_client.jar uri adminId adminPassword -deleteRemoveInheritedSharedLibrary -appName application -name name

The following example allows the oracle.jdbc shared library to be inherited by the application named Myapp:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1
-deleteRemoveInheritedSharedLibrary -appName Myapp -name oracle.jdbc

Table 11-24 -deleteRemoveInheritedSharedLibrary Command Parameters

Parameter Description

-appName

Required. The name of the application, as defined at deployment time, that will inherit the shared library.

-name

Required. The name of the shared library to be inherited.


Managing Application Lifecycle

You can use the admin_client.jar utility to start, restart, or stop an application and its child applications in a specific OC4J instance or in a group of OC4J instances. You can also list the status of deployed applications in a specific OC4J instance or in a group of OC4J instances. The following topics are included in this section:

Starting Applications

Use the -start command to start an application and its child applications on target OC4J instances. Applications are automatically redeployed at startup if a file within the application has been modified.

The syntax of this command follows:

java -jar admin_client.jar uri adminId adminPassword -start appName

The -start command requires the application name as specified at deployment time. The following example starts the ascontrol application on node2 within a cluster:

java -jar admin_client.jar deployer:oc4j:opmn://node2.company.com:6004/home 
oc4jadmin password -start ascontrol

Stopping Applications

Use the -stop command to stop an application and its child applications on target OC4J instances. By default, applications are stopped immediately. Any requests that are currently being processed are lost. For planned shutdown scenarios, an application can have a specified amount of time to complete request processing before the application is stopped.

The syntax of this command follows:

java -jar admin_client.jar uri adminId adminPassword -stop appName [-timeout
timeInSeconds] [-graceful true|false]

The -stop command requires the application name as specified at deployment time. The following example stops the ascontrol application on node2 within a cluster. The application is allowed 5 seconds to complete requests before the application is forcefully stopped.

java -jar admin_client.jar deployer:oc4j:opmn://node2.company.com:6004/home 
oc4jadmin password -stop ascontrol -timeout 5

Table 11-25 -stop Command Parameters

Parameter Description

-timeout

Optional. The amount of time to wait for the application to stop gracefully. The application is stopped forcefully after the timeout is reached. The default timeout is 0 if no timeout is specified.

-graceful

Optional. The graceful option specifies the method used to stop the application. The value true implies that the application server waits for the in-flight requests to complete before stopping the application. The value false implies that in-flight requests terminate and the application is stopped immediately (forcefully). The default setting is true.

The -graceful parameter takes precedence over the -timeout parameter if the value is set to false.


Restarting Applications

Use the -restartApp command to stop and then start an application and its child applications on target OC4J instances. Applications are automatically redeployed at startup if a file within the application has been modified. By default, applications are stopped immediately. Any requests that are currently being processed are lost. For planned shutdown scenarios, an application can have a specified amount of time to complete request processing before the application is stopped.

The syntax of this command follows:

java -jar admin_client.jar uri adminId adminPassword -restartApp appName [-timeout
timeInSeconds] [-graceful true|false]

The -restartApp command requires the application name as specified at deployment time. The following example restarts the ascontrol application on node2 within a cluster. The application is allowed 5 seconds to complete requests before the application is forcefully stopped and then started.

java -jar admin_client.jar deployer:oc4j:opmn://node2.company.com:6004/home 
oc4jadmin password -restartApp ascontrol -timeout 5

Table 11-26 -restartApp Command Parameters

Parameter Description

-timeout

Optional. The amount of time to wait for the application to stop gracefully. The application is stopped forcefully after the timeout is reached. The default timeout is 0 if no timeout is specified.

-graceful

Optional. The graceful option specifies the method used to stop the application. The value true implies that the application server waits for the in-flight requests to complete before stopping the application. The value false implies that in-flight requests terminate and the application is stopped immediately (forcefully). The default setting is true.

The -graceful parameter takes precedence over the -timeout parameter if the value is set to false.


Listing Applications

Use the -listApplications command to display the status of applications that are currently deployed in an OC4J instance or in a group of OC4J instances that are part of a cluster. The following status information is listed by default: application name, contained modules, application type, application state, and parent application. For more detailed information, use the -verbose option, which is described below.

The syntax of this command follows:

java -jar admin_client.jar uri adminId adminPassword -listApplications [-verbose]

The following example displays detailed information for the deployed applications on a cluster that consists of multiple OC4J instances that are listening on the OPMN request port 6003:

java -jar admin_client.jar deployer:cluster:opmn://localhost:6003/default_group
 oc4jadmin welcome1 -listApplications -verbose

Table 11-27 -listApplications Command Parameters

Parameter Description

-verbose

Optional. Displays more details. The additional details include: application context root binding, routing enabled, group name, and state replication.


Restarting and Stopping OC4J Instances

You can use the admin_client.jar utility to stop a standalone OC4J server, a specific OC4J instance in a managed environment, or a group of OC4J instances. The -shutdown command shuts down the specified OC4J instance or instances and for any OPMN-managed instance, notifies OPMN that it is being shut down. The -restart command restarts the specified instance or instances.

The following topics provide the syntax and examples for these commands:

Restarting an OC4J Instance or Group of Instances

Use the admin_client.jar -restart command, as follows, to restart an OC4J instance or group of OC4J instances:

java -jar admin_client.jar uri adminId adminPassword -restart

For example, the following command restarts a standalone OC4J server:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin password -restart

The following command restarts all of the OC4J instances that are members of default_group in each Oracle Application Server within the cluster topology:

java -jar admin_client.jar deployer:cluster:opmn://node1.company.com/default_group oc4jadmin password -restart

Stopping an OC4J Instance or Instances

Use the admin_client.jar -shutdown command, as follows, to stop an OC4J instance or group of OC4J instances:

java -jar admin_client.jar uri adminId adminPassword -shutdown

For example, the following command stops a standalone OC4J server:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin password -shutdown

This command shuts down the entire OC4J server, terminating all threads immediately, as if the host machine were unplugged. If you use this command, the current state for clustered applications will not be replicated.

The following command stops the specified OC4J instance in an OPMN-managed Oracle Application Server environment:

java -jar admin_client.jar deployer:oc4j:opmn://localhost/home oc4jadmin password -shutdown

The next command stops all of the OC4J instances that are members of default_group in each Oracle Application Server within the cluster topology:

java -jar admin_client.jar deployer:cluster:opmn://node1.company.com/default_group oc4jadmin password -shutdown

These commands shut down the specified instance or instances and terminate all threads immediately. If you use the -shutdown command, the current state for clustered applications will not be replicated. For each OPMN-managed OC4J instance, admin_client.jar notifies OPMN that the server is being shut down on purpose, to prevent OPMN from attempting to restart it.

Managing Data Sources

You can use the admin_client.jar utility to manage data sources in an OC4J instance or in a group of OC4J instances, as the following topics describe:

Adding, Testing, Listing and Removing Data Source Connection Pools

You can use the admin_client.jar utility to add, test, list, and remove data source connection pools in an OC4J instance or in a group of OC4J instances, as the following topics describe:

Adding a Data Source Connection Pool

Use the -addDataSourceConnectionPool command to add a data source connection pool for an application in an OC4J instance or in each OC4J instance of a group within a cluster.

The syntax for adding a data source connection pool follows:

java -jar admin_client.jar uri adminId adminPassword -addDataSourceConnectionPool
-applicationName applicationName -name name -factoryClass factoryClass
-dbUser dbUser -dbPassword dbPassword -url url
[-factoryProperties name1 value1 [name2 value2 [...]]]

For example:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 
-addDataSourceConnectionPool -applicationName default -name ScottConnectionPool 
-factoryClass oracle.jdbc.pool.OracleDataSource 
-dbUser scott -dbPassword tiger -url jdbc:oracle:thin:@localhost:1521:xe

Table 11-28 -addDataSourceConnectionPool Command Parameters

Parameter Description

-applicationName

Required. The name of the application for which to add the data source connection pool.

-name

Required. The name of the connection pool.

-factoryClass

Required. The fully qualified path of the connection factory implementation.

-dbUser

Required. The default user name to use to get connections.

-dbPassword

Required. The default password to use to get connections.

-url

Required. The connection factory URL to use to get connections.

-factoryProperties

Optional. One or more property name and value pairs to set on the connection factory definition.


Testing a Data Source Connection Pool

Use the -testDataSourceConnectionPool command to test an application's connection to a data source connection pool in an OC4J instance or in each OC4J instance of a group within a cluster.

The syntax for testing a connection to a data source connection pool follows:

java -jar admin_client.jar uri adminId adminPassword -testDataSourceConnectionPool
-name name -sqlStatement sqlStatement [-applicationName applicationName] 
[-dbUser dbUser] [-dbPassword dbPassword] 

For example:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1
-testDataSourceConnectionPool -sqlStatement "select * from dual" 
-applicationName default -name ScottConnectionPool

Table 11-29 -testDataSourceConnectionPool Command Parameters

Parameter Description

-name

Required. The name of the connection pool.

-sqlStatement

Required. The SQL statement to use to test the connection

-applicationName

Optional. The name of the application for which to test the data source connection pool.

-dbUser

Optional. The default user name to use to get connections.

-dbPassword

Optional. The default password to use to get connections.


Listing Data Source Connection Pools

Use the -listDataSourceConnectionPools command to view a list of data source connection pools that are configured for an application. The list includes each connection pool's configured properties.

The syntax for listing data source connection pools follows:

java -jar admin_client.jar uri adminId adminPassword
 -listDataSourceConnectionPools [-applicationName applicationName]

For example:

java -jar admin_client.jar deployer:oc4j:localhost:23791
 oc4jadmin oc4j -listDataSourceConnectionPools -applicationName default

Table 11-30 -listDataSourceConnectionPools Command Parameters

Parameters Description

-applicationName

Optional. The name of the application for which to list configured data source connection pools. The default application's connection pools are listed if no application name is specified.


Removing a Data Source Connection Pool

Use the -removeDataSourceConnectionPool command to remove a data source connection pool from an application in an OC4J instance or in each OC4J instance of a group within a cluster. The syntax for removing a data source connection pool follows:

java -jar admin_client.jar uri adminId adminPassword 
-removeDataSourceConnectionPool -name name [-applicationName applicationName]

For example:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 
-removeDataSourceConnectionPool -name ScottConnectionPool -applicationName default 

Table 11-31 -removeDataSourceConnectionPool Command Parameters

Parameter Description

-name

Required. The name of the connection pool.

-applicationName

Optional. The name of the application from which to remove the data source connection pool.


Adding, Testing, Listing, and Removing Data Sources

You can use the admin_client.jar utility to add, test, list, and remove data sources in an OC4J instance or in a group of OC4J instances, as the following topics describe:

Adding a Managed Data Source

Use the -addManagedDataSource command to add a managed data source for an application in an OC4J instance or in each OC4J instance of a group within a cluster. The syntax for adding a managed data source follows:

java -jar admin_client.jar uri adminId adminPassword -addManagedDataSource
-applicationName applicationName -name name 
-jndiLocation jndiLocation -connectionPoolName connectionPoolName 
[-dbUser dbUser] [-dbPassword dbPassword] [-loginTimeout loginTimeout] 
[-txLevel txLevel] [-dbSchema dbSchema] [-manageLocalTransactions true|false] 

For example:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 
-addManagedDataSource -applicationName default -name ScottDataSource 
-jndiLocation jdbc/ScottDataSource -connectionPoolName ScottConnectionPool

Table 11-32 -addManagedDataSource Command Parameters

Parameter Description

-applicationName

Required. The name of the application for which to add the data source.

-name

Required. The name of the data source.

-jndiLocation

Required. The location to use to bind the new data source into JNDI.

-connectionPoolName

Required. The name of the connection pool with which the data source interacts.

-dbUser

Optional. The default user for the new data source.

-dbPassword

Optional. The default password for the new data source.

-loginTimeout

Optional. The login timeout for the new data source.

-txLevel

Optional. The transaction level (local or global).

-dbSchema

Optional. The database schema to use if the EJB CMP implementation being used is Orion CMP. (TopLink CMP is the default.)

-manageLocalTransactions

Optional. Indicates whether or not OC4J should manage local transactions. The default value is true.


Removing a Managed Data Source

Use the -removeManagedDataSource command to remove a managed data source from an application in an OC4J instance or in each OC4J instance of a group within a cluster. The syntax for removing a managed data source follows:

java -jar admin_client.jar uri adminId adminPassword -removeManagedDataSource
-name name [-applicationName applicationName] 

For example:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 
-removeManagedDataSource -name ScottDataSource -applicationName default 

Table 11-33 -removeManagedDataSource Command Parameters

Parameter Description

-name

Required. The name of the data source to remove.

-applicationName

Optional. The name of the application from which to remove the data source.


Adding a Native Data Source

Use the -addNativeDataSource command to add a native data source for an application in an OC4J instance or in each OC4J instance of a group within a cluster. The syntax for adding a native data source follows:

java -jar admin_client.jar uri adminId adminPassword -addNativeDataSource 
-name name -dbUser dbUser -dbPassword dbPassword 
-jndiLocation jndiLocation -loginTimeout loginTimeout 
-dataSourceClass dataSourceClass -url url [-applicationName applicationName] [-properties name1 value1 [name2 value2 ][...]]

For example:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 
-addNativeDataSource -name ScottDataSource 
-dbUser scott -dbPassword tiger -jndiLocation jdbc/ScottNativeDataSource
-loginTimeout 5 -dataSourceClass com.acme.DataSourceImpl
-url jdbc:oracle:thin:@localhost:1521:xe

Table 11-34 -addNativeDataSource Command Parameters

Parameter Description

-name

Required. The name of the new data source.

-dbUser

Required. The default user for the new data source.

-dbPassword

Required. The default password for the new data source.

-jndiLocation

Required. The location to use to bind the new data source into JNDI.

-loginTimeout

Required. The login timeout for the new data source.

-dataSourceClass

Required. The fully qualified class of the new data source.

-url

Required. The url used by the new data source to connect to the database.

-applicationName

Optional. The name of the application for which to add the data source.

-properties

Optional. The property or properties for the new data source.


Removing a Native Data Source

Use the -removeNativeDataSource command to remove a native data source from an application in an OC4J instance or in each OC4J instance of a group within a cluster. The syntax for removing a native data source follows:

java -jar admin_client.jar uri adminId adminPassword -removeNativeDataSource 
-name name [-applicationName applicationName]

For example:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 
-removeNativeDataSource -name ScottDataSource 

Table 11-35 -removeNativeDataSource Command Parameters

Parameter Description

-name

Required. The name of the data source to remove.

-applicationName

Optional. The name of the application from which to remove the data source.


Testing a Database Connection

Use the -testDatabaseConnection command to test an application's connection to a database in an OC4J instance or in each OC4J instance of a group within a cluster.

The syntax for testing a database connection follows:

java -jar admin_client.jar uri adminId adminPassword -testDatabaseConnection
-sqlStatement sqlStatement -factoryClass factoryClass -dbUser dbUser 
-dbPassword dbPassword -url url [-applicationName applicationName] 

For example:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1
-testDatabaseConnection -sqlStatement "select * from dual"
-factoryClass oracle.jdbc.pool.OracleDataSource -dbUser scott
-dbPassword tiger -url jdbc:oracle:thin:@localhost:1521:xe -applicationName default 

Table 11-36 -testDatabaseConnection Command Parameters

Parameter Description

-sqlStatement

Required. The SQL statement to use to test the connection.

-factoryClass

Required. The JDBC factory to test (instance of Driver, DataSource, ConnectionPoolDataSource, or XADataSource).

-dbUser

Required. The user name to use to test the connection.

-dbPassword

Required. The password to use to test the connection.

-url

Required. The URL to set on the JDBC factory.

-applicationName

Optional. The name of the application.


Testing a Data Source

Use the -testDataSource command to test an application's connection to a data source in an OC4J instance or in each OC4J instance of a group within a cluster.

The syntax for testing a data source follows:

java -jar admin_client.jar uri adminId adminPassword -testDataSource
-name name -sqlStatement sqlStatement [-applicationName applicationName] 
[-dbUser dbUser] [-dbPassword dbPassword]

For example:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1
-testDataSource -name ScottDataSource -sqlStatement "select * from dual"
-applicationName default -dbUser scott -dbPassword tiger 

Table 11-37 -testDataSource Command Parameters

Parameter Description

-name

Required. The data source to test.

-sqlStatement

Required. The SQL statement to use to test the connection,

-applicationName

Optional. The name of the application.

-dbUser

Optional. The user name to use to test the connection.

-dbPassword

Optional. The password to use to test the connection.


Listing Data Sources

Use the -listDataSources command to view a list of data sources that are configured for an application. The list includes each data source's configured properties.

The syntax for listing data sources follows:

java -jar admin_client.jar uri adminId adminPassword
 -listDataSources [-applicationName applicationName]

For example:

java -jar admin_client.jar deployer:oc4j:localhost:23791
 oc4jadmin oc4j -listDataSources -applicationName default

Table 11-38 -listDataSources Command Parameters

Parameter Description

-applicationName

Optional. The name of the application for which to list configured data sources. The default application's data sources are listed if no application name is specified.


Getting the Data Sources Descriptor for an Application

Use the -getDataSourcesDescriptor command to retrieve an application's data sources descriptor. The syntax for getting a data sources descriptor follows:

java -jar admin_client.jar uri adminId adminPassword -getDataSourcesDescriptor
[-applicationName applicationName]  

Table 11-39 -getDataSourcesDescriptor Command Parameter

Parameter Description

-applicationName

Optional. The name of the application to which the data sources descriptor belongs.


Managing JMS Resources

You can use the admin_client.jar utility to manage JMS resources in an OC4J instance or in a group of OC4J instances, as the following topics describe:

Managing JMS Connection Factories

You can use the admin_client.jar utility to manage the OC4J JMS connection factories, as the following topics describe:

Adding a JMS Connection Factory

Use the -addJMSConnectionFactory command to add a JMS connection factory to an OC4J instance or to each instance of a group within a cluster. The syntax for this command follows:

java -jar admin_client.jar uri adminId adminPassword -addJMSConnectionFactory
-domain domain -jndiLocation jndiLocation [-host host] [-port port]
[-username username] [-password password] [-clientID clientID] [-isXA true|false]

For example:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 
-addJMSConnectionFactory -domain Queue -jndiLocation jms/ExampleQueueCF

Table 11-40 -addJMSConnectionFactory Command Parameters

Parameter Description

-domain

Required. The JMS domain of this connection factory (`QUEUE', `TOPIC', or `UNIFIED').

-jndiLocation

Required. The JNDI location to which this connection factory will be bound.

-host

Optional. The host name associated with this connection factory (defaults to the containing OC4J JMS server host).

-port

Optional. The port number associated with this connection factory (defaults to the containing OC4J JMS server port).

-username

Optional. The user name associated with this connection factory (defaults to anonymous).

-password

Optional. The password associated with this connection factory (defaults to null).

-clientID

Optional. The JMS client ID associated with this connection factory (defaults to null).

-isXA

Optional. Whether or not this is an XA connection factory (defaults to false).


Removing a JMS Connection Factory

Use the -removeJMSConnectionFactory command to remove a JMS connection factory from an OC4J instance or instances. The syntax for this command follows:

java -jar admin_client.jar uri adminId adminPassword -removeJMSConnectionFactory
-jndiLocation jndiLocation

For example:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 
-removeJMSConnectionFactory -jndiLocation jms/ExampleQueueCF

Table 11-41 -removeJMSConnectionFactory Command Parameter

Parameter Description

-jndiLocation

Required. The JNDI location of the connection factory to remove.


Getting Information About JMS Connection Factories

Use the -getJMSConnectionFactories command to return the attributes for each of the JMS connection factories in an OC4J instance or in a group of OC4J instances within a cluster. The syntax for this command follows:

java -jar admin_client.jar uri adminId adminPassword -getJMSConnectionFactories

For example:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 
-getJMSConnectionFactories

Managing JMS Destinations

You can use the admin_client.jar utility to manage the OC4J JMS destinations, as the following topics describe:

Adding a JMS Destination

Use the -addDestination command to add a JMS destination. The syntax for this command follows:

java -jar admin_client.jar uri adminId adminPassword -addDestination
-domain domain -name name -jndiLocation jndiLocation [-persistenceFile persistenceFile] [-description description]

For example:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 
-addDestination -domain Queue -name ExampleQueue -jndiLocation jms/ExampleQueue

Table 11-42 -addDestination Command Parameters

Parameter Description

-domain

Required. The JMS domain of this destination (`QUEUE' or `TOPIC').

-name

Required. The OC4J JMS provider-specific name of the destination.

-jndiLocation

Required. The JNDI location to which this destination will be bound.

-persistenceFile

Optional. The persistence file associated with this destination (defaults to null).

-description

Optional. A textual description of this destination (defaults to null).


Removing a JMS Destination

Use the -removeDestination command to remove a JMS destination from an OC4J instance or from each OC4J instance in a group. The syntax for this command follows:

java -jar admin_client.jar uri adminId adminPassword -removeDestination
-name name [-force true|false] [-removePFile true|false]

For example:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 
-removeDestination -name ExampleQueue -removePFile true

Table 11-43 -removeDestination Command Parameters

Parameter Description

-name

Required. The OC4J JMS provider-specific name of the destination to remove.

-force

Optional. Removes the destination regardless of whether messages or consumers exist on it (defaults to false).

-removePFile

Optional. Removes the persistence file from the file system (defaults to false).


Getting Information About JMS Destinations

Use the -getDestinations command to return the attributes for each of the OC4J JMS destinations from an OC4J instance or from each OC4J instance in a group. The syntax for this command follows:

java -jar admin_client.jar uri adminId adminPassword -getDestinations

For example:

java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 
-getDestinations

Managing OC4J Through a Remote Client

You can use a remote client to manage OC4J after you install the files from the remote Administrative Client Utility, as described in "Downloading and Extracting the Remote Administration Client". Then you can use admin_client.jar through the command-line tool or the JMX Remote API.

Using admin_client.jar Commands Remotely

After you connect to an OC4J application server target, as explained in "Downloading and Extracting the Remote Administration Client", you can issue admin_client.jar commands from a remote client. Use the same syntax that you would use from within an OC4J instance.

Connecting to a Remote Oracle Application Server Instance Using JConsole

JConsole is a JMX GUI console included in JDK 5.0. JConsole can connect to any JVM and hook into its running MBeanServer, displaying a series of pages on which various system details such as Thread and Memory usage of the JVM are displayed. JConsole can connect to a local JVM, or it can use the JMX Remote API and connect to a remote JVM.

The Administrative Client Utility distribution contains the libraries required to enable JConsole to connect to a remote OC4J or Oracle Application Server instance. To connect to the target instance, the JConsole utility (which is provided as a native executable in a Windows environment) needs to be configured with the relevant details of the Administrative Client Utility distribution.

To connect to an Oracle Application Server instance:

  1. Add /j2ee/instance/admin_client.jar to the CLASSPATH environment variable:

    set CLASSPATH=j2ee/home/admin_client.jar
    
  2. Add the JConsole libraries to the CLASSPATH environment variable:

    set CLASSPATH=%CLASSPATH%;%JAVA_HOME%\lib\jconsole.jar
    set CLASSPATH=%CLASSPATH%;%JAVA_HOME%\lib\tools.jar
    
  3. Configure the JMX connector to use the OC4J ORMI protocol:

    set PROPS= jmx.remote.protocol.provider.pkgs=oracle.oc4j.admin.jmx.remote
    
  4. Run jconsole:

    %JAVA_HOME%\bin\jconsole
    -J-Djava.class.path=%CLASSPATH% 
    -J-D%PROPS%
    

    This will launch JConsole.

  5. On the Advanced Tab of the Connect to Agent screen, enter the connect string for the OC4J or Oracle Application Server target as well as the administration user name and password for the target.

    The pattern of the JMX URL is different for OC4J targets from the pattern for Oracle Application Server targets. Table 11-44 shows examples of these URL patterns.

    Table 11-44 JMX URLs for OC4J and Oracle Application Server Targets

    Target JMX URL

    Standalone OC4J Server

    service:jmx:rmi://test-cycle.oracle.com:23791

    OC4J Instance on Oracle Application Server

    service:jmx:ormi:///opmn://test-cycle.oracle.com:6010/test1

    Oracle Application Server Cluster

    service:jmx:rmis:///opmn://stadp69:6003/cluster/as101/admin


  6. The JConsole utility will show the OC4J MBeans from the target instance. These MBeans can be used to view and manage the configuration of the OC4J instance.

In a Windows environment, the environment used by JConsole can be modified by using a special System property form:

-J-Dname=value

A sample command script follows:

setlocal

set URL=service:jmx:rmi:///opmn://test-cycle.oracle.com:6010/testunit

set JAVA_HOME=C:\java\jdk150_07

set JCONSOLE_CPset JCONSOLE_CP=%JCONSOLE_CP%;%JAVA_HOME%\lib\jconsole.jar
set JCONSOLE_CP=%JCONSOLE_CP%;%JAVA_HOME%\lib\tools.jar

set ORACLE_HOME=D:\oc4j_admin_client
set ORACLE_CP=
set ORACLE_CP=%ORACLE_CP%;%ORACLE_HOME%\j2ee\home\admin_client.jar;

set CLASSPATH=%JCONSOLE_CP%;%ORACLE_CP%
set PROPS=
set PROPS=%PROPS%  
-J-Djmx.remote.protocol.provider.pkgs=oracle.oc4j.admin.jmx.remote

set PROPS=%PROPS% -J-Djava.class.path=%CLASSPATH%

jconsole %PROPS% %URL%

endlocal

Using a JMX Programmatic Client to Manage OC4J Remotely

The Administrative Client Utility distribution provides a full client environment for JMX client applications to connect to remote OC4J instances. You can use a JMX programmatic client to manage OC4J remotely through the JMX Remote API (JSR160), which can establish a connection to the MBeanServer. The only JAR files you need to run with JDK 5.0 are oc4jclient.jar and admin_client.jar, which the Administrative Client Utility distribution provides.

The following example uses these JAR files with the JMX API:

// A URL is of the form "service:jmx:rmi://127.0.0.1:23791" 
             JMXServiceURL serviceURL = new JMXServiceURL(_url); 
  
             Hashtable credentials = new Hashtable(); 
              credentials.put("login", _username); 
              credentials.put("password", _password); 
  
             // Properties required to use the OC4J ORMI protocol 
             Hashtable env = new Hashtable(); 
             env.put(JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES, 
 "oracle.oc4j.admin.jmx.remote"); 
             env.put(JMXConnector.CREDENTIALS, credentials); 
             JMXConnector jmxCon = 
 JMXConnectorFactory.newJMXConnector(serviceURL, env); 
             jmxCon.connect(); 
  
             MBeanServerConnection mbeanServer = 
 jmxCon.getMBeanServerConnection(); 

In JDK 5.0 this code compiles with no Oracle libraries required, just the libraries provided by the JDK:

clear 
 @echo off 
 @setlocal 
  
 set J2EE_HOME=c:\java\oc4j-1013-prod\j2ee\home 
 set JAVA_HOME=c:\java\jdk50 
 set CLASSPATH=. 
  
 rem 
 rem Uncomment below if using JDK14 
 rem set CLASSPATH=%CLASSPATH%;%J2EE_HOME%\lib\jmxri.jar 
 rem set CLASSPATH=%CLASSPATH%;%J2EE_HOME%\lib\jmx_remote_api.jar 
 rem set CLASSPATH=%CLASSPATH%;%J2EE_HOME%\lib\javax77.jar 
 rem 
  
 %JAVA_HOME%\bin\javac -classpath %CLASSPATH% -d . *.java 
 @endlocal 

To run the code with the oc4j_admin_client_101350.zip distribution:

  1. Create a runnable JAR file.

  2. Drop the JAR file into the j2ee/home directory of the Administrative Client Utility distribution.

  3. Connect to a remote OC4J instance.

The code runs in JDK 5.0 with $ORACLE_HOME/j2ee/home/oc4jclient.jar and $ORACLE_HOME/j2ee/home/admin_client.jar:

@echo off 
@setlocal 
clear 
set J2EE_HOME=c:\java\oc4j-1013-prod\j2ee\home 
set JAVA_HOME=c:\java\jdk50 

rem Runtime classpath 
set CLASSPATH=. 
set CLASSPATH=%CLASSPATH%;%J2EE_HOME%\oc4jclient.jar; 
set CLASSPATH=%CLASSPATH%;%J2EE_HOME%\admin_client.jar; 

rem 
rem Uncomment if using JDK14 
rem set CLASSPATH=%CLASSPATH%;%J2EE_HOME%\lib\jmxri.jar 
rem set CLASSPATH=%CLASSPATH%;%J2EE_HOME%\lib\jmx_remote_api.jar rem set CLASSPATH=%CLASSPATH%;%J2EE_HOME%\lib\javax77.jar 
@endlocal 

The connection URL in the main method of the example is set to connect to a local OC4J instance. If you want to connect to Oracle Application Server through an ORMI port, use a Service URL of the following form:

service:jmx:rmi|ormi:///opmn://stadp57.us.oracle.com:6003/home

A service URL will obtain the ORMI port from the OPMN daemon. The ORMI port is assigned at runtime. Using the OPMN connection string path will connect you to the specified OC4J instance.

For more information about how to use a JMX client to manage OC4J instances remotely, see "Remote Management Using the JMX Remote API (JSR-160)" in the Oracle Containers for J2EE Developer’s Guide.