6 Using the admin_client.jar Utility

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:

• Performing Operations on a Group of OC4J Instances Within a Cluster

• Performing Operations on a Specific OC4J Instance

• Performing Operations on a Standalone OC4J Server

• Validating a 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 6-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 6-1 OC4J Instance Running on Multiple JVMs in an Oracle Application Server Instance Within a Cluster

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

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

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

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

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

deployer:oc4j:host:rmiPort

deployer:oc4j:myserver:23791

deployer:oc4j:rmis:host:ormisPort

deployer:oc4j:rmis:myserver:23943

java -jar admin_client.jar uri adminId adminPassword -validateURI

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.4.0), is available for downloading from Oracle Technology Network and is on the Oracle Application Server companion CD. The distribution file, oc4j_admin_client_101340.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_101340.zip from the Oracle Technology Network:

   http://download.oracle.com/otn/java/oc4j/10131/oc4j_admin_client_101340.zip
   

2. Extract the contents of oc4j_admin_client_101340.zip into a local directory. For example:

   >mkdir oc4j_admin_client
    >cd oc4j_admin_client
    >jar xvf d:\software\oc4j_admin_client_101340.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 6-4.

SEVERE

WARNING

INFO

CONFIG

FINE

FINER

FINEST

For example:

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

Deploying a J2EE Application (EAR)

Use the -deploy command to deploy or redeploy a J2EE application packaged as an EAR file. The EAR-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] [sequential [waitsec]] [-enableIIOP] 
[-iiopClientJar path/filename] [-deploymentPlan path/filename] [-removeArchive]

You can include the -bindAllWebApps parameter to bind all Web modules within the EAR 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 

-sequential 15

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 or redeploy a standalone Web module packaged as a WAR file.

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

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

For more information, see "Deploying Resource Adapters" in the Oracle Containers for J2EE Deployment Guide.

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.

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

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

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.4.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 EAR or Standalone WAR

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

The syntax for undeploying an EAR or standalone WAR 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.

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

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

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

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

Removing a Shared Library

Use the -removeSharedLibrary command to remove a shared library from the OC4J target. The syntax of this command follows:

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

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.

Adding, Testing, and Removing Data Source Connection Pools

You can use the admin_client.jar utility to add, test, 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

• Testing a Data Source Connection Pool

• Removing a Data Source Connection Pool

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 [...]]]

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

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

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

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

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

Adding, Testing, and Removing Data Sources

You can use the admin_client.jar utility to add, test, 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

• Removing a Managed Data Source

• Adding a Native Data Source

• Removing a Native Data Source

• Testing a Database Connection

• Testing a Data Source

• Getting the Data Sources Descriptor for an Application

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] 

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

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

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

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 ][...]]

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

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

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

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

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 

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

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

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

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

• Removing a JMS Connection Factory

• Getting Information About JMS Connection Factories

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]

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

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

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

java -jar admin_client.jar uri adminId adminPassword -getJMSConnectionFactories

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

• Removing a JMS Destination

• Getting Information About JMS Destinations

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

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

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

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

java -jar admin_client.jar uri adminId adminPassword -getDestinations

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

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 6-30 shows examples of these URL patterns.

   Table 6-30 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_101340.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.