Previous Contents Index DocHome Next |
iPlanet Application Server Enterprise Connector for R/3 Developer's Guide |
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 back-end system. The UIF API is an object-oriented framework.The iPlanet Application Server Enterprise Connector for R/3 is used to execute R/3 functions on a remote R/3 server. The servlet or EJB uses the R/3 connector to access the R/3 server.
This chapter describes the procedures for acquiring UIF objects and executing function objects.
The following topics are described:
Data Objects
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 R/3 allows you to access data through the data-object interface.
presents a unified representation of back end data types
The types of data objects are:
Primitive Objects
Primitive Objects
A primitive data-type object contains a single value of one of the following types:
Integer, float, double
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, for example four characters as shown in the following line:
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 R/3 prevents a data object being used as an attribute of itself. Indirect circular references are not checked by iPlanet Application Server for R/3.
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 field's corresponding data types. Instances of data objects can be created from 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.
UIF API Naming Conventions
Methods in the UIF API conform to a naming convention that specifies the following:The following example shows a UIF API method:
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:
None (primitive)
Attr (complex DataObject such as a list, array, or structure) that uses path to address attribute.
Elem (list/array) uses index to address element.
- 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.
Type
The types of operations are:
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.
Working with Servlet Samples
To execute an operation the servlet must be capable of the following: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.
Creating the Service Provider Object
The service provider object is the logical representation of a connection to a back-end 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.
Table 3-2 defines the function object parameters.
Table 3-2 Standard Provider Object Types
Creating Function Objects
A function object is a group of related operations that share a common state. In iPlanet Application Server for R/3, 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.
Table 3-3 defines the function object parameters.
Table 3-3 Function Object Parameters
Setting Up and Executing the Function Object
To Set Up and Execute the Function Object
Specify and enable the service provider.
Code Example 3-5 shows how to set up and execute the function object.Set the web-user ID that represents the web domain, which is then mapped to the back-end domain.
Prepare the function object, set up the propertySet, and set the input parameters in the function object's data block.
- Refer to the following section, R/3 User Management, for details.
R/3 User Management
The application programmer provides a WebUserId to the R/3 Enterprise connector, which determines the R/3 authorization context to be used to process the request. The WebUserId must be set with the configuration structure of the service provider before enabling by calling the enable() method.Code Example 3-6 illustrates how to set WebUser-test as the WebUserId before enabling the service provider.
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.You can deploy the servlet in one of the following ways:
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 R/3 Administrator's Guide, Chapter 3 - Managing Data: The Data Mining Tool.
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 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.
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 the iPlanet Application Server and then registered with iPlanet Application Server; for example, static HTML files.
Using the Command Line to Perform Deployment
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.
Previous Contents Index DocHome Next
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.
Last Updated November 01, 2000