Basic SOA Using REST

3.2 XML Documents and Schema for EIS Records

The first step toward implementing an SOA component that consumes or provides EIS records involves formatting the EIS records that need to be exchanged as XML documents. This process is formalized by creating an XML Schema to represent the structure of an XML document for a particular EIS record. This section introduces some simple examples that are used throughout this chapter to illustrate the role of XML and XML Schema in SOA-style applications development based on Web Services.

Understanding these examples requires a basic knowledge of XML and XML Schema. If you are new to XML, you should get an introductory text such as Beginning XML by David Hunter et al. [Hunter]. For the necessary background on XML Schema, I suggest Definitive XML Schema by Priscilla Walmsley [Walmsley]. Alternatively, if you know basic XML, but need to brush up on XML Schema, you can probably find all you need to know for this book by reading through the W3C’s “XML Schema Part 0: Primer” [XSD Part 0].

To illustrate how XML is used, I employ an example based on the fictitious XYZ Corporation. The example illustrates real SOA challenges faced by many companies. XYZ Corporation has an Order Management System (OMS) that needs to be integrated with a Customer Service System (CSS).

The OMS should be thought of as an EIS, such as SAP, for taking customer orders and tracking them through delivery. The CSS should be thought of as an EIS, such as Oracle’s Siebel Customer Relationship Management Applications, that is used by customer service employees as a tool for handling customer inquiries.

XYZ Corporation would like to build an SOA application bridging the OMS and the CSS. Every time a new order is entered in the OMS (or an existing order is updated), the new SOA application should transfer that information to the CSS and add it to the relevant customer’s history log.

The purpose of this SOA application is to ensure that customer service representatives have fast access, through the CSS, to basic customer order information. If customer service representatives need access to more detailed order information from the OMS, the CSS will contain the keys within the customer history log (updated via the SOA application) to query the OMS and access that detailed information.

Figure 3-1 illustrates what an OMS order record looks like as it might appear on a user interface.

The structure displayed in the user interface provides a guide to constructing an XML document for the EIS order record. Note that the record is divided into four sections that contain data: Order Number, Order Header, Order Items, and Other Information. Example 3-1 illustrates how this record can be represented as an XML document.

Example 3-1 An XML Representation of the Order Record Appearing in Figure 3-1

Note the use of namespaces in this example. The Order element is from the namespace http://www.example.com/oms. Note that http://www.example.com is the URL used by XYZ Corporation as the base part of its corporate namespaces. The /oms indicates, more specifically, the namespace associated with the OMS. When developing SOA systems with XML, it is important to use namespaces, because documents originating from different systems may use the same tags (e.g., “item”), and it is important to interpret the tag in the proper context. For more information on namespaces and how they are used, see the World Wide Web Consortium’s (W3C) Recommendation [Namespaces in XML].

In addition to namespaces, when developing SOA systems based on XML, it is important to employ XML Schema to validate documents. Just as a relational database management system allows you to impose constraints on data values and format within the database schema, so XML Schema can be used to validate the integrity of XML documents. XML Schema is important for maintaining data quality and integrity when sharing information among multiple systems.

Notice that the Order element of order.xml contains the attribute:

xsi:schemaLocation="http://www.example.com/oms http://soabook.com/example/oms/orders.xsd"

This attribute associates order.xml with an XML Schema and contains two references. First, http://www.example.com/oms gives the namespace to be used for interpreting the schema. Second, http://soabook.com/ example/oms/orders.xsd is a location where the schema can be found.

Example 3-2 shows just a fragment3 of the schema used to validate order.xml. As indicated by the file reference printed at the bottom of the example, the entire schema document can be found at com/javector/ chap4/eisrecords/order.xsd. This schema (order.xsd) and its instance document (the order.xml file) are simplified examples of the SAP XML interface for the business object SalesOrder within the Logistics Module.

Although this example is simplified, it illustrates the major issues faced when creating an SOA application that accesses SAP or another EIS.

3. Because fragments published in this book correspond directly to the source files in the accompanying download package, sometimes—for XML documents—the closing tags get cut off. Although that can sometimes make the structure look confusing or “off balance,” I decided that was better than including the entire XML file in cases where the length could run on for several pages.

Example 3-2 A Fragment of the XML Schema for Validating an Order Document

Notice that schemas allow you to restrict values and specify formats for data. For example, the element OrderKey, that is the unique identifier for sales documents, is restricted to being, at most, 10 characters in length. The restriction is accomplished using the restriction element in the simple type definition of OrderKey. Restrictions on simple types like this are known as facets. For further explanation of simple type facets, see [XSD Part 0]. Facets are an important data quality management tool in an SOA environment because they enable you to ensure that the data being shared across systems is properly formatted and can be interpreted by the receiving system.

Next, Figure 3-2 shows the Customer History Record from the Customer Service System (CSS). Consider how it relates to orders and how it is used within the CSS.

The simple SOA application described in this chapter is responsible for linking the OMS to the CSS to ensure that each time an order is created or modified in the OMS, a corresponding Customer History Record is sent and entered in the Customer History Log within the CSS. The Customer History Log is a record of all transactions the customer has had with XYZ Corporation. It is important to note that not all of the order information is stored in the Customer History Log within the CSS. Only enough is stored so that if a customer calls with a question about an order, the customer service representative can pull up the History Log and drill down to individual order records stored in the OMS to answer the customer’s questions. Individual, detailed order records are retrieved from the OMS in real time using the keys stored in the CSS.

The architecture is designed this way to avoid storing lots of redundant data in the CSS and OMS. The problem with redundant data is that it takes up unnecessary disk space, and tends to get out of sync with the original data, creating data quality problems that can be quite difficult to debug and clean up.

The form in Figure 3-2 shows the minimal set of information that needs to be moved from the OMS to the CSS. Example 3-3 shows how that information is structured as an XML record. The OMS sends this type of XML to the CSS each time there is a new order.

In this example, the CustomerNumber element uniquely identifies the customer and is referenced by the CUST_NO element, inside the Order- Header element illustrated in Figure 3-1. Likewise, the OrderNumber element inside the OrderLookupInfo element referenced the OrderKey element illustrated in Figure 3-1. These constraints could be enforced within the schema by using the unique, key, and keyref XML Schema Elements (see Section 5 of [XSD Part 0]). However, for simplicity, those types of constraints are left out for now.

Example 3-4 shows a fragment of the schema for validating the Customer History Record. This schema is important for validating the quality of the data being reformatted and exchanged by the SOA application bridge.

Example 3-4 XML Schema for an Entry in the CSS Customer History Log

4 <schema targetNamespace="http://www.example.com/css"
5 xmlns="http://www.w3.org/2001/XMLSchema"
6 xmlns:css="http://www.example.com/css" version="1.0"
7 elementFormDefault="qualified">
8 <element name="CustomerHistoryEntries"
type="css:CustomerHistoryEntriesType"/>
9 <element name="CustomerHistoryEntry" type="css:CustomerHistoryEntryType"/>
10 <complexType name="CustomerHistoryEntriesType">
11 <sequence>
12 <element ref="css:CustomerHistoryEntry" maxOccurs="unbounded"/>
13 </sequence>
14 </complexType>
15 <complexType name="CustomerHistoryEntryType">
16 <sequence>
17 <element name="CustomerNumber">
18 <annotation>
19 <documentation>Unique Customer Identifier</documentation>
20 </annotation>
21 <simpleType>
22 <restriction base="string">
23 <maxLength value="10"/>
24 </restriction>
25 </simpleType>
26 </element>
27 <element name="OrderLookupInfo">
28 <annotation>
29 <documentation>Keys and searchable text that can be used to look
30 up additional order information from the OMS</documentation>
31 </annotation>
32 <complexType>
33 <sequence>
34 <element name="OrderNumber">
35 <annotation>
36 <documentation>Unique Sales Order Identifier - Key for CSS
37 lookup of order records</documentation>
38 </annotation>
39 <simpleType>
40 <restriction base="string">
41 <maxLength value="10"/>
42 </restriction>
43 </simpleType>
44 </element>
book-code/chap03/eisrecords/src/xml/custhistentries.xsd

As in Example 3-2, you can see the facets are used to restrict the values for CustomerNumber and OrderNumber. Notice that schemas allow us to restrict values and specify formats for data. For example, the element OrderKey, that is the unique identifier for sales documents, is restricted to being, at most, 10 characters in length. The restriction is accomplished using the restriction element in the simple type definition of OrderKey.

3.2.1 No WSDL Doesn’t Necessarily Mean No Interfaces

The previous examples show how XML Schema can be used to define structure for XML documents. That structure is critical for defining how applications interact with each other in an SOA-style Web Services infrastructure.

It is a fundamental principle of systems integration design that applications must interact across well-defined interfaces. Even in this simple example, as illustrated in Example 3-4, you can see how XML Schema can be used to define the structure of an update record to the CSS Customer History Log. The Customer History schema defines the interface to the Customer History Log. In this manner, any system that needs to update the CSS with customer activity can map whatever form their data is in to the custhistentry.xsd schema and send it as a message to the CSS. The following two concepts, illustrated by the simple examples in this section, provide the foundation for SOA-style integration using Web Services:

1. XML documents are used to exchange messages between applications.
2. XML Schema documents define the application interfaces.

Point (2) is important to bear in mind. It tells you that, even when using RESTful services (without WSDL and SOAP), the schema of the XML documents being exchanged between SOA components can be used to define interfaces for the services. Unfortunately, this use of XML Schema to formalize interfaces for RESTful services is not universally accepted as part of the REST framework.4 If you plan to use REST for your SOA applications, however, I strongly encourage you to provide XML Schema to define the message structure interface for each service.

This section gave you a quick introduction to how EIS records can be represented as XML documents. In the next section, we begin to look at the basics of messaging—sending XML over the Hypertext Transfer Protocol (HTTP).