78 leveraging pattern constraints within your simple type definition, you can significantly reduce the amount of validation code you need to write for your Web service. Let’s take a look at an example of where a pattern restriction can be helpful. Recall that the OrderItem method exposed by the Commerce Web service accepts a parameter called Item . In the previous example, I defined a type called ProductId for defining the type of data that can be contained within the Item element. In addition to length restrictions, suppose that an instance of a ProductId cannot contain the following characters: / \ [ ] : ; | = , + * < >. If I were to use the ProductId type as defined previously, I would have to write code to ensure that no illegal characters were included within the Item element. Instead, I will add a pattern constraint to the ProductId definition that restricts the type of characters that values of that type can contain. <?xml version=‘1.0’?> <schema xmlns="http://www.w3.org/2001/XMLSchema.xsd" xmlns:tns="urn:Commerce" targetNamespace="urn:Commerce"> <simpleType name="ProductId"> <restriction base="string"> <minLength value="1"/> <maxLength value="20"/> <pattern value=‘[^/\&#x5B;&#x5D;:;|=,+*?&gt;&lt;]+’/> </restriction> </simpleType> <! Request Message (work-in-progress) > <element name=‘Item’ type=‘tns:ProductId’/> <! Response Message (work-in-progress) > <element name=‘Amount’ type=‘double’ nillable=‘true’/> </schema> Another useful constraint is the enumeration. The value of an enumeration can contain one of a fixed set of possible values. For example, suppose I want to restrict the value of the Item attribute to one of a set of possible values. The following example creates a datatype called Items that can contain the possible values of the Item element: <?xml version=‘1.0’?> <schema xmlns="http://www.w3.org/2001/XMLSchema.xsd" xmlns:tns="urn:Commerce" targetNamespace="urn:Commerce"> <! Removed the ProductId type definition for clarity > <simpleType name="Items"> <restriction base="ProductId"> 79 <enumeration value="Apple"/> <enumeration value="Banana"/> <enumeration value="Orange"/> </restriction> </simpleType> <! Request Message (work-in-progress) > <element name=‘Item’ type=‘tns:Items’/> <! Response Message (work-in-progress) > <element name=‘Amount’ type=‘double’ nillable=‘true’/> </schema> The Items type definition creates an enumeration of type ProductId with three possible values. The Item element is defined as type Items, so it can contain only the value Apple, Banana, or Orange. Simple types can also derive by list. Deriving by list indicates that the value of the type can contain one or more values of the base type, where each value is delimited by whitespace. An example is the SOAP encodingStyle attribute. Recall that this attribute can accept a whitespace-delimited list of URIs. The following example defines the SOAP encodingStyle attribute: <simpleType name=‘encodingStyle’> <list base=‘uri-reference’/> </simpleType> List types are not a substitute for SOAP encoded arrays. SOAP arrays provide a standard method of encoding for instances of simple types as well as complex types. SOAP Encoding also defines syntax for the partial serialization of arrays. Simple types can also be derived by union. An instance of a type derived by union can contain a value of one of the types contained within the union. The following example defines two unions, MyUnion and PhoneNumber: <?xml version=‘1.0’?> <schema xmlns="http://www.w3.org/2001/XMLSchema.xsd"> <simpleType name="MyUnion"> <union memberTypes="string int"/> </simpleType> <simpleType name="PhoneNumber"> <union> <simpleType name="UsPhoneNumber"/> <restriction base="string"/> 80 <pattern value="([0-9]{3}) [0-9]{3}-[0-9]{4}"/> </restriction> </simpleType> <simpleType name="UkPhoneNumber"> <restriction base="string"> <pattern value="+[0-9]{2} ([0-9])[0-9]{3} [0-9]{3} [0- 9]{4}"/> </restriction> </simpleType> </union> </simpleType> </schema> The preceding schema shows two ways of defining union simple types. The first type definition uses the memberTypes attribute to list the types contained within the union. The MyElement element can contain string or int values. The second type definition defines a union composed of embedded simple type definitions. The two embedded types define a U.S. phone number and a U.K. phone number. The PhoneNumber union can contain values such as (303) 555-1212 or +44 (0)121 643 2345. Type definitions can be either named or anonymous. If a type definition is embedded within another definition (an element definition, for example), you do not have to provide the type with a name. Here is a modified version of the Commerce Web service schema that defines the enumeration as an anonymous type: <?xml version=‘1.0’?> <schema xmlns="http://www.w3.org/2001/XMLSchema.xsd" xmlns:tns="urn:Commerce" targetNamespace="urn:Commerce"> <! Portions of the schema have been removed for clarity. > <! Request Message (work-in-progress) > <element name=‘Item’> <simpleType> <restriction base="ProductId"> <enumeration value="Apple"/> <enumeration value="Banana"/> <enumeration value="Orange"/> </restriction> </simpleType> </element> </schema> 81 The enumeration containing possible values for the Item element is defined as an anonymous type. Because the enumeration is defined within the scope of the element definition, the type attribute does not need to be specified because it is implied. Because the enumeration type can be referenced only by the element itself, it is not necessary to specify a name for the type. You should define anonymous types with caution. Types that are used only once are good candidates for anonymous type definitions. However, if the datatype might be reused in other contexts, you should avoid declaring anonymous type definitions. You should also be cautious about using simple types, including built-in types, within RPC- style Web services. Parameters that are passed by value can be defined using simple types. But parameters passed by reference should not. Recall that SOAP Encoding specifies a means of encoding parameters passed by reference using the id and href attributes. Because elements defined using simple types cannot contain attributes, they cannot be properly encoded within the SOAP message. For this reason, the SOAP Encoding schema defines wrapper types for the built-in types defined by XML Schema. Complex Types A complex type is a logical grouping of element and/or attribute declarations. One can argue that XML instance documents aren’t very interesting or useful without complex types. For example, the SOAP Envelope schema defines numerous complex types. The Envelope itself is a complex type because it must contain other elements such as the Body element and possibly a Header element. I will use complex types to define the body of the response and request SOAP messages for the Commerce Web service. A complex type is defined using the complexType element. The complexType element contains declarations for all elements and attributes that can be contained within the element. For example, the body of the PurchaseItem request and response messages can be described by creating a complex type. Here is the schema definition for the Commerce Web service: <?xml version=‘1.0’?> <schema xmlns="http://www.w3.org/2001/XMLSchema.xsd" xmlns:tns="urn:Commerce" targetNamespace="urn:Commerce"> <! Type Definitions > <simpleType name="ProductId"> <restriction base="string"> <minLength value="1"/> <maxLength value="20"/> <pattern value=‘[^/\&#x5B;&#x5D;:;|=,+*?&gt;&lt;]+’/> </restriction> </simpleType> <simpleType name="Items"> <restriction base="ProductId"> <enumeration value="Apple"/> 82 <enumeration value="Banana"/> <enumeration value="Orange"/> </restriction> </simpleType> <! Request Message (work-in-progress) > <element name=‘PurchaseItem’> <complexType> <element name=‘Item’ type=‘tns:ProductId’/> <element name=‘Quantity’ type=‘int’/> </complexType> </element> <! Response Message (work-in-progress) > <element name=‘PurchaseItemResponse’> <complexType> <element name=‘Amount’ type=‘double’ nillable=‘true’/> </complexType> </element> </schema> The schema defines two complex types that define the body of the SOAP request and response message. In accordance with the SOAP specification, I defined a PurchaseItem element to contain all of the parameters passed to the PurchaseItem method of the Commerce Web service. The body of the response message will contain an element named PurchaseItemResponse and will contain one subelement for the return type. Complex types can be divided into two categories: types that contain other elements and types that do not. Within a complex type definition, you can specify either a complexContent or a simpleContent element. The previous datatype definitions did not contain either of these elements. If neither element is used in the complex type definition, complexContent is assumed. Therefore, the following more verbose definition of the PurchaseItem element is equivalent to the previous definition: <?xml version=‘1.0’?> <schema xmlns="http://www.w3.org/2001/XMLSchema.xsd" xmlns:tns="urn:Commerce" targetNamespace="urn:Commerce"> <! Portions of the schema have been removed for clarity. > <! Request Message (work-in-progress) > <element name=‘PurchaseItem’> <complexType> <complexContent> 83 <extension> <element name=‘Item’ type=‘tns:ProductId’/> <element name=‘Quantity’ type=‘int’/> </extension> </complexContent> </complexType> </element> </schema> Notice that the schema also includes the extension element. If either simpleContent or complexContent is specified, its immediate child element must be either the restriction or extension element. By default, a complex type will define an extended version of its base type. If the base type is not specified, the type definition will extend anyType. In other words, a complex type definition that does not explicitly state whether it contains complex or simple content will default to containing complex content and deriving from anyType by extension. As with simple type definitions, you can create complex types that are more restrictive than the base type. Unlike simple types, which restrict the string value of an instance of a type, complex types have restrictions related to the element and attribute definitions contained within the type. The following example defines the Family complex type and then defines some types that derive by restriction: <?xml version=‘1.0’?> <schema xmlns=‘http://www.w3.org/2001/XMLSchema’> <! Base type > <complexType name=‘Family’> <element name=‘Parent’ minOccurs=‘1’ maxOccurs=‘2’/> <element name=‘Child’ type=‘string’ minOccurs=‘0’/> <complexType name=‘Children’> <! The number of parents is restricted to one. > <complexType name=‘SingleParentFamily’> <complexContent> <restriction base=‘Family’> <element name=‘Parent’ type=‘string’ minOccurs=‘1’ maxOccurs=‘1’/> <element name=‘Child’ type=‘string’ minOccurs=‘0’/> </restriction> </complexContent> </complexType> <! No Child elements are allowed. > <complexType name=‘ChildlessFamily’> 84 <complexContent> <restriction base=‘Family’> <element name=‘Parent’ type=‘string’ minOccurs=‘1’ maxOccurs=‘1’/> <element name=‘Child’ type=‘string’ minOccurs=‘0’ maxOccurs=‘0’/> </restriction> </complexContent> </complexType> <! The name of the children can only be George. > <complexType name=‘ForemanFamily’> <complexContent> <restriction base=‘Family’> <element name=‘Parent’ type=‘string’ minOccurs=‘0’ maxOccurs=‘2’/> <element name=‘Child’ type=‘string’ minOccurs=‘0’ fixed=‘George’/> </restriction> </complexContent> </complexType> <! Not a legal type declaration > <complexType name=‘OrphanedFamily’> <complexContent> <restriction base=‘Family’> <element name=‘Parent’ type=‘string’ minOccurs=‘0’ maxOccurs=‘0’/> <element name=‘Child’ type=‘string’ minOccurs=‘0’/> </restriction> </complexContent> </complexType> </schema> I defined three valid restricted derivatives of the Family type. The SingleParentFamily datatype restricts the number of Parent elements that can appear within an instance. The ChildlessFamily datatype disallows the optional Child element from appearing within an instance. Then, in true George Foreman fashion, the ForemanFamily datatype allows Child elements as long as the name of each is George. One caveat with restricted types—and with extended types, for that matter—is that the derived types must be able to be substituted for their base type without any issue. The two derived types in the example, SingleParentFamily and ForemanFamily, meet this requirement. The OrphanedFamily type definition does not meet this requirement. Because 85 the base type Family states that you must have at least one Parent element, an instance of OrphanedFamily cannot serve as a substitute. Recall that SOAP Encoding provides a means of maintaining the identity of parameters passed by reference. This is accomplished with the id and href attributes. These attributes allow an element to reference data that is encoded at another location within or even outside of the SOAP message. (See Chapter 3 for more information.) The following example illustrates the need for such a mechanism: // Server Code: public void TestReference(ref int x, ref int y) { x += 3; y += 10; } // Client Code: int z = 2; TestReference(ref z, ref z); // z should now equal 20 (2 + 3 + 10). For the TestReference method to run correctly, the identity of z must be maintained. Therefore, the elements for parameters x and y cannot be of type int defined by XML Schema because the elements will not be able to contain the href and id attributes to be defined. So, the SOAP Encoding schema extends the built-in types. The following example performs the same redefinition: <?xml version=‘1.0’?> <schema xmlns="http://www.w3.org/2001/XMLSchema.xsd" targetNamespace=‘urn:ExtendedBuiltinTypes’> <complexType name=‘int’> <simpleContent> <extension base=‘int’> <attribute name=‘id’ type=‘ID’/> <attribute name=‘href’ type=‘uriReference’/> </extension> <simpleContent> </complexType> </schema> SOAP Encoding specifies that the order in which parameters of an RPC- style message appear is significant. Therefore, I use the sequence element in the schema to indicate that the Item element must appear first, followed by the Quantity element. You can also specify any combination of the minOccurs and maxOccurs attributes. In this case, neither attribute was specified, so the default value of 1 will be assumed. The following is the complete schema for the Commerce Web service: 86 <?xml version=‘1.0’?> <schema xmlns="http://www.w3.org/2001/XMLSchema.xsd" xmlns:tns="urn:Commerce" targetNamespace="urn:Commerce"> <! Type Definitions > <simpleType name="ProductId"> <restriction base="string"> <minLength value="1"/> <maxLength value="20"/> <pattern value=‘[^/\&#x5B;&#x5D;:;|=,+*?&gt;&lt;]+’/> </restriction> </simpleType> <simpleType name="Items"> <restriction base="ProductId"> <enumeration value="Apple"/> <enumeration value="Banana"/> <enumeration value="Orange"/> </restriction> </simpleType> <! Request Message (work-in-progress) > <element name=‘PurchaseItem’> <complexType> <sequence> <element name=‘Item’ type=‘tns:ProductId’/> <element name=‘Quantity’ type=‘int’/> </sequence> </complexType> </element> <! Response Message (work-in-progress) > <element name=‘PurchaseItemResponse’> <complexType> <element name=‘Amount’ type=‘double’ nillable=‘true’/> </complexType> </element> </schema> 87 Other elements that can be used to achieve specific behavior related to the elements defined within a type include the choice and all elements. The choice element allows only one of the elements defined within the complex type to appear within an instance of the type. The all element allows any subset of the elements defined within the type to appear in any order. There is one more difference between the all element and the sequence and choice elements. Complex type declarations made within the latter elements can contain maxOccurs and minOccurs attributes. However, elements defined within the all element can specify only a maxOccurs and a minOccurs attribute with a value of 0 or 1. By default, datatypes defined using the complexContent element do not allow mixed content. Mixed content means values that contain text as well as child elements. You can override this behavior by adding a mixed attribute and setting its value to true. In most cases, including this one, disallowing mixed content is preferred. Sometimes it is necessary to specify that any element or attribute can appear within an instance of a complex type. For example, the anyType type indicates that any element or attribute can appear within an element of type anyType. You can do this by using the any and anyAttribute elements within the complex type definition. Here is the definition of the anyType type: <?xml version=‘1.0’?> <schema xmlns=‘http://www.w3.org/2001/XMLSchema’ xmlns:tns=‘http://schemas.xmlsoap.org/soap/envelope/’ targetNamespace=‘http://schemas.xmlsoap.org/soap/envelope/’> <xs:complexType name="anyType" mixed="true"> <xs:annotation> <xs:documentation> Not the real urType, but as close an approximation as we can get in the XML representation</xs:documentation> </xs:annotation> <xs:sequence> <xs:any minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:anyAttribute/> </xs:complexType> </schema> The preceding portion of the schema for XML Schema itself defines the anyType complex type. The any element states that any element can appear within an element of type anyType. The minOccurs and maxOccurs attributes are also used to indicate that zero or more elements can appear. You can also impose additional constraints on the attributes and elements that can appear within an instance document by using the namespace attribute. This attribute allows you to declare what namespace-scoped attributes and elements can and cannot be contained within an instance document. Table 4-4 lists the possible values of the namespace attribute. [...]... consuming XML Schema schemas for Web services 99 Chapter 5: Using WSDL to Document Web Services Overview In the previous chapter, you learned how to create a schema to describe the format of a SOAP message You can use XML Schema to describe the layout of a message and the type of data the message contains, and the resulting schema can be used to validate the message received by the Web server However, XML. .. represents the long version of the U.S Federal income tax form It might not be necessary for all filers to complete the entire long form, so the government issues the EZ form The EZ form is a derivative of the long form with restrictions on the amount of data it can contain You can dictate how a datatype can be inherited by setting the final attribute in the complexType element Table 4-6 describes the possible... form datatype by extension for use within its own internal system When it comes time to electronically file the tax form, the schema for the Web service needs a means of disallowing instances of the extended versions of the long form datatype This is accomplished by setting the block attribute on the tax form element declaration to extension The other possible values of the block attribute are listed... operation types, the default name is the name of the operation element in which they are contained For request-response operation types, the name of the input and output elements default to the name of the operation with Request or Response appended to the end For solicit-response, the name of the output element defaults to the name of the operation with Solicit or Response appended to the end Because... definition The style of the message is indicated by the style attribute The value is either rpc or document If the style is set to rpc, each part within the operation will represent a parameter The parameters must be encoded in the body of the SOAP message in a struct-like fashion as dictated by the SOAP specification The name of the operation element must match the name of the element that contains the parameters... mentioned earlier, the style attribute can be set to either rpc or document to indicate the style of the message The soapAction attribute specifies the value of the SOAPAction header The soapAction attribute is required if HTTP is the transport protocol The value can be blank if the HTTP request URL adequately describes the intent of the message The client should pass the value of the soapAction attribute... operation, there is no default name for the fault element Therefore, each fault element must be uniquely named within its parent operation element Here is the portType definition for the Calculator Web service: < ?xml version="1.0" encoding="utf-8"?> ... straightforward, but a formal association between the Add and Subtract request messages and their associated response messages would remove any possible ambiguity A formal description of the message patterns is even more important for more complex Web services Some Web services might accept a request but not send a corresponding response back to the client Others might only send messages to the client The. .. default value If the style attribute is not set, the default value is document The soap:operation element provides binding information for the operation as a whole You can use it to specify the document style as well as the SOAPAction HTTP header value for HTTP bindings The following portion of the Calculator Web service WSDL document demonstrates the use of the soap:binding element: < ?xml version="1.0"... The GetQuote method accepts information about the requested tire and the quantity The price of the new tires is then returned as a double However, because the Tire datatype is abstract, the Web service needs to receive a derivative of the Tire type The following SOAP message requests a quote for new tires of type AutoTire: < ?xml version="1.0" encoding="utf-8"?> . represents the long version of the U.S. Federal income tax form. It might not be necessary for all filers to complete the entire long form, so the government issues the EZ form. The EZ form is. be assumed. The following is the complete schema for the Commerce Web service: 86 < ?xml version=‘1.0’?> <schema xmlns="http://www.w3.org/2001/XMLSchema.xsd" xmlns:tns="urn:Commerce". documents. For example, tax preparation services often collect information beyond what is called for on the long income tax form. The tax preparation service might therefore want to derive from the