SOAP VERSION 1.2 Chinese Manual 4

5. SOAP encoding

The SOAP encoding style is based on a simple type system, and this system is generally in the common characteristics of the type system in the program language, database, and semi-structural data. A type is either a simple (quantified) type or a composite type, which consists of multiple parts, each part of which is a type. There will be a more detailed description below. This section defines a sequencing rule for the order of type of object map. It operates at two levels. First, a mode of the XML syntax layer is constructed by the pattern described by this type of system is given on a symbol. Next, a model of a type system and a representation of a value consistent with this mode are provided, and a mode of an XML instance layer is constructed. Conversely, first provide an example of these rules XML, and then give the original mode, one original value is also constructed.

The namespace identifiers used in the elements and properties defined in this section are "http://www.w3.org/2001/06/soap-encoding". In the examples of these codes, it is assumed that all namespace declarations are at higher elements levels.

The data model and coding style described in this section are encouraged instead of prerequisites, other data models and codes can also be used in combination with SOAP (see section 4.1.1).

5.1 Rule for type encoding using XML

XML allows very flexible encoding data very flexible. SOAP only defines a very limited coding rule. This section defines a coding rule at a high level, and the next section describes the clear type of coding rule that is when there is a more detailed demand. The encodings described in this section can be used in combination with the RPC calls and responses described in Section 7.

To describe the encoding, the following terms will be used:

The "value" value is a string, a metric (number, date, a rose) name, or a combination of a plurality of simple values. All values ​​have a clear type. The Simple Value is a simple value that does not contain any portion that can be named. The simple value of ions can be specific strings, certificates or rose values. "Compound value" composite value is a gathering of a value. Examples of composite values ​​can be specific purchase orders, inventory reports, street addresses, etc. In a composite value, each associated value can be distinguished by a role name, or a number of orders can be used to distinguish between, of course, can be used simultaneously. This is called "Accessor" access ID. The ions of the composite value include a specific purchase order, inventory report, etc. An array is also a composite value. It can be seen as a composite value of an access identity (Accessor) having multiple identical names, such as RDF. "Array" array is a composite value, and there is only a different location between its member values. The "Struct" structure is a composite value, and the distinction between its member values ​​is to rely on access identification (Accessor). At the same time all the names of access identity should be different. The Simple Type is a simple type of simple value. Simple types of examples include those "string", "integer", rose classes, etc. "Compound Type" composite type is a class of composite values. Examples of composite types include an abstract type of purchasing order, which has the same access identifier (Shipto, Totalcost, etc.), of course they have different values ​​(perhaps constraints may be constrained for some values). In a composite type, an access identity is unique in this conformational type, and if it is unable to distinguish between an access identity in other composite types, the access identity name is the name of the composite type to become The only identifier, this name is "local name". Whether the name is directly or indirectly based on a URI, if the access identifier does not have to add type name constraints, then the name is "global name". The information given in the mode of the value list is possible to determine that some values ​​can only be associated with a simple instance of an access identity. For other possible situations, this assertion cannot be disconnected. A value is called "Single-Reference" single reference, if only one access identifier can be referenced. If you can be quoted by multiple references, whether in fact, there is a potential, that is, "multi-reference" more references. Note that there is a certain value in a mode is single to use and others are more references. In syntactics, an element can be "independent" or "embedded". A separate element appears as a top element in order. And others are embedded elements. Although the XSI: Type property can make the value of the value as described herein, that is, the structure of the containing value also contains the type of value, but the type of sequencing rule allows the value of the value can only be defined in the schema (SCHEMA). These modes can be described using the specification defined in "XML Schema Part 1: Structures" [10] and "XML Schema Part 2: DataTypes [11], of course, other mode definitions can also be used. Note that although this, many modes define only the structure (STRUCT) and array (array) types, and the order rules are likely to try the composite type outside of the structure (STRAY) type.

The order rules are as follows:

All values ​​should be expressed as contents. A multi-reference value must be represented as an independent element. And a single reference value should not be said (but can be the case). For each element containing a value, the value of the value indicates that the following at least one of the conditions must be met: (a) Element instance containing this value contains an XSI: Type property, (b) element instance containing this value is included in an ENC : The element of the arraytype property (may be set to default), (c) the name of the element with a type of explicit association, and this type is determined by a mode. A simple value should be expressed as character data, that is, no child elements. Each simple value must have a type, which is either in the DataTypes section [11] of the XML Schema specification, or its source type should be listed in this section (see Section 5.2). A composite value should be encoded as an element sequence, each of which is represented by an embedded element, and their name is one or one. If the name of the access identity is part in the type containing it, it has an unmodified element name, while others should have a fully modified name (see Section 5.4). A simple or composite value of a multi-reference should be encoded as a separate element, which should contain a local "ID" attribute with non-limiting names, which is the ID type defined in XML specification [7]. . Each access identifier for this value is an empty element, which has a local unmodified attribute "href", which is the "URI-REFERENCE" type defined in the XML Schema specification [11], " The value of the HREF "property is a URI clip identifier that references to the corresponding independent element. Strings and byte arrays are represented as multi-reference simple types, but special rules also allow them to represent more efficiently (see Section 5.2.1 and Section 5.2.3). A string or byte array access identifier may have an attribute of an ID type named "ID" in XML specification [7]. If this is, all other access identities for the same value can be encoded as an empty element, which should include a local "href" attribute with a non-limiting name, the type of the attribute is an XML Schema specification [ 11] The "URI-REFERENCE" type defined in the 11th, the value of the "HREF" attribute is a URI clip identifier that references the corresponding independent element. Multiple references to a value encoding are allowed, which seems to be referenced by reference to multiple different values, but only the meaning of the XML instance is not changed only when it is from the context. The array is a composite value (see section 5.4.2). The SOAP array is defined as the type "ENC: Array" or type is from "Enc: Array". The SOAP array has one or more dimension, and its members are distinguished by the order. The value of an array is expressed as a sequence that reflects the elements of the array, and these members appear from small to large order. For multi-dimensional arrays, the element dimension changes from right to left order. No member elements are named a separate element (see Rule 2). The SOAP array can be a single value, or a multi-reference value, so that it can be represented as an embedded element or a separate element. The SOAP array must contain a "ENC: ArrayType" property, where the type of value defined contains the value of the element describes the array with the dimension. The value of the "ENC: ArrayType" property is as follows:

ArrayTypeValue = atype asizeatype = qname * (rank) Rank = "[" * (",") "]"] "=" ["#olength"] "= 1 * Digit" Atype "structure is an array contains elements included in arrays Name of the type, first it contains a QNAME indicating that QNAME should appear in the "Type" attribute in the XML Schema element declaration, QNAME is a constraint (meaning all of the elements they contain, should claim consistent with the specified type That is, the type referenced in ENC: ArrayType must be the type or hyperweight of all array elements). For those arrays or "jagged arrays", using the RANK structure, the element of the array is an array, and the specific type of the array will instantiate the value when the definition of the following specific member array, zero in the Rank, one To multiple commas, the member variable is a one-dimensional, two-dimensional or multi-dimensional array. For multidimensional arrays, dimension is defined as a "," separated dimension sequence, each dimension number of counts of 1. The "Asize" structure contains a length of each dimension of an array indicated by a comma-separated sequence consisting of zero, one or more integers. A sequence consisting of zero integer indicates that there is no particular limitation on the array, but the specific size will be determined by the underlying member. For example, a group with 5 members, the member type is an array, and the value of its ArrayTyPeValue should be "int [] [5]". Where the value of atype is "int []", the value of Asize is "[5]". Similarly, a group with three members, member types are INTEGER 2D arrays, and its value of ARRAYTYPEVALUE should be "int [,] [3]". Among them, the value of atype is "int [,]", and the value of asize is "[3]". The SOAP array member can include an "Enc: Offset" property to indicate the offset in the array of the member. This can also be used to indicate the offset of members in an array described in a portion (see section 5.4.2.1). Similarly, the SOAP array member can include a "enc: position" property to indicate the location of the member in its loading. This can also be used to indicate the position of the member in a sparsely described array (see section 5.4.2.2). The value of "enc: offset" and "enc: position" attribute is defined as: arraypoint = "[" #olength "]" their base is 0. NULL values ​​and default values ​​can be omitted in access identification elements. NULL value can be specified in an attribute XSI: null using a value of 1 in an access identification element, or may be other dependent attributes and values.

Note that rule 2 allows the individual elements and the member elements in the array to have different names for the included types.

5.2 Simple Type

For simple types, SOAP uses all types, including values ​​and vocabulary spaces (Lexical Spaces) defined in "Build-in DataTypes" section in "XML Schema Part 2: DataTypes" [11]. Examples include:

Typeexampleint58502float314159265358979e 1NEGATIVEINTEGER-32768STRINGLOUIS "Satchmo" ARMSTRONG

The data type declared in the XML Schema specification can be used directly in element mode. The type of these types can also be used. Below is an example of a pattern fragment and a corresponding type of element data:

EXAMPLE 7

Schema with Simple Types

Here are some legal elements:

EXAMPLE 8

45

5.9

-450

Blue

Message Fragment Corresponding to the Schema in EXAMPLE 7

Whether the simple value type is defined in the "XML Schema Part 2: DataTypes" specification, or based on the type definition mechanism provided by the XML Schema specification, it must be encoded as an element.

If a simple value is encoded as an independent element or a heterogeneity element, it is convenient to have an element declaration corresponding to the data type. Because the type definition is included in the "XML Schema Part 2: DataTypes" specification, it contains a declaration of the corresponding element, while the ENC mode and namespace declare an element for each simple data type. These are can be used.

EXAMPLE 9

45

5.2.1 String

"String" Data Type is defined in "XML Schema Part 2: DataTypes" [11]. It is worth noting that in many databases or programming languages, the "string" type is not consistent. In some special languages, only some characters may appear in "String". (These values ​​may need to represent some data types other than XSD: String)

A string can be encoded as a single reference or multi-reference value.

Elements containing the string value can have a "id" attribute. Additional access identification elements can have the "href" property that matches it.

For example, if there are two access identities to the same String, it can be manifested as:

EXAMPLE 10

Hello

Two Accessors for the Same String

In any case, it is true that two references to a String (or String subtype) are not essentially different from the instance of a String (or String subtype):

EXAMPLE 11

hello

Hello

Two Accessors for the Same String

The mode description for these examples may be:

EXAMPLE 12

XMLns: enc = "http://www.w3.org/2001/06/soap-encoding">

Schema for Example 11

(In this example, the ENC: String type for describing the element type is a convenient method to describe the type of element is "XSD: String", and it can come with "ID" and "href" properties. You can see SOAP Encoding mode is defined. Mode can also use declarations in these SOAP Encoding mode, but not necessarily.)

5.2.2 enumeration

"XML Schema Part 2: DataTypes" specification [11] defines a mechanism called "Enumeration". The SOAP data model uses this mechanism. However, due to some subtle differences in the definition, there are some subtle differences in the definition, we describe more detailed concepts and describe how to encode one of the values ​​that become a list of Raised lists. Specifically, it encodes the name of this value.

In concept, "Rapu" expressed a group of different names. A concrete rose is a specific list of different values ​​that meet the basic type. For example, a collection of color names ("Green", "BLUE", "brown") can be defined as a rose, value ("1", "3", "5") based on built-in String type, may be one Based on Integer's Rapu, and so on. "XML Schema Part 2: DataTypes" specification [11] supports all simple types of simple types outside Boolean. "XML Schema Part 2: Structure" specification [10] language can be used to define a generic type. If a mode is generated from another symbol system without a specific basic type, then "String" is used. In the following mode, "EyColor" is defined as a String's rising, which may include "Green", "Blue", "brown", and the instance data is also given.

EXAMPLE 13

XMLns: TNS = "http://example.org/2001/06/samples"

Targetnamespace = "http://example.org/2001/06/samples">

Schema with enumeration

EXAMPLE 14

brown

Message Fragment Corresponding to the schema in Example 13

5.2.3 byte arrays

A Byte array can be encoded as a single reference or multi-reference value. The coding rule of the Byte array is similar to string.

Special, elements containing a Byte array value can have a "id" attribute. Additional access identification elements can have a "href" attribute for matching.

Recommended representation of an opaque BYTE array is to use "Base64" encoding mode defined in XML Schema Specifications [10] [11], the specific encoding algorithm is defined in RFC 2045 [13]. However, the data line length of Base64 encoded data in MIME will not exist in SOAP. The "ENC: Base64" subtype should be used in SOAP to define the base64 encoding.

EXAMPLE 15

XMLns: enc = "http://www.w3.org/2001/06/soap-encoding"

XSI: Type = "ENC: Base64">

AG93IG5VDYBICM73BIBJB3CNCG ==

Image with base64 encoding

5.3 Polymorphism

Many languages ​​allow access identities to access several types of values, each type can be used at runtime. A polymorphic access identification instance must contain a "XSI: Type" property to describe the actual value of the type.

For example, a polymorphic access identifier named "COST" with a value of "XSD: float" can be encoded as:

EXAMPLE 16

XMLns: XS = "http://www.w3.org/2001/xmlschema"

XSI: Type = "xs: float"> 29.95

POLYMORPHIC Accessor

The relative to it is a value type unchanged COST access ID.

EXAMPLE 17

29.95

Accessor Whose Value Type is invariant

5.4 composite type

SOAP defines composite types in accordance with the following structural modes that are often seen in the program language: Struct

"Struct" is a composite type value, and its member's access identifier name is the only flag of mutual distinguishment, which should be different from each other.

Array

"Array" is a composite type value, and the order position of its member is uniquely different from each other.

SOAP also allows the data to be sequencing, that is, not Array, such as a single data node in the Directed-Labled-Graph data model, there are many different access identities, some of which will occur multiple times. SOAP sequence does not require the lower data model to distinguish the order difference between the access identity, but if there is such a order, the access identity must be encoded in accordance with the order.

5.4.1 Quote for composite values

Members of the composite value are encoded to access identification elements. The access identifier is distinguished by their name (eg, in Struct), and the element name is to access the identification name. The access identity name is part, the scope is included in their type, with an unmodified element name, while others have a complete modifier.

Here is an example of a "book" structure:

EXAMPLE 18

Henry Ford

prefactory text

this is a book.

Book Structure

The following is a mode segment describing the structure:

EXAMPLE 19

XMLns: XS = 'http://www.w3.org/2001/xmlschema'>

Schema for Example 18

Below is an example of a type containing a simple type member also contains a composite type member. It shows two layers of references. Note "HREF" attribute of "Author" access identification element A reference to the value corresponding to the "ID" value. The situation in "Address" is also similar.

EXAMPLE 20