=pod
=head1 NAME
SOAP::WSDL::Manual::XSD - SOAP::WSDL's XML Schema implementation
=head1 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.
=head1 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.
=head2 Conversions
=head3 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 L<SOAP::WSDL::XSD::Typelib::Builtin|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
L<HTML::Template::Compiled|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.
=head3 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.
=head1 HOW IT WORKS
=head2 Base classes
SOAP::WSDL::XSD provides a set of base classes for the construction of XML
schema defined type classes.
=head3 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.
=head3 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.
=head3 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
L</TRANSLATION RULES> for details.
=head3 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.
=head1 TRANSLATION RULES
=head2 element
TODO add more elaborate description
=head3 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
=head3 element with ref attribute
Elements defined by referencing another element inherit from the
corresponding element class.
referenced Element class
^
|
Element ref="" class
=head3 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
=head3 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
=head2 complexType
TODO add more elaborate description
Some content models are not implemented yet. The content models
implemented are described below.
=head3 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.
=head3 complexType with "sequence" variety
The implementation of the "sequence" variety is the same as for all.
=head3 complexType with "choice" variety
The implementation for choice currently is the same as for all - which means,
no check for occurrence are made.
=head3 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.
=over
=item * 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
=item * 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 L<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
=back
=head2 SimpleType
TODO add more elaborate description
Some derivation methods are not implemented yet. The derivation methods
implemented are described below.
=head3 Derivation by list
Derivation by list is implemented by inheriting from both the base type and
SOAP::WSDL::XSD::Typelib::XSD::list.
=head3 Derivation by restriction
Derivation by restriction is implemented by inheriting from a base type and
applying the required restrictions.
=head1 FACETS
XML Schema facets are not implemented yet.
They will probably implemented some day by putting constant methods into
the correspondent classes.
=head2 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 C<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
C<attr>. The name is chosen to allow mimicing SOAP::Lite's behaviour, which
allows setting a SOAP::Data object's attributes via C<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 C<all>. The
individual attributes can be set and retrieved via the respective set_FOO /
get_FOO methods.
The C<attr> method provides auto-vivification: An xml object's attribute set
is instantiated when accessed.
Auto-vivification is only triggered if there actually B<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',
});
}
=head2 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.
=head1 CAVEATS
=over
=item * 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 !
=back
=head1 BUGS AND LIMITATIONS
The following XML Schema declaration elements are not supported yet:
=head2 XML Schema elements partially supported
=head3 Type definition elements
=over
=item * simpleContent
simpleContent is only supported with a restriction or extension with a C<base>
attribute. simpleContent declarations deriving from a atomic type are not
supported (yet).
=back
=head3 Inclusion elements
=over
=item * import
The import inclusion element requires the schemaLocation attribute for
resolving the XML schema to import. Support for the import element is
implemented in L<SOAP::WSDL::Expat::WSDLParser|SOAP::WSDL::Expat::WSDLParser>,
so alternative parsers may or may not support the import element.
L<SOAP::WSDL::Expat::WSDLParser|SOAP::WSDL::Expat::WSDLParser> keeps track of
included schemas and prevents import loops.
=back
=head3 Facets
The following XML Schema declaration elements are supported, but have no
effect yet.
=over
=item * enumeration
=item * fractionDigits
=item * lenght
=item * maxExclusive
=item * maxInclusiove
=item * maxLength
=item * minExclusive
=item * minInclusive
=item * minLength
=item * pattern
=item * totalDigits
=item * whitespace
=back
=head2 XML Schema elements not implemented
=head3 Declaration elements
=over
=item * notation
=back
=head3 Content model definition elements
=over
=item * any
The horror of each XML schema implementation: Just anything...
C<any> declarations are not supported yet.
=item * anyAttribute
=item * attributeGroup
C<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.
=item * group
The group definition element is not supported yet.
=back
=head3 Identity definition elements
These declaration elements don't declare XML elements, but apply identity
constraints. They have no effect yet.
=over
=item * field
=item * key
=item * keyref
=item * selector
=item * unique
=back
=head3 Inclusion elements
=over
=item * include
Use of the include inclusion element is forbidden by the WS-I basic profile.
It is not supported (yet).
=item * redefine
Not supported (yet).
=back
=head3 * Documentation elements
=over
=item * appinfo
The appinfo documentation element is ignored.
=back
=head1 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
=head1 AUTHOR
Martin Kutter E<lt>martin.kutter fen-net.deE<gt>
=head1 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 $
=cut