|
Oracle® Containers for J2EE Deployment Guide
10g Release 3 (10.1.3) Part No. B14431-01 |
|
 Previous |
 Next |
|
Oracle® Containers for J2EE Deployment Guide
10g Release 3 (10.1.3) Part No. B14431-01 |
|
|
Previous |
Next |
OC4J provides a command-line utility— admin_client.jar—that can be used to perform deployment-related operations on active OC4J instances in an Oracle Application Server clustered environment as well as on standalone OC4J servers.
Among the tasks you can perform with this utility:
Deploy an application (EAR), a standalone Web module (WAR), a standalone EJB module (EJB JAR) or a standalone resource adapter (RAR) to a specific OC4J instance or to a "group" of instances within a cluster
Undeploy an application, Web module, EJB module or resource adapter
Incrementally update a deployed EJB module with modified classes
Create a new shared library
Stop, start or restart a specific application, on a specific OC4J instance or cluster-wide
This chapter includes the following topics:
The admin_client.jar is installed by default in ORACLE_HOME/j2ee/home in an OC4J instance.
Note that OC4J must be started before this utility can be used.
The admin_client.jar utility uses the following syntax. The parameters are described in the table below.
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(s) supplied. The syntax for the URI varies depending on the instance(s) being targeted. See the following for the format of this URI:
The OC4J administration user name and password are also passed to the 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 home OC4J instance on node1, a member of an Oracle Application Server cluster:
java -jar admin_client.jar deployer:oc4j:opmn://node1.company.com/home oc4jadmin password -application petstore -start
Use the following URI to specify all OC4J instances within a group as the target. A group is defined as a loosely syncronized set of like-named OC4J instances within the same cluster topology. For example, all instances named home within a cluster would collectively form a group across which configuration operations can be executed simultaneously.
The URI utilizes the OPMN-based clustering framework, in which cluster nodes are aware of one another. You only need to supply 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 is as follows:
deployer:cluster:[rmis]:opmn://opmnHost[:opmnPort]/oc4jInstanceName
For example:
deployer:cluster:opmn://node1/home
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 the 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 not specified, the default port 6003 will be used.
|
oc4jInstanceName
|
Required. The common instance name shared by OC4J instances within the group. |
Use the following URI to target a specific OPMN-managed OC4J instance, including an instance within a cluster. Note that cluster: is replaced by oc4j: in the prefix.
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 is as 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. |
opmnPort
|
Optional. The OPMN request port, as specified in opmn.xml. If not 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. |
Use the following URIs to target a standalone OC4J server instance.
If using RMI, the URI syntax is as follows:
deployer:oc4j:host:rmiPort
If using ORMI over SSL (ORMIS), specify the following:
deployer:oc4j:rmis:host:ormisPort
For example:
deployer:oc4j:myserver:23791 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 used. The SSL port, as specified in the instance-specific rmi.xml file.
|
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 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:
Create a logging.properties file containing a single line:
oracle.oc4j.admin.jmx.client.CoreRemoteMBeanServer.level=INFO
Note that if you create this file in a location other than ORACLE_HOME/j2ee/home/, you must include the path to the file in the command below.
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 following Java log level values:
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 may 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 configuration-related messages or problems. |
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
You can use admin_client.jar to deploy an application (EAR), a standalone Web module (WAR) or a standalone resource adapter (RAR) to a specific OC4J instance or to all instances within a cluster.
This chapter covers the following:
|
Usage Note:
|
Use the -deploy command to deploy or redeploy a J2EE application packaged as an EAR file. The EAR-specific syntax is as follows:
java -jar admin_client.jar uri adminId adminPassword -deploy -file path/filename -deploymentName appName [-bindAllWebApps [webSiteName]] [-targetPath path] [-parent appName] [-deploymentDirectory path] -enableIIOP [-iiopClientJar path/filename]
Ideally, you should include the -bindAllWebApps subswitch to bind all Web modules within the EAR to the Web site they will be accessed through. 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 home instances within the cluster of which node1 is a member. 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/home oc4jadmin password -deploy -file C:/dev/utility.ear -deploymentName utility -bindAllWebApps
Table 11-5 -deploy Command Subswitches for EAR Deployment
| Subswitch | Description |
|---|---|
-file
|
Required. The path and file name of the EAR file to deploy. |
-deploymentName
|
Required. The user-defined application deployment name, used to identify the application within OC4J. |
-bindAllWebApps
|
Optional. Binds all Web modules to the specified Web site, or to the default Web site if none specified. If not specified, you must use the -bindAllWebApps command described on .
You can optionally supply a value for |
-targetPath
|
Optional. The directory to deploy the EAR to. If not specified, the EAR is deployed to the ORACLE_HOME/j2ee/instance/applications/ directory by default.
The deployed EAR file is also copied to this directory. Each successive deployment will cause this EAR file to be overwritten. |
-parent
|
Optional. The parent application of this application. The default is the global or default application.
|
-deploymentPlan
|
Optional. The path and filename 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 |
-sequential
|
Optional. Include to deploy the archive to each OC4J instance within the cluster in sequence. Requests will not be routed to an instance while the EAR is being deployed to it.
If not included, the archive is simultaneously deployed to all instances by default. This option is valid in a clustered environment only; it is not valid for standalone OC4J. |
-enableIIOP
|
Optional. Include to generate IIOP client stubs on the OC4J server.
The application-level stubs generated for all EJB modules are output to an archive named Note that the |
-iiopClientJar
|
Optional. The path and filename of the JAR to output IIOP client stubs to.
The application-level stubs generated for all EJB modules are output to an archive named In addition, stubs for each individual EJB module are generated in an archive with the same name in the Note that the |
Use the -deploy command to deploy or redeploy a standalone Web module packaged as a WAR file.
The WAR-specific syntax is as 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]
The WAR must be designated a child of another deployed application that does not already contain a Web module component; otherwise, it will be deployed to the default application.
Note that 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. Re-package 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 across all OC4J home instances within the cluster. Because the -bindAllWebApps subswitch 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/home oc4jadmin password -deploy -file C:/dev/acme-web.war -deploymentName utility -bindAllWebApps -parent default
Table 11-6 -deploy Command Subswitches for WAR Deployment
| Subswitch | Description |
|---|---|
-file
|
Required. The path and file name of the RAR file to deploy. |
-deploymentName
|
Required. The user-defined Web module name, used to identify it within OC4J. |
-bindAllWebApps
|
Optional. Binds all Web modules to the specified Web site, or to the default Web site if none specified.
You can optionally supply a value for |
-targetPath
|
Optional. The directory to deploy the archive to. If 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 |
-contextRoot
|
Optional. The Web module context, which will be appended to the URL used to access the application through a Web browser. If not specified, the value passed in for -deploymentName will be used.
For example, if you supply |
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.
Because a standalone RAR is a resource that may be shared by multiple applications, redeploying or undeploying a standalone RAR requires a restart of the default application. This in turn will force a restart of all deployed applications, which are child applications of default. See "Starting/Stopping/Restarting an Application" for instructions on restarting an application.
The RAR-specific syntax is as follows:
java -jar admin_client.jar uri adminId adminPassword>-deploy -file path/filename-deploymentName connectorName [-nativePathLib path] [-grantAllPermissions]
The following command deploys the acme-rar.rar module to all OC4J home instances within the cluster.
java -jar admin_client.jar deployer:cluster:opmn://node1.company.com/home oc4jadmin password -deploy -file /dev/acme-rar.rar -deploymentName acme-rar -grantAllPermissions
Table 11-7 -deploy Command Subswitches for RAR Deployment
| Subswitch | Description |
|---|---|
-file
|
Required. The path and file name of the RAR file to deploy. |
-deploymentName
|
Required. The user-defined connector name, used to identify the connector within OC4J. |
-nativeLibPath
|
Optional. The path to the directory containing native libraries (such as DLLs) within the RAR file. |
-grantAllPermissions
|
Optional. Include to grant all runtime permissions requested by the resource adapter, if required. |
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 subswitch on the -deploy command. However, if the -bindAllWebApps subswitch was not specified when the EAR was deployed, you can bind modules to a Web site post-deployment.
This section covers the following topics:
Use the -bindAllWebApps command to bind all Web modules within a J2EE application to the same Web site, or to the default-web-site by default.
The syntax is:
java -jar admin_client.jar uri adminId adminPassword -bindAllWebApps -appName appName -webSiteName siteName
Table 11-8 -bindAllWebApps Command Subswitches
| Subswitch | Description |
|---|---|
-appName
|
Required. The name of the parent application as specified at deployment time. |
-webSiteName
|
Optional. The name of the name_web-site.xml file that denotes the Web site to bind the Web modules to. If omitted, all modules are bound to default-web-site.
|
Use the -bindWebApp command to bind a single Web module within a J2EE application to a specific Web site, or to default-web-site by default. You can also optionally set the context root that will be used to access the module.
The syntax is:
java -jar admin_client.jar uri adminId adminPassword -bindAllWebApps -appName appName -webModuleName moduleName -webSiteName siteName -contextRoot contextRoot
Table 11-9 -bindWebApp Command Subswitches
| Subswitch | 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 name of the name_web-site.xml file that denotes the Web site to bind the Web module to. If omitted, all modules are bound to default-web-site.
|
-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 not supplied, the context root specified in the parent application's |
The -redeploy command can be used to redeploy a previously-deployed archive.
Note that this operation performs a "graceful" redeployment as it stops the application if it is running, 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—it simply undeploys, redeploys and then restarts it.
The syntax is as follows:
java -jar admin_client.jar uri adminId adminPassword -deploy -file path/filename -deploymentName appName [-keepSettings] [-sequential]
Table 11-10 -redeploy Command Subswitches
| Subswitch | Description |
|---|---|
-file
|
Required. The path and filename of the EAR file to deploy. |
-deploymentName
|
Required. The user-defined application deployment name, used to identify the application within OC4J. This value must exactly match the name of the existing application on the server. |
-keepSettings
|
Optional. If included, 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 not specified, values will be set to those in the deployment descriptors packaged with the archive. |
-sequential
|
Optional. Include to deploy the archive to each OC4J instance within the cluster in sequence. The redeployment on each target must complete before continuing on to the next target. Requests will not be routed to an instance while the EAR is being deployed to it.
If not included, the archive is simultaneously deployed to all instances by default. This option is valid in a clustered environment only; it is not valid for standalone OC4J. |
The -undeploy command removes an application or standalone Web or connector module from the target OC4J instances, as the following topics describe:
Undeploying an EAR or standalone Web module removes it from the OC4J runtime. Existing Web site bindings are also deleted.
The syntax is as follows. Note that the name of the application or module must be supplied.
java -jar admin_client.jar uri adminId adminPassword -undeploy appName
Because a standalone RAR is a resource that may be shared by multiple applications, undeploying a standalone RAR requires a restart of the default application. This in turn will force a restart of all deployed applications, which are child applications of default. See "Starting/Stopping/Restarting an Application" for instructions on restarting an application.
The syntax is as follows. Note that the -isConnector subswitch must be included along with name of the connector.
java -jar admin_client.jar uri adminId adminPassword-undeploy connectorName -isConnector
The -updateEJBModule command allows incremental or partial redeployment of EJB modules within an application running in an OC4J instance. This feature makes it possible to redeploy only those beans within an EJB JAR that have changed, without requiring the entire module to be redeployed.
The syntax is as follows. Note that 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:oc4j:opmn://node1.company.com/home oc4jadmin password -updateEJBModule -appName petstore -ejbModuleName customerEjb.jar -file build/customerEjb.jar
Table 11-11 -updateEJBModule Syntax
| Option | Description |
|---|---|
-appName
|
Required. The name of the application the EJB is part of. If 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. |
Shared libraries can be created or removed on OC4J instances.
|
Note: In the current release, the commands listed below can only be run against a single OC4J instance, either OPMN managed or standalone. The commands will not create or modify shared libraries across a cluster. |
You can use the -publishSharedLibrary command to create the shared library directory structure and install the binaries that comprise the library within it on a single OC4J instance. The shared library will be created in the ORACLE_HOME/j2ee/instance/shared-lib directory within the 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 is as follows. Note that the path and file name for multiple code sources— binaries that will comprise 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 single OC4J instance.
java -jar admin_client.jar deployer:oc4j:opmn://server.company.com:6004/instance2/home oc4jadmin password -publishSharedLibrary -name acme.common version 2.5 -installCodeSources /myserver/tmp/acme-apis.jar /myserver/tmp/acmeImpl.jar
The resulting directory structure within the target OC4J server would be:
ORACLE_HOME/j2ee/home/shared-lib
/acme.common
/2.5
acme-apis.jar
acmeImpl.jar
Table 11-12 -publishSharedLibrary Command Subswitches
| Subswitch | 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, |
-version
|
Required. The shared library version number. This value should ideally reflect the code implementation version. |
-parentName
|
Optional. The name of the parent shared library, if applicable. |
-parentVersion
|
Optional. The parent shared library version number, if applicable. |
-installCodeSources
|
The path and file names for one or more JAR or ZIP files to upload to the OC4J server to add to the shared library. Separate each path/file name string with a space. |
-addCodeSources
|
Optional. The path and file names for JAR or ZIP files that have already been uploaded to the OC4J server to add to the shared library. Separate each path/file name string with a space. |
-imports
|
Optional. The name of one or more existing shared libraries to import into this shared library. Separate each name string with a space.
Note that you can optionally specify the maximum and/or minimum version of the library to import. |
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 is as follows. Note that the path and file name for multiple code sources— binaries that will comprise 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:oc4j:opmn://server.company.com:6004/instance2/home oc4jadmin password -modifySharedLibrary -name acme.common version 2.5 -addCodeSources /myserver/tmp/acme-helpers.jar
Table 11-13 -modifySharedLibrary Command Subswitches
| Subswitch | 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 server and installed as part of the shared library. Separate each path/file name string 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 server to add to the shared library. Separate each path/file name string with a space. |
-removeCodeSources
|
Optional. The path and file name for JAR or ZIP files to remove from the shared library. |
-addImports
|
Optional. The name of one or more existing shared libraries to import into this shared library. Separate each name string with a space.
Note that you can optionally specify the maximum and/or minimum version of the library to import. |
-removeImports
|
Optional. The name of one or more existing shared libraries to remove from this shared library.
Note that you can optionally specify the maximum and/or minimum version of the library to remove. |
Use the -describeSharedLibrary command to view the code sources and imported shared libraries that comprise the specified shared library.
The syntax is as follows:
java -jar admin_client.jar uri adminId adminPassword -describeSharedLibrary -name libName -version libVersion
You can use admin_client.jar to start, stop or restart an application and its child applications on a specific OC4J instance or across an entire cluster. If a file within the application has been modified, the application will be automatically redeployed at startup.
The syntax is as follows:
java -jar admin_client.jar uri adminId adminPassword -start|-stop appName
The following example starts the petstore application on node2 within the cluster:
java -jar admin_client.jar deployer:oc4j:opmn://node2.company.com:6004/home oc4jadmin password -start petstore
