Operations on business objects

This section describes operations that involve manipulating business objects and their values. It includes these operations:

Creating a new business object

Use the constructor method new to create a new business object.

Syntax

new 
 
 BusObj(String busObjType)
 

Parameters

busObjType
The name of a business object definition

Return value

An object of type BusObj.

Exceptions

ObjectException - Raised if the business object argument is invalid.

Notes

This method creates a business object with no values. You set the values when you populate the attributes.

If an attribute in the new business object is defined as a child business object or child business object array, you must explicitly create the child business object and associate it with the attribute; for more information, refer to "Creating a child business object in a new business object".

Example

The following example uses the Customer business object definition to create a new business object called destinationCustomer. The new business object is created but has no attribute values.

BusObj destinationCustomer = new BusObj("Customer");
 

Creating a child business object in a new business object

When you create a new business object, an attribute that is defined to contain a child business object of cardinality one or n has no value. For that attribute to have value, you must explicitly create a child business object or child business object array and then associate it with the attribute. This section shows how to do that for a single child business object and for an array.

Creating a single child business object

The following steps illustrate first creating a new business object and then creating a child business object that is contained in one of its attributes:

  1. Use the new method to create a parent business object.
  2. Use the new method to create one child business object of the type for which the attribute is defined.
  3. Use the BusObj.set() method to set the attribute value in the parent object to the new child business object.

The following example illustrates the creation of a new Invoice business object, which has an attribute called SoldToAddressAttribute. This attribute holds the address of the sold-to customer and is a business object of type Address. The example shows the association between the parent business object and the child business object.
// Declarations BusObj invoice = new BusObj("Invoice"); // Create child business object in invoice invoice.set("SoldToAddressAttribute", new BusObj("Address"));

If the collaboration needs to manipulate the child business object, the example might look like this:
// Declarations BusObj invoice = new BusObj("Invoice"); BusObj soldToAddress = new BusObj("Address"); // Manipulate child business object soldToAddress // Associate child business object soldToAddress with parent invoice invoice.set("SoldToAddressAttribute", soldToAddress);

Creating a child business object array

In this section, the following steps illustrate creating a new business object and then creating a child business object array that is contained in one of its attributes:

  1. Use the new method to create a business object. This is the parent business object.
  2. For the attribute in the parent that is defined to contain a business object with cardinality equal to n, create one business object of the attribute's specified type.
  3. Set the parent's attribute value to the new single business object.
  4. Declare a BusObjArray object, get the value of the attribute, and assign it to the array.

You can then use methods of the BusObjArray class to add elements or perform other operations on the business object array.

The following example illustrates the creation of a new Bill of Materials business object, the creation of a child business object array for its LineItems attribute, and the placing of additional business objects on the array.
// Declarations BusObj bom = new BusObj("Bill_Of_Materials"); BusObjArray lineItemArray = null; BusObj singleLineItem = new BusObj ("LineItem"); // Create first child item bom.set("LineItemsAttribute", singleLineItem); //If there are additional line items, do this once lineItemArray = bom.getBusObjArray("LineItemAttribute"); // Now do this for each additional child item lineItemArray.addElement(new BusObj("singleLineItem"));

Copying the triggering event

The first action of every scenario should handle the scenario's flow trigger. Process Designer Express automatically declares a variable of BusObj type called triggeringBusObj; this variable holds the flow trigger ( triggering event or triggering access call) that caused the scenario to execute.

Process Designer Express also automatically declares template BusObj variables for each defined port. The name of the BusObj variable matches the port name, with BusObj appended.

For example, suppose the triggering event for a scenario is Customer.Create. The port that receives the triggering event is called SourceCust. Process Designer Express automatically declares a variable named SourceCustBusObj, combining the port name with the BusObj suffix. In this case, Process Designer Express displays the following variable declaration:
BusObj SourceCustBusObj = new BusObj("Customer");

You can add the following code fragment to copy the triggering event to SourceCustBusObj.
SourceCustBusObj.copy(triggeringBusObj);

Many collaborations are triggered by multiple types of business objects. You must first determine the type of the business object before you can create a business object to hold the flow trigger. Use the BusObj.getType() method on the flow trigger to first ascertain its type, then create the appropriate type of business object, and finally copy the flow trigger to the newly created business object.
sourceBusObj = new BusObj(triggeringBusObj.getType()); sourceBusObj.copy(triggeringBusObj);

Tip:
It is good programming practice to first copy the triggeringBusObj variable to another variable before you do any operations on it.

Copying or duplicating a business object

There are two methods that move values from one business object into another business object: copy() and duplicate(). Both methods deal with the entire hierarchy of a business object, copying the parent business object and all of its children. Table 35 describes both methods.

Table 35. Comparison of the copy() and duplicate() methods
Method Description
copy() Sets all the attribute values of an existing business object to those of another business object.
duplicate() Creates a new business object by cloning an existing business object. Reproduces both the attribute values and the verb. The return value for this method must be assigned to a variable.

The difference between the two methods is mainly the preexistence of the business object where you want to put the copied values.

Copying

Before you use the copy() method, there must be an existing business object to which you want to copy values. Use the new method to create the business object if it does not exist.

The following example copies the attribute values contained in a Customer business object received from the source application to a business object that will be sent to the destination application:
BusObj destination = new BusObj("Customer"); destination.copy(sourceBusObj);

Note:
The copy() method copies the entire business object, including all child business objects and child business object arrays. This method does not set a reference to the copied object. Instead, it clones all attributes; that is, it creates separate copies of the attributes.

Duplicating

In contrast to the copy() method, duplicate() creates a complete clone of an existing business object and returns it.

The following example clones the source business object and assigns it to a variable called destination:
BusObj destination = sourceBusObj.duplicate();

Using attribute values

Collaborations frequently retrieve the values of attributes contained in business objects that they have received.

If a collaboration needs to do something with an attribute value it has received, it should check to make sure that the attribute value is not null before using it (see "Checking for nulls").

Checking for nulls

To check for a null attribute value, a collaboration calls BusObj.isNull(attribute). A null value usually appears for one of the following reasons:

The following code sample sets a value in a billing business object, using data received in an Order business object. If the received order data is itself null or blank, then the code sets the attribute to "Unknown."
//Check whether ProductLine is null or blank; if so, default it if (order.isNull("ProductLine") || order.isBlank("ProductLine")) { logInfo("Setting ProductLine to default Unknown"); order.set("ProductLine", "Unknown"); } //Now set Billing object's equivalent attribute to the same value billing.set("ProductLine", order.get("ProductLine");

The isNull() method can be used on all types of attributes, including those that contain child business objects or child business object arrays.

Comparing an attribute value with a known value

A collaboration can use the Java programming language equals() method to check the value of an attribute against a specific, expected value. The equals() method compares the expected value with the retrieved attribute value, as the following example shows. Call equals() on the known object and compare it to the unknown attribute.

In this example, Smith is the value expected in the LName attribute.


String name = "Smith"; boolean checkName=name.equals(CustBusObj.get("LName"));

Retrieving the attribute

This section covers types of operations for retrieving attributes. These operations are presented in order of increasing complexity:

Retrieving an attribute of a basic type

The BusObj.get() methods retrieve attribute values that are of basic types. Basic types for an attribute are the supported primitives, as Table 36 shows.

Table 36. Retrieving attributes of basic data types
Basic data type Method to set attribute
boolean
getBoolean()
double
getDouble()
float
getFloat()
int
getInt()
long
getLong()
Object
get()
LongText
getLongText()
String
getString()

The following example retrieves the contents of the Credit-Limit attribute, which is an int.
int creditLimit = customer.getInt("Credit-Limit");

If you do not know the data type of the attribute, use the form of the get() method that retrieves a Java Object data type.

Note:
The get() method returns a copy of the attribute. It does not return an object reference to this attribute in the source business object. Therefore, any change to attribute in the source business object is not made to the value that get() returns. Each time this method is called, it returns a new copy (clone) of the attribute.

Retrieving an attribute from a child business object

If an attribute is a business object type, the cardinality defined in the business object definition specifies whether the attribute contains a single business object or an array. If the cardinality is:

The following example retrieves the single-cardinality Address business object contained in the SoldToAddress attribute of a Bill of Materials business object.
BusObj addr = new BusObj("Address"); addr = bom.getBusObj("SoldToAddress");

The following example searches for sold-to addresses in the United States. The business object structure is:

Setting attribute values

This section covers three types of operations for setting attributes. These operations are presented in order of increasing complexity:

Setting an attribute of a basic type

The BusObj.set() methods set attribute values that are of basic types. Basic types for an attribute are the supported primitives: boolean, double, float, int, long, Object, and String.

All the set() methods have the same name but their signatures differ: the first parameter is always a String containing the name of the attribute whose value is to be set. The second parameter is a variable or constant that is a primitive type, a String object, or an Object type. You call the same set() method regardless of the type of the variable; the method is overloaded so that it accepts a variable of any type. The compiler determines which variation of the method to use.

The following example sets the values of two attributes: FirstName and Salary.
Customer.set("FirstName", "Sue"); Customer.set("Salary", 30500);

You can use the BusObj.get() and BusObj.set() methods to copy attribute values from one business object to another. The following example gets the String variables HeaderId and ServiceId from the source business object and sets the attributes HeaderId and SalesNum in the destination business object to those values.


DestinationBusObj.set( "HeaderId", SourceBusObj.getString("HeaderId")); DestinationBusObj.set( "SalesNum", SourceBusObj.getString("ServiceId"));

Note:
The set() method sets an object reference to the value when it assigns the value to the attribute. It does not clone the attribute value from the source business object. Therefore, any changes to the value in the source business object are also made to the attribute in the business object that calls set().

Setting an attribute in a single child business object

To set an attribute in a child business object whose cardinality is equal to 1, you must first get a handle to the child business object.

Use the BusObj.getBusObj() method to get a handle or reference to the child business object and assign the results to a BusObj type variable. Then call the BusObj.set() method; this invokes the overloaded version of the method that matches the data type of the attribute.

The example that follows is based on Figure 69. The Customer business object has an attribute called Address, which is a reference to a child business object called CustAddress.

Figure 69. Single child business object


The code example does the following:

  1. Declares a variable called addr
  2. Retrieves the Customer business object's Address attribute and assigns it to addr
  3. Sets the City attribute
    BusObj addr = Customer.getBusObj("Address"); addr.set("City", "SF");

Setting an attribute in an array of child business objects

To set an attribute in an array of child business objects (an attribute whose cardinality is equal to n), use the BusObj.getBusObjArray() method and assign the results to a BusObjArray type variable. Then use the BusObjArray methods on that variable.

The code examples that follow are based on the following structure.

Figure 70. Child business object arrays


The following example sets the OrderID attribute of the business object marked 1 in Figure 70.
BusObjArray[] orders = cust.getBusObjArray("Orders").elementAt(1); orders[1].set("OrderID", "x1234");

The following example sets the Factory attribute of the business object marked 2 in Figure 70.
BusObjArray items = orders[1].getBusObjArray("Items"); BusObj item = items.elementAt(1); item.set("Factory", "MyCompany");

Setting an attribute value to null

The following example sets the value of the Total attribute of the order business object to null:
order.set("Total", null);

You can use this technique to set any type of attribute to null, whether the attribute value is a basic type, BusObj type, or BusObjArray type. However, you cannot use it to set child business objects in an array to null.

Copyright IBM Corp. 2003, 2004