Automatic type mapping support is here!

[Owen D Burroughs <OW...@uk.ibm.com>]

Hi all,

As previously mentioned in posts, I have been working on adding code to
WSIF, to allow it to automatically determine mappings from xml names to
Java class names, so reducing (or in many cases eliminating) the need to
call mapType. The new code has now been committed. Here's an overview of
what's been done:

Key features of the new code
----------------------------
1) In a majority of cases, a user can invoke a service that uses complex
types, without
   a need to make a call to WSIFSerivce.mapType
2) The conventions used to convert an xml name to a Java class name can by
overriden by
   the user
3) The code improves upon the automatic type mapping currently used by stub
invocations.
   That code uses the Schema2Java class which has a number of limitations,
not least of
   which is that it does not understand arrays The Schema2Java code is now
deprecated.
3) The code is backwards compatible with the current WSIF implementation -
automatic
   mapping of types is off by default for dynamic invocations and on for
stub invocations. For dynamic
   invocations It is "switched on" at the WSIFServiceFactory level.

NOTE: calls to mapPackage will trigger automatic mapping of types since
such mapping information would be of no use otherwise.



How to use the new functionality
--------------------------------
In order to maintain backwards compatibility, automatic mapping of types is
off by default for dynamic invocations but on for stub invocations (which
until now have used the Schema2Java code to work out mappings) and also
triggered by calls to mapPackage.

To use the new functionality, the user calls one of two new methods on
WSIFServiceFactory:

      /**
       * Set a flag to indicate whether or not instances of WSIFService
created by this factory, will
       * attempt to automatically calculate mappings between xml names and
Java class names for the
       * types in the wsdl.
       * @param on Whether automcatic mapping of types is on or off. The
default is off
       */
    public void automaticallyMapTypes(boolean on) {
    }

      /**
       * Set a flag to indicate whether or not instances of WSIFService
created by this factory, will
       * attempt to automatically calculate mappings between xml names and
Java class names for the
       * types in the wsdl. This method also allows the user to
programatically specify the names of the
       * WSIFMapper and WSIFMappingConvention classes to be used by
WSIFServices created by this factory.
       * A null value for a class name will be ignored i.e. no overriding
will take place.
       * @param on Whether automcatic mapping of types is on or off. The
default is off
       * @param mapperClassName The WSIFMapper implementation class name
       * @param conventionClassName The WSIFMappingConvention
implementation class name
       */
    public void automaticallyMapTypes(boolean on, String mapperClassName,
String conventionClassName) {
    }


so for example:

    WSIFServiceFactory factory = WSIFServiceFactory.newInstance();
    factory.automaticallyMapTypes(true);
    factory.getService(....


NOTE: Support for the WSIFService mapType and mapPackage methods is still
provided. Any calls to such methods will override information produced by
the automatic mapping functionality. The helps maintain backwards
compatibility and also allows for "less standard" mappings.


WSIFMapper and WSIFMappingConvention
------------------------------------
As part of this proposal, two new interfaces are defined. These are
    org.apache.wsif.mapping.WSIFMapper
and
    org.apache.wsif.mapping.WSIFMappingConvention.


WSIFMapper
- - - - - -
A WSIFMapper defines a way of producing a list of QName to Java class name
mappings. It defines the logic for determining what type of mapping is
required for a particular org.apache.wsif.schema.SchemaType. The mapping
itself is then produced by an associated
org.apache.wsif.mapping.WSIFMappingConvention instance


WSIFMappingConvention
- - - - - - - - - - -
A WSIFMappingConvention defines a convention for converting an xml name to
a Java class name. Different techniques can be applied to complexTypes,
simpleTypes and global elements.


A default implementation of each interface is provided and will be used
unless the user specifies otherwise. The default classes are:

    org,apache.wsif.mapping.WSIFDefaultMapper
and
    org,apache.wsif.mapping.WSIFDefaultMappingConvention

For more information about these classes, see the appropriate source code.

In order to specify a custom WSIFMapper or WSIFMappingConvetion, properties
can by set either in the wsif.properties file or as system properties in
the Java runtime. The names of the properties to set are:

    org.apache.wsif.mapper
    org.apache.wsif.mappingconvention

These are defined as constants in WSIFConstants.

A user can also set the class names on the WSIFServiceFactory. See "How to
use the new functionality" above.

An alternative WSIFMappingConvention is provided is the new code. It is

   org.apache.wsif.providers.soap.apacheaxis.WSDL2JavaMappingConvention

This class uses WSDL2Java methods defined in Axis to generate class names.
Since it imports Axis classes, it has been placed in the Axis provider
package.


Please post queries regarding this to the wsif-dev mailing list.

Regards,
Owen