Provided by: libsoap-wsdl-perl_2.00.10-1_all bug

NAME

       SOAP::WSDL::Manual::XSD - SOAP::WSDL's XML Schema implementation

DESCRIPTION

       SOAP::WSDL's XML Schema implementation translates XML Schema definitions into perl
       classes.

       Every top-level type or element in a XML schema is translated into a perl class (usually
       in it's own file).

       Atomic types are either directly included in the class of their parent's node, or as sub-
       package in their parent class' file.

       While the implementation is still incomplete, it covers the XML schema definitions used by
       most object mappers.

USAGE

       You can use SOAP::WSDL::XSD based classes just like any perl class - you may instantiate
       it, inherit from it etc.

       You should be aware, that SOAP::WSDL::XSD based classes are inside-out classes using
       Class::Std::Fast, though - things you would expect from hash-based classes like using the
       blessed hash ref as data storage won't work.

       Moreover, most all SOAP::WSDL::XSD::Typelib based classes override Class::Std::Fast's
       default constructor for speed - you should not expect BUILD or START methods to work,
       unless you call them yourself (or define a new constructor).

       All SOAP::WSDL::XSD based complexType classes allow a hash ref matching their data
       structure as only parameter to new(). You may mix hash and list refs and objects in the
       structure passed to new - as long as the structure matches, it will work fine.

       All SOAP::WSDL::XSD based simpleType (and builtin) classes accept a single hash ref with
       the only key "value" and the value to be set as value.

   Conversions
       Array dereference

       All SOAP::WSDL::XSD based classes overload arrayification - that is being accessed as a
       list ref - with a method returning [ $self ].

       This means that you can safely use the results of get_ELEMENT calls on complexTypes as
       list refs (you'll have to check for definedness, though - see
       SOAP::WSDL::XSD::Typelib::Builtin for details.

       To iterate over a (potential) list of child elements just do the following:

        if (defined $obj->get_ELEMENT()) {
            for (@{ $obj->get_ELEMENT() }) {
               ...
            }
        }

       This is especially useful in mini-languages like HTML::Template::Compiled, where you could
       say

        <%IF_DEFINED obj.get_ELEMENT %>
           <%LOOP obj.get_ELEMENT %>
              ...
           <%/LOOP>
        <%IF%>

       Note that this does not work in HTML::Template::Compiled yet - the code generated for the
       template checks UNIVERSAL::isa instead of dereferencing.  There's a ticket open in HTC to
       solve the issue.

       as_hash_ref

       SOAP::WSDL::XSD::Typelib::ComplexType based objects have a method as_hash_ref, which
       returns the object's content as a hash reference.

       This can be convenient for cloning:

        my $class = ref $old;
        my $clone = $class->new( $old->as_hash_ref() );

       To convert from one type to another, you can just say

        my $new = MyTypes::NewType->new( $old->as_hash_ref() );

       Of course this will only work if MyTypes::NewType has a superset of the old object class'
       elements.

       Note that XML attribute data is not included in the hash ref output yet.

HOW IT WORKS

   Base classes
       SOAP::WSDL::XSD provides a set of base classes for the construction of XML schema defined
       type classes.

       Builtin types

       SOAP::WSDL::XSD provides classes for all builtin XML Schema datatypes.

       For a list and reference on these classes, see SOAP::WSDL::XSD::Typelib::Builtin.

       Derivation classes

       For derivation by list, the list derivation class SOAP::WSDL::XSD::Typelib::Builtin::list
       exists.

       Derivation by restriction is handled without the help of additional classes.

       Element construction class

       For the construction of element classes, the element superclass
       SOAP::WSDL::XSD::Typelib::Element exists. All elements are ultimately derived from this
       class. Elements may inherit from type classes, too - see "TRANSLATION RULES" for details.

       complexType construction class

       For the construction of complexType classes, the construction class
       SOAP::WSDL::XSD::Typelib::ComplexType is provided. It provides a __factory method for
       placing attributes in generated classes, and generating appropriate setter/getter
       accessors.

       The setters are special: They handle complex data structures of any type (meaning hash
       refs, list refs and objects, and any combination of them), as long as their structure
       matches the expected structure.

TRANSLATION RULES

   element
       TODO add more elaborate description

       element with type attribute

       Elements defined by referencing a builtin or user defined type inherit from
       SOAP::WSDL::XSD::Typelib::Element and from the corresponding type class.

         Element       Type
         base class    class
            ^            ^
            |            |
             ------------
                 |
        Element type="" class

       element with ref attribute

       Elements defined by referencing another element inherit from the corresponding element
       class.

        referenced Element class
                 ^
                 |
        Element ref="" class

       element with atomic simpleType

       Elements defined by a atomic simpleType from SOAP::WSDL::XSD::Typelib::Element and from
       the base type of the atomic type.

          Element     atomic Type
         base class   base class
            ^              ^
            |              |
             --------------
                   |
        element simpleType class

       element with atomic complexType

       Elements defined with a atomic complexType inherit from SOAP::WSDL::XSD::Typelib::Element
       and from SOAP::WSDL::XSD::Typelib::ComplexType.

          Element     complexType
         base class   base class
            ^              ^
            |              |
             --------------
                   |
        element complexType class

   complexType
       TODO add more elaborate description

       Some content models are not implemented yet. The content models implemented are described
       below.

       complexType with "all" variety

       Complex types with "all" variety inherit from SOAP::WSDL::XSD::Typelib::ComplexType, and
       call it's factory method for creating fields and accessors/mutators for the complexType's
       elements.

       All element's type classes are loaded. Complex type classes have a "has a" relationship to
       their element fields.

       Element fields may either be element classes (for element ref="") or type classes (for
       element type=""). No extra element classes are created for a complexType's elements.

         complexType
         base class
              ^
              |
        complexType all
        ----------------     has a
        element name="a" ------------> Element or type class object
        element name="b" ------------> Element or type class object

       The implementation for all does enforce the order of elements as described in the WSDL,
       even though this is not required by the XML Schema specification.

       complexType with "sequence" variety

       The implementation of the "sequence" variety is the same as for all.

       complexType with "choice" variety

       The implementation for choice currently is the same as for all - which means, no check for
       occurrence are made.

       complexType with complexContent content model

       Note that complexType classes with complexContent content model don't exhibit their type
       via the xsi:type attribute yet, so they currently cannot be used as a replacement for
       their base type.

       SOAP::WSDL's XSD deserializer backend does not recognize the xsi:type="" attribute either
       yet.

       ·   restriction variety

           ComplexType classes with restriction variety inherit from their base type.  No
           additional processing or content checking is performed yet.

               complexType
             base type class
                   ^
                   |
              complexType
              restriction

       ·   extension variety

           ComplexType classes with extension variety inherit from the XSD base complexType class
           and from their base type.

           Extension classes are checked for (re-)defining all elements of their parent class.

           Note that a derived type's elements (=properties) overrides the getter / setter
           methods for all inherited elements. All object data is stored in the derived type's
           class, not in the defining class (See Class::Std for a discussion on inside out object
           data storage).

           No additional processing or content checking is performed yet.

             complexType        complexType
             base class       base type class
                  ^                 ^
                  |                 |
                   -----------------
                  |
              complexType
               extension

   SimpleType
       TODO add more elaborate description

       Some derivation methods are not implemented yet. The derivation methods implemented are
       described below.

       Derivation by list

       Derivation by list is implemented by inheriting from both the base type and
       SOAP::WSDL::XSD::Typelib::XSD::list.

       Derivation by restriction

       Derivation by restriction is implemented by inheriting from a base type and applying the
       required restrictions.

FACETS

       XML Schema facets are not implemented yet.

       They will probably implemented some day by putting constant methods into the correspondent
       classes.

   Attributes
       The attribute set for a XML element (derived from anySimpleType or complexType) is
       implemented as a sub-package of the element derived from
       SOAP::WSDL::XSD::Typelib::AttributeSet.

       The sub-package is named as the corresponding type or element package, suffixed with
       "XmlAttr". The suffix "XmlAttr" has carefully been chosen to avoid potential naming
       clashes: The name XmlAttr cannot be included as element or type name in XML schemas - the
       XML standard bans the use of names starting with "xml" (case-insensitive).

       All XML attributes for a XML element are set- and retrievable via the method "attr". The
       name is chosen to allow mimicing SOAP::Lite's behaviour, which allows setting a SOAP::Data
       object's attributes via "attr".

        my $attrSet = $obj->attr();
        $obj->attr({
            whitespace => 'preserve',
            nillable => 1,
        });

       SOAP::WSDL::XSD::Typelib::AttributeSet is derived from
       SOAP::WSDL::XSD::Typelib::ComplexType with content model "all". The individual attributes
       can be set and retrieved via the respective set_FOO / get_FOO methods.

       The "attr" method provides auto-vivification: An xml object's attribute set is
       instantiated when accessed.

       Auto-vivification is only triggered if there actually is a set of attributes for the
       class/object in question, so you may want to test whether the result of ->attr is defined:

        my $attr = $unknownObject->attr();
        if (defined($attr)) {
            $unknownObject->attr({
                some => 'value',
            });
        }

   group
       CAVEAT: Group resolution is not implemented yet.

       XML Schema Group definitions are just treated as aliases that can be inserted in
       complexType definitions by referencing them. That is, there's no difference between a
       complexType with simpleContent and a sequence of three elements, and a complexType with
       simpleContent referencing a group containing the same sequence of elements.

CAVEATS

       ·   START and BUILD are not being called

           In contrast to "normal" Class::Std::Fast based objects, the classes of the
           SOAP::WSDL::XSD::Typelib:: hierarchy (and all type and element classes generated by
           SOAP::WSDL) override Class::Std's constructor for performance reasons.

           If you inherit from such a class and place a START or BUILD method in it, it will not
           get called - at least not unless you place something like this at the top of you code:

            use Class::Std::Fast::Storable;

           In this case, Class::Std::Fast::Storable will export a new() method into your class,
           which in turn calls START and BUILD.

           The constructors of all SOAP::WSDL::XSD::Typelib:: classes don't !

BUGS AND LIMITATIONS

       The following XML Schema declaration elements are not supported yet:

   XML Schema elements partially supported
       Type definition elements

       ·   simpleContent

           simpleContent is only supported with a restriction or extension with a "base"
           attribute. simpleContent declarations deriving from a atomic type are not supported
           (yet).

       Inclusion elements

       ·   import

           The import inclusion element requires the schemaLocation attribute for resolving the
           XML schema to import. Support for the import element is implemented in
           SOAP::WSDL::Expat::WSDLParser, so alternative parsers may or may not support the
           import element.

           SOAP::WSDL::Expat::WSDLParser keeps track of included schemas and prevents import
           loops.

       Facets

       The following XML Schema declaration elements are supported, but have no effect yet.

       ·   enumeration

       ·   fractionDigits

       ·   length

       ·   maxExclusive

       ·   maxInclusiove

       ·   maxLength

       ·   minExclusive

       ·   minInclusive

       ·   minLength

       ·   pattern

       ·   totalDigits

       ·   whitespace

   XML Schema elements not implemented
       Declaration elements

       ·   notation

       Content model definition elements

       ·   any

           The horror of each XML schema implementation: Just anything...

           "any" declarations are not supported yet.

       ·   anyAttribute

       ·   attributeGroup

           "attributeGroup" declarations actually just are macros for XML Schema writers:
           Including an attributeGroup in a declaration has the same effect as including all
           attributes in the group.

           Just not implemented yet.

       ·   group

           The group definition element is not supported yet.

       Identity definition elements

       These declaration elements don't declare XML elements, but apply identity constraints.
       They have no effect yet.

       ·   field

       ·   key

       ·   keyref

       ·   selector

       ·   unique

       Inclusion elements

       ·   include

           Use of the include inclusion element is forbidden by the WS-I basic profile.  It is
           not supported (yet).

       ·   redefine

           Not supported (yet).

       * Documentation elements

       ·   appinfo

           The appinfo documentation element is ignored.

LICENSE

       Copyright 2007,2008 Martin Kutter.

       This file is part of SOAP-WSDL. You may distribute/modify it under the same terms as perl
       itself

AUTHOR

       Martin Kutter <martin.kutter fen-net.de>

REPOSITORY INFORMATION

        $Rev: 390 $
        $LastChangedBy: kutterma $
        $Id: Client.pm 390 2007-11-16 22:18:32Z kutterma $
        $HeadURL: http://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL/trunk/lib/SOAP/WSDL/Client.pm $