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 |

# 7 Managing Administered Objects

This chapter discusses how to configure and manage resource adapter administered objects, including the following topics:

- Introduction to Administered Objects

- Understanding Deployment Configuration of Administered Objects

- Binding and Editing Administered Objects in OC4J

- Looking Up Administered Objects

## Introduction to Administered Objects

This section provides an overview of administered objects used with resource adapters, covering the following:

- What Is an Administered Object?

- Example: What Is an Interaction Spec?

- Example: What Are JMS Topics and Queues?

### What Is an Administered Object?

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.

### Example: Wh at Is an Interaction Spec?

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.

### Example: Wh at Are JMS Topics and Queues?

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.

## Understa nding Deployment Configuration of Administered Objects

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.

## Binding and Editing Administered Objects in OC4J

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:

- Create and Bind an Administered Object

- View or Edit an Administered Object

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.

### Cre ate and Bind an Administered Object

To use an administered object you must create it and bind it, using the following steps in the Application Server Control Console:

1. Go to the Administered Objects tab from the appropriate Resource Adapter Home page.

2. Choose the "Create" function.

3. 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.

4. In the next Create Administered Object page, specify a JNDI location.

5. 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.

6. 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 | `<adminobject-class>` subelement | JavaBean class that represents an administered object.
JNDI Location | `location` attribute | JNDI location of an administered object instance.
Name (under configuration properties) | `name` attribute of `<config-property>` subelement | Name of a configuration property of an administered object.
Value (under configuration properties) | `value` attribute of `<config-property>` subelement | 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 the `ra.xml` file.

### View or Edit an Administered Object

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:

1. Go to the Administered Objects tab of the appropriate Resource Adapter Home page.

2. Choose the JNDI location of the administered object you want to edit.

3. 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.

4. Apply the changes.

Also see the context-sensitive topic "Administered Object Page" in the Application Server Control online help.

## Looking Up Administered Objects

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");