Chapter 1   Concepts


This chapter describes the iPlanet Unified Integration Framework (UIF) concepts. Also included are topics you need to be familiar with before setting up UIF or before using the UIF Application Programming Interface (API) in Java 2 Enterprise Edition (J2EE) components.

This chapter contains the following sections:

• About UIF

• UIF Architecture

• UIF Abstractions Overview

• UIF Tools

• UIF API

• UIF Application Development Model

Refer to the "Glossary" for descriptions of terms used in this guide.

About UIF

---

UIF is used to build interactive web-based applications on top of disparate enterprise data sources. Specifically, UIF allows the accessing of data on a supported Enterprise Information System (EIS) using the UIF APIs via a Servlet, a JavaServer Page (JSP) or an Enterprise JavaBean (EJB) running in an iPlanet Application Server.

The UIF APIs include functionality found traditionally on various low level EIS APIs. Consequently, application developers are able to use the UIF APIs and service descriptions in the UIF repository to bring the EIS data and services to the web sooner, since they can bypass the need to learn the low-level EIS APIs.

In addition, UIF supports I18N features of iPlanet Application Server. When the iPlanet Application Server is running in I18N mode, UIF allows locale and character set specific J2EE components to interact with the respectively configured enterprise data sources.

UIF Architecture

---

UIF is designed to be easy to use, scalable, and reliable service inside the iPlanet Application Server. This section explains the UIF architecture and UIF's role in process-based or J2EE applications.

Figure 1-1 shows the relationship between a Servlet, JSP, or EJB running in the iPlanet Application Server, UIF, and the EIS.

Figure 1-1    UIF Overview

The UIF architecture includes a common set of APIs used to access data, UIF Runtime, UIF data repository, and an enterprise connector that implements the specific EIS data access services.

Application developers use the UIF APIs to uniformly access data. UIF runtime provides the connection management, thread management, resource pooling, user mapping, and the enterprise connector interaction services. A platform specific enterprise connector implements a UIF to enterprise connector contract, and provides the translation, data marshalling and unmarshalling between the UIF and the EIS. The UIF repository holds parameters and information about the EIS system, like the EIS definitions, data types, and business functions.

Figure 1-2 shows the UIF architecture layers, components and functions. In addition it also shows the application layer comprising of J2EE Applications or iPlanet Process Manager (iPM) applications or generic tools.

Figure 1-2    UIF Architecture Layers

A runtime snapshot of the UIF architecture comprises of the UIF APIs, UIF repository, UIF runtime, and the enterprise connector.

• UIF APIs - Java APIs for the application programmer to facilitate interactions with the enterprise connector.

• UIF Repository - A Lightweight Directory Access Protocol (LDAP) based repository which is used at runtime. The datasource administrator loads the UIF Repository at development time. The UIF Repository contains the datasource, function object and data object definitions. These definitions are used at runtime in order to instantiate the in-memory representation and interacts with the enterprise connector.

• UIF Runtime - This core piece enables all interactions between the application, repository and the enterprise connector. When the application requests to load a datasource for interaction, UIF runtime instantiates the in-memory representation of an EIS instance, which contains information on the location of the datasource and other access parameters. Further interactions on that datasource are facilitated by the UIF runtime, by loading the function object definitions from the repository and letting the application set the data object values and interacting with the enterprise connector by using various interaction models, such as Request/Response, Send/Receive etc. (UIF currently supports Request/Response model only), to execute the fully prepared function object.

• Enterprise Connector - The enterprise connector acts as a bridge between the UIF and the EIS. It adheres to the UIF interaction contract, and provides connectivity and interaction to the EIS. An enterprise connector, comes with a data mining and administration tools to mine the service definitions and interaction definitions into the UIF repository from the EIS.

  UIF in combination with a specific set of EIS enterprise connectors are used to build interactive web-based eBusiness applications and analytical applications for human resource management, financial, distribution, manufacturing, and supply chain management within an enterprise system.

UIF Abstractions Overview

---

The UIF runtime is based on the following abstractions and services:

• UIF Internal Runtime Services

• Repository Schema and Definitions

• Enterprise Connector

• Execution Control Flow

Figure 1-3 shows a detailed view of the UIF components with an example of an iPlanet R/3 Enterprise Connector.

Figure 1-3    UIF Components

UIF Internal Runtime Services

The UIF internal runtime services include the following services:

• Data Object Service

• Repository Service

• Metadata Service

• User Mapping Service

• Runtime Service

Data Object Service

The Data Object (DO) service implements a universal data representation object. A DO is a hierarchical data representation object, somewhat like a C/C++ structure. It can contain structures, arrays and lists, nested to arbitrary levels. DOs are self describing and support introspection. Programmatically, a DO is addressed using path names like A.B[2].C, and can iterate over DOs contents using iterators.

DOs pass all information and data across API boundaries between the application and UIF, and between UIF and the enterprise connector. The structural flexibility and introspectability of DOs allows the APIs between the three layers to be well defined and fixed.

Creation and destruction of DOs potentially has a high performance penalty due to their dynamic structure and flexibility. To reduce the potential penalty DOs are optimized via memory management and object reuse.

Repository Service

The Repository service models a persistent hierarchy of information that is like LDAP, but with a higher level of data contents. Persistence is provided on top of LDAP. The Repository service API is not exposed to the application. The Repository service users are mainly the UIF runtime and the enterprise connector management consoles.

Leaf nodes in the repository are either primitive key value nodes or complex data object type definition (dataTypes) nodes. Most data type nodes in the repository represent metadata mined from the EIS. They define types for parameter data blocks, configuration information blocks, and user mapping structures.

Data type nodes can be embedded and reused by other data type definitions. Also, a given data type can be used in multiple contexts where the field values for the data types are initialize in the different contexts. The fields are initialize via a template node which includes a data type reference and the initial field values for the data types.

The repository service maintains a read only cache of objects which are populated on demand. The cache does not refresh itself from LDAP once loaded. Therefore, changes to LDAP does not reflect in the repository service until the application server (KJS) is restarted. Note that the repository contains information which determines the enterprise connector behavior and cannot be used while in an inconsistent state. Changes to the repository are not updated until the application server is restarted.

The repository browser allows users to explore the repository contents. The tool has no editing features, however it does provide import, export, delete, and refresh actions on repository nodes. The repository contents are imported from the enterprise connector management console. An export function is also available via the repository browser which exports any subtree as an Extensible Markup Language (XML) document.

Although the repository service does not impose any specific organization (schema) on the repository contents, the UIF runtime requires the contents to be organized in a specific and well defined way. This organization is the UIF repository schema. Therefore, repository contents are not supposed to be arbitrarily modified by the user. Contents are modified as part of specific administration activities controlled by the management console, which makes appropriate programmatic use of the import and export functions. In addition, the UIF runtime service runs a consistency check on repository contents at startup.

Metadata Service

The Metadata service is used mainly by the UIF runtime service and is responsible for instantiating data objects from data type and template definitions in the repository. It also manages object reuse via data object freelists. The freelists are organized by data type and allow the administrator to set an upper boundary on memory usage, as well as other tuning parameters.

User Mapping Service

The User Mapping service has two separate user identity domains: web and EIS. An incoming request has a specific web user identity associated to it. The web identity needs to be mapped to an EIS user identity specific to the datasource.

The web user identity is set in the service provider configuration by the application. The enterprise connector maps the web user identity to the EIS user identity when the service provider is enabled (session state is created). The EIS user identity is maintained as part of the session state.

The User Mapping service maintains the user mapping tables. There are two distinct tables: EIS user identities and web-to-EIS mappings. The mapping service provides the enterprise connector with methods to determine an EIS user identity, given a web user identity as per the mapping tables. The EIS user table is loaded via a user mining function in the enterprise connector management console. The datasource administrator loads the user mapping table interactively via the management console (refer to your specific iPlanet Enterprise Connector Administrator's Guide).

Runtime Service

The Runtime service supports the EIS interaction abstraction and elements which support the interaction. The service currently supports only synchronous request and response interaction model. The runtime service includes core services for connection pooling and lifecycle management, thread management, conversation and session state management, and exception management. Most importantly, the service interprets UIF repository datasource information to create a UIF datasource object.

Two primary element objects of the UIF runtime are the serviceProvider and functionObject.

serviceProvider Object
A serviceProvider object represents a communication session with a specific datasource. The application creates a service provider by supplying a path to the definition in the repository. A serviceProvider's configuration (set by the datasource administrator) points to the EIS with the appropriate connection pooling and lifecycle management settings.

Underlying the serviceProvider is a connection object which is native to the enterprise connector and represents the EIS physical connection. The object is not readily understood by the UIF runtime. However, it is the UIF runtime's responsibility to manage the creation, destruction, and reuse (pooling and lifecycle management) of connection objects via callbacks into the enterprise connector. These settings are also part of the serviceProvider definition in the repository.

A serviceProvider has a session state object associated with it. This is used by the enterprise connector to keep session associated information, such as transaction identity and user identity. This state is not exposed to the application and the state object interacts with J2EE transaction and security models.

functionObject Object
A functionObject instance represents a specific business method available for execution on the datasource. The application creates a functionObject by supplying a path to the datasource definition in the repository. A functionObject definition is created by the data mining tool from metadata residing on the EIS.

A functionObject has one, but sometimes more enterprise connector specific operations defined on it. These operations execute enterprise connector specific interaction steps. For example, an R/3 functionObject may define a single execBAPI operation; whereas an MQseries functionObject may define three operations - SEND/POLL/RECEIVE. When executed, an operation passes data to and from the enterprise connector via a data block. Since this data block represents inputs and outputs for a specific functionObject, data blocks of different function objects usually are of different data types.

In order to execute an operation, a functionObject requires a communication session. A communication session associates a serviceProvider with a functionObject before using the functionObject. A connector type may allow several functionObject interactions to execute over the same serviceProvider, in which case the interactions share session state (for example, transaction and user identity). A single functionObject interaction is also called a conversation, which occurs over a session. The conversation can also have a state which is shared by the operations which drive the conversation.

Repository Schema and Definitions

The UIF repository contains enterprise connector mined information on the EIS specific services, their input and output details, and other configuration information. This section explains the contents of the repository, how they are organized, and how UIF uses them.

The UIF runtime requires a specific organization in the repository. Currently no mechanism enforces this organization. In addition, the UIF runtime runs a schema validation check at startup.

Broadly, the organization has two sections: adapterTypes and dataSources. The adapterType section contains one subtree entry per enterprise connector. The entry contains common definitions which form the basis for defining datasources on that connector type. The adapterType entry is created when an enterprise connector is installed.

The dataSource section contains subtree entries, each of which is a logical UIF datasource. A datasource corresponds to a specific EIS and is supported by the corresponding connector type. Multiple datasources may be defined for a single connector type, if there are multiple EISs of the same type.

---

Note

Datasources are defined depending on the EISs at a particular installation. The datasource definition activity is tightly controlled by the management console. There are two distinct user roles with datasources - the datasource administrator and the application developer. The datasource administrator is responsible for creating and administering datasource entries, while the application developer develops applications which access these datasources. A datasource definition is usually heavily preconfigured by the datasource administrator. Therefore, the application developer uses preconfigured function objects (much like using EJBs with deployment descriptor values already set).

---

Broadly, a datasource definition contains:

• serviceProvider definitions which represent a communication session to a specific EIS.

• Connection pool definitions.

• Data type definitions derived from metadata mined from the specific EIS.

• functionObject definitions which represent business methods available for execution on the specific EIS (for example, storedProc, prepared query, R/3 BAPI, PeopleSoft message, or CICS txn). These definitions are derived from metadata mined from the EIS.

• EIS user identity and user mapping tables.

• Connector type specific configuration information which controls the enterprise connector's interaction with the specific EIS.

Please refer to Chapter 3 "Repository" for details.

Enterprise Connector

The enterprise connector's main responsibility is to act as a bridge between UIF and EIS. It manages the communication with the EIS, and data marshalling and unmarshalling between data objects and EIS formats. The UIF provides an enterprise connector side contract consisting of several interfaces which the enterprise connector implements in order to integrate with UIF. The EIS specific implementation of this contract is the essence of an enterprise connector. The UIF and enterprise connector contract interfaces are broadly separated into the following three categories:

• Connection pooling callbacks - used for creating, matching and reserving, returning, and destroying connections.

• Communication model callbacks - used for creating and destroying conversation and session state objects.

• Execution callbacks - used for executing operations. All data marshalling and unmarshalling is done here.

The enterprise connector also has an exception throwing mechanism. The enterprise connector can throw an exception which propagates upwards through the UIF layer and emerges in the Java application as a Java exception. For enterprise connector specific exception information refer to your specific iPlanet Enterprise Connector Developer's Guide.

Management Console

The management console is used to view and change an EIS configuration in the UIF Repository. Each enterprise connector has a specific management console. However, all management consoles allow an administrator to perform the following tasks:

• Create a new datasource

• Configure a datasource, for example, setting connectivity and I18N parameters to the specific EIS instance

• Configure pooling parameters

• Mine and load function objects into the respository

• Configure user mapping

• Monitor and manage EIS specific functions, for example, a CICS relay program

For enterprise connector specific management console information refer to your specific iPlanet Enterprise Connector Administrator's Guide.

Enterprise Connector-to-EIS Architecture

Figure 1-4 shows the components overview between the Enterprise Connector and the EIS.

Figure 1-4    Enterprise Connector to EIS

The enterprise connector lives as part of the application server during runtime and gets replicated as the iPlanet Application Server replicates.

The enterprise connector uses an EIS specific client access layer to provide the connection and interaction. The enterprise connector uses an EIS specific client access layer to supply the connection. The connection protocol between the client access layer and EIS, is EIS specific (usually Transmission Control Protocol/Internet Protocol (TCP/IP), but in some cases other protocols are used, for example CICS uses SNA LU 6.2). UIF maintains a connection pool for each EIS and each connection is reused for multiple application requests.

Depending on the specific EIS, establishing communication between the enterprise connector and EIS may require installing an extra components on the EIS. For example, CICS requires a relay program. For more information about pooling, see Chapter 4 "Pooling Concepts".

Execution Control Flow

The application developer uses the repository browser and decides to execute a specific function object under a specific datasource. General usage and control flow are outlined below (not all steps and callbacks are described):

1. Creates the service provider by specifying a repository path

2. Sets the service provider configuration data object fields (for example, web userid)

3. Enables the service provider

4. Creates the function object by specifying a repository path

5. Associates the service provider with the function object

6. Sets the inputs on the data block of the function object

7. Executes the operation on the function object

8. Disables the service provider

   Refer to the Chapter 5 "Programming Model" for further details.

UIF Tools

---

The UIF tools consist of the Repository Browser, the Enterprise Connector specific management console, and Data Mining tool, and are used as follows:

• The Repository Browser - is used to view the repository contents, and to import and export EIS metadata. It allows developers to discover EIS business functions available for execution.

• The Management Console - is used to browse or change the enterprise connector configuration, and to monitor EIS status. Each enterprise connector has an enterprise connector specific management console.

• The Data Mining Tool (is part of the management console and is not a separate tool) - is used to determine the EIS's available transactions, and to load its meta information into the repository as function objects available for execution by a J2EE application.

Figure 1-5 shows the tools used to configure UIF.

Figure 1-5    iPlanet Application Server to EIS Connection

UIF API

---

UIF provides a Java API to enable a J2EE application developer to uniformly interact with the disparate datasources. The API gives fine grained control over the interaction with the EIS. Please refer to the Chapter 7 "API Reference" for details.

UIF Application Development Model

---

After installing UIF and the enterprise connector on the iPlanet Application Server and the EIS, its time to develop a J2EE Component to invoke an EIS-based transaction. The following steps are recommended:

1. Run the data mining tool from the management console to create repository entries for function objects which need to be execute. For more information on the management console, refer to your specific iPlanet Enterprise Connector Administrator's Guide.

2. Import the EIS services as function objects using the management console.

3. Select the datasource in the repository browser to view the:
   1. service provider definition for the configuration attributes needed to establish a connection

   2. function object definition to determine:

      Use these parameters for the UIF API methods to call.

      1. what (if any) property set attributes are required

      2. what inputs are expected in the data block

      3. what outputs are defined in the data block

   For more information about using the repository browser, see Using the UIF Repository Browser.

4. Write the J2EE components which use the UIF API. For an overview of the UIF API and sample code, see Chapter 5 "Programming Model". For more details about the UIF API, see Chapter 7 "API Reference".

5. After writing and testing a Servlet, JSP, or EJB, use the iPlanet Application Server Deployment Manager to deploy the application. Explicitly deploy the repository contents by exporting its contents to XML and importing the XML file on the deployment machine. For more information about exporting and importing XML files, see Using the UIF Repository Browser. For information about iPlanet Application Server deployment, see the iPlanet Application Server Deployment Guide.

Its now time to execute a J2EE component within your application. Refer to the Chapter 5 "Programming Model" for further details.