Skip Headers

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

Previous | Next |

# 9 Deploying with Application Server Control Console

The Oracle Enterprise Manager 10g Application Server Control Console provides a Web-based interface for completing a range of deployment-related tasks, including:

- Deploying, undeploying and redeploying standalone modules (WARs, CARs, etc.) as well as complete J2EE applications into OC4J

- Creating and editing re-usable deployment plans

- Configuring application security and clustering at deployment time

- Importing shared libraries for use by the application, as well as modifying the list of inherited libraries

- Deploying an application to specific OC4J instances or to a "group" of instances within an Oracle Application Server cluster

See the online Help provided with Application Server Control Console for detailed instructions on using the various features provided.

This chapter includes the following sections:

- Accessing Application Server Control Console

- Deploying to OC4J Instances Within a Cluster

- Deploying/Redeploying an Application

- Completing the Deployment Tasks

- Undeploying an Application

## Accessing Application Server Control Console

The Application Server Control Console is installed and configured automatically when you install OC4J. This section covers the following topics:

- Accessing Application Server Control Console in Standalone OC4J

- Accessing Application Server Control Console in Oracle Application Server

See the online Help provided with Application Server Control Console for detailed instructions on using this interface.

Note: The current release of Application Server Control Console does not provide management support for either OPMN or Oracle HTTP Server. Use the OPMN command-line tool, opmnctl, to start/stop and manage instances of these components.

### Accessing Application Server Control Console in Standalone OC4J

The Application Server Control Console is installed and configured automatically when you install the OC4J software. It is started by default when OC4J is started.

The console is accessed through the `default` Web site, which is configured to listen for HTTP requests on port 8888. To access the console, simply type the following URL in a Web browser:

    http://hostname:8888/em

### Accessing Application Server Control Console in Oracle Application Server

The Application Server Control Console is installed and configured automatically when you install OC4J using the Oracle Universal Installer.

The console is started with all other installed Oracle Application Server components using the OPMN command-line tool, `opmnctl`, which is installed in the `ORACLE_HOME``/opmn/bin` directory on each server node. Start all installed components by issuing the following command:

    cd ORACLE_HOME/opmn/bin
    opmnctl startall

In a typical Oracle Application Server installation, all Web applications, including Application Server Control Console, are accessed through Oracle HTTP Server (OHS). Use the following URL to access the console:

    http://ohs_host_address:port/em

- `ohs_host_address` is the address of the OHS host machine; for example, `server07.company.com`

- `port` is an HTTP listener port assigned to OHS by OPMN. Run the following `opmnctl` command on the OHS host machine to get the list of assigned listener ports from OPMN:

      opmnctl status -l

  Supply the port designated as `http1` in the OPMN status output as the value for `port`:

      HTTP_Server | HTTP_Server | 6412 | Alive | 1970872013 | 1
      6396 | 0:48:01 | https1:4443,http2:722,http1:7779

## Deploying to OC4J Instances Within a Cluster

Application Server Control Console enables you to deploy an application to a specific OC4J instance or to a "group" of instances within an Oracle Application Server cluster. 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 an application can be deployed.

1. Click the Cluster Topology link on the Application Server Control Console home page. The resulting page displays the following:

   - All Oracle Application Server instances that are currently part of the cluster

   - The active OC4J instances within each Oracle Application Server instance

   - The applications deployed into each OC4J instance

2. Select the deployment target:

   - To deploy to a group of OC4J instances, click the common instance name shared by the group under Groups at the bottom of the page.

   - To deploy to a specific OC4J instance, click the link for the target instance you want to deploy the application to.

3. Once the target instance has been accessed, deploy the application by following the instructions in "Deploying/Redeploying an Application".

## Deploying/Redeploying an Application

The Application Server Control Console provides a three-page deployment wizard that provides a streamlined, user-friendly deployment process.

Note: If the HTTP session times out due to browser inactivity while you are using the deployment wizard, you will have to re-start the deployment process from the beginning.

1. Click the Applications tab ->Deploy button to access the deployment wizard.

2. Select the archive to upload to the OC4J server in the first page of the wizard.

   You also have the option to navigate to the location of an existing deployment plan, which can be applied to the archive or used as a template for a new deployment plan. If no deployment plan is specified, a new deployment plan will be created by default. See Chapter 8, "Working With Deployment Plans" for more information.

3. Set application attributes and bind the Web application to a Web site in the second page of the deployment wizard.

   Specify the application or module name, which will be used to identify the application within OC4J. This name will also be displayed in Application Server Control Console.

   Next, select the parent application of the application or module being deployed. If none specified, the `default` application is used.

   Finally, if deploying a Web application, bind the application to the Web site that will be used to access it. This binding is accomplished by selecting the name of the XML configuration file that defines the Web site from the list.

   The list contains all Web sites currently defined for the OC4J server instance. In most cases, applications will be bound to the `default` Web site, which is defined by the `default-web-site.xml` configuration file.

4. Complete the deployment tasks and/or edit the deployment plan directly before deploying the archive in the third page of the deployment wizard.

   In this final screen, you have the option of completing a number of configuration tasks before deploying the application. These tasks provide an alternative to editing the deployment plan, which contains configuration data that will be set in the OC4J deployment descriptors generated during deployment. See "Completing the Deployment Tasks" for details on each optional task.

   You also have the option of editing the deployment plan directly before deploying the archive. The edited deployment plan can then be saved for re-use. See Chapter 8, "Working With Deployment Plans" for more details on creating and editing deployment plans.

5. Deploy the application.

   Note that the archive is not actually deployed until you click the Deploy button. The deployment plan, which up until this point exists only on the client side, will also be sent to the OC4J server with the archive. Note that once started, the deployment process will continue, even if the Web browser is closed.

## Completing the Deployment Tasks

The third panel in the Application Server Control Console deployment wizard gives you the option to complete a number of configuration tasks before deploying an application. Provide a more straightforward option for completing similar tasks through the deployment plan editor.

Just as with the deployment plan editor, values set through the various deployment tasks pages are written to the appropriate OC4J-specific deployment descriptor at deployment time.

### Selecting the Security Provider

OC4J supports two different provider types: XML for application development mode, and LDAP for production environments. Each provider type implements a repository for secure, centralized storage, retrieval, and administration of provider data.

- Select File-Based Security Provider to use the XML-based provider.

  The XML-based provider is a lightweight implementation suitable for application prototyping in a development environment. User, realm, and policy information is stored in an XML file, normally `jazn-data.xml`.

- Select Oracle Identity Management Security Provider to use the LDAP-based Oracle Internet Directory provider.

  This security provider is useful for applications being deployed into a production environment. User, realm, and policy information is persisted to the LDAP-based Oracle Internet Directory (OID).

  Note that the OC4J instance must be configured to use Oracle Internet Directory before an application can be configured to use it.

- Select Oracle Security Provider for 3rd Party LDAP Server to use a non-Oracle LDAP provider.

  Select this option to configure the application to use Active Directory, Sun Directory Server or another LDAP server. Use the tools provided by the LDAP server vendor for realm and principals management.

### Mapping Security Roles to Users and Groups

Map any security roles defined in your application to existing users and groups. If you have defined a security role within your application, you can map this role to a security group or role. You do not define security groups and users in this screen.

### Configuring Enterprise JavaBeans Included in the Application

You can configure a number of properties for the EJBs packaged with the application being deployed.

- Configure the following properties for each entity bean packaged with the application. The values displayed are the default values.

  Table 9-1 Entity Bean Properties

  Property | Values
  --- | ---
  Persistence Type | Indicates whether the bean will use bean-managed or container-managed persistence.
  Min Instances | Sets the number of minimum bean implementation instances to be kept instantiated or pooled.
  Max Instances | Defines the maximum number of bean instances, either instantiated or pooled, allowed in memory.
  Max Transaction Retries | Specifies the number of times to retry a transaction that was rolled back due to system-level failures.
  Pool Cache Timeout | Sets the amount of time, in seconds, that stateless sessions are to remain cached in the pool. At the specified interval, all unassigned beans in the pool are removed.
  JNDI Name | Defines the JNDI name this EJB will be bound to.

- Select the data sources to associate with EJB modules containing entity beans.

  By default, all entity beans deployed into OC4J will use the Oracle TopLink persistence manager. Data sources can be created through the Administration tab -> Services ->JDBC Resources page in Application Server Control Console.

- Configure the following for each session bean packaged with the application. The values displayed are the default values.

  Table 9-2 Session Bean Properties

  Property | Values
  --- | ---
  Min Instances | Sets the number of minimum bean implementation instances to be kept instantiated or pooled.
  Max Instances | Defines the maximum number of bean instances, either instantiated or pooled, allowed in memory.
  Max Transaction Retries | Specifies the number of times to retry a transaction that was rolled back due to system-level failures.
  Call Timeout | Specifies the maximum time, in milliseconds, to wait for any resource to make a business/life-cycle method invocation.
  Pool Cache Timeout | Sets the amount of time, in seconds, that stateless sessions are to remain cached in the pool. At the specified interval, all unassigned beans in the pool are removed.
  JNDI Name | Defines the JNDI name this EJB will be bound to.

- Configure the following for each message-driven bean packaged with the application. The values displayed are the default values.

  Table 9-3 Message-Driven Bean Properties

  Property | Values
  --- | ---
  Dequeue Retry Count | Specifies how often the listener thread tries to re-acquire the JMS session once database failover has occurred. Valid for container-managed transactions only.
  Dequeue Retry Count | Specifies the interval between attempts to re-acquire the JMS session.
  Transaction Timeout | Sets the transaction timeout interval, in seconds, for any container-managed transactional MDB.
  Number of Listener Threads | Sets the number of listener threads spawned to listen for incoming JMS messages on the topic or queue. Topics can only have one thread; queues can have more than one thread.

### Configuring Class Loading/Shared Libraries

Optionally manage the libraries imported by the application. By default, an application inherits the same set of shared libraries present in its parent application, including any shared libraries inherited from the `default` application.

The default page displays all of the shared libraries currently installed on the OC4J server instance. Shared libraries must have already been installed on the OC4J server instance to be imported.

- Select the Import box next to each shared library to import. To use the latest installed version of the library, do not specify a version number.

- Specify a minimum or maximum version of a shared library to import.

  Use this feature to import a different version of a shared library than that inherited from the application's parent. For example, you could import an earlier version of the Oracle JDBC driver than that inherited from the OC4J `default` application by specifying the maximum version to import.

- De-select the Import box for any shared library that should not be inherited from the parent application.

  To remove all inherited shared libraries, deselect the Inherit parent application's imported shared libraries checkbox. This action adds the following `<remove-inherited>` element to the `orion-application.xml` file that will be generated for the application at deployment time:

      <imported-shared-libraries>
        <remove-inherited name="*" />
      </imported-shared-libraries>

- Optionally specify additional code sources to add as library paths to the OC4J instance.

  To add a code source, specify either a relative or absolute path or URL to the archive. Specified directories are scanned for archives to load at OC4J server startup.

- Manage the classloader created for each Web module.

  OC4J creates a classloader instance for each Web module deployed as a WAR into the server instance.

  Check the Search Local Classes First checkbox to force the class loader to also load JARs containing classes and resources packaged within the WAR before loading JARs external to the WAR.

  For example, suppose you want to ensure that your Web module uses the version of `log4j` packaged within your WAR, and not use the version of `log4j` bundled with a resource adapter deployed into the OC4J instance. Selecting this option forces the classloader to load the local log4j JAR file contained within the WAR.

  If the WAR contains a MANIFEST.MF, you can force JARs declared as named extensions to be loaded by checking the Include WAR Manifest Class Path box. You can also specify the relative or absolute paths to one or more additional code sources containing classes or resources to be loaded in the Classpath field. Using either of these features causes classes to be loaded by the Web module's classloader, just as if they were packaged within the WAR.

### Configuring Clustering

The OC4J clustering framework supports replication of objects and values contained in an HTTP session or a stateful session Enterprise JavaBean instance across OC4J instances.

By default, applications inherit the clustering configuration set at the parent application level. However, clustering can also be configured at the application level at deployment time. A configuration property set at the application level overrides the corresponding value inherited from the parent application.

- Select Enable Clustering to enable clustering support for the application. The value selected overrides the setting inherited from the application's parent.

  If clustering has been enabled at the parent application level, the parent's configuration will be applied by default.

- Select Peer-to-Peer Replication to enable the peer-to-peer replication mechanism. Note that the mechanism used is dependent on the type of OC4J installation.

  - OC4J instances within Oracle Application Server

    In an Oracle Application Server cluster, dynamic peer-to-peer is used to enable OC4J instances to dynamically discover and communicate with one another.

    Dynamic peer-to-peer is used by default if clustering is enabled; no additional configuration is needed.

    Note that you can optionally specify the IP address for a Network Interface Card (NIC) to bind to. This is useful if you have OC4J host machines with multiple network cards, each with a specific IP address.

  - Standalone OC4J installation

    In a standalone configuration, each node in the cluster can be statically configured to recognize at least one other peer node. As a node becomes aware of each of its peers, it also becomes aware of each peer's peer(s)—with the end result that all of the nodes in the cluster become aware of one another.

- Select Multicast Replication to configure OC4J to send and receive HTTP session and stateful session bean state changes via multicast packages.

  This is the default replication protocol used in a standalone OC4J installation. The multicast address and port must be the same for all instances in the cluster. The OC4J default address is `230.230.0.1`; the default port is `45566`.

  Note that you can optionally specify the IP address for a Network Interface Card (NIC) to bind to. This is useful if you have OC4J host machines with multiple network cards, each with a specific IP address

- Select Database Replication to replicate application state to a database.

  Select the JNDI name of the data source providing the connection to the database from the Database JNDI Location pull-down menu. See the Oracle Containers for J2EE Services Guide for details on creating and using data sources.

### Providing Resource Mappings

Any resources included in the EAR file being deployed will be displayed in the Application Server Control Console. Map any environment references in your application to physical entities currently present in the operational environment to JMS topics and queues, data sources or resource adapters.

Map any references to resources in your application, such as data sources or mail queues, to physical entities currently present in the OC4J container. Note that if you need a specific resource, you must have already added this to the OC4J container before you deploy your application in order for you to match them in this step.

For most applications, the resource reference you must designate is the data source JNDI name. You cannot configure the data source information through Deployment Tasks in Application Server Control; it only designates an already configured data source or a data source that you will be configuring later. Designate the JNDI location name of the data source that the application will be using.

If you have any MDBs in your EAR file, you may be required to add information about the subscriptions or topics. If you are defining `DataSource` objects for CMP entity beans, you are given the option to add a JNDI location for those `DataSource` objects.

## Undeploying an Application

Undeploying an application or module removes the code from the OC4J runtime and deletes all existing Web site bindings.

1. Click the Applications tab ->Undeploy button.

2. Select the application, then click the Undeploy button.