Skip Headers

Oracle® Containers for J2EE Resource Adapter Administrator's Guide 10g Release 3 (10.1.3) B14436-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 2 Overview: Administering Resource Adapters

This chapter provides a top-level discussion of how to administer your resource adapters, covering the following topics:

- A Brief Overview of OC4J Administration

- Summary of Application Server Control Pages for Resource Adapters

- General Resource Adapter Administration Features

- Summary of Resource Adapter MBeans and Administration

- Resource Adapter Lifecycle: Startup and Shutdown

## A Brief Overview of OC4J Administration

Before discussing resource adapter administration, we summarize OC4J features in the following areas:

- OC4J Deployment and Configuration Features

- OC4J and Oracle Application Server Administration Tools

### OC4J Deployment and Configuration Features

OC4J supports the following standards for deploying and managing applications in a J2EE environment:

- Java Management Extensions (JMX) 1.2 specification allows standard interfaces to be created for managing resources, such as services and applications, in a J2EE environment. The OC4J implementation of JMX provides a user interface that you can use to completely manage an OC4J server and applications running within it.

- Java 2 Platform, Enterprise Edition Management Specification (JS R-77) allows objects known as MBeans (managed beans) to be created for runtime management of applications in a J2EE environment. In OC4J, you can directly access MBeans through the System MBean Browser in Oracle Enterprise Manager 10g, but many of their properties are exposed in a more user-friendly way through other features of Enterprise Manager. These interfaces are summarized in "Summary of Resource Adapter MBeans and Administration".

- Java 2 Enterprise Edition Deployment API Specification (JS R-88) defines a standard API for configuring and deploying J2EE applications and modules into a J2EE-compatible environment. The OC4J implementation includes the ability to create or edit a deployment plan containing the OC4J-specific configuration data needed to deploy a component into OC4J.

The OC4J depl oyment plan editor and System MBean Browser are exposed through Oracle Enterprise Manager 10g Application Server Control, referred to as Application Server Control. The user interface for this is the Application Server Control Console. Additionally, for convenience, many parameters corresponding to MBeans properties, including all key properties relating to resource adapters, are exposed through other pages of the Application Server Control Console.

You should generally use the Application Server Control Console to configure and deploy your OC4J applications (using the deployment plan editor), as well as for any runtime administration or reconfiguration. Avoid direct manipulation of OC4J MBeans or of OC4J-specific XML configuration files where possible. The XML files are updated automatically by OC4J when you use the Application Server Control Console. There may be deployment situations, however, where an `oc4j-ra.xml` or `oc4j-connectors.xml` property is not exposed through the Application Server Control Console. In these situations, directly creating the XML file for deployment may be the only option.

For general information about OC4J deployment, configuration, and administration, refer to the Oracle Containers for J2EE Deployment Guide and the Oracle Containers for J2EE Configuration and Administration Guide. For more information about Application Server Control, you can also refer to the introduction to administration tools in the Oracle Application Server Administrator's Guide.

Note: Due to the inherently ambiguous semantics involved in changing certain configuration settings while a resource adapter is in use, some updates through MBeans, including updates through the Application Server Control Console, do not take effect until the resource adapter is restarted. When you make such a change through the Application Server Control Console, OC4J updates the console and corresponding XML file immediately, even though the new value might not take effect until after restart.

### OC4J and Oracle Application Server Administration Tools

In either an Oracle Application Server or standalone OC4J environment, you can deploy and configure your J2EE applications and resource adapters in OC4J through the Application Server Control, introduced in "OC4J Deployment and Configuration Features". This is generally the preferred way to manage your applications, and is therefore emphasized in this document. You can deploy an application through the Application Server Control Console "Deploy" feature in the Applications tab that is accessible from the OC4J Home page. Application Server Control Console pages for resource adapter configuration are discussed throughout this document.

In standalone OC4J, you also have the option of using the command-line OC4J `admin_client.jar` tool to deploy and bind your J2EE applications.

Alternatively, if you use the Oracle JDeveloper tool to develop your application, you can use it to deploy the application and any resource adapters as well.

Also, in some cases and particularly during development, it may be necessary to configure aspects of an OC4J application through direct manipulation of OC4J-specific XML files. For this reason, reference documentation for these files is included in the OC4J documentation set. Elements and attributes of the `oc4j-connectors.xml` and `oc4j-ra.xml` OC4J-specific resource adapter configuration files are documented in Appendix A, "OC4J Resource Adapter Configuration Files".

See the Oracle Containers for J2EE Deployment Guide and Oracle Containers for J2EE Configuration and Administration Guide for general information about using the Application Server Control Console or `admin_client.jar` tool to deploy and manage your applications. There is also extensive online help for the Application Server Control Console.

## Summary of Application Server Control Pages for Resource Adapters

The Application Server Control Console provides a Web-based user interface for deploying, configuring, and monitoring applications, as well as managing the OC4J instance and the Web services used by your applications. It is installed, preconfigured, and started automatically when you install the OC4J software (either in a standalone or Oracle Application Server environment), and is bound to whichever port the OC4J instance is using. In an Oracle Application Server environment, the port is usually 7777. In a standalone environment, the port is typically 8888; use this port of the appropriate host to access the console:

    http://hostname:8888

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

The console is organized into functional areas for applications, administration, performance, and Web services. You can manage resource adapters through the applications area.

Resource adapter configuration procedures in this document start from the Resource Adapter Home page.

The rest of this section covers the following topics:

- How to Get to the Resource Adapter Home Page

- Contents of the Resource Adapter Home Page

- Summary of Pages You Can Reach from the Resource Adapter Home Page

### How to Get to the Resource Adapter Home Page

To get to the home page for a standalone resource adapter:

1. From the OC4J Home page, select the Applications tab.

2. View "Standalone Resource Adapters".

3. Select the resource adapter of interest.

To get to the home page for a resource adapter that was deployed with an application:

1. From the OC4J Home page, select the Applications tab.

2. View "Applications".

3. Select the desired application.

4. From the resulting Application Home page, under "Modules", select the resource adapter module of interest.

### Contents of the Resource Adapter Home Page

Table 2-1 summarizes the resource adapter general properties shown in the home page, noting what XML entities they correspond to or are related to.

Table 2-1 General Properties Shown in the Resource Adapter Home Page

Application Server Control Property | Corresponding or Related XML Entity | Description
--- | --- | ---
Name | `name` attribute of a `<connector>` element in `oc4j-connectors.xml` | The name of the resource adapter, as determined during deployment for a standalone resource adapter (such as through the Application Server Control Console deployment page), or according to the RAR file name, without the `.rar` extension, for a resource adapter deployed within an EAR file.
Status | n/a | Specifies whether the resource adapter is currently up (running). This is according to runtime polling by OC4J.
Path | `path` attribute of a `<connector>` element in `oc4j-connectors.xml` | The directory path from which the RAR file was deployed.
Description | `<description>` subelement of the applicable `<connector>` element in `ra.xml` | An optional description of the resource adapter.
Vendor Name | `<vendor-name>` subelement of the `<connector>` element in `ra.xml` | The vendor that supplies the resource adapter.
EIS Type | `<eis-type>` subelement of the `<connector>` element in `ra.xml` | The EIS for which this resource adapter is designed (for example, OracleAS JMS).
Adapter Version | `<version>` subelement of the `<connector>` element in `ra.xml` | Version number of the resource adapter, as specified by the vendor.
JCA Specification Version | `<resourceadapter-version>` subelement of the `<connector>` element in `ra.xml` | J2EE specification level supported by the resource adapter (either 1.0 or 1.5).
License Required | `<license-required>` subelement of the `<license>` element, which is a subelement of the `<connector>` element in `ra.xml` | A Boolean value specifying whether a license is required for this resource adapter. (There is optionally a `<description>` subelement of `<license>` to describe the licensing terms.)

Table 2-2 summarizes the resource adapter service contract properties shown in the home page, noting what XML entities they correspond to or are related to.

Table 2-2 Service Contract Properties Shown in the Resource Adapter Home Page

Application Server Control Property | Corresponding or Related XML Entity | Description
--- | --- | ---
Communication with EIS | `<inbound-resourceadapter>` and `<outbound-resourceadapter>` subelements of the applicable `<resourceadapter>` element in `ra.xml` Note: These are J2CA 1.5 subelements. | Indicates "inbound" if only `<inbound-resourceadapter>` subelements are found, "outbound" if only `<outbound-resourceadapter>` subelements are found, or "bidirectional" if both are found. Note: For J2CA 1.0, only outbound communication is possible.
Connection Definitions | `<connection-definition>` subelement of the applicable `<outbound-resourceadapter>` element in `ra.xml` Note: These are J2CA 1.5 elements. | Indicates the number of connection definitions (the number of `<connection-definition>` elements) there are for this resource adapter. Note: In J2CA 1.0, there can be only one connection definition for each resource adapter.
Transaction Support | `<transaction-support>` subelement of the applicable `<outbound-resourceadapter>` element in `ra.xml` Note: In J2CA 1.0, `<transaction-support>` is a subelement of `<resourceadapter>`. | Indicates the level of transaction supported by this resource adapter: `NoTransaction`, `LocalTransaction`, or `XATransaction` (global transaction). See "Resource Adapter Configuration for Level of Transaction Support".
Authentication Mechanisms | `<authentication-mechanism>` subelement of the applicable `<outbound-resourceadapter>` element in `ra.xml` Note: In J2CA 1.0, `<authentication-mechanism>` is a subelement of `<resourceadapter>`. | Indicates the type of authentication mechanism supported by this resource adapter, such as `BasicPassword`. (The typical use of a user name and password for sign-on.)
Reauthentication Support | `<reauthentication-support>` subelement of the applicable `<outbound-resourceadapter>` element in `ra.xml` Note: In J2CA 1.0, `<reauthentication-support>` is a subelement of `<resourceadapter>`. | A Boolean value specifying whether the resource adapter supports reauthentication of an existing managed connection instance.

Table 2-3 discusses the message listener types shown in the home page, noting the corresponding XML entities. The elements mentioned are among the definitions under a `<messageadapter>` subelement of an `<inbound-resourceadapter>` element in the `ra.xml` file.

Table 2-3 Message Listener Types Shown in the Resource Adapter Home Page

Application Server Control Property | Corresponding or Related XML Entity | Description
--- | --- | ---
Message Listener Type (an entry for each message listener supported by the resource adapter) | `<messagelistener-type>` subelement of `<messagelistener>` in `ra.xml` (one `<messagelistener>` element for each supported message listener) | The Java type of a supported message listener (such as `javax.jms.MessageListener`). Note: Multiple message listener types can be supported by a single resource adapter.

### Summary of Pages You Can Reach from the Resource Adapter Home Page

Starting from the Resource Adapter Home page, you can reach the following:

- Connection Factories tab: Edit, create, delete, or monitor a connection factory (referring to a particular JNDI location); or edit, create, delete, or monitor a shared connection pool.

  - Create Connection Factory page: Choose the connection factory interface, then specify the JNDI location, mode of connection pooling (if any), and configuration property settings for a new connection factory.

  - Edit Connection Factory page: Set configuration properties, connection pooling, security, and other options for a connection factory.

    - General tab: View configuration properties for connections from the factory. For a connection factory with private connection pooling, you can link from this tab to the Private Connection Pool page to edit parameters such as minimum and maximum number of connections in the pool.

    - Security tab: Set principal mapping entries for declarative container-managed sign-on to the EIS.

    - Options tab: Specify the desired path to a log file, or set the user and password to sign on to the EIS for transaction recovery.

  - Connection Factory Metrics page: Displays connection factory and connection pool metrics to monitor connections.

  - Create Shared Connection Pool page: Set connection pooling parameters (such as minimum and maximum number of connections in the pool) for a new connection pool.

  - Shared Connection Pool page: Modify connection pooling parameters for an existing connection pool.

- Administered Objects tab: Create, edit, or delete an administered object.

  - Create Administered Object page: Specify the JNDI location and set configuration properties for a new administered object.

  - Administered Object page: View configuration properties for an existing administered object.

- Admin istration tab: Set configuration properties for the resource adapter instance, or view the deployment descriptor (`ra.xml`) or proprietary deployment descriptor. Viewing the proprietary deployment descriptor displays the following:

  - The `oc4j-connectors.xml` `<connector>` element for the resource adapter

  - The `oc4j-ra.xml` file for the resource adapter

These pages, and what you can do from them, are discussed in more detail later in this document. You can also find more information in the context-sensitive topics "Resource Adapter Home Page", "Resource Adapter Connection Factories Page", "Resource Adapter Administered Objects Page", and "Resource Adapter Administration Page" in the Application Server Control online help.

## General Resource Adapter Administration Features

This section highlights general configuration features for a resource adapter, covering the following topics:

- Setting Properties of the Resource Adapter JavaBean

- Configuring the Use of Resource Adapter Native Libraries

### Setting Prop erties of the Resource Adapter JavaBean

A resource adapter instance is a JavaBean, which has configurable properties according to the setup in the `ra.xml` file. Consider the following example:

    <connector ... >
       <resourceadapter>
          <resourceadapter-class>
             oracle.j2ee.ra.jms.generic.JMSResourceAdapter
          </resourceadapter-class>
          <config-property>
             <config-property-name>lookupMethod</config-property-name>
             <config-property-type>java.lang.String</config-property-type>
             <config-property-value>resourceProvider</config-property-value>
          </config-property>
          <config-property>
             <config-property-name>resourceProviderName</config-property-name>
             <config-property-type>java.lang.String</config-property-type>
             <config-property-value>MQSeries</config-property-value>
          </config-property>
          ...
       </resourceadapter>
    </connector>

This indicates that `lookupMethod` and `resourceProviderName` are properties of the resource adapter JavaBean.

You can specify new values for resource adapter configuration properties, using the Application Server Control Console as follows:

1. From the appropriate Resource Adapter Home page, choose the Administration tab.

2. From the Administration tab, go to the Configuration Properties task.

3. The resulting Configuration Properties page lists configuration properties for the particular resource adapter. For each property, the assembled value from `ra.xml` is listed, and the current deployed value from `oc4j-connectors.xml` is listed. Given the preceding `ra.xml` example, `lookupMethod` and `resourceProviderName` would be listed.

4. Specify new deployed values as desired. For example, assume `resourceProviderName` is listed with an assembled value of `MQSeries`, as in the preceding example, but you want to change it to `MQSeries2`. Simply specify this in the "Deployed Value" field.

5. Apply the changes.

For more information about pages summarized in the preceding steps, see the context-sensitive topics "Resource Adapter Administration Page" and "Resource Adapter Configuration Properties Page" in the Application Server Control online help.

Note: While Application Server Control enables you to edit configuration properties, a resource adapter may not support dynamic updates. If you try to edit a configuration property in this circumstance, an exception is thrown.

Any new (deployed) value is reflected in a `<config-property>` element in the `oc4j-connectors.xml` file, with appropriate `name` and `value` attributes, as summarized in Table 2-4. Note that `<config-property>` elements have different uses. In this case, `<config-property>` is a subelement of the`<connector>` element for the resource adapter, and that is a subelement of the top-level `<oc4j-connectors>` element in `oc4j-connectors.xml`.

Table 2-4 Resource Adapter JavaBean Configuration Properties

Application Server Control Property | Corresponding XML Entity | Description
--- | --- | ---
As applicable for the resource adapter, and as indicated by configuration property Name, Type, Assembled Value, and Deployed Value. (The Name, Type, and Assembled Value are according to `ra.xml`.) | `<config-property>` `name` and `value` attributes for Name and Deployed Value | These attributes correspond to the name and desired deployed value of a resource adapter JavaBean property.

### Configu ring the Use of Resource Adapter Native Libraries

You can deploy a native library with a resource adapter and instruct OC4J where to find it. A native library is typically a `.dll` file in a Windows environment or a `.so` file in a Solaris environment, for example.

Native library locations are not configurable through Application Server Control Console. Instead, use the `<native-library>` element of the `oc4j-connectors.xml` file to specify a relative location for the library, where the relative path is according to the path of the library in the deployment RAR file for the resource adapter.

For the following RAR file, the path would be "`./`".

    META-INF/ra.xml
    META-INF/oc4j-ra.xml
    howto.html
    images/icon.jpg
    ra.jar
    cci.jar
    mylib.dll

The configuration would therefore be:

    <native-library path="./mylib.dll" />

Or, for this RAR file, the path would be "`/mydir/`":

    META-INF/ra.xml
    META-INF/oc4j-ra.xml
    mydir/mylib.dll
    howto.html
    images/icon.jpg
    ra.jar
    cci.jar

And the configuration would be:

    <native-library path="mydir/mylib.dll" />

The `<native-library>` element is also discussed in "<native-library>".

## Summary of Resource Adapter MBeans and Administration

Standards-compliant MBeans play a role in OC4J runtime configuration. The following sections provide an overview:

- General Overview of OC4J MBean Administration

- Summary of OC4J Resource Adapter MBeans

### General Ov erview of OC4J MBean Administration

OC4J support for the JMX specification allows standard interfaces to be created for managing resources dynamically, including resources relating to resource adapters, in a J2EE environment. The OC4J implementation of JMX provides a JMX client, the System MBean Browser, that you can use to manage an OC4J instance through MBeans that are provided with OC4J.

An MBean is a Java object that represents a JMX manageable resource. Each manageable resource within OC4J, such as an application or a resource adapter, is managed through an instance of the appropriate MBean. Each MBean provided with OC4J exposes a management interface that is accessible through the System MBean Browser in the Application Server Control Console. You can set MBean attributes, execute operations to call methods on an MBean, subscribe to notifications of errors or specific events, and display execution statistics.

Note: This information is provided for reference, but key resource adapter configuration settings are exposed in a more user-friendly manner through other features of the Application Server Control Console. Procedures for particular tasks are described throughout this document.

To access the browser from the OC4J Home page, select the Administration tab and then, under the list of tasks, go to the JMX task "System MBean Browser". From the browser, you can do the following:

- Select the MBean of interest in the left-hand frame.

- Use the Attributes tab in the right-hand frame to view or change attributes. A settable attribute has a field where you can type in a new value. Then apply the change.

- Use the Operations tab in the right-hand frame to invoke methods on the MBean. Select the operation of interest. In the Operation window, you can it with specified parameter settings.

- Use the Notifications tab (where applicable) in the right-hand frame to subscribe to notifications. You can select each item for which you want notification, and then apply the changes.

- Use the Statistics tab (where applicable) in the right-hand frame to display execution statistics.

Be aware that MBeans and their attributes vary regarding when changes take effect. In the runtime model, changes take effect immediately. In the configuration model, some changes take effect when the resource is restarted, others when the application is restarted, and still others when OC4J is restarted. There is also variation in whether changes are persisted.

See the Oracle Containers for J2EE Configuration and Administration Guide for details. The System MBean Browser itself also provides information about the MBeans.

### Sum mary of OC4J Resource Adapter MBeans

OC4J exports a set of MBeans for each resource adapter, to support administration during application runtime. Some OC4J MBeans are required in order to support the J2EE management specification, but may offer extended features. Other OC4J MBeans are Oracle extensions to the model.

Table 2-5 summarizes the OC4J implementations of MBeans, relating to resource adapters, that are required of an application server according to JSR-77. These implementations are in the `oracle.oc4j.admin.management.mbeans` package.

Notes: MBeans marked with a double-asterisk ("**") in the following tables have properties whose changes will not take effect until the resource adapter or OC4J (usually the resource adapter) is restarted. MBeans are self-documenting in the System MBean Browser, providing some documentation of MBean attributes, operations, and notifications (as applicable).

Table 2-5 Mandatory System MBeans for Resource Adapters

MBean | Description
--- | ---
ResourceAdapterModule ** | Identifies a resource adapter archive (RAR file) as a whole, and allows configuration of properties across the archive (possibly extending across multiple resource adapters).
ResourceAdapter ** | Identifies a single resource adapter across an archive.
JCAResource | Identifies a single configured resource from a resource adapter that is available to all components deployed within OC4J.
JCAConnectionFactory ** | Identifies a configured connection factory instance within a resource.
JCAManagedConnectionFactory | Identifies the managed connection factory associated with a connection factory instance.

Table 2-6 summarizes OC4J MBeans, relating to resource adapters, that are Oracle extensions. These MBean implementations are also in the `oracle.oc4j.admin.management.mbeans` package.

Table 2-6 Additional System MBeans for Resource Adapters

MBean | Description
--- | ---
WorkManagerResource | Identifies the work manager associated with a resource.
JCAEndpointActivation | Identifies an endpoint that has been activated to use this resource.
JCAMessageEndpointFactory | Identifies the endpoint factory that is associated with an endpoint activation.
JCAAdminObject | Identifies an administered object supported by this resource adapter.
JCAAdminObjectInstance ** | Identifies a configured instance of one of the administered objects supported by this resource adapter.
JCASharedConnectionPool | Identifies one of the shared connection pools that is defined for this resource adapter.
JCAConnectionPool | Identifies one of the private connection pools that is defined for this resource adapter.
JCAConnectionDefinition | Identifies one of the connection definitions that is packaged with this resource adapter.

## Resource Ada pter Lifecycle: Startup and Shutdown

When a resource adapter is deployed, or when an application server, such as OC4J, is started, the application server requires a mechanism to "bootstrap" (load and initialize) an instance of the resource adapter. When a resource adapter is undeployed or otherwise stopped, or when an application server is stopped, the application server requires a mechanism to notify the resource adapter to stop functioning prior to being unloaded. These functional areas are covered by the J2CA lifecycle management contract.

This section introduces key aspects of this contract, and also covers how to manually stop a resource adapter. The following topics are covered:

- Key APIs of the Lifecycle Management Model

- Understanding the Resource Adapter Startup Process

- Understanding the Resource Adapter Shutdown Process

- Manually Shutting Down or Restarting a Resource Adapter in OC4J

### Key APIs of the Lifecycle Management Model

A resource adapter is implemented by the resource adapter provider as a JavaBean class implementing the following SPI interface:

- `javax.resource.spi.ResourceAdapter`

The resource adapter provider deploys the JavaBean class as part of the overall resource adapter deployment, and also specifies configuration for `ResourceAdapter` instances in the standard `ra.xml` deployment descriptor.

The `ResourceAdapter` interface specifies the following methods that are called by the application server for resource adapter startup and shutdown, respectively:

- `void start(javax.resource.spi.BootstrapContext ctx)`

- `void stop()`

The `BootstrapContext` interface is implemented by the application server, with methods that give access to certain application server resources.

### Understanding the Resource Adapter Startup Process

Resource adapter startup is initiated by OC4J and occurs in the following circumstances:

- When the resource adapter is deployed to OC4J

- When OC4J is restarted after the resource adapter has been deployed

OC4J takes the following steps for resource adapter startup:

1. Instantiates the `ResourceAdapter` JavaBean for this resource adapter, configuring its properties according to specifications in the `ra.xml` file.

2. Creates a `BootstrapContext` instance to pass to the `ResourceAdapter` instance.

3. Calls the `ResourceAdapter` JavaBean `start()` method, passing in the `BootstrapContext` instance.

4. Initializes and binds any connection factories. (See "Introduction to How EIS Connections Are Obtained" for a definition of "connection factory".)

5. Initializes and binds any administered objects. (See "What Is an Administered Object?" for a definition of "administered object".)

The `start()` method is the vehicle by which the resource adapter can execute initialization procedures, establish communications with the EIS, and possibly start the EIS service. Initialization procedures may include, for example, creating threads, setting up network endpoints, or creating objects (such as administered objects) specific to the resource adapter.

The `BootstrapContext` instance has methods giving access to application server resources, such as by returning a `java.util.Timer` instance to schedule future tasks, a `javax.resource.spi.work.WorkManager` instance to manage work units, or a `javax.resource.spi.XATerminator` instance for transaction completion or recovery. The `start()` method may use the work manager to submit work units for execution, or the XA terminator to complete imported transactions. (For information about work management and transaction inflow, see "Overview of the Work Management Contract" and "Overview of Related Contracts for Inbound Communication".)

Notes: The preceding discussion assumes a J2CA 1.5 environment. Only the step involving connection factories is relevant in a J2CA 1.0 environment. The `<start-order>` element in the `oc4j-connectors.xml` file determines the order in which resource adapters are loaded and started by OC4J within an application, or the order in which standalone resource adapters are loaded and started, as applicable. See "<start-order>". If the `start()` method throws an exception, OC4J considers the startup process to have failed and makes no further attempt to call the `start()` method on the same `ResourceAdapter` instance. Instead, it creates a new `ResourceAdapter` instance when it tries to start the resource adapter again. The OC4J `ResourceAdapter` MBean—which includes `start()`, `stop()`, and `restart()` methods to start, stop, or restart a resource adapter—uses the start and stop functionality of the resource adapter JavaBean. (See "Summary of Resource Adapter MBeans and Administration" for information about OC4J MBeans.)

### Understanding the Resource Adapter Shutdown Process

Resource adapter shutdown is initiated by OC4J and occurs in the following circumstances:

- When the resource adapter is undeployed

- When OC4J is shut down

- When you manually stop the resource adapter (described in the next section, "Manually Shutting Down or Restarting a Resource Adapter in OC4J")

Resource adapter shutdown is a two-phase process:

1. In the first phase, OC4J must ensure that all applications and operations that depend on the resource adapter are terminated before the resource adapter is shut down. This includes the following:

   - Deactivate any message endpoints that receive messages through this resource adapter.

   - Stop any applications that use this resource adapter.

   The first phase guarantees that application threads no longer use the resource adapter instance and that all application activities, including transactional activities, are completed.

2. In the second phase, begun only after completion of the first phase, OC4J calls the `ResourceAdapter` JavaBean `stop()` method to notify the resource adapter to stop functioning. This allows it to be safely unloaded.

   When the `stop()` method is called, the resource adapter performs any necessary cleanup and then performs an orderly shutdown. This may include the following:

   - Close network endpoints.

   - Relinquish threads.

   - Release active work units.

   - Allow any transactions in the commit phase to complete.

   - Flush any cached data to the EIS.

   - Unbind and clean up connection factories.

   - Unbind and clean up any administered objects.

Notes: The preceding discussion assumes a J2CA 1.5 environment. In a J2CA 1.0 environment, all that is relevant is the unbinding and cleaning up of connection factories. After the shutdown steps, any application still holding handles to cached connection factories or administered objects may see unexpected behavior. OC4J treats the resource adapter as nonfunctional after the `stop()` method is called. OC4J ignores exceptions from the `stop()` method To restart a resource adapter after it has been stopped, OC4J creates a new `ResourceAdapter` instance, then calls the `start()` method on that instance.

### Manually Sh utting Down or Restarting a Resource Adapter in OC4J

You can manually shut down a resource adapter in OC4J. In the Application Server Control Console, take the following steps from the appropriate Resource Adapter Home page:

1. Choose the Stop function.

2. In the resulting Confirmation page, say Yes to confirm the action.

After shutting down a resource adapter, you can restart it as follows, also from the Resource Adapter Home page:

1. Choose the Start function. (No further steps are necessary.) Status of the resource adapter is displayed on the home page.