Chapter 5   Programming Model


This chapter describes the UIF application programming model used inside your J2EE components, for example, Servlets, JSPs and EJBs.

This chapter contains the following sections:

• Data Objects

• Using the UIF API

• Developing J2EE I18N Applications with UIF

Data Objects

---

A function object is the fundamental unit of interaction with the enterprise connector. Data objects are typically used as input and output parameters to the function objects. The application programmer is responsible for preparing the input data objects, executing the function object, and interpreting the output data object, through the UIF API. The UIF data object interface:

• Presents a unified and abstract representation of EIS data types

• Supports most primitive data types

• Provides the ability to construct and interpret complex data

Data objects are built from primitive data types. In general, a primitive data object contains a primitive value, for example an integer or a string. A complex data object is a list, an array, or a structure.

As part of the data mining process, the administrator populates the repository with the data object definitions. The application programmer needs to follow these definitions to construct, and interpret the input and output data objects when interacting with the EIS. Data object construction and interpretation is described in the Using the UIF API.

---

Note

The data objects represent data in a hierarchal fashion and circular references are not allowed. UIF only prevents adding a data object as an attribute of itself, the application programmer is responsible for preventing indirect circular references. If a circular reference is made via another object, it is not discovered when the reference time is established. If a circular reference is used at runtime, unpredictable results occur.

---

Primitive Objects

A primitive data type object contains a single value of one of the following types:

• Integer, float, double

• Fixed length string or variable length string

• Fixed size byte array or variable size byte array

When a primitive data object is assigned to a list, array, or structure, the data object is unwrapped and its value is copied into the list, array, or structure. The data object itself is not used. When a primitive value is obtained by using an untyped get method, such as getField(), getElem(), getAttr(), or getCurrent(), the returned value is wrapped in a primitive data object. In this case, the value is copied, modifying the returned primitive data object does not change the source object.

Strings correspond to the Java string data type. A fixed length string has a maximum length, whereas a variable length string has no length restriction. A fixed size byte array has a maximum size, whereas a variable size byte array has no size restriction.

In general, when a new value replaces an old value, the old value is released. Therefore, when a new value is assigned to a variable length string or a variable size byte array, the old value is released. When a new value is assigned to a fixed length string or a fixed size byte array, the new value is copied over the old one. For a fixed length string, the copied string is truncated to fit if necessary. For a fixed size byte array, a shorter array is zero filled on the right, and a longer array is truncated to fit.

The maximum length of a fixed length string and the maximum size of a fixed size byte array are set when they are first set. For example, when setting a list element to contain a fixed length string, the string's maximum size is set when added to the value. In the following example, the maximum length of the fixed length string set to an element in a list is four characters:

list.addElemFString("abcd");

Attempting to replace the string with a five character string (abcde), the last character (e) is truncated.

---

Note

The length of the fixed length string is its maximum length; not its current length, because its current length may be less than its maximum length. The size of a byte array is its maximum size; not its current size, because the byte array may not be filled to capacity. When The iPlanet Application Server is running in I18N mode, UIF takes care of preparing the Fixed Strings to accommodate the incoming multibyte character set values, based on the datasource character set configuration information. For a detailed description on the default character set, available EIS character set and how to specify them, see your specific iPlanet Enterprise Connector Developer's and Administrator's Guides.

---

Structure Objects

Structure objects contain other data objects or primitive values as fields. Each object within the structure object is referred to by a string that represents the field name. Field names have a maximum length of 64 characters.

List Objects

A list object contains data objects or primitive values as elements in the list. These elements can be heterogeneous. Each element within a list object is referred to by an integer that specifies its position in the list object.

Array Objects

An array object, like a list object, contains data objects or primitive values as elements in the object. Array objects inherit from list objects. The difference between an array object and a list object is that the array's elements must be homogeneous. Each element within the array object is referred to by an integer that specifies its position in the array object.

Type Info Objects

Type info objects are structure objects that contain the type information of a data object. For example, a type info object might define the fields in a structure, and their corresponding data types. Instances of data objects can be created from type info objects. These instances each contain a reference to a type info object. Many data objects can share the same type info object.

DataObjectInfo Type	Target Object
IBSPDataObjectPrimitiveInfo describes the type number, size of value (if type is string or binary), and default value	IBSPDataObjectPrimitive
IBSPDataObjectStructureInfo describes the type info of all fields of the structure. The type info of each field is in turn described by a type info object	IBSPDataObjectStructure
IBSPDataObjectListInfo describes the initial capacity and maximum element count of the list	IBSPDataObjectList
IBSPDataObjectArrayInfo describes the initial capacity, maximum element count and the type info of elements of the array	IBSPDataObjectArray

API Naming Conventions

Most methods in the API conform to a naming convention that specifies

• Kind of operation: typically, get or set

• Target: a list, structure, and so on

• Type of target: an int, string, and so on

For example, the method that sets a list element from a string is setElemString(). The following table shows the possible combinations:

Operation	Target	Type
get set	NONE (Primitive) Attr (complex dataObject, such as a list, array, or structure); uses path to address attribute Elem (List/Array); uses index to address element Field (Structure); uses name to address field Current (Itr); addresses object iterator is currently on.	Int Float Double String FString Binary VBinary dataObject NONE

Attributes and Paths

In the UIF API, methods of the IBSPDataObject interface do not distinguish between an element in a list or array, or a field in a structure. In this case, the element or field is referred to as an attribute.

The path to an element is its element number, beginning with 0. The path to a field is its field name. Combining element numbers and field names are used to create paths to attributes in complex data objects. For example, a structure field containing a list of elements. In these cases, specifying the path as the individual attributes separated by dots (.). For example, use "field1.[0]" to identify the first list element at field1 in the structure.

Changing Data Types

If an attribute's type is primitive, it cannot change. For example, the following code causes an error because it tries to change the primitive type from an integer to a float:

list.addElemInt(100); // assume 100 is added to element 1
list.setElemFloat(1, 3.14); // fails because element 1 type is int

The following example shows how to change the data type of a non-primitive data:

list.addElemDataObject(aStruct); // add a structure to element 1
list.setElemDataObject(1, array); // change to array

Interface Hierarchy

The following diagram shows the interface hierarchy for data object interfaces:

Using the UIF API

---

The UIF programming model gives fine grained control to the application programs. The usage of the UIF API should broadly follow these steps:

• Acquiring the UIF Runtime Object

• Creating a Service Provider Object

• Creating a Function Object

• Setting Up and Executing the Function Object

The following sections provide examples of how to perform these tasks.

Acquiring the UIF Runtime Object

The runtime object is the entry point into UIF. It is both the object factory and the access point for creating other objects.

The following sample shows how to acquire a runtime object from a Servlet:

private IBSPRuntime getRuntime()

{

com.kivasoft.IContext _ctx = ((com.netscape.server.servlet.platformhttp.PlatformServletContext)
getServletContext()).getContext();

   IBSPRuntime ibspruntime = access_cBSPRuntime.getcBSPRuntime
         (_ctx, null, null);
   return ibspruntime;   

}

Creating a Service Provider Object

The service provider is a logical representation of a connection to an EIS. Typically, the service provider is not bound to a physical connection until it is absolutely necessary. A service provider must be enabled before it can be used.

The following sample shows how to create a service provider object:

private IBSPServiceProvider getServiceProvider(IBSPRuntime runtime)

{

   if (runtime != null)
      return runtime.createServiceProvider("<connector>", "<connector>_spname");
   else

   return null;

}

where, "<connector>" is the datasource name, and "<connector>_spname" is a service provider name defined for that datasource.

Creating a Function Object

A function object is a group of related operations that share a common state. In UIF, a function object needs to be set up and associated with a service provider before the function object can be executed.

The following sample shows how to create a function object:

IBSPFunctionObject fn = null;

...
{

   fn = runtime.createFunctionObject("<connector>", "phonebook");

}

where, "<connector>" is the datasource name and "phonebook" is the function object name in the repository.

Setting Up and Executing the Function Object

To execute a function object, your Servlet must perform the following actions:

1. Create and enable the service provider

2. Create the function object and associate it to the service provider

3. Prepare the function object and set the input parameters in the datablock

4. Execute the function object

5. Retrieve the output parameters from the function block

6. Disable the service provider

The following sample shows how to set up and execute a function object.

IBSPDataObject getCustomerDetail(String custId)

{

IContext ctx = null;

IBSPServiceProvider sp = null;

IBSPRuntime runtime = null;

IBSPDataObject result = null;

try {

   // Get context

   ctx = ((com.netscape.server.servlet.platformhttp.PlatformServletContext)g etServletContext()).getContext();

   // Get UIF runtime

   runtime = access_cBSPRuntime.getcBSPRuntime(ctx, null, null);

   // Create ServiceProvider 'conn' under datasource 'HR'

   sp = runtime.createServiceProvider("HR", "conn");

   // Enable the ServiceProvider

   IBSPDataobject config = sp.getConfig();

   config.setAttrString("WebUserId", m_UserId);

   sp.enable();

   // Create the target FunctionObject 'getCustomerDetail'

   IBSPFunctionObject fn = runtime.createFunctionObject("HR",
   "getCustomerDetail");

   // Associate the FunctionObject with the ServiceProvider

   fn.useServiceProvider(sp);

   // Prepare the FunctionObject for execution of operation 'doit'

   fn.prepare("doit");

   // Set inputs in datablock

   IBSPDataObject data = fn.getDataBlock();

   data.setAttrString("INPUT.custId", custId);

   // Execute the FunctionObject

   fn.execute();

   // Retreive outputs from datablock

   result = data.getAttr("OUTPUT.custDetail");

}

// Catch any exception which may be thrown

catch (BspException)

{

   // BspException actions

}

// Disable the ServiceProvider (regardless of whether an exception was thrown)

finally

{

if (sp != null)

   sp.disable();

}

return result;

}

Executing Multiple Function Objects

An application may need to execute several functions objects or repeatedly execute a single function object within a Servlet, JSP, or EJB. To repeatedly execute a function object, follow these steps:

1. Prepare the function object

2. Set the input parameters

3. Execute the function object

4. Retrieve the results

5. Loop as many times as needed

To execute several function objects, the application can create and associate multiple function objects with the same service provider at any point, and execute them. Some enterprise connectors support transactions that are started and terminated by an enterprise connector specific function object operation(s). For these enterprise connectors, a transaction context is associated with the service provider instance. All function objects using this service provider instance execute as part of the transaction associated with the service provider at that time.

Developing J2EE I18N Applications with UIF

---

UIF supports the development of J2EE I18N applications using various character sets supported by iPlanet Application Server. To use UIF in I18N mode, please make sure that the iPlanet Application Server is running in International mode. For details on how to run the iPlanet Application Server in International mode, please refer to iPlanet Application Server documentation.

UIF datasources are configured to operate using a specific character set, that is specified in the UIF Repository. UIF uses the datasource character set to prepare the buffer sizes to accommodate multibyte character data with FString data type. For a detailed description on the Enterprise Connectors default character set, allowed operating character set and how to specify them, see your specific iPlanet Enterprise Connector Developer's and Administrator's Guides.

For details on how to write J2EE I18N applications, please refer to the following documentation:

• Java Servlet API Specification, Version 2.2, located on the web at http://java.sun.com/products/servlet/2.2/, sections 5.8 Internationalization (The Request) and 6.4 Internationalization (The Response).

• JavaServer Pages Specification, Version 1.1, located on the web at http://java.sun.com/products/jsp/download.html, section 2.7.4 Delivering Localized Contents.

• Designing Enterprise Applications, Version 1.0, located on the web at http://java.sun.com/j2ee/download.html#blueprints, section 4.5 Internationalization and Localization.