|
Oracle® Containers for J2EE Resource Adapter Administrator's Guide
10g Release 3 (10.1.3) B14436-01 |
|
 Previous |
 Next |
|
Oracle® Containers for J2EE Resource Adapter Administrator's Guide
10g Release 3 (10.1.3) B14436-01 |
|
|
Previous |
Next |
This chapter provides a top-level discussion of how to administer your resource adapters, covering the following topics:
Before discussing resource adapter administration, we summarize OC4J features in the following areas:
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 (JSR-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 (JSR-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 deployment 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. |
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.
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:
To get to the home page for a standalone resource adapter:
From the OC4J Home page, select the Applications tab.
View "Standalone Resource Adapters".
Select the resource adapter of interest.
To get to the home page for a resource adapter that was deployed with an application:
From the OC4J Home page, select the Applications tab.
View "Applications".
Select the desired application.
From the resulting Application Home page, under "Modules", select the resource adapter module of interest.
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 |
|
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 |
|
Status |
n/a |
Specifies whether the resource adapter is currently up (running). This is according to runtime polling by OC4J. |
|
Path |
|
The directory path from which the RAR file was deployed. |
|
Description |
|
An optional description of the resource adapter. |
|
Vendor Name |
|
The vendor that supplies the resource adapter. |
|
EIS Type |
|
The EIS for which this resource adapter is designed (for example, OracleAS JMS). |
|
Adapter Version |
|
Version number of the resource adapter, as specified by the vendor. |
|
JCA Specification Version |
|
J2EE specification level supported by the resource adapter (either 1.0 or 1.5). |
|
License Required |
|
A Boolean value specifying whether a license is required for this resource adapter. (There is optionally a |
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 |
Note: These are J2CA 1.5 subelements. |
Indicates "inbound" if only Note: For J2CA 1.0, only outbound communication is possible. |
|
Connection Definitions |
Note: These are J2CA 1.5 elements. |
Indicates the number of connection definitions (the number of Note: In J2CA 1.0, there can be only one connection definition for each resource adapter. |
|
Transaction Support |
Note: In J2CA 1.0, |
Indicates the level of transaction supported by this resource adapter: |
|
Authentication Mechanisms |
Note: In J2CA 1.0, |
Indicates the type of authentication mechanism supported by this resource adapter, such as |
|
Reauthentication Support |
Note: In J2CA 1.0, |
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) |
|
The Java type of a supported message listener (such as Note: Multiple message listener types can be supported by a single resource adapter. |
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.
Administration 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.
This section highlights general configuration features for a resource adapter, covering the following topics:
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:
From the appropriate Resource Adapter Home page, choose the Administration tab.
From the Administration tab, go to the Configuration Properties task.
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.
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.
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 |
|
These attributes correspond to the name and desired deployed value of a resource adapter JavaBean property. |
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>".
Standards-compliant MBeans play a role in OC4J runtime configuration. The following sections provide an overview:
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.
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:
|
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. |
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:
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.
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:
Instantiates the ResourceAdapter JavaBean for this resource adapter, configuring its properties according to specifications in the ra.xml file.
Creates a BootstrapContext instance to pass to the ResourceAdapter instance.
Calls the ResourceAdapter JavaBean start() method, passing in the BootstrapContext instance.
Initializes and binds any connection factories. (See "Introduction to How EIS Connections Are Obtained" for a definition of "connection factory".)
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:
|
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:
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.
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:
|
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:
Choose the Stop function.
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:
Choose the Start function. (No further steps are necessary.) Status of the resource adapter is displayed on the home page.
