issue #144 proposal - array metadata in SOAP Encoding (long)

 Hello all. 8-)
 This message is a proposal for how we can encode arrays in SOAP
Encoding in more XML-like way.

 First let me review the requirements for encoding Arrays:
 1) encoding must be able to serialize one-dimensional and
multidimensional arrays,
 2) an instance of an array must be able to convey the type of its
elements
 3) an instance of an array must be able to convey the its size in
all its dimensions
 4) encoding must be able to serialize partially transmitted
arrays efficiently (sparse arrays are also partially transmitted)

 The pieces of information that need to be encoded are:
 a) number of dimensions of an array
 b) size in each of the dimensions
 c) the actual items along with their types
 d) positions of the items (in case of partially transmitted
arrays)

 The current spec serializes items a) and b) into a string of a
rather non-XMLish structure (the arrayType attribute), also the
item d) is encoded in a similar way (in offset and position
attributes).
 The proposal serializes item a) implicitly when serializing item
b), it serializes item b) in a an attribute of the type List of
(positiveInteger or '*'), item c) as usual, with the types
specified using xsi:type on the members, possibly defaulted by a
different attribute, and item d) using two attributes, offset and
position, this time Lists of nonNegativeInteger.

 ------------------------------ the proposal begin
 4.1 rule #8
 Arrays are compound values (see also 4.4.2 Arrays). SOAP Encoding
arrays are defined as having a type of "enc:Array" or a type
derived there from.
 SOAP Encoding arrays have one or more dimensions. An array value
is represented as a series of elements reflecting the array, with
members appearing in ascending ordinal sequence. For
multi-dimensional arrays the dimension on the right side varies
most rapidly.
 SOAP Encoding arrays can be single-reference or multi-reference
values, and consequently may be represented as the content of
either an embedded or independent element.
 A SOAP Encoding array MAY contain an enc:arraySize attribute of
the type "List of (positiveInteger or '*')" whose items mean the
sizes in each of the array's dimensions (unspecified size in case
of the asterisk). The number of the sizes representes the number
of dimensions of this array. The default value of this attribute
is "*". For example, enc:arraySize="3 5" attribute signifies a
two-dimensional array with three rows and five columns.
enc:arraySize="* 5" signifies a two-dimensional array with an
unspecified number of rows and five columns.
 In case there is an asterisk on other than the first position,
all the elements in the array MUST specify their position.
 A SOAP Encoding array MAY contain an enc:itemType attribute of
the type QName. This type specifies the base type for the type of
every member of the array. The default value of this attribute is
anyType. Each member's type must be a subtype of itemType or it
must be the itemType itself.
 A SOAP Encoding array MAY contain an enc:offset attribute
indicating the position of the first item in the enclosing array.
This can be used to indicate the offset position of a partially
represented array (see 4.4.2.1 Partially Transmitted Arrays).
 Likewise, members of an array MAY contain an enc:position
attribute indicating the position of that member in the enclosing
array. This can be used to describe members of sparse arrays (see
4.4.2.1 Partially Transmitted Arrays). The position attribute MUST
be used either on all of the members or on none of them at all.
 The value of the enc:offset and the enc:position attribute is of
type "List of nonNegativeInteger" with offsets and positions based
at 0.
 In the presence of both offset and position the position
attribute has precedence over the offset attribute, they are not
combined.
 The number of the members in an array must not be greater than
the size of the array (taking into account the offset attribute).
No two members in an array may specify the same position.


 4.4.2 Arrays
 SOAP Encoding arrays are defined as having a type of enc:Array or
a derived type having that type in its derivation hierarchy (see
also rule 8 in 4.1 Rules for Encoding Types in XML). Such derived
types would be restrictions of the enc:Array type and could be
used to represent, for example, arrays limited to integers or
arrays of some user-defined enumeration. Arrays are represented as
element values, with no specific constraint on the name of the
containing element (just as values generally do not constrain the
name of their containing element). The elements which make up the
array can themselves can be of any type, including nested arrays.
 An array is represented as an ordered sequence of elements
constituting accessors to the items of the array. Within an array
value, element names are not significant for distinguishing
accessors. As with compound types generally, if the value of an
item in the array is a single-reference value, the item contains
its value. Otherwise, the item references its value via an href
attribute.

 [stripped examples and schemata updated according to the rules above]

 4.4.2.1 Partially Transmitted Arrays
 SOAP Encoding provides support for partially transmitted arrays -
arrays in which some members are not transmitted. SOAP Encoding
provides two varieties of partially transmitted arrays:
 1) arrays whose beginning and/or ending is skipped,
 2) sparse arrays in which all its members specify their
positions.
 The first variety of arrays MAY contain the attribute enc:offset
which specifies how much of the beginning of the array is skipped.
Skipping the ending of an array is done by simply not transmitting
the members at the end.
 In the case of offsetted arrays the first member's position
equals the offset, the next member's position follows the same
rules as in non-offsetted arrays. For example:

<enc:Array enc:offset="2 2" enc:arraySize="4 3">
   <x>3rd row, 3rd col</x>
   <x>4th row, 1st col</x>
   <x>4th row, 2nd col</x>
</enc:Array>

 The members of the second variety of arrays - sparse arrays -
MUST all contain the attribute enc:position.
 ------------------------------ the proposal end


 Summary of my changes:

 I have split the attribute arrayType into two attributes, one
one that specifies the size of the array, other that specifies
the type of the members. In this situation we have no more string
parsing because the types are usual XML Schema types - QName,
integer and a list - so life should be considerably easier on the
developers. Also, none of the attributes is now necessary in case
of a linear array if we don't want to know beforehand the types.
 I have changed the type of the attributes position and offset to
match the above so that it's consistent.
 I have clarified the usage of offset and position (according to
my view on how to use these attributes).
 I have consolidated the sections on sparse arrays and partially
transmitted arrays because sparse arrays are also partially
transmitted. 8-)

 I have not attempted to resolve the meaning of the omitted
elements (nil, nothing) in partially transmitted arrays because
the heated debates on this issue would probably set back my
proposal.

 Hope you enjoyed this email. 8-)

                            Jacek Kopecky

                            Systinet, Inc.
                            http://www.systinet.com/

Received on Thursday, 25 October 2001 13:56:11 UTC