Instantiating Objects and Resolving References

When developing an XML operation, you specify which methods the XML operation calls. To call these methods at runtime, the web service requires certain objects. For each method call, it locates or instantiates:

• An instance of the class in which the method is defined
• An instance of each class required by the method as a parameter

To perform this task, the web service maintains a reference to each of these target objects and a definition of how to instantiate an object of the appropriate class should the target object not exist. As you add method calls to an XML operation, default object references and target object definitions are automatically added to the web service. These defaults are usually appropriate and do not need editing.

However, you can manually specify the target of an object reference, and you can edit and create new target object definitions to suit your requirements. You might need to manually resolve object references to enterprise beans that were created outside of the IDE.

This section provides instructions that explain how to:

• Specify the target of an object reference
• Define a new target object
• Edit a target object definition

---

Specifying the Target of an Object Reference

To specify the target of an object reference:

1. Open the Resolve Object References dialog box.

In the Explorer, right-click your web service and choose Resolve Object References. The Resolve Object References dialog box (see FIGURE B-1) is displayed.

 FIGURE B-1 Resolve Object References Dialog Box

[ D ]

If your web service has references to XML operations, the table in the dialog box has an additional column displaying XML operation names, as illustrated in FIGURE B-2.

 FIGURE B-2 Resolve Object References Dialog Box With XML Operations

2. Locate the object reference you want to edit.

Object references are listed at the top of the dialog box in table format. Each row represents one reference. The following table describes the columns.

Column Name	Description
Target Class	Class of object required by the reference.
XML Operation	Name of XML operation that holds the reference to the target object.
Usage	Indicates how the XML operation uses the target object. There are two possible uses. The XML operation can: Call a method on the target object Pass the target object as a parameter to a method call This column provides the name of the method that is called and shows (by use of an asterisk) how the target object is used to facilitate the method call. For example, a value of *.getCustomer indicates that a method named getCustomer is called on the target object. A value of updateCustomer(customerInfo:*) indicates that the target object is passed as the customerInfo parameter to a method named updateCustomer.
Target Object	Name of object that resolves the reference.

3. Select an object to resolve your reference.

In the row representing the object reference you are editing, click in the Target Object column and select an object from the list that drops down. This list displays all available objects of the required class, which includes target objects already defined in this dialog box.

---

Defining a New Target Object

If none of the target objects already defined is appropriate for your object reference, you can define a new target object.

To define a new target object:

1. Open the Resolve Object References dialog box.

In the Explorer, right-click your web service and choose Resolve Object References. The Resolve Object References dialog box is displayed (see FIGURE B-1).

2. Select the reference for which you want to define a new target object.

The dialog box displays the definition for the current target object.

3. Click Add Target Object.

The New Target Object dialog box is displayed.

4. Type a name for the target object in the Target Object Name field.

5. Click OK.

The dialog box automatically resolves your reference to the newly defined target object. Your new target object uses the same definition as the previous one. Only the name by which it is referenced is changed. For instructions on editing the definition, see Editing a Target Object Definition.

---

Editing a Target Object Definition

The target object definition specifies how the web service:

• Locates a target object that is already instantiated
• Instantiates a new target object

A web service can have multiple references that resolve to the same target object. For example, the same session bean might be used in many XML operations in the web service. In such a scenario, editing the target object definition affects each of these references because they all resolve to the same object. If this behavior is inappropriate for your application, you might need to create a new target object definition for one or more of your references. For instructions on creating a new definition, see Defining a New Target Object.

To edit a target object definition:

1. Open the Resolve Object References dialog box.

In the Explorer, right-click your web service and choose Resolve Object References. The Resolve Object References dialog box is displayed (see FIGURE B-1).

2. Edit the Name field, if necessary.

This field specifies the name by which the target object can be referenced. The target object's value is also displayed in the Target Object column in the list of object references at the top of the dialog box. This field is required.

3. Edit the Scope field, if necessary.

This required field defines the scope within which the target object can be referenced. Options are:

• Session. The target object can be referenced by all XML operations in the session for the duration of the session.
• Message. The target object can be referenced only during the execution of the client request that instantiated it. Because only one XML operation is executed per request, access to the target object is limited to that one XML operation. Each time the XML operation is executed, a new target object is created.

---

Note - Your choice of scope has no effect on the runtime characteristics of a web service that you create in the current release of the Sun ONE Studio 4, Enterprise Edition for Java IDE.

---

4. Edit the Source field, if necessary.

This field specifies the type of mechanism by which the target object is obtained or instantiated. Options are:

• Enterprise JavaBean. The target object is the remote or home interface of an enterprise bean. A home interface is obtained through a JNDI lookup. A remote interface is obtained through a method call to the corresponding home interface.
• Constructor. The target object is returned by a call to a constructor method on the target class.
• Static Method. The target object is returned by a call to a static method.

5. Edit the remaining fields, if necessary.

The Source field affects which other fields in the dialog box are displayed and enabled for input. Edit the remaining fields in the dialog box by referring to the descriptions in whichever of the following tables is appropriate for your target object's source.

If the source is an enterprise bean, refer to TABLE B-1.

TABLE B-1 Fields Enabled When Source Field Is Set to Enterprise JavaBean

Field	Description
EJB Name	Canonical name of the enterprise bean as defined in the EJB module deployment descriptor.
EJB Type	Type of enterprise bean, either entity or session. Required.
EJB Ref Name	String in the JNDI lookup that specifies the target object. The default value is the value of the Name field, prefixed with the string ejb/. Required.
EJB Remote Interface	Remote interface of the enterprise bean. Required even if the target object is the home interface.
EJB Home Interface	Home interface of the enterprise bean. Required.
Method	Find or create method called on the home interface to return the remote interface. A find method is used for an entity bean and a create method is used for a session bean. Required only if the target object is a remote interface.

If the sources is a constructor, refer to TABLE B-2.

TABLE B-2 Fields Enabled When Source Field Is Set to Constructor

Field	Description
Class	The class in which the constructor of the target object is defined. This field is automatically filled in when you select a constructor for the Constructor field. Read-only.
Constructor	Constructor method used to instantiate the target object. The class of the constructor is specified in the Class field. Required.

If the sources is a static method, refer to TABLE B-3.

TABLE B-3 Fields Enabled When Source Field Is Set to Static Method

Field	Description
Class	The class in which the static method that returns the target object is defined. This field is automatically filled in when you select a static method for the Static Method field. Read-only.
Static Method	Static method used to instantiate the target object. Required.

6. Map method parameters to sources, if necessary.

If the Map Parameters button is enabled, follow these steps to provide values for parameters of the method specified in the Method, Constructor, or Static Method field.

a. Click Map Parameters.

The Map Parameters dialog box is displayed.

 FIGURE B-3 Map Parameters Dialog Box

b. Locate the row that represents the parameter you want to map.

Each row represents one method parameter. If your method takes multiple parameters, use the Parameter Name column to identify the parameters. This column gives the names of the parameters if the method is provided as source code. If the method is provided in a JAR file, the Parameter Name column indicates the order in which the method requires the parameters by displaying names such as param1, param2, and so on.

c. Specify a value type for your parameter.

Click in the Value Type column and select an option from the list. The following table describes the options.

Option	Description
Constant	Maps the parameter to the value specified in the Value field.
Environment Entry	Maps the parameter to the value of the environment entry specified in the Value field. For information on setting environment entries, see .
Target Object	Maps the parameter to the object specified in the Value field. The object can be a target object defined in the web service's Resolve Object References dialog box.
Input Document Element	Maps the parameter to the input document element specified in the Value field. The data type of the input document element must be an object (for example, String); it cannot be a primitive (for example, it cannot be int). For information on declaring the data type of an input document element, see .

d. Specify a value for your parameter in the Value field.

The following table explains how to specify a value depending on your parameter's value type.

Value Type	User Action
Constant	Type a literal value in the Value field.
Environment Entry	Type the name of an environment entry in the Value field. For information on setting environment entries, see .
Target Object	Click the Value field and select an object from the list. The list includes all target objects of the class specified in the Data Type field that are defined in the web service.
Input Document Element	Click the Value field and select an input document element from the list. The list includes input document elements that are both: Of the specified data type Defined in each XML operation that references the target object The second requirement ensures that the parameter you are mapping has a source for its value in all circumstances. For example, two XML operations could reference the same target object, but you might not know which XML operation will be executed first. Therefore, each of these XML operations must provide a value for the parameter so that no matter which is executed first, a parameter value is available. For more information on input document elements, see .