JSR110 “JWSDL” Maintenance Release

OVERVIEW:

A maintenance release of JWSDL is being proposed as a Minor Revision of JSR110, as described in section 4.2.1 ‘Minor Revision Process’ of the JCP 2.1 Procedures.  This will require changes to the JWSDL 1.0 specification and updates to its Reference Implementation (WSDL4J 1.4) and its TCK 1.0 to support those changes. The maintenance release will deliver JWSDL 1.1, WSDL4J 1.5 and TCK for JWSDL 1.1.

 

The objectives of this maintenance release are to:

  1. Roll-up bug fixes since WSDL4J 1.4 into a new version of the WSDL4J reference implementation (WSDL4J 1.5) .  These fixes have been applied to WSDL4J HEAD in CVS and the details are in the CVS change log.
  2. Modify the JWSDL specification and API to make its use of extensibility attributes and extensibility elements consistent with the W3C WSDL specification. The details are described below.
  3. Add a light weight schema capability to provide access to nested schemas.

 

JWSDL 1.0 is based on the WSDL 1.1 specification, which specifies the WSDL elements that support extensible attributes and those that support extensible elements. See WSDL 1.1 schema (http://schemas.xmlsoap.org/wsdl/) for details.  However the extensible attribute and element support currently specified in JWSDL 1.0 and implemented in WSDL4J 1.4 is not entirely consistent with the WSDL 1.1 specification. This maintenance release will synchronize JWSDL with the WSDL 1.1 specification.

 

The table below compares the extensibility support defined by the WSDL 1.1 specification with that currently specified by JWSDL 1.0 and to be specified by JWSDL 1.1 (inconsistencies are highlighted in italics):

 

 

JWSDL interface

WSDL 1.1 schema type

Extensibility defined in WSDL 1.1

Extensiblity defined in JWSDL 1.0

Extensibility defined in JWSDL 1.1

Definition

tDefinitions

Elements

Elements

Elements

Import

tImport

Attributes

none

Attributes

Types

tTypes

Elements

Elements

Elements

Message

tMessage

Elements

none

Elements

Part

tPart

Attributes

Attributes

Attributes

PortType

tPortType

Attributes

none

Attributes

Operation

tOperation

Elements

none

Elements

Input

tParam

Attributes

none

Attributes

Output

tParam

Attributes

none

Attributes

Fault

tFault

Attributes

none

Attributes

Binding

tBinding

Elements

Elements

Elements

BindingOperation

tBindingOperation

Elements

Elements

Elements

BindingInput

tBindingOperationMessage

Elements

Elements

Elements

BindingOutput

tBindingOperationMessage

Elements

Elements

Elements

BindingFault

tBindingOperationFault

Elements

Elements

Elements

Service

tService

Elements

Elements

Elements

Port

tPort

Elements

Elements

Elements

 

CHANGE LOG:

 

Please post comments on the proposed changes to the JSR110 mailing list:   jsr110-eg-disc@yahoogroups.com

 

 

PROPOSED CHANGES

 

No.

Details

Comments

 

All proposed changes were reviewed by Maintenance Review ending 20 Dec 2004.

 

 

 

 

 

ACCEPTED CHANGES

 

1

Maintenance release version numbers will be as follows:

JWSDL 1.1

WSDL4J 1.5

TCK for JWSDL 1.1

 

2

A new interface javax.wsdl.extensions.AttributeExtensible will be created for supporting extensible attributes. 

 

  public static final int NO_DECLARED_TYPE = -1;

  public static final int STRING_TYPE = 0;

  public static final int QNAME_TYPE = 1;

  public static final int LIST_OF_STRINGS_TYPE = 2;

  public static final int LIST_OF_QNAMES_TYPE = 3;

 

 

public Object getExtensionAttribute(QName name);

Return the extension attribute for this element with the specified ‘name’ or null if it is not defined.

 

public void setExtensionAttribute(QName name, Object value);

Set an extension attribute on this element. Pass in a null value to remove an extension attribute.

 

public Map getExtensionAttributes();

Get the map containing all the extension attributes defined on this element. The keys are the qnames of the attributes.

 

public List getNativeAttributeNames();

Get the list of local attribute names defined for this element in the WSDL specification.

The type of an extension attribute may be a QName, a String, a List of QNames or a List of Strings. Therefore, the extension attribute will be retrieved as a java.lang.Object and the JWSDL client must cast it to the appropriate type (QName, String or List).

 

The constants representing these types will be used when registering or querying an extensible attribute type in the ExtensionRegistry (see No. 5 below).

3

The javax.wsdl.* interfaces for Import, Part, PortType, Input, Output and Fault will extend javax.wsdl.extensions.AttributeExtensible  to include extensible attribute support.

 

The javax.wsdl.* interfaces for Definition, Types, Message, Operation, Binding, BindingOperation, BindingInput, BindingOutput, BindingFault, Service and Port will not extend AttributeExtensible as these elements do not support extensible attributes in WSDL 1.1

These are the WSDL elements defined by the WSDL 1.1 Schema as supporting extensible attributes.

4

The javax.wsdl.Part interface in JWSDL 1.0 defines the methods:

public QName getExtensionAttribute(QName name);

public void setExtensionAttribute(QName name, QName value);

public Map getExtensionAttributes();

 

These will be removed from Part in JWSDL 1.1, as they are refactored into the javax.wsdl.extensions.AttributeExtensible interface, which Part will now extend.

Note, with this refactoring the extension attribute type will be Object, not QName (see No. 2 comment on AttributeExtensible about QName, Strings or Lists).  So any JWSDL 1.0 clients that use extensible attributes with Part will need to be modified for JWSDL 1.1 to cast Object to QName.

5

To support the registration of extensible attributes javax.wsdl.extensions.ExtensionRegistry will have the following field and methods added:

 

protected Map extensionAttributeTypeReg = new Hashtable();

This is a Map of Maps. The top-level Map is keyed by (Class)parentType, and the inner Maps are keyed by (Name)attrName.

 

public int queryExtensionAttributeType(Class parentType, QName attrName)

Look up the type of the extensibility attribute with the qname attrName, which was defined on an element represented by the specified parentType.

 

public void registerExtensionAttributeType(Class parentType, QName attrName, int attrType)

Declare that the type of the specified extension attribute, when it occurs as an attribute of the specified parent type, should be assumed to be attrType.

The type of an extension attribute can be QName, String, List of QNames or List of Strings. Constants for these will be defined in AttributeExtensible (see No. 2 above).

6

In JWSDL 1.0 the javax.wsdl.* interfaces for Definition, Types, Binding, BindingOperation, BindingInput, BindingOutput, BindingFault, Service and Port have methods to support extensible elements.  In JWSDL 1.1 these methods will be refactored into a new interface javax.wsdl.extensions.ElementExtensible which these javax.wsdl.* interfaces will extend.

 

The methods refactored into javax.wsdl.extensions.ElementExtensible will be:

 

public void addExtensibilityElement(ExtensibilityElement extElement);

 

public List getExtensibilityElements();

In WSDL 1.1, these elements support extensible elements. This refactoring is for consistency and clarity – both ElementExtensible and AttributeExtensible will now be defined in javax.wsdl.extensions.* and extended by the appropriate javax.wsdl.* interfaces.

7

To comply with WSDL 1.1 the javax.wsdl.* interfaces for Message and Operation will also extend javax.wsdl.extensions.ElementExtensible

They do not yet support extensible elements in JWSDL 1.0

8

Lightweight Schema Support

 

A new ‘lightweight’ schema mechanism will be added that can be used to access schema elements, including schemas that have been nested using import, include or redefine elements. Three new interfaces will be defined in javax.wsdl.extensions. schema.*:

 

Schema extends ExtensibilityElement, Serializable

SchemaReference extends Serializable

SchemaImport extends SchemaReference

 

See the Javadoc for these interfaces for specific details.

 

Schema represents a schema element. It provides access to the DOM element representation of the schema and references to any schemas nested as imports, includes or redefines. If required, a JWSDL implementation may add its own schema parsing capability.

 

SchemaReference represents the ‘link’ from a Schema to any nested schemas. Those nested schemas are in turn represented as Schemas. The include and redefine elements have an id and a schemaLocation attribute and are represented directly by SchemaReference.

 

SchemaImport adds a namespace URI to SchemaReference and is used to represent an import element.

 

All schemas will be parsed into a chain of  Schemas and SchemaReferences or SchemaImports that mirrors the nesting in the WSDL and schema documents. The JWSDL client uses these 3 interfaces to navigate the schemas.

JWSDL is not a schema parser and Schema is not a full schema parser. It is a navigation and access mechanism. Unless the JWSDL implementation adds its own schema parsing, the client application must manipulate the DOM element that represents the schema to access the schema details.

 

See example in Supplementary Note 3 below.

 

Following feedback during the Maintenance Review, the following name changes were made:

  1. ‘javax.wsdl.extensions.lightweightschema’ is now ‘javax.wsdl.extensions.schema’
  2. Class ‘LightWeightSchema’ is now ‘Schema’

 

 

 

 

DEFERRED CHANGES

 

 

No proposed changes were deferred

 

 

 

 

 

Supplementary Notes:

The following notes are intended to clarify or elaborate on the changes described in the Change Log above, but they do not introduce any additional changes to the JWSDL specification that would be subject to approval in the Change Log.

 

NOTE 1: Extensibility changes to WSDLReaderImpl

For JWSDL 1.1 there will be no interface changes (that is, no Spec changes) to javax.wsdl.xml.WSDLReader but in WSDL4J 1.5 there will be some changes to com.ibm.wsdl.xml.WSDLReaderImpl, described below:

 

The parsing of extensibility attributes will be added for the elements; Import, PortType, Input, Output, Fault. Their parseXXXX methods will invoke method parseExtensiblityAttributes. 

 

In WSDL4J 1.4 extensibility attributes are only parsed for the element Part, hence the specific reference to Part in the method signature:

protected void parseExtensibilityAttributes(Element el, Part part, Definition def)

 

To accommodate the other elements that will support extensible attributes, this method signature will change in WSDL4J 1.5 to:

protected void parseExtensibilityAttributes(Element el, Class parentType, AttributeExtensible attrExt, Definition def)

 

The invocation of the parseExtensiblityElement method will be added to parseMessage and parseOperation. In WSDL4J 1.4 it is already being invoked for the other elements that support extensible elements.

 

NOTE 2: Extensibility changes to WSDLWriterImpl

For JWSDL 1.1 there will be no interface changes (that is, no Spec changes) to javax.wsdl.xml.WSDLWriter but in WSDL4J 1.5 there will be some changes to com.ibm.wsdl.xml.WSDLWriterImpl, described below:

 

The writing of extensibility attributes will be added for the elements ; Import, PortType, Input, Output, Fault. Their printXXXX methods will invoke method printExtensiblityAttributes.

 

In WSDL4J 1.4 extensibility attributes are only written for the element Part, hence the specific reference to Part in the method signature:

protected void printExtensibilityAttributes(Part part,  Definition def, PrintWriter pw)

 

To accommodate the other elements that will support extensible attributes, this method signature will change in WSDL4J 1.5 to:

protected void printExtensibilityAttributes(Class parentType,  AttributeExtensible attrExt, Definition def, PrintWriter pw)

 

The invocation of the printExtensiblityElement method will be added to printMessage and printOperation. In WSDL4J 1.4 it is already being invoked for the other elements that support extensible elements.

 

NOTE 3: Lightweight Schema Example

Assume a WSDL file MyTravelService.wsdl that uses a schema import to import Flights.xsd and a wsdl import to import Hotels.xsd. 

Flights.xsd includes the schema Booking.xsd.

Hotels.xsd imports two other schemas, Reservation.xsd and Cancellation.xsd.

 

The WSDL fragment for MyTravelService.wsdl is:

 

<?xml version="1.0" encoding="UTF-8"?>

<definitions name="MyTravelService" xmlns:xsd=http://www.w3.org/2001/XMLSchema targetNamespace=.....>

    <types>

      <xsd:schema>

        <xsd:import schemaLocation="Flights.xsd" namespace="http://mytravel.com/schema/Flights"/>

      </xsd:schema>

    </types>

    <import location="Hotels.xsd" namespace="http://mytravel.com/schema/Hotels"/>

    <message ....>

        <part ..../>

    </message>

    <message ....>

        <part ..../>

    </message>

    <portType ...>

        ....

    </portType>

</definitions>

 

The schema fragment for Flights.xsd is:

 

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs=http://www.w3.org/2001/XMLSchema targetNamespace.....>

      <xs:annotation>

            <xs:documentation>Flights</xs:documentation>

            <xs:appinfo/>

      </xs:annotation>

      <xs:include id="booking" schemaLocation="Booking.xsd"/>

      <xs:element ...>

           ....

      </xs:element>

      ....

</xs:schema>

 

The schema fragment for Hotels.xsd is:

 

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs=http://www.w3.org/2001/XMLSchema targetNamespace.....>

      <xs:annotation>

            <xs:documentation>Hotels</xs:documentation>

            <xs:appinfo/>

      </xs:annotation>

      <xs:import namespace="http://mytravel.com/schema/Reservation" schemaLocation="Reservation.xsd"/>

      <xs:import namespace="http://mytravel.com/schema/Cancellation" schemaLocation="Cancellation.xsd"/>

      <xs:element ...>

           ....

      </xs:element>

      ....

</xs:schema>

 

 

The graph of wsdl and lightweight schema objects is depicted by this diagram:

 

>Definition (javax.wsdl)                    <<< MyTravelService.wsdl

 |

 imports

 |     |

 |      --->Import (javax.wsdl)

 |         |

 |          --->Definition (javax.wsdl)

 |             |

 |              --->Types  (javax.wsdl)

 |                 |

 |                  --->Schema   (javax.wsdl.extensions.schema)       <<< Hotels.xsd

 |                     |

 |                     imports

 |                           |

 |                           |--->SchemaImport  (javax.wsdl.extensions.schema)

 |                           |   |

 |                           |    --->Schema                          <<< Reservation.xsd

 |                           |

 |                            --->SchemaImport

 |                               |

 |                                --->Schema                          <<< Cancellation.xsd

 |

 types

     |

      --->Types  (javax.wsdl)

         |

          --->Schema   (javax.wsdl.extensions.schema)                 <<< Flights.xsd

             |

             includes

                    |

                     --->SchemaReference  (javax.wsdl.extensions.schema)

                        |

                         --->Schema                                   <<< Booking.xsd

 

 

 

End of Maintenance Release Notes