Identifying and then specifying services is a core part of establishing a Service-Oriented Architecture. It starts with assessing and decomposing key business processes. This decomposition leads to identification of a set of services, each represented by a WSDL definition. Within this definition, references exist to XML schema type definitions that describe the message structure of the messages that the services exchange. Combined with protocol bindings that contain definitions for message protocol and network transport details (such as SOAP over HTTP), the WSDL definition provides a standardized, complete service contract that potential customers can use to access the service, without knowledge of how the actual service logic is implemented.
Figure 1 shows the key constituents of a service interface or service description. This article presents an approach that shows how to define this service contract, including use of industry standard message models. A fictional case study is used from the insurance industry: Acme insurance company.
Figure 1. Service interface (WSDL) constituents
Before any detailed analysis can begin, start by identifying the main business goals or current pain points within the enterprise. This list leads to a list of business processes that are appropriate for further decomposition. For the fictional insurance company, detailed discussions were held with client business and subject matter experts, resulting in the identification of the following business goal: Deliver underwriting excellence through improved increased operational efficiencies. Further analysis of this goal indicated that there was a requirement to improve underwriting efficiencies in the area of vehicle insurance, because the current systems carried the potential to make errors in premium calculations if retrieved vehicle information was not correct. Once the business goal was identified, it was easy to determine the relevant business process: order and aggregate information.
Furthermore, key input to the service interfaces are use cases, which provide information on the actions that need to be performed, the data elements associated with these operations, and any applicable business rules. The Order and Aggregate Information process was further decomposed to help identify relevant service candidates. The related operations were identified using business process analysis (primarily business process decomposition) and use case scenarios as inputs.
Figure 2. Process decomposition to identify services
Figure 2 shows an example of the process decomposition, resulting in identification of four operations associated with an activity called Retrieve Vehicle Request. For simplicity, this article uses the term Vehicle Service as the name for the service representing this activity. The Vehicle Service's four operations are described as follows:
- GetYears(): GetYears provides the ability for vehicle drill-down capabilities. A call to this operation with no make or model parameters is like a SELECT DISTINCT ON YEAR operation that provides all of the years available for selection in the data. Calls to GetYears() with a model or make limit the returned values that pertain to the particular make or model.
- GetModels(): GetModels provides the models that pertain to a make, a year or a make-and-year combination. GetModels provides the ability for vehicle drill-down capabilities.
- GetMakes(): GetMakes provides a list of vehicle makes. A call to the operation with no parameters passed provides a listing of all the makes that the data store has to offer. If year is passed in as the parameter, the operation returns makes that existed for that particular year.
- GetVehicleProfile(): GetVehicleProfile returns all of the information for a particular make, model, and year combination or for VIN number. A list can be returned.
Figure 3. Operations and associated data elements for service interface to support
Figure 3 shows a detailed listing of the operations of the vehicle service and its associated data elements. Note that the service you are designing in this case is very data centric, meaning it returns different variations of data that are related to vehicle information. The vehicle service also does not offer any update capability, so it will most likely be implemented as read-only. You can safely assume that this service will be usable across multiple business domains, even though it was identified through decomposition of one particular business process.
The information is captured in a spreadsheet. This spreadsheet can be used to capture other information, such as the backend system interfaces (not detailed in this article) and the data elements supported by industry-specific schemas.
For the example, a data mapping spreadsheet was used to capture all the data elements associated with the request and response messages associated with a specific service action or operation. Starting with an analysis of relevant use cases and involving line of business personnel ensured alignment between the design of the service and the business problem it is helping to solve.
There are two reasons to now look toward an industry-standard model to serve as the basis for the concrete service interface. One reason is that the service will most likely interact with external partners, both as consumers and providers of information, so using a standard message format makes the service more interoperable overall. Another reason is that a data-centric service like the vehicle service will end up being reused across the enterprise, and using a standard as the basis for an enterprise-wide canonical message model seems appropriate. For the example, the insurance company chooses ACORD as a standard that is relevant to define the vehicle service, because it contains predefined data types that can be reused.
The next step in the process is to identify the data elements in the ACORD schema that the actual service interface requires. Before you start this step, it is essential to determine which version of the ACORD standard the client organization supports. After you know the version, you need to identify the schema that is relevant to the service under consideration. Predictably, the ACORD vehicle schema is the focus of this article. Aggregate elements associated with the vehicle schema are analyzed to identify all the root elements that correspond with the data elements of the service interface. Figure 4 shows how the data elements identified through the use cases and the matching data elements in the vehicle schema are captured in the spreadsheet.
This data mapping helps to identify the following:
- Data elements that are needed by the service (as required by the use cases), which are supported by the current version of the ACORD standard
- Data elements that are not supported by the current version of the ACORD standard. These are the elements that are specific to a specific companyâs business need.
Figure 4. Spreadsheet to capture information
Understanding mapping considerations
This section highlights some key considerations related to message schemas, schema maintenance, and data typing.
Exploring message schema considerations
Throughout the data mapping exercise, you might have observed the following:
- Not all of the data elements that the use cases required were supported by the ACORD vehicle schema.
- The ACORD schema supports a significantly large number of complex types. This results in various options to be considered. Pros and cons for each option are listed below:
Table 1. ACORD schema
|Option 1: Use the entire ACORD schema for the service||Fully compliant with the industry standard as you use the imported standard schema.||Large number of classes generated by tooling. Results in large XML messages.|
|Option 2: Develop a client-organization-specific schema||Results in less generated code. Results in smaller XML messages, which take less time to be processed, validated, debugged, and so on.||Not compliant with industry standard.|
|Option 3: Use a subset of the relevant ACORD schema and extend to accommodate client-specific data elements||Results in less generated code, because only a subset of the relevant ACORD schema is used (such as the vehicle ACORD schema). Results in smaller XML messages, which take less time to be processed, validated, debugged, and so on. Based on industry standard.||Not fully standard compliant.|
Given this analysis, the Acme insurance company chooses option 3:
- The vehicle ACORD schema is to be used instead of the entire ACORD schema.
- The schema is extended to support additional parameters the vehicle service requires. This allows the schema to be based on the standard while keeping the number of objects created to a minimum.
Figure 5. Example schema extension
Figure 5 shows an example of how the standard type acord:PersVehInfo_Type was extended to support two new data elements, RegionalCostNewAmt and Cylinders, by taking advantage of XML schema type inheritance.
Exploring data binding considerations
When implementing a Web service in Java™, the most common approach is to use tooling to generate code artifacts using the JAX-RPC standard. A common tool for generating code that maps to a given WSDL definition is called WSDL2Java. JAX-RPC also defines how XML schema constructs are to be mapped and deserialized in Java. For example, WebSphere® Application Server provides a WSDL2Java tool and runtime classes for serializing Java objects into XML and for deserializing XML documents into Java. This makes the fact that SOAP messages are exchanged on the outside of a service transparent to the developer of the actual service logic.
However, JAX-RPC defines support for some XML schema constructs as optional, and many of these are used in industry schemas, such as ACORD. There is no standard way of handling these. In fact, WebSphere Application Server does not support common elements such as group or choice. Moreover, large and heavily nested schemas can also lead to generation of many Java classes that are complex and hard to use.
There are several options to overcome this:
- During generation of code artifacts, you can turn off the Java-to-XML mapping. In that case, the pure XML content is passed into the service implementation class and can be parsed and handled there. While this requires more code to be developed, it allows full control over if and how XML content is used.
- WebSphere Application Server supports plugging in a custom data binding mechanism instead of using the default, JAX-RPC-based data binding mechanism. You can then implement your own version of serialization or reuse any other mechanism that serves your needs. For example, you can leverage any existing JAXB implementation this way.
- You can also modify the schema beyond the custom extensions already discussed. In other words, you start out with the standard and modify it until it meets your needs. However, note that this leads to an interface that is most likely closely related to, but not compliant with, the standard.
- You can replace the most complex types in the schema with the generic <xsd:any/> element before you run the WSDL2Java tool. This avoids creating many Java classes as mentioned, but just like in the first option in this list, it leaves parsing and handling of these types to the service implementation logic.
In the future, the JAX-WS 2.0 standard API will replace the JAX-RPC standard API. The 2.0 version completely delegates Java-to-XML mapping to JAXB 2.0, which supports the full set of XML schema elements. While this solves the problem of unsupported schema, it still leaves the risk of generating a large amount of Java code, especially when using complex schemas.
Understanding data typing considerations
As mentioned, adopting an industry-standard message structure helps to support reusability of services overall and provides for easier integration with both internal and external applications, such as third party databases. However, highlighted below is an issue that might arise due to data typing, forcing you to further augment the industry-standard schema.
Typically, industry standards are W3C XML schema compliant. They often leverage ways offered by the XML Schema specification to constrain data types, in order to make them as specific as possible. For example, the length element, which is used frequently throughout the ACORD standard, is generally typed to xsd:decimal. In many cases, though, when mapping this element to an existing database or application interface, you notice that it is defined as a string instead, and it includes character data, such as 5ft10in. Other examples are enumerations or other restrictions of a data type's valid range of values, which can be defined in the standard but which cannot be mapped properly to existing data.
In order to address this type of discrepancy, it is important to enhance data mapping documentation with additional information about any extensions that need to be made.
Understanding schema maintenance considerations
The majority of industry-standard message specifications consist of a single large schema. For example, the ACORD schema is 1.5 MB. Slicing the schema into smaller, more manageable slices for both maintenance and implementation reasons is recommended. Typically, the schema can be split along the lines of business (LOB) or along business entity lines for even more granularity (such as vehicle, client or customer). In the case of the vehicle service, assume that the associated schema will be reused across multiple business processes and domains, so you need to isolate it in its own schema and namespace.
Moreover, in order to promote reusability of schemas at the enterprise level, any reusable schemas need to be stored in a repository in the enterprise domain. You need to develop a strategy for maintaining, storing, and discovering the schema. This, then, becomes part of overall service governance.
Relating XSD and WSDL
This section examines the relationships between the ACORD standard XML schema and the schema of your Acme insurance company, as well as its relationship with the WSDL definition for the vehicle Web service.
Figure 6. Relationships between XSDs and WSDL
Step 1: The standard schema
Figure 7 shows a partial list of the elements and types defined in the ACORD standard schema related to vehicles.
Figure 7. ACORD XML schema extract
All the elements and types of this schema belong to the namespace called http://www.ACORD.org/standards/PC_Surety/ACORD1.8.0/xml/. Here is a snippet of the actual schema, stored in a file called vehicle_acord.xsd:
Listing 1. Snippet of vehicle_acord.xsd
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns="http://www.ACORD.org/standards/PC_Surety/ACORD1.8.0/xml/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.ACORD.org/standards/PC_Surety/ACORD1.8.0/xml/" elementFormDefault="unqualified" attributeFormDefault="unqualified" version="1.8.0"> <xsd:element name="SignonRq" type="SignonRq_Type"/> <xsd:complexType name="SignonRq_Type"> <xsd:sequence> <!-- <xsd:group ref="SIGNONENTITY" minOccurs="0"/> --> <xsd:element ref="SignonPswd" minOccurs="0"/> <xsd:element ref="SignonCert" minOccurs="0"/> <xsd:element ref="SignonTransport" minOccurs="0"/> <xsd:element ref="SessKey" minOccurs="0"/> <xsd:element ref="ClientDt"/> <xsd:element ref="CustLangPref"/> <xsd:element ref="ClientApp"/> <xsd:element ref="ProxyClient" minOccurs="0"/> <xsd:element ref="SuppressEcho" minOccurs="0"/> </xsd:sequence> </xsd:complexType> <!-- <xsd:group name="SIGNONENTITY"> <xsd:choice> <xsd:element ref="SignonPswd"/> <xsd:element ref="SignonCert"/> <xsd:element ref="SignonTransport"/> <xsd:element ref="SessKey"/> </xsd:choice> </xsd:group> â¦â¦â¦â¦â¦â¦
Step 2. Custom extensions
Next, take a look at the specific schema in a file called vehicle_acme.xsd that was developed for the Acme insurance example. This file defines new elements and types that are relevant to Acme in a new namespace, http://vehicle.gbo.acme.com. The file imports all the elements and types from the vehicle_acord.xsd file and extends some of the elements and types from it to support elements and types that are not found in the standard.
Figure 8. Partial list of elements and types from vehicle_acme.xsd file
Listing 2 shows a snippet of the vehicle_acme.xsd file. It highlights the import statement for the standard schema.
Listing 2. The vehicle_acme.xsd file
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns="http://vehicle.gbo.acme.com" xmlns:acord="http://www.ACORD.org/standards/PC_Surety/ACORD1.8.0/xml/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://vehicle.gbo.acme.com" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xsd:import namespace="http://www.ACORD.org/standards/PC_Surety/ACORD1.8.0/xml/" schemaLocation="vehicle_acord.xsd"/> <xsd:complexType name="VehInfo_Type"> <xsd:complexContent< <xsd:extension base="acord:VehInfo_Type"> <xsd:sequence> <xsd:element ref="SubModel" minOccurs="0"/> <xsd:element ref="BaseModel" minOccurs="0"/> <xsd:element ref="ModelNumber" minOccurs="0"/> <xsd:element ref="RetailAmt" minOccurs="0"/> <xsd:element ref="PolicyType" minOccurs="0"/> <xsd:element ref="BusinessTransactionType" minOccurs="0"/> <xsd:element ref="RegionalCostNewInd" minOccurs="0"/> <xsd:element ref="State" minOccurs="0"/> <xsd:element ref="MotorcycleType" minOccurs="0"/> <xsd:element ref="RecreationalVehicleType" minOccurs="0"/> <xsd:element ref="BoatType" minOccurs="0"/> <xsd:element ref="Hull" minOccurs="0"/> <xsd:element ref="LivestockTrailerType" minOccurs="0"/> <xsd:element ref="LivestockTrailerSubType" minOccurs="0"/> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> â¦â¦
Step 3. Creating the WSDL definition
Finally, examine the relationship between the WSDL and the schema. As shown in Figure 6, the VehicleInformationService.wsdl imports the vehicle_acme.xsd file to use the defined elements and types as message parts. Listing 3 shows an extract of the VehicleInformationService.wsdl file, which shows the appropriate import statement and the reuse of the elements.
Listing 3. An extract of the VehicleInformationService.wsdl file
Note that the namespace of the actual service is different than the namespace of the imported elements and types in the schema. This is generally considered a best practice, because it allows reusing the schema artifacts across a number of different service definitions.
In this article, you saw an approach for supporting a standardized, industry-specific messaging standard. The article introduced an example based on the insurance industry, which led to the ACORD standard. You learned some of the key considerations associated with supporting an entire schema, a client-organization-specific schema, or a customized subset of the industry schema. The recommendation was to use a subset of the standardized schema and extend it to support customer-specific data elements. This allows the message specification to be compliant with the industry standard while keeping the number of generated artifacts for service development to a minimum. Moreover, you learned some key considerations for dealing with data typing and data binding issues. You also learned that a corporate-wide governance strategy needed to be developed for effective maintenance and versioning of the schema to promote re-usability.
Note that the use of industry standards varies widely, depending on the industry and the address business scenarios. Those solutions might look slightly different.
We want to thank Nina Chien from IBM Global Business Services and Shakeel Mahate of IBM Software Group for their help with this article.
- Learn more about the ACORD schema from the Association for Cooperative Operations Research and Development.
- Review Service-oriented modeling and architecture for a seminal work on this topic.
- Check out the developerWorks article, Using the <xsd:any/> element for custom serialization.
- Refer to the SOA Primer.
- The SOA and Web services zone on IBM developerWorks hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop Web services applications.
- The IBM SOA Web site offers an overview of SOA and how IBM can help you get there.
- Stay current with developerWorks technical events and webcasts.
- Browse for books on these and other technical topics at the Safari bookstore.
Get products and technologies
- Innovate your next development project with IBM trial software, available for download or on DVD.
- Participate in the discussion forum.
- Get involved in the developerWorks community by participating in developerWorks blogs.
Dig deeper into SOA and web services on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.