The business object package API

Perform business object serialization and deserialization to and from XML

Nick Maynard (nick.maynard@uk.ibm.com), Scenario Analyst, IBM UK Ltd.

Nick Maynard has worked in the Scenario Analysis Lab at IBM Hursley since joining IBM as a graduate in 2003 from Imperial College of Science, Technology and Medicine. He specialises in Linux, Web services and business Integration technologies.

Summary: One of the advantages of building business processes in WebSphere® Integration Developer and WebSphere Process Server is the representation of customer data as business objects. The XML representation of these objects is difficult to obtain if the customer wishes to perform advanced XML manipulation, or merely inspect the XML source. In this article you'll see how to use the business object package APIs for serialization and deserialization tasks, with examples and sample custom visual snippet code.

Date: 05 Jul 2006
Level: Advanced
Activity: 478 views
Comments:

Introduction

IBM WebSphere® Process Server V6.0 and IBM WebSphere Integration Developer V6.0 provide many advanced facilities to BPEL developers, including an implementation of the Service Data Object standard. We'll describe particular functionality of the business object package API in WebSphere Process Server, which provides developers advanced capabilities for creating, comparing and manipulating business objects. You'll learn how to use the XML functionality of the business object package API to serialize and deserialize business objects to and from XML, and see a sample implementation of some visual snippets utilizing this technique.

Overview

Business Process Execution Language (BPEL) is an XML-based language that specifies the behavior of business processes. Developers from IBM, BEA Systems, Inc., and Microsoft originally wrote and submitted BPEL to the Organization for the Advancement of Structured Information Standards (OASIS) Standards Committee in April 2003. BPEL describes business processes as interactions between Web services, and presents a process as a Web service. IBM WebSphere Process Server V6.0 contains an implementation of this language. IBM WebSphere Integration Developer v6.0 contains a graphical editor for BPEL processes and creates EAR files from business processes.

Serializing and deserializing business objects to and from XML

The business object package

IBM WebSphere Process Server v6.0 provides methods for interacting with business objects through the business object package APIs.

We will use the following sections of the package:

Interface name	Functionality
BOXMLDocument	An object implementing the BOXMLDocument interface represents a business document. A business document can be created by using BOXMLSerializer.createXMLDocument encapsulates a DataObject can be serialized and deserialized using the BOXMLSerialization service
BOXMLSerializer	The BOXMLSerializer service provides the following capabilities: creation of a business document from a DataObject serialization/deserialization of a business document serialization/deserialization of a DataObject

Preparing your workspace with business object definitions

In order to utilise the XML (de)serialization capabilities of the business object package APIs, you must first perform the following steps:

Ensure the BO_Utilities_Library library is listed as a dependency of your business module.
Ensure the XSD definitions for the business objects are accessible by the business module. If you have included the XSDs as part of a library, you should ensure that the library is listed as a dependency of your business module. Ensure your business module's dependency ordering is such that your libraries containing the XSD definitions are listed ABOVE (included before) the BO_Utilities_Library.
Ensure any XML you wish to deserialize is valid according to the XSD definitions you have included. If it is not valid deserialization will fail.

Serializing a business object to XML

To serialize a business object to XML, we must use the functionality provided by the business object package APIs within WebSphere Process Server . Listing 1 illustrates the basic method.

Listing 1. Sample Java code for serializing a business object to XML

// The businessObject reference should refer to a valid business object
DataObject businessObject;
String businessObjectName, businessObjectNamespace;

// Create a serializer
BOXMLSerializer serializer = new BOXMLSerializerImpl();

// Use the serializer to create a business document
BOXMLDocument document = serializer.createXMLDocument(businessObject, 
  businessObjectNamespace, businessObjectName);

// Write the business document to XML
ByteArrayOutputStream stream = new ByteArrayOutputStream();
try {
	serializer.writeXMLDocument(document, stream);
} catch (IOException e) {
	e.printStackTrace();
}
String xmlRepresentation = stream.toString();

Some refinements on the above code are possible:

The business object name and namespace can be obtained automatically by inspecting the business object.
A serializer can be obtained using a ServiceManager to locate a provided instance.
Character sets other than the system default can be used to extract a string from the output stream.

These additional refinements have been implemented in the sample visual snippet code provided to you - see the Download section.

Deserializing XML to a business object

To deserialize an XML document to a business object, we must again use the functionality provided by the business object package APIs within WebSphere Process Server . Listing 2 illustrates the basic method.

Listing 2. Sample Java code for deserializing an XML document to a business object

// The xmlDocument string should contain the XML document
String xmlDocument;

// Create a serializer
BOXMLSerializer serializer = new BOXMLSerializerImpl();

// Create an input stream from the XML document
ByteArrayInputStream stream = new ByteArrayInputStream(xmlDocument.getBytes());

// Use the serializer to create a business document
BOXMLDocument document;
try {
	document = serializer.readXMLDocument(stream);
} catch (IOException e) {
	e.printStackTrace();
}

// Extract the business object from the business document
DataObject businessObject = document.getDataObject();

Some refinements on the above code are possible:

A serializer can be obtained using a ServiceManager to locate a provided instance.
Character sets other than the system default can be used to create the input stream from the xmlDocument string.

These additional refinements have been implemented in the sample visual snippet code provided to you - see the Downloads section.

Sample code

Downloading and installing the sample code

The sample code includes a Project Interchange file containing the projects for use in WebSphere Integration Developer.

To import the sample code into your workspace:

See the Download section to download the sample code to your hard drive.
Ensure your installation of WebSphere Integration Developer has the latest fixes applied.
Start WebSphere Integration Developer and open a workspace.
Click File -> Import...
Select "Project Interchange" and click Next.
Browse to the location of your downloaded Project Interchange file.
Select all the projects for import.
Click Finish.

The BO_Utilities_Library sample code

Inspect the BO_Utilities_Library sample code

Show the Physical Resources view by clicking Window -> Show View -> Physical Resources.
Expand the BO_Utilities_Library project.
Expand the utility folder.
Double click on BusinessObjectToXMLString.activity and examine the visual snippet.

Figure 1. The businessObjectToXMLString visual snippet
Double click on BusinessObjectToXMLString.java and examine the Java source code for the snippet. You will observe it is similar to code Listing 1.
Double click on XMLStringToBusinessObject.activity and examine the visual snippet.

Figure 2. The XMLStringToBusinessObject visual snippet
Double click on XMLStringToBusinessObject.java and examine the Java source code for the snippet. You will observe it is similar to code Listing 2.

The Valuation_Project sample code

Note: This is an extremely simplistic example, and merely illustrates usage of the sample visual snippets.

The Valuation_Project module shows an example use for the snippets provided by the BO_Utilities_Library library.

The example process Value_Car values a car by calling a Valuation partner. The Valuation partner accepts only XML strings as input and output.

In order to comply with the Valuation partner interface, Value_Car contains two snippets which use the BusinessObjectToXMLString and XMLStringToBusinessObject snippets to convert its business objects to and from XML. It also outputs the XML strings to the log.

Summary

In this article we used some of the capabilities of the business object package API, and conducted serialization and deserialization of business objects to and from XML. This capability can allow the use of advanced techniques on business objects, such as XSLT transformation.

Download