Chapter 3   Working With Data Objects


The applications programmer needs to be able to understand and know how to use the UIF API to develop a servlet, or EJB, which communicates with the backend system. The UIF API is an object-oriented framework.

The iPlanet Application Server Enterprise Connector for PeopleSoft is used to execute PeopleSoft functions on a remote PeopleSoft server. The servlet or EJB uses the PeopleSoft connector to access the PeopleSoft server.

This chapter describes the procedures for acquiring UIF objects and executing function objects. The following topics are described:

• Data Objects

• UIF API Naming Conventions

• Working with Servlet Samples

Data Objects

---

A data object is used by UIF to represent data or metadata in a generic fashion.

Data objects are used to exchange data between a servlet and UIF, and between UIF and the connector.

iPlanet Application Server Enterprise Connector for PeopleSoft allows you to access data through the data-object interface.

The data-object interface:

• presents a unified representation of backend data types

• represents complex data

• supports most common primitive data types.

The types of data objects are:

• Primitive Objects

• Structure Objects

• Array Objects

• Type Information Objects

Primitive Objects

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

• integer, float, double

• fixed-length string, variable-length string

Figure 3-1    Primitive Object

integer, float, double

Integer, float, and double-data type objects hold a value whose type corresponds to the Java data type.

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.

fixed-length string, variable-length string

Strings correspond to the Java string data type. A fixed length string has a maximum length, whereas a variable length string has no restrictions by the connector or UIF.

The maximum length of a fixed-length string is set when the string's initial value is specified, in example four characters as shown in the following line:

list.addElemFString("abcd")

A fixed length string is truncated if it is longer than the string's initial value.

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. A structure's fields are heterogeneous.

Figure 3-2    Structure Object

Circular references are not allowed. iPlanet Application Server Enterprise Connector for PeopleSoft prevents a data object being used as an attribute of itself. Indirect circular references are not checked by iPlanet Application Server for PeopleSoft.

---

Caution

No error message is generated if an indirect circular reference is defined. Unpredictable results occur if a circular reference is used at runtime.

---

Array Objects

An array object contains data objects or primitive values as elements in the object. Array elements must be homogeneous. Each element within the array object is referred to by an integer that specifies its position in the array object.

Figure 3-3    Array Object

Type Information Objects

Type information objects are structured objects that contain the type information of a data object; for example, the definition of the fields in a structure and the fields corresponding data types. Instances of data objects can be created of type information objects. Each of these instances contain a reference to a type of information object. Numerous data types can share the same type information object.

Table 3-1 Type Information Objects

DataObjectInfo Type	Target Object
IBDPDataObject contains information about the structure of the data; for example, types, value.	IBSPDataObject
IBSPDataObjectPrimitiveInfo describes the type number, size of value (if type is string or binary), and the default value.	IBSPDataObjectPrimitive
IBSPDataObjectStructureInfo describes the type info of all fields of the target structure. The type info of each field is in turn described by a type info object.	IBSPDataObjectStructure
IBSPDataObjectListInfo describes the initial capacity and maximal element count of the target list.	IBSPDataObjectList
IBSPDataObjectArrayInfo describes the initial capacity, maximal element count and the type info of elements of the target array.	IBSPDataObjectArray

UIF API Naming Conventions

---

Methods in the UIF API conform to a naming convention that specifies the following:

• operation

• target

• type

The following example shows a UIF API method:

getElemString()

get is the operation, Elem is the target, and String is the type.

Operation

There are many types of operations but the two most commonly used are:

• get

• set

Target

The targets are:

• None (primitive)

• Attr (complex DataObject such as a list, array, or structure) that uses path to address attribute.

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

  The path to an element is its element number, beginning from zero. The path to a field is its field name. Element numbers and field names can be combined to create paths to attributes in complex data objects, such as a field of a structure that contains a list of elements. In this case, you specify the path as the individual attributes separated by periods (.); for example, use "field1.[01]" to identify the first element of a list at field1 in the structure.

• Elem (list/array) uses index to address element.

• Field (structure) uses name to address field.

• Current (itr) addresses object iterator is currently on.

Type

The types of operations are:

• Int

• Float

• Double

• String

• FString

• DataObject

• None

  
  

  ---

  Note	The PeopleSoft connectors do not support image data types.

  ---

  
  

Changing Attribute Types

An attribute type can not be changed. Code Example 3-1 causes an error because it tries to change the type of a primitive object from an integer to a float.

Code Example 3-1 Changing Data Types

---

list.addElemInt (100) ; // assume 100 is added to element 1

list.setElemFloat (1, 3.14) ; // fails because the type of element is int

You can change the data type of non-primitive, as in the following example:

list.addElemDataObject (aStruct) ; // add a structure is to element 1

list.setElemDataObject (1, array) ; // change to array succeeds

Working with Servlet Samples

---

To execute an operation the servlet must be capable of the following:

• Acquiring the UIF Runtime Object

• Creating the Service Provider Object

• Creating Function Objects

• Setting Up and Executing the Function Object

The following examples show how to carry out 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.

Code Example 3-2 shows how to acquire a runtime object.

Code Example 3-2 Acquiring the UIF Runtime Object

---

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 the Service Provider Object

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

Code Example 3-3 shows how to create the service provider object.

Code Example 3-3 Creating the Service Provider Object

---

private IBSPServiceProvider getServiceProvider(IBSPRuntime runtime)

{

deb.println("Before createServiceProvider()");

if (runtime != null)

return runtime.createServiceProvider("PSFT", "connection");

else

deb.println("runtime is null");

return null;

}

Table 3-2 defines the function object parameters.

Table 3-2 Service Provider Object Typs

Parameter	Definition
PSFT	Data source name
connection	Service provider name

Creating Function Objects

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

Function object definitions, which represent business-methods available for execution on the specific enterprise systems, are derived from metadata mined from the enterprise system.

Code Example 3-4 shows how to create the function object.

Code Example 3-4 Function Object

---

IBSPFunctionObject fn = null;

...

if(   runtime != null )

{

deb.println("Before getServiceProvider()");

sp = getServiceProvider(runtime);

deb.println("After getServiceProvider()");

if( sp != null )

{

deb.println("Before createFunctionObject()");

fn = runtime.createFunctionObject("PSFT", "ProcessMsg");

}

}

Table 3-3 defines the function object parameters.

Table 3-3 Function Object Parameters

Parameter	Definition
PSFT	Data source name
ProcessMsg	PSFT function name

Setting Up and Executing the Function Object

To Set Up and Execute the Function Object:

1. Specify and enable the service provider.

2. Set the web-user ID that represents the web domain and will be mapped to the backend domain.

3. Prepare the function object, set up the propertySet, and set the input parameters in the function object's data block.

4. Execute the function object.

5. Retrieve the output parameters from the function block.

6. Disable the service provider.

Code Example 3-5 shows how to set up and execute the function object.

Code Example 3-5 Setting Up and Executing the Function Object

---

public void execute (String WebUserId) throws Exception, BspException

{

IBSPFunctionObject fn = null;

IBSPDataObject data = null, prop = null;

IBSPServiceProvider sp=null;

int hr = 1;

try

{

IBSPRuntime runtime = getRuntime();

if(   runtime != null )

{

sp = getServiceProvider(runtime);

if( sp != null )

{

IBSPDataObject config=sp.getConfig();

config.setAttrFString("WebUserId",WebUserId);

fn = runtime.createFunctionObject("PSFT", "ProcessMsg");

hr = sp.enable();

if(hr!=0)

return;

if( fn != null )

{

hr = fn.useServiceProvider(sp);

if(hr!=0)

return;

hr = fn.prepare("Execute");

if(hr!=0)

return;

data = fn.getDataBlock();

if( data != null )

setInputData(data);

prop = fn.getProperties();

if( prop != null )

setInputProperties(prop);

hr = fn.execute();

if( hr == 0 )

{

data = fn.getDataBlock();

if(data != null )

getOutputData(data);

prop = fn.getProperties();

if(prop != null)

getOutputProperties(prop);

} // if(hr == 0)

else

deb.println("Execute Failed");

} // if(fn != null)

else

deb.println("Create function object Failed");

} // if( sp != null )

else

deb.println("Create service provider Failed");

hr = sp.disable();

}

else

deb.println("Create runtime Failed");

}

catch(BspException BspError)

{

.

.

.

Deploying a Connector Application

---

A developer creates an application on a development machine and then deploys the application to an application server. Deployment of an application includes installing all application files and registering all components on the destination server.

In addition to deploying the servlet you must create and import the XML files, which describe the function objects, to the repository. For more details on how to do this, see the iPlanet Application Server Enterprise Connector for PeopleSoft Administrator's Guide.

You can deploy the servlet in one of the following ways:

• Using the Deployment Tool

• Using the Command Line to Deploy

The following sections describe the above mentioned methods of deployment.

Using the Deployment Tool

The iPlanet Application Server Deployment Tool is a GUI-based tool that allows you to:

• Package J2EE Application Components Into Modules

• Assemble the Module Into a Deployable Unit

• Deploy the Unit to One or More iPlanet Application Server Operating Environments

Package J2EE Application Components Into Modules

J2EE application components are archived into modules according to the container that receives them upon deployment. You can archive J2EE application components into an EJB JAR module (archived with a JAR extension) or a Web Application module (archived with a WAR extension). Each module also contains a J2EE and an iPlanet Application Server-specific deployment descriptors saved to XML files.

Assemble the Module Into a Deployable Unit

J2EE modules that comprise an application are assembled into a single application Enterprise Archive (EAR) file. The application EAR file also contains a J2EE deployment descriptor saved to an XML file. Depending on your requirements, the EAR file might also contain alternate deployment descriptor XML files to be used in deployment.

---

Note	EAR archives are meant to be cross-platform and will work no matter where you build the archive. For example, you can successfully deploy EAR files that you have built on NT to Solaris and vice versa.

---

Deploy the Unit to One or More iPlanet Application Server Operating Environments

At deployment, the EAR file is copied to the targeted iPlanet Application Server environments. Some archived application files are automatically distributed to their appropriate directories on one or more instances on iPlanet Application Server and then registered with iPlanet Application Server. For example, static HTML files,

Using the Command Line to Deploy

A Web Application Module can be deployed as a stand-alone unit or can be packaged with other modules to create an application .ear file. The .ear file contains all the modules with the application components required to run an application, along with component-level and application-level deployment descriptor files.

After you create an EAR file or a module that you may want to deploy, you may want to register it automatically via a batch file at a scheduled time and date. In this case, you would create the EAR file or module as you normally would using the Deployment Tool, but you would not use the tool for deployment.

For more detailed information on Deployment, consult the Deployment Tool Outline Help, which installs as part of the iPlanet Application Server Deployment Tool.