|
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 discusses how to configure and manage resource adapter administered objects, including the following topics:
This section provides an overview of administered objects used with resource adapters, covering the following:
An administered object is a utility Java object, provided with a resource adapter, for use by an application component in conjunction with that resource adapter. A resource adapter may or may not provide administered objects. Typically, an administered object is used for messaging and is specific to a particular messaging style or message provider. For example, a Java Message System (JMS) "queue" object may be required to synchronously send and receive messages to Oracle Advanced Queueing through the JMS API. An administered object in J2CA acts as a placeholder for an entity defined elsewhere, such as for the queue object that is defined in the JMS environment. (Administered objects are not necessary for asynchronous messaging, the setup of which involves activation spec JavaBeans instead, as described in "Understanding the Resource Adapter Configuration".)
Classes for administered objects are supplied by resource adapter providers. Each class must be a JavaBean class implementing some appropriate standard interface. Configuration of an administered object includes the following:
Setting any properties, which is accomplished by the resource adapter provider through the ra.xml file for deployment, or later by the OC4J administrator through Application Server Control
Binding the object into JNDI for lookup by application components, which you accomplish through Application Server Control
The next couple of sections discuss examples of two particular kinds of administered object. Many more examples are possible.
The CCI InteractionSpec interface provides the mechanism for holding properties for interactions. (See "What Are the Interface Libraries of the J2EE Connector Architecture?" for information about interactions and the CCI Interaction interface.) An interaction spec implementation must support standard properties that include an EIS function name and "interaction verb", which specifies whether an interaction execution results in synchronously receiving a data record, synchronously sending a data record, or both. There are also standard properties to provide information to an interaction object about result set requirements (fetch size, for example).
An interaction spec instance can optionally be registered as an administered object, allowing application components to look it up in the JNDI namespace through a standard resource environment reference that was specified during deployment.
See version 1.5 of the J2EE Connector Architecture Specification for additional information.
JMS includes two modes of operation, known as "publish/subscribe" and "point-to-point". The publish/subscribe mode uses "topic" objects defined in JMS, and the point-to-point mode uses "queue" objects defined in JMS. In the J2EE Connector Architecture, these messaging modes involve the use of administered objects to act as placeholders for topics and queues, respectively. These administered objects, created by an administrator for use by a JMS client, provide a convenient way to specify configuration information for JMS.
Point-to-point messaging uses queues of messages, with a client sending messages to a single queue and typically having all its messages delivered from a single queue. Most queues are static resources created by an administrator. JMS defines how a client sends messages to a queue and receives messages from a queue.
Publish/subscribe messaging uses message topics, where each topic represents a node of a hierarchy of possible message subjects. The publish/subscribe model specifies how JMS clients can publish messages to a topic or subscribe to messages from a topic. In JMS, a topic object more specifically acts as a broker, gathering messages published to it and distributing messages to subscribers as appropriate. Publishers and subscribers remain independent of each other, and the topic entity adjusts automatically as publishers and subscribers are added or dropped.
A topic is represented by an instance of a class that implements the javax.jms.Topic interface. A queue is represented by an instance of a class that implements the javax.jms.Queue interface. Each encapsulates a provider-specific message destination address. More specifically, a Topic object encapsulates a provider-specific topic name, while a Queue object encapsulates a provider-specific queue name. As administered objects, topics and queues can contain provider-specific configuration information as well.
The Topic and Queue interfaces do not depend on JNDI, but it is a JMS convention to use JNDI to bind and look up Topic and Queue instances. Topics and queues are used for examples later in this chapter.
|
Note: Topics and queues support concurrent use. |
Administered objects are configured for deployment in the ra.xml file, typically by the resource adapter provider, as in the following example for JMS topics and queues. The <adminobject> element is a subelement of the <resourceadapter> element.
<connector ... >
...
<resourceadapter>
...
<!-- Queue admin object -->
<adminobject>
<adminobject-interface>javax.jms.Queue</adminobject-interface>
<adminobject-class>
oracle.j2ee.ra.jms.generic.AdminObjectQueueImpl
</adminobject-class>
<config-property>
<config-property-name>jndiName</config-property-name>
<config-property-type>java.lang.String</config-property-type>
<config-property-value>MQQ</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>
</adminobject>
<!-- Topic admin object -->
<adminobject>
<adminobject-interface>javax.jms.Topic</adminobject-interface>
<adminobject-class>
oracle.j2ee.ra.jms.generic.AdminObjectTopicImpl
</adminobject-class>
<config-property>
<config-property-name>jndiName</config-property-name>
<config-property-type>java.lang.String</config-property-type>
<config-property-value>MQT</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>
</adminobject>
...
</resourceadapter>
...
</connector>
The <adminobject-class> element specifies the administered object class, and the <adminobject-interface> element specifies the interface that this class implements.
The <config-property> elements and their subelements specify the name, type, and deployed value of properties of the administered objects.
For queues, in this example, the JMS Queue interface is implemented by the class AdminObjectQueueImpl. This administered object has the following properties:
jndiName: type String, deployed value MQQ
resourceProviderName: type String, deployed value MQSeries
For topics, in this example, the JMS Topic interface is implemented by the class AdminObjectTopicImpl. This administered object has the following properties:
jndiName: type String, deployed value MQT
resourceProviderName: type String, deployed value MQSeries
(You can change the deployed values later, through Application Server Control, as described in the next section, "Binding and Editing Administered Objects in OC4J".)
|
Note: OC4J instantiates each administered object during resource adapter deployment, as well as at OC4J startup or restart, using the configured property values. |
To use an administered object in OC4J, you must initially use the Application Server Control "Create" function to bind it to a JNDI location. You can also edit property values at this time, or at a later time. Changes take effect when the resource adapter is restarted. The following sections describe the steps involved:
OC4J binds each administered object into the JNDI namespace. For resources to be directly visible from java:comp/env, there must be an appropriate resource reference. You would accomplish this using a <resource-ref> element in either the web.xml file (for Web modules) or the ejb-jar.xml file (for EJB modules). Even without such a resource reference, though, you can do a lookup according to the JNDI location that you specify when you bind the administered object.
To use an administered object you must create it and bind it, using the following steps in the Application Server Control Console:
Go to the Administered Objects tab from the appropriate Resource Adapter Home page.
Choose the "Create" function.
In the resulting Create Administered Object page, choose an administered object class. The list of available classes is according to the <adminobject-class> elements in the ra.xml file.
In the next Create Administered Object page, specify a JNDI location.
Optionally specify any new values for the configuration properties. The list of available configuration properties and their initial values is according to the ra.xml configuration of the administered object class you select.
Apply the changes.
Also see the context-sensitive topics "Create Administered Object - Select Class Page" and "Create Administered Object Page" in the Application Server Control online help.
When you create and bind an administered object, OC4J makes appropriate entries in the oc4j-connectors.xml file. For each administered object, OC4J writes an <adminobject-config> element, which is a subelement of the top-level <connector> element. The <adminobject-config> element includes the following:
location attribute for the JNDI location, such as:
<adminobject-config location="mqjms/MyQ" >
<adminobject-class> subelement for the name of the implementing class, such as:
<adminobject-class>
oracle.j2ee.ra.jms.generic.AdminObjectQueueImpl
</adminobject-class>
<config-property> subelement for each property of the administered object, with name and value attributes, such as:
<config-property name="jndiName" value="MQQ" /> <config-property name="resourceProviderName" value="MQSeries" />
Table 7-1 summarizes the correlation between Application Server Control properties and corresponding attributes and subelements of <adminobject-config> elements in the oc4j-connectors.xml file.
Table 7-1 Administered Object JNDI Location and Configuration Properties
| Application Server Control Property | Corresponding XML Entity | Description |
|---|---|---|
|
Object Class |
|
JavaBean class that represents an administered object. |
|
JNDI Location |
|
JNDI location of an administered object instance. |
|
Name (under configuration properties) |
|
Name of a configuration property of an administered object. |
|
Value (under configuration properties) |
|
Value of a configuration property of an administered object. |
|
Note: You can create and bind multiple administered objects for any given administered object type that is defined in thera.xml file.
|
You can edit the property values of an administered object you previously created. Existing administered objects are identified by their JNDI locations (and you cannot change a location).
Use the following steps in the Application Server Control Console:
Go to the Administered Objects tab of the appropriate Resource Adapter Home page.
Choose the JNDI location of the administered object you want to edit.
In the resulting Administered Object page, you can view the configuration properties of the administered object. Additionally, you can specify new values for any editable configuration properties as desired.
Apply the changes.
Also see the context-sensitive topic "Administered Object Page" in the Application Server Control online help.
Once administered objects have been deployed and configured, as described previously, they can be accessed by application components through JNDI lookups.
For this discussion, following up on earlier discussion of JMS topics and queues in this chapter, assume administered objects for topics and queues have been deployed with JNDI locations mqjms/MyT and mqjms/MyQ, respectively.
Further assume the topics and queues will be used in a servlet, with the following resource environment reference mapping in the web.xml file:
<web-app ... >
...
<resource-env-ref>
<resource-env-ref-name>jms/TOPIC1</resource-env-ref-name>
<resource-env-ref-type>javax.jms.Topic</resource-env-ref-type>
</resource-env-ref>
<resource-env-ref>
<resource-env-ref-name>jms/QUEUE1</resource-env-ref-name>
<resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
</resource-env-ref>
...
</web-app>
And assume there has been Web module configuration, such as through Application Server Control, that results in the following mapping, as reflected in the orion-web.xml file:
<orion-web-app ...>
...
<resource-env-ref-mapping name="jms/QUEUE1" location="mqjms/MyQ" />
<resource-env-ref-mapping name="jms/TOPIC1" location="mqjms/MyT" />
...
</orion-web-app>
The preceding entries map actual JNDI locations (such as mqjms/MyQ) to logical JNDI locations (such as jms/QUEUE1). These entries allow a servlet to look up a topic as follows:
InitialContext ic = new InitialContext();
Topic ourT = (Topic)ic.lookup("java:comp/env/jms/TOPIC1");
And allow a servlet to look up a queue as follows:
InitialContext ic = new InitialContext();
Queue ourQ = (Queue)ic.lookup("java:comp/env/jms/QUEUE1");
