Enabling Enterprise-Class Web Services
In the last chapter, we talked about the business requirements and the business reasons for choosing a web services architecture for the solution. Before you start designing the web services to meet these business requirements, you have to take a close look at the factors to be considered for enabling enterprise-class web services. Enterprise-class web services represent a level of technical and operational maturity that is consistent with the increasingly stringent requirements of today's enterprise. As we progress toward building such web services, in this chapter, we take a close look at designing interoperability, publishing an enduring web services contract, exposing the business-tier components, and planning for a robust production environment.
The WebLogic Workshop web services framework abstracts the developer from the plumbing code required to build enterprise-class web services. WebLogic Workshop combines the visual development environment with the runtime framework to help developers and nondevelopers effectively and efficiently build these services.
Designing Interoperability
The two dominant web services development platforms are on J2EE and .NET. Most often, the client accessing the web services cannot be predetermined. Therefore, it is important to make certain design choiceschoice of standards, WSDL design, and SOAP messaging stylethat enhance the interoperability of the web services implementation across different platforms.
Conforming to Standards
Using the web services standardsXML, WSDL, SOAP, and UDDI, as well as WS-Security (security), Web Services Distributed Management (manageability), and the Business Process Execution Language (orchestration)strictly as defined by the standard bodies is a necessary requirement for interoperability. Following the recommendation from bodies such as the WS-I not only improve interoperability, but it also facilitates fast implementation with business partners.
Standards are important at all levels of web services communication. By using a standard way of exchanging data using XML, choosing a common SOAP message protocol, and describing services through WSDL, you enable the users of your service to communicate with your application regardless of the platform they are using. This approach helps you to integrate your web services with those of your business partners without relying on proprietary vendor technology.
In WebLogic Workshop, exposing an operation through these standards is extremely easy. Workshop introduces a simple javadoc-based annotation @jws:operation for marking up standard Java code. If you simply put this annotation before a method in a standard Java class file, Workshop exposes that method as a web service that fully supports the web services standards.
Designing WSDL First
In general, designing the WSDL first is the right way to start your web services. The WSDL represents the contract between you and the user of your service. Not unlike the real world, the contract needs to be well crafted. It needs to spell out in the clearest possible terms what the service offersand, ideally, what it does not do.
Most often, developers seldom design the WSDL because many SOAP implementations provide tools to automatically generate a WSDL file from a COM object or Java class files. Surprisingly, this can cause issues of interoperability between different Java application servers and between .NET and Java implementations. This is because the automatically generated WSDLs might not be interpretable across different platforms. For example, some application servers cannot use WSDLs that have imported or included XML Schemas. Designing the WSDL first and then creating the web service avoids the issue.
The recommendation is that you generate WSDL using techniques based on the Unified Modeling Language (UML) or using WSDL editors (see Figure 5.1). We cover in detail how to design WSDL using XMLSPY, a WSDL editor, in the next chapter.
WSDL modeling in UML can be another way of creating WSDL rather than using WSDL editors. The Object Management Group (OMG) has established a Model Driven Architecture (MDA) and Unified Modeling Language (UML) for modeling software applications. UML is a graphical language for specifying, visualizing, constructing, and documenting software systems. Because of its wide acceptance and capabilities, UML is the natural choice for any modeling activities. UML profiles provide a generic extension mechanism for building UML models in particular domains such as Web Modeling Profile, XSD Schema Profile, and Business Profile Modeling. A profile consists of stereotypes, constraints, and tagged values that allow modeling of all WSDL definitions.
Figure 5.1 XMLSPY, a sample WSDL editor
Deriving from the MDA, the modelling of the WSDL can be divided into a platform-independent model (PIM) and a platform-specific model (PSM). A WSDL file has two sections, the abstract section and the bindings section. The PIM represents the abstract section of the WSDL. This includes Definitions, Service, PortType(s), Messages, Parts, and PartType(s). The PSM completes the bindings section of the WSDL. The elements modelled here include Service, Ports, and Binding(s).
Selecting SOAP Messaging
The style, or binding style, decision controls how the elements just under the SOAP body are constructed. The two choices are RPC and document. The use, or encoding, concerns how types are represented in XML. The two choices are literal and SOAP encoded. Literal follows an XML Schema definition. SOAP encoded follows special encoding rules detailed in the SOAP 1.1 specification to produce XML that can contain references pointing within the message. The WS-I Basic Profile Version 1.0a specification recommends the use of literal encoding; it actually discourages the use of SOAP encoding.
Theoretically, you should be able to mix and match any of the styles and uses for SOAP messaging. However, practically, the RPC-encoded and document-literal choices are the ones used. In addition, many web service platforms don't directly support RPC-literal. WebLogic Workshop uses document-literal as its default message format, but it also supports the RPC-encoded message format. To specify the message format that a web service uses to communicate with the web service control, you can set the soap-style attribute of the @jc:protocol annotation to document for the document-literal message format or rpc for the SOAP-RPC format.
RPC-encoded seemed reasonable in a world without XML Schema. Now that XML Schema is here to stay, document-literal is quickly becoming the de facto standard among developers and toolkits, thanks to its simplicity and interoperability results.
Styles: Document and RPC
Document style indicates that the SOAP body contains an XML document. In this approach, you the send XML document as is. The sender and receiver must agree on the format of the document ahead of time. Here is an example of a document-style message:
<SOAP-ENV: Envelope xmlns:SOAP-
ENV=http://schemas.xmlsoap.org/soap/envelope/
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
mlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <SOAP-ENV:Body> <m:inValidateConfig xmlns:m="http://production.psg.hp.com/types"> <m:Config> <m:Model/> <m:Cstic/> </m:Config> <m:User AccountID=0000000000> <m:Password>String</m:Password> <m:IpcVersion>OLD</m:IpcVersion> <m:ConfigID>String</m:ConfigID> </m:inValidateConfig> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Observe that all elements are defined within the same namespace. With a document-style web service, you are free to define the XML however you want because all the XML is explicitly specified.
RPC style indicates that the SOAP body contains an XML representation of a method call. RPC style uses the names of the method and its parameters to generate structures that represent a method's call stack. Here's an example of a RPC-style message:
<SOAP-ENV:Body> <m:validate xmlns:m="local
host:7001/services/validate" SOAP-ENV:encodingStyle=
"http://schemas.xmlsoap.org/soap/encoding/"> <in0 xsi:type="xsd:string">String</in0> </m:validate> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
RPC relies on some rules. Observe that the root element is qualified with a namespace, but the child element uses an unqualified name. The root element is named after the operation: validate for a SOAP request and opNameResponse for a SOAP response. Each child is a parameter, or a return value named opNameReturn.
The binding style is specified in the WSDL. There actually is a style attribute that can be RPC or Document in the <soapbind:binding> element, which is the <wsdl:binding> element's first child. Table 5.1 illustrates the differences between RPC and Document.
Table 5.1 Binding Style in a WSDL
|
RPC |
Document |
<soapbind:binding> element |
style="rpc" |
style="document" |
<wsdl:part> element(s) |
<part> element can be many; each contains a "type" attribute. |
Only one <part> element containing an "element" attribute. |
<wsdl:part> element(s) explained |
Specify the type so that the SOAP engine can use RPC rules to make it either a parameter or a return value. |
The SOAP body has an XML element that is fully specified in <wsdl:types>. |
Use: Literal and Encoding
The use, or encoding, concerns how types are represented in XML. The two choices are literal and SOAP encoded. Literal follows an XML Schema definition. SOAP encoded follows special encoding rules detailed in the SOAP 1.1 specification (section 5) to produce XML that can contain references pointing within the message. Now to compare the literal and encoded use, let's compare the example from the document style that also uses the literal with another example showing the encoding use.
Here's the literal use:
<m:User AccountID=0000000000> <m:Password>xyz </m:Password> <m:User>
Here's the encoding use:
< AccountID xsi:type ="xsd:string">0000000000</ AccountID r> <Password xsi:type="xsd:string">xyz</Password>
SOAP encoding automatically maps all eligible fields to elements, not attributes. With the literal use of an XML Schema, on the other hand, you can specify what items are attributes and what items are elements. In the previous example, the simple AccountID field can be written more compactly as an attribute.
Now we can examine how use is specified in the WSDL. Table 5.2 shows the difference in literal versus encoded in the WSDL document.
Table 5.2 Use/Encoding Specified in a WSDL
|
Encoded |
Literal |
<soapbind:body> use attribute |
use="encoded" |
use="literal" |
Other <soapbind:body> attributes |
encodingStyle="http:// schemas.xmlsoap.org/soap/ encoding/" |
|