Extended WSDL XML Schema Support

Web service interfaces are described in a structured way by Web Services Description Language (WSDL) documents, using XML. Domino® Designer supports both import from and export to WSDL. WSDL documents can be imported into skeletal Java™ or LotusScript® implementations, and can be generated from LotusScript or Java Web service implementations. Domino also provides runtime SOAP message-to-implementation de/serialization, based on mappings between Web service implementation objects and their associated WSDL constructs.

With Domino Designer 8.0, the basic XML Schema support provided in 7.0 has been extended to include:

  • Generating WSDL XML Schema-compliant literal array expressions for services of some literal SOAP message types.
  • Importing some XML Schema constructs in the form of mappings to corresponding Java or LotusScript implementation patterns.
  • Importing MBCS Unicode character name attribute values for mapped constructs in the WSDL document.
  • Importing XML Schema <redefines> elements.

Additionally, the following versioned behaviors have been introduced:

  • 7.x Web services replicated to an 8.0 Domino server behave as they do on the 7.x servers.
  • 8.0 Web services replicated to a 7.x Domino server do not run at all.
  • Exporting then re-importing Web service design elements requires regenerating the WSDD deployment descriptor for the current version running.

Literal arrays

The Web Service Interoperability Organization (WSI) has defined a Basic Profile of Web service clarifications to ensure interoperability through commonly supported functionality. WS-I Basic Profile 1.1 expressly prohibits SOAP-encoded arrays.

Arrays appear in various forms and contexts in LotusScript and Java programs:

  • LotusScript arrays
  • Java arrays

In N/D 7.0.x, they routinely map to SOAP-encoded arrays in Designer-generated WSDL (a legacy of the underlying Axis 1.1 open source implementation). This behavior will be retained for encoded services only; Domino 8.0 will introduce new behaviors for literal services (rpc/literal, document/literal, and wrapped).

For WS-I literal service conformance, arrays will generate into WSDL 1.1 as follows.

Note: Examples tend to show arrays of base type "xsd:string", however, in practice, the elements of an array may be of any simple or complex type.

LotusScript arrays

LotusScript arrays appear as follows:

  1. Sub or function input parameters (dim'd by deserialization)
  2. Sub or function output parameters (in a holder class -- dim'd by deserialization and/or service impl)
  3. Function return types (in a holder class -- dim'd by the service)
  4. Class member, dynamic arrays (dim'd by deserialization and/or service impl)
  5. Class member, fixed-size arrays -- NOT SUPPORTED
  6. Type member, fixed-size arrays (dim'd at compilation)

LotusScript array elements may be of some built-in type, a class, a user-defined type, or another array.

Dynamic array dimensions, including multiple dimensions, are only resolved at runtime. Generated WSDL may require fixups/reimport.

Fixed-size array dimensions are not detected during WSDL generation. Generated WSDL may require fixups/reimport.

Java arrays

Java arrays appear as follows:

  1. Method input parameters (declared dimensions)
  2. Method output parameters (in a holder class, declared dimensions)
  3. Method return types (declared dimensions)
  4. Class members (declared dimensions)

Java array base element type may be of some built-in type, a class (including java.lang.Object), or another array.

The following Java classes are also array-like:

  • java.util.ArrayList
  • java.util.Collection
  • java.util.HashMap
  • java.util.HashTable
  • java.util.Map
  • java.util.Vector

LotusScript examples

LotusScript array subroutine or function input parameters, subroutine or function output parameters, and function return types generate into WSDL in the following ways.

1. For encoded services (current 7.0 behavior), the WSDL is generated as follows.

Named SOAPENC array-based <complexType> 's derived by restriction from type "soapenc:Array", e.g:

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

2. For literal services (new for 8.0), the WSDL is generated as follows.

Named <complexType>'s, containing a <sequence> of one <element> typed as the base type of the underlying array element, with an attribute, maxOccurs = "unbounded", e.g:

<complexType name="xsd_stringArray">
  <sequence>
    <element name="item" minOccurs="0" maxOccurs="unbounded" type="xsd:string"/>
  </sequence>
</complexType>
Note: Currently, the <complextype> imports as a class with a single array member.

LotusScript dynamic array class members and fixed-size array type members generate into WSDL in the following ways.

3. For encoded services (current 7.0 behavior), the WSDL is generated as follows.

A member <element> of some <complexType> mapped from its parent LotusScript class, where the member element's <schema> data type is of form 1, for example:

<complexType name="ParentLSClass">
   ...
   <element name="member" type="impl:ArrayOf_xsd_String/>
   ...
</complexType>

4. For literal services (new 8.0 behavior), the WSDL is generated as follows.

A member <element> typed as the base type of the underlying array element, with an attribute, maxOccurs = "unbounded"

<complexType name="ParentLSClass">
  ...
  <element name="member" maxOccurs="unbounded" nillable="true" type="xsd:string"/>
  ...
</complexType>

Java Examples

Java method input parameters, method output parameters, and method return types generate into WSDL in the following ways.

1. For encoded services -- see example 1 under LotusScript Examples

2. For literal services -- see example 2 under LotusScript Examples

Java class members will generate WSDL in the following ways.

3. For encoded services (current 7.0 behavior), the WSDL is generated as follows.

a. A member <element> of some <complexType> mapped from its parent Java class, where the member element's <schema> data type is of form 1, for example:

<complexType name="ParentJavaClass">
   ...
   <element name="member" type="impl:ArrayOf_xsd_String/>
   ...
</complexType>

or

b. A member <element> typed as the base type of the underlying array element, with an attribute, maxOccurs = "unbounded" (where the implementation Java class member is a Java Bean indexed property), e.g:

<complexType name="ParentJavaClass">
  ...
  <element name="member" maxOccurs="unbounded" nillable="true" type="xsd:string"/>
  ...
</complexType>

4. For literal services (new 8.0 behavior) , the WSDL is generated as follows.

A member <element> typed as the base type of the underlying array element, with an attribute, maxOccurs = "unbounded"

<complexType name="ParentJavaClass">
  ...
  <element name="member" maxOccurs="unbounded" nillable="true" type="xsd:string"/>
  ...
</complexType>
Note: Where the Java member is a multi-dimensional array, the type attribute value will reference some WSDL <schema> data type of form 2.

5. The special-case Java classes will map as follows.

java.util.ArrayList

soapenc:Array for "encoded" services

literal array for "literal" services (new 8.0 mapping)

java.util.Collection

soapenc:Array for "encoded" services

literal array for "literal" services (new 8.0 mapping)

java.util.HashMap

apachesoap:Map

java.util.HashTable

apachesoap:Map

java.util.Map

apachesoap:Map

java.util.Vector

apachesoap:Vector

Note: "Map" and "Vector" types generated into WSDL are from the http://xml.apache.org/xml-soap ("apachesoap") target namespace.
Note: byte[ ] arrays will continue to map to type "xsd:base64Binary" (current 7.0 behavior).