RE: Why use WSDL?

Anne Thomas Manes Fri, 07 May 2004 14:13:48 -0700

Yes. Convert collections to arrays or arrays within an array.

There's some discussion within the W3C WSDL group to define some recommended
schema examples. See the attached email.

Anne

-----Original Message-----
From: Dorner Thomas [mailto:[EMAIL PROTECTED] 
Sent: Friday, May 07, 2004 7:57 AM
To: '[EMAIL PROTECTED]'
Subject: AW: Why use WSDL?

OkOKOkkkk,

one moment, do i understand it?

You say i should not use Hashmaps or Hashtables for SOAPConnections?

I shall use Arrays - for this I should use 2 Dimensional Arrays or Array in
Array?

Can u explain more detailed???? please

Thanks Tomi

-----Urspr�ngliche Nachricht-----
Von: Galbreath, Mark A [mailto:[EMAIL PROTECTED]
Gesendet: Freitag, 7. Mai 2004 13:50
An: '[EMAIL PROTECTED]'
Betreff: RE: Why use WSDL?

You mean to say to DO expose collections AS arrays?

-----Original Message-----
From: Anne Thomas Manes [mailto:[EMAIL PROTECTED]
Sent: Friday, May 07, 2004 7:50 AM
To: [EMAIL PROTECTED]
Subject: RE: Why use WSDL?

Sorry -- what I meant to say ...

First rule of interoperability -- do NOT expose collections (List, Map, etc)
through your interface. 

Anne

-----Original Message-----
From: Anne Thomas Manes [mailto:[EMAIL PROTECTED] 
Sent: Friday, May 07, 2004 7:40 AM
To: [EMAIL PROTECTED]
Subject: RE: Why use WSDL?

Turn your hashmap into an array.

First rule of interoperability -- do expose collections (List, Map, etc)
through your interface. 

Anne

-----Original Message-----
From: Dorner Thomas [mailto:[EMAIL PROTECTED] 
Sent: Friday, May 07, 2004 2:54 AM
To: '[EMAIL PROTECTED]'
Subject: AW: Why use WSDL?

Some problems by using wsdl:

I have a auto generated wsdl (java2wsdl axis)- A friend wanna use
this wsdl by by axis c++ (wsdl2ws) to generate the classes.

My wsdl contains a Hashmap - see example:

 <wsdl:types>
- <schema targetNamespace="http://xml.apache.org/xml-soap";
xmlns="http://www.w3.org/2001/XMLSchema";>
  <import namespace="http://schemas.xmlsoap.org/soap/encoding/"; /> 
- <complexType name="mapItem">
- <sequence>
  <element name="key" nillable="true" type="xsd:string" /> 
  <element name="value" nillable="true" type="xsd:string" /> 
  </sequence>
  </complexType>
- <complexType name="Map">
- <sequence>
  <element maxOccurs="unbounded" minOccurs="0" name="item"
type="apachesoap:mapItem" /> 
  </sequence>
  </complexType>
  </schema>
  </wsdl:types>

But the tool can�t handle the type Hashmap - exception:

org.apache.axis.wsdl.wsdl2ws.WrapperFault: unregisterd type
{http://xml.apache.org/xml-soap}Map refered

So, not even axis can handle their own wsdl?
Their is also a Hashtable in c++!?

Have somebody an idea to solve this problem?

Thanks Thomas

-----Urspr�ngliche Nachricht-----
Von: Hittesdorf,Michael [mailto:[EMAIL PROTECTED]
Gesendet: Donnerstag, 6. Mai 2004 17:43
An: [EMAIL PROTECTED]
Betreff: RE: Why use WSDL?

Some good reasons to use WSDL:

1. WSDL aids interoperability. You can post your WSDL to a directory and
any Web Services developer in any technology (Java, .NET, etc.) will
have everything they need to build a client to invoke your service
(assuming it conforms to established conventions/standards, such as
WS-I)

2. WSDL is more expressive than Java alone. With WSDL I can specify
message payloads, invocation styles (RPC or document) and encoding, as
well as endpoint addresses.

3. WSDL is a required artifact for many testing tools, Web Services
frameworks, and service management products. Without WSDL, you can't
take advantage of these technologies

4. WSDL is a standard.  Though Axis lets you develop 'Web Services'
without WSDL, this is not the accepted approach.  You are better off
conforming to standards and conventions when building software that
potentially needs to communicate with the outside world.

5. WSDL assists in portability. If you want to switch from Axis to
another Web Services toolkit, you will have a definition of your service
from which to start.

There are probably other reasons but these are what comes immediately to
mind.

Mick

-----Original Message-----
From: Robert Mecklenburg [mailto:[EMAIL PROTECTED]

Sent: Thursday, May 06, 2004 9:17 AM
To: Axis Users
Subject: Why use WSDL?

I'm new to axis and web services and I have a basic question.

Why bother with wsdl?

Here is a service:

public class Service
{
  public String doSomething(String name) throws RemoteException
  { ...
    return result;
  }
}

Here is a client:

public class Client
{
  public String add(String name) throws AxisFault
  {
    Call call = new Call(getServerURL() + "/Service");
    return (String) call.invoke("doSomething", new Object[] {name});
  }
}

What could be simpler?  When I started with axis I wrote interfaces,
then ran Java2WSDL, then generated client and server stubs with
WSDL2Java.  For a similar service I wound up with 7 classes and 200
lines of code -- all of which appears to be pointless.  I can do the
same thing with 0 extra classes and two lines of simple java if I
avoid the WSDL.

So I'm trying to figure out what I'm missing.  Obviously someone
thinks WSDL is worth all the extra obscurity, code bloat, and build
complexity.  Please tell me your reasons.

Thanks!
--

Robert

E-MAIL CONFIDENTIALITY NOTICE:  The contents of this e-mail message and any
attachments are intended solely for the

addressee(s) and may contain confidential and/or legally privileged
information. If you are not the

intended recipient of this message or if this message has been addressed to
you in error, please

immediately alert the sender by reply e-mail and then delete this message
and any attachments. If you

are not the intended recipient, you are notified that any use,
dissemination, distribution, copying, or

storage of this message or any attachment is strictly prohibited.

--- Begin Message ---
Title: Schema Examples for Primer

In fulfilment of my action item from the January 8th telcon[1],
here are a proposed set of schema examples for inclusion in the
WSDL 2.0 Primer.

If you can remember that far back, these examples are offered as
a pattern useful for describing some common data structures in WSDL.
The intent is to give implementers simple patterns for exposing data
structures in schema and to facilitate the round tripping from code
onto the wire and back again.

The data structures under consideration are programming language and
environment agnostic:

- Collection
- Vector
- Map

COLLECTION
----------

A collection of data items (an object, class, structure, record etc)
is best represented as a complexType with the individual items as
elements and/or attributes. Sadly it needs saying that the compositors
"sequence", "all" *and* "choice" should be supported.

<xs:complexType name="ProductType">
    <xs:sequence>
      <xs:element name="name" type="xs:string"/>
      <xs:element name="colour" type="xs:string"/>
    </xs:sequence>
    <xs:attribute name="id" type="xs:string" />
</xs:complexType>

Extending a Collection
----------------------

Explicit (active) extensibility of a collection may be expressed
using 'any' and 'anyAttribute' as in the following example adapted
from the draft TAG finding on extensibility and versioning[2]:

   <xs:complexType name="ProductType">
      <xs:sequence>
        <xs:element name="name" type="xs:string"
            minOccurs="1" maxOccurs="1"/>
        <xs:element name="colour" type="xs:string"/>
        <xs:any processContents="lax"
              minOccurs="0" maxOccurs="unbounded"/>
     </xs:sequence>
     <xs:attribute name="id" type="xs:string" />
     <xs:anyAttribute/>
   </xs:complexType>

The 'any' wildcard is only deterministic when applied to the end of
a 'sequence' - determinism being particularly important when generating
messages from a schema definition. Again it needs saying that tools
should support the 'namespace' attribute including the '##any',
'##other' and '##targetnamespace' values.

I suggest we discuss Henry Thompson's findings on passive versioning
separately [3].

VECTOR
------

A vector is an ordered sequence of items of the same data type. This is
a very common construct in programming languages appearing as an array or
list. Multi-dimensional arrays may be built by composing vectors within
vectors. Formalising more complex constructs such as sparse or jagged
matrices are beyond the scope of these examples.

The WSDL 1.1 note[4] suggested naming array types using the prefix
"ArrayOf" and offered the following schema extract for presenting arrays
in WSDL:

<xs:complexType name="ArrayOfFloat">
    <xs:complexContent>
      <xs:restriction base="soapenc:Array">
         <xs:attribute ref="soapenc:arrayType"
                    wsdl:arrayType="xsd:float[]"/>
      </xs:restriction>
    </xs:complexContent>
</xs:complexType>

Some encoded tools rely upon the soapenc:arrayType annotation attribute
appearing on the wire, e.g.:

    <prices soapenc:arrayType="xs:float[3]">
      <price xsi:type="xs:float">0.34</price>
      <price xsi:type="xs:float">0.44</price>
      <price xsi:type="xs:float">0.21</price>
    </prices>

Other implementations require the array size to match
the number of items appearing in the container structure.

This led to very good interoperability between SOAP section 5 aware
tools but introduced difficulties for document processors which had to
nest the repeated elements in otherwise flat documents as well as
providing soapenc and xsi annotations. So the WS-I Basic Profile[5]
specifically prohibited using the SOAP section 5 annotation as well
advising against using the "ArrayOf" prefix. The following schema extract
is given as an example for an array:

<xsd:element name="MyArray1" type="tns:MyArray1Type"/>
<xsd:complexType name="MyArray1Type">
    <xsd:sequence>
      <xsd:element name="x" type="xsd:string"
                   minOccurs=0 maxOccurs="unbounded"/>
    </xsd:sequence>
</xsd:complexType>

Serialised as:

<MyArray1>
    <x>abcd</x>
    <x>efgh</x>
</MyArray1>

I'd quite like to endorse the above pattern for an example of a
vector as it's a common output from current tools when generating
document/literal 1.1 WSDLs from code. But elements which may be
repeated outside of an array container should also be mapped
in code as an array, e.g:

<xs:complexType name="Address">
    <xs:sequence>
      <xs:element name="lines" type="xs:string" maxOccurs="unbounded"/>
      <xs:element name="telnos" type="xs:string" maxOccurs="unbounded"/>
    <xs:sequence>
</xs:complexType>

The above example would be presented as a collection containing two
separate arrays. Unfortunately this isn't orthogonal: a WS-I example
array would flip into a collection containing an array if it was later
extended to contain another element. Not good. So we should offer:

<xs:element name="products" type="tns:Product" maxOccurs="unbounded"/>

as an example for a vector, making the WS-I example present a collection
containing a single vector. This actually what a number of existing
WSDL 1.1 toolkits do anyway.

MAP
---

A map is a common construct provided by many languages as a 'hash
table', 'dictionary', 'map', 'indexed table', 'associative
array', 'associative memory' etc.

SOAPBuilders discussed how to exchange map types several times. Looking
through the mailing list[6] it seems that the proposals were mainly aimed
at section 5 encoding using on the wire annotations, element naming
conventions or extensions of a common type. I didn't think these approaches
suitable for a generalised literal context so looked for a common schema
pattern to express a map.

The Key
-------

A map may be viewed as a Vector in which each item is accessible via
a unique key:

- The key is unique and identifies a collection of data items.
- The key is often (but not always) a simpleType.

In the following example list of products, each item is identified
by a productId:

     '10203' => {
         name => 'apple'
         price => '35',
     },

     '10204' => {
         name => 'pear',
         price => '50',
     },

This could be represented in XML as:

     <product id="10203">
         <name>apple</name>
       <price>35</price>
     </product>

     <product id="10204">
         <name>pear</name>
       <price>50</price>
     </product>

To turn a Vector into a map all that is required is to recognise
which element attribute contained within of the repeated element
is the key. W3C Schema offers a number of standard mechanisms to
describe uniqueness:

   - xs:ID
   - xs:unique
   - xs:key

xs:ID as a Key
--------------

xs:ID is similar to the DTD ID type with the following properties:

   - the type has the same lexical space as xs:NCName
   - the ID may be an attribute or an element
   - the ID value must be unique with the document
   - there may be one or more ID's associated with an element

The PSVI set contains a ID/IDREF table[7] which is an index pointing
to nodes with an included xs:ID element/attribute.

The new xml:id[8] attribute from the XML Base WG offers an neat way of
expressing an ID value for an element targeted at recipients who may not
have access to a schema. A so called 'disengaged' agent may easily more
recognise a map from a document containing xml:id attributes and present
the repeated element as an associative array, e.g:

     <product xml:id="product_10203">
         <name>apple</name>
       <price>35</price>
     </product>

     <product xml:id="product_10204">
         <name>pear</name>
       <price>50</price>
     </product>

WSDL Schema for above xml:id example:

   <types>
     <xs:schema targetNamespace="http://www.w3.org/1998/XML/Namespace">
       <xs:attribute name="id" type="xs:ID"/>
     </xs:schema>

     <xs:schema targetNamespace="http://www.openuri.org/">
       <xs:import namespace="http://www.w3.org/XML/1998/namespace"/>

       <xs:complexType name="ProductType">
         <xs:sequence>
           <xs:element name="name" type="xs:string"/>
           <xs:element name="price" type="xs:string"/>
         </xs:sequence>
         <xs:attribute ref="xml:id" use="required" />
       </xs:complexType>

       .....
     </xs:schema>
   </types>

xs:unique as a Key
------------------

The xs:unique provides a means of expressing that an element or attribute
value is unique within a specified set of elements. A selector XPath
_expression_ defines the set of elements and attributes which constitute
the context, a second field XPath _expression_ identifies an element or
attribute which must be unique within the context, e.g.:

<xs:element name="products">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="product" type="ProductType"
               maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>

    <xs:unique name="product">
      <xs:selector xpath="product"/>
      <xs:field xpath="@id"/>
    </xs:unique>

</xs:element>

<xs:complexType name="ProductType">
    <xs:sequence>
      <xs:element name="name" type="xs:string"/>
      <xs:element name="price" type="xs:string"/>
    </xs:sequence>
    <xs:attribute name="id" type="xs:string" />
</xs:complexType>

xs:key as a Key
---------------

xs:key is very similar to xs:unique, but adds a constaint that all
nodes corresponding to all fields have to be present. Key has been
designed for use with xs:keyref - similar to ID/IDREF in DTD with
the difference that the uniqueness is within a XPath defined scope.
xs:key is therefore preferable to xs:unique when describing a key.

Map Summary
-----------

   - ID is an NCName datatype. A raw number such as an ISBN such as
     "0123456789" could be represented as "isbn_0123456789", more
     complex types such as a Java object will require a hashed key
     value.

   - ID has to be unique within the entire document. A context specific
     prefix could added to the front of each key.

   - there may be more than one ID, xs:unique or xs:key value for
     a repeated element. Rules as to which element/attribute should be
     used as the primary key could be provided, or be left undefined.

   - ID's are presented in the PSVI ID/IDREF table. May assist processing.

   - xs:unique and xs:key are more explicit in which containing elements
     form the map.

   - xs:unique and xs:key allow multiple fields to form a composite key

   - xs:unique and xs:key are complex and not well supported by current
     implementations

   - not all schema languages have a means of expressing a uniqueness
     constraint. xs:unique and xs:key don't map well to Relax NG.

I'd suggest using the simple xml:id as a good mechanism for generating
a map from code with the caveats on the key having to be NCName as well
as document wide unique.

I suggest we offer xml:id, xs:ID, xs:unique and xs:key as patterns for
recognising a map when binding schema to code.

Paul

--
Paul Sumner Downey
Web Services Integration
BT Exact

[1] minutes from January 8th Telcon:
http://tinyurl.com/2gflf
http://lists.w3.org/Archives/Public/www-ws-desc/2004Jan/att-0029/minutes_200
40108.htm#item05

[2] David Orchard, Norman Walsh, "Versioning XML Languages":
http://www.w3.org/2001/tag/doc/versioning.html

[3] Henry Thompson, XML2004 "Versioning made easy with W3C Schema":
http://lists.w3.org/Archives/Public/www-ws-desc/2004Apr/0019.html
slides:
http://www.markuptechnology.com/XMLEu2004/

[4] WSDL 1.1 Note:
http://www.w3.org/TR/wsdl

[5] WS-I Basic Profile 1.0 Board Approved Draft, example array:
http://tinyurl.com/2o9x2
http://www.ws-i.org/Profiles/Basic/2003-03/BasicProfile-1.0-BdAD.html#IDAAN4
GB

[6] SOAPBuilders long thread on map types
- includes contributions from Glen and Gudge!
http://groups.yahoo.com/group/soapbuilders/message/1331

[7] PSVI Set Contribution: ID/IDREF Table:
http://www.w3.org/TR/xmlschema-1/#sic-id

[8] xml:id Working Draft:
http://www.w3.org/TR/xml-id/

--- End Message ---

RE: Why use WSDL?

Reply via email to