This section describes operations that involve manipulating business objects and their values. It includes these operations:
Use the constructor method new to create a new business object.
new BusObj(String busObjType)
An object of type BusObj.
ObjectException - Raised if the business object argument is invalid.
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".
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");
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.
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:
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); |
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:
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")); |
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); |
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
The difference between the two methods is mainly the preexistence of the business object where you want to put the copied values.
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); |
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(); |
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").
To check for a null attribute value, a collaboration calls BusObj.isNull(attribute). A null value usually appears for one of the following reasons:
Upon creation of a business object, all attributes are null and they remain null until explicitly set. These include child business objects and child business object arrays.
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.
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")); |
This section covers types of operations for retrieving attributes. These operations are presented in order of increasing complexity:
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.
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:
//Look for sold-to address in the US //Start with the busOrg business object //Get the child business object array in the "SoldToSite" attribute if (!busOrg.isNull("SoldToSite")) { BusObjArray siteAddArray = busOrg.getBusObjArray("SoldToSite"); // //String to compare with sold-to country name String countryName = "USA"; //Get size of child business object array int count = siteAddArray.size(); // //For each business object in the array get the SoldToAddress //attribute, which is a business object, and compare its //SoldToCountryName attribute to the string "USA" // for (int i = 0; i < count ; i ++) { BusObj siteAddr = siteAddArray.elementAt( i ); if (!siteAddr.isNull("SoldToAddress")) { BusObj soldToAddress = siteAddr.getBusObj("SoldToAddress"); if (countryName.equalsIgnoreCase( soldToAddress.getString("SoldToCountryName"))) { //do something } }//end if }//end for }//end if |
This section covers three types of operations for setting attributes. These operations are presented in order of increasing complexity:
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")); |
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:
BusObj addr = Customer.getBusObj("Address"); addr.set("City", "SF"); |
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"); |
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.