.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "SOAP::WSDL::Manual::XSD 3pm" .TH SOAP::WSDL::Manual::XSD 3pm "2022-10-14" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" SOAP::WSDL::Manual::XSD \- SOAP::WSDL's XML Schema implementation .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\s-1SOAP::WSDL\s0's \s-1XML\s0 Schema implementation translates \s-1XML\s0 Schema definitions into perl classes. .PP Every top-level type or element in a \s-1XML\s0 schema is translated into a perl class (usually in it's own file). .PP Atomic types are either directly included in the class of their parent's node, or as sub-package in their parent class' file. .PP While the implementation is still incomplete, it covers the \s-1XML\s0 schema definitions used by most object mappers. .SH "USAGE" .IX Header "USAGE" You can use \s-1SOAP::WSDL::XSD\s0 based classes just like any perl class \- you may instantiate it, inherit from it etc. .PP You should be aware, that \s-1SOAP::WSDL::XSD\s0 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. .PP Moreover, most all SOAP::WSDL::XSD::Typelib based classes override Class::Std::Fast's default constructor for speed \- you should not expect \&\s-1BUILD\s0 or \s-1START\s0 methods to work, unless you call them yourself (or define a new constructor). .PP All \s-1SOAP::WSDL::XSD\s0 based complexType classes allow a hash ref matching their data structure as only parameter to \fBnew()\fR. 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. .PP All \s-1SOAP::WSDL::XSD\s0 based simpleType (and builtin) classes accept a single hash ref with the only key \*(L"value\*(R" and the value to be set as value. .SS "Conversions" .IX Subsection "Conversions" \fIArray dereference\fR .IX Subsection "Array dereference" .PP All \s-1SOAP::WSDL::XSD\s0 based classes overload arrayification \- that is being accessed as a list ref \- with a method returning [ \f(CW$self\fR ]. .PP 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. .PP To iterate over a (potential) list of child elements just do the following: .PP .Vb 5 \& if (defined $obj\->get_ELEMENT()) { \& for (@{ $obj\->get_ELEMENT() }) { \& ... \& } \& } .Ve .PP This is especially useful in mini-languages like HTML::Template::Compiled, where you could say .PP .Vb 5 \& <%IF_DEFINED obj.get_ELEMENT %> \& <%LOOP obj.get_ELEMENT %> \& ... \& <%/LOOP> \& <%IF%> .Ve .PP 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 \s-1HTC\s0 to solve the issue. .PP \fIas_hash_ref\fR .IX Subsection "as_hash_ref" .PP SOAP::WSDL::XSD::Typelib::ComplexType based objects have a method as_hash_ref, which returns the object's content as a hash reference. .PP This can be convenient for cloning: .PP .Vb 2 \& my $class = ref $old; \& my $clone = $class\->new( $old\->as_hash_ref() ); .Ve .PP To convert from one type to another, you can just say .PP .Vb 1 \& my $new = MyTypes::NewType\->new( $old\->as_hash_ref() ); .Ve .PP Of course this will only work if MyTypes::NewType has a superset of the old object class' elements. .PP Note that \s-1XML\s0 attribute data is not included in the hash ref output yet. .SH "HOW IT WORKS" .IX Header "HOW IT WORKS" .SS "Base classes" .IX Subsection "Base classes" \&\s-1SOAP::WSDL::XSD\s0 provides a set of base classes for the construction of \s-1XML\s0 schema defined type classes. .PP \fIBuiltin types\fR .IX Subsection "Builtin types" .PP \&\s-1SOAP::WSDL::XSD\s0 provides classes for all builtin \s-1XML\s0 Schema datatypes. .PP For a list and reference on these classes, see SOAP::WSDL::XSD::Typelib::Builtin. .PP \fIDerivation classes\fR .IX Subsection "Derivation classes" .PP For derivation by list, the list derivation class SOAP::WSDL::XSD::Typelib::Builtin::list exists. .PP Derivation by restriction is handled without the help of additional classes. .PP \fIElement construction class\fR .IX Subsection "Element construction class" .PP 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"\s-1TRANSLATION RULES\*(R"\s0 for details. .PP \fIcomplexType construction class\fR .IX Subsection "complexType construction class" .PP 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. .PP 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. .SH "TRANSLATION RULES" .IX Header "TRANSLATION RULES" .SS "element" .IX Subsection "element" \&\s-1TODO\s0 add more elaborate description .PP \fIelement with type attribute\fR .IX Subsection "element with type attribute" .PP Elements defined by referencing a builtin or user defined type inherit from SOAP::WSDL::XSD::Typelib::Element and from the corresponding type class. .PP .Vb 7 \& Element Type \& base class class \& ^ ^ \& | | \& \-\-\-\-\-\-\-\-\-\-\-\- \& | \& Element type="" class .Ve .PP \fIelement with ref attribute\fR .IX Subsection "element with ref attribute" .PP Elements defined by referencing another element inherit from the corresponding element class. .PP .Vb 4 \& referenced Element class \& ^ \& | \& Element ref="" class .Ve .PP \fIelement with atomic simpleType\fR .IX Subsection "element with atomic simpleType" .PP Elements defined by a atomic simpleType from SOAP::WSDL::XSD::Typelib::Element and from the base type of the atomic type. .PP .Vb 7 \& Element atomic Type \& base class base class \& ^ ^ \& | | \& \-\-\-\-\-\-\-\-\-\-\-\-\-\- \& | \& element simpleType class .Ve .PP \fIelement with atomic complexType\fR .IX Subsection "element with atomic complexType" .PP Elements defined with a atomic complexType inherit from SOAP::WSDL::XSD::Typelib::Element and from SOAP::WSDL::XSD::Typelib::ComplexType. .PP .Vb 7 \& Element complexType \& base class base class \& ^ ^ \& | | \& \-\-\-\-\-\-\-\-\-\-\-\-\-\- \& | \& element complexType class .Ve .SS "complexType" .IX Subsection "complexType" \&\s-1TODO\s0 add more elaborate description .PP Some content models are not implemented yet. The content models implemented are described below. .PP \fIcomplexType with \*(L"all\*(R" variety\fR .IX Subsection "complexType with all variety" .PP Complex types with \*(L"all\*(R" 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. .PP All element's type classes are loaded. Complex type classes have a \*(L"has a\*(R" relationship to their element fields. .PP Element fields may either be element classes (for element ref="\*(L") or type classes (for element type=\*(R""). No extra element classes are created for a complexType's elements. .PP .Vb 8 \& complexType \& base class \& ^ \& | \& complexType all \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- has a \& element name="a" \-\-\-\-\-\-\-\-\-\-\-\-> Element or type class object \& element name="b" \-\-\-\-\-\-\-\-\-\-\-\-> Element or type class object .Ve .PP The implementation for all does enforce the order of elements as described in the \s-1WSDL,\s0 even though this is not required by the \s-1XML\s0 Schema specification. .PP \fIcomplexType with \*(L"sequence\*(R" variety\fR .IX Subsection "complexType with sequence variety" .PP The implementation of the \*(L"sequence\*(R" variety is the same as for all. .PP \fIcomplexType with \*(L"choice\*(R" variety\fR .IX Subsection "complexType with choice variety" .PP The implementation for choice currently is the same as for all \- which means, no check for occurrence are made. .PP \fIcomplexType with complexContent content model\fR .IX Subsection "complexType with complexContent content model" .PP 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. .PP \&\s-1SOAP::WSDL\s0's \s-1XSD\s0 deserializer backend does not recognize the xsi:type="" attribute either yet. .IP "\(bu" 4 restriction variety .Sp ComplexType classes with restriction variety inherit from their base type. No additional processing or content checking is performed yet. .Sp .Vb 6 \& complexType \& base type class \& ^ \& | \& complexType \& restriction .Ve .IP "\(bu" 4 extension variety .Sp ComplexType classes with extension variety inherit from the \s-1XSD\s0 base complexType class and from their base type. .Sp Extension classes are checked for (re\-)defining all elements of their parent class. .Sp 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). .Sp No additional processing or content checking is performed yet. .Sp .Vb 8 \& complexType complexType \& base class base type class \& ^ ^ \& | | \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& | \& complexType \& extension .Ve .SS "SimpleType" .IX Subsection "SimpleType" \&\s-1TODO\s0 add more elaborate description .PP Some derivation methods are not implemented yet. The derivation methods implemented are described below. .PP \fIDerivation by list\fR .IX Subsection "Derivation by list" .PP Derivation by list is implemented by inheriting from both the base type and SOAP::WSDL::XSD::Typelib::XSD::list. .PP \fIDerivation by restriction\fR .IX Subsection "Derivation by restriction" .PP Derivation by restriction is implemented by inheriting from a base type and applying the required restrictions. .SH "FACETS" .IX Header "FACETS" \&\s-1XML\s0 Schema facets are not implemented yet. .PP They will probably implemented some day by putting constant methods into the correspondent classes. .SS "Attributes" .IX Subsection "Attributes" The attribute set for a \s-1XML\s0 element (derived from anySimpleType or complexType) is implemented as a sub-package of the element derived from SOAP::WSDL::XSD::Typelib::AttributeSet. .PP The sub-package is named as the corresponding type or element package, suffixed with \f(CW\*(C`XmlAttr\*(C'\fR. The suffix \*(L"XmlAttr\*(R" has carefully been chosen to avoid potential naming clashes: The name XmlAttr cannot be included as element or type name in \s-1XML\s0 schemas \- the \s-1XML\s0 standard bans the use of names starting with \*(L"xml\*(R" (case-insensitive). .PP All \s-1XML\s0 attributes for a \s-1XML\s0 element are set\- and retrievable via the method \&\f(CW\*(C`attr\*(C'\fR. The name is chosen to allow mimicking SOAP::Lite's behaviour, which allows setting a SOAP::Data object's attributes via \f(CW\*(C`attr\*(C'\fR. .PP .Vb 5 \& my $attrSet = $obj\->attr(); \& $obj\->attr({ \& whitespace => \*(Aqpreserve\*(Aq, \& nillable => 1, \& }); .Ve .PP SOAP::WSDL::XSD::Typelib::AttributeSet is derived from SOAP::WSDL::XSD::Typelib::ComplexType with content model \f(CW\*(C`all\*(C'\fR. The individual attributes can be set and retrieved via the respective set_FOO / get_FOO methods. .PP The \f(CW\*(C`attr\*(C'\fR method provides auto-vivification: An xml object's attribute set is instantiated when accessed. .PP Auto-vivification is only triggered if there actually \fBis\fR a set of attributes for the class/object in question, so you may want to test whether the result of \->attr is defined: .PP .Vb 6 \& my $attr = $unknownObject\->attr(); \& if (defined($attr)) { \& $unknownObject\->attr({ \& some => \*(Aqvalue\*(Aq, \& }); \& } .Ve .SS "group" .IX Subsection "group" \&\s-1CAVEAT:\s0 Group resolution is not implemented yet. .PP \&\s-1XML\s0 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. .SH "CAVEATS" .IX Header "CAVEATS" .IP "\(bu" 4 \&\s-1START\s0 and \s-1BUILD\s0 are not being called .Sp In contrast to \*(L"normal\*(R" Class::Std::Fast based objects, the classes of the SOAP::WSDL::XSD::Typelib:: hierarchy (and all type and element classes generated by \s-1SOAP::WSDL\s0) override Class::Std's constructor for performance reasons. .Sp If you inherit from such a class and place a \s-1START\s0 or \s-1BUILD\s0 method in it, it will not get called \- at least not unless you place something like this at the top of you code: .Sp .Vb 1 \& use Class::Std::Fast::Storable; .Ve .Sp In this case, Class::Std::Fast::Storable will export a \fBnew()\fR method into your class, which in turn calls \s-1START\s0 and \s-1BUILD.\s0 .Sp The constructors of all SOAP::WSDL::XSD::Typelib:: classes don't ! .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" The following \s-1XML\s0 Schema declaration elements are not supported yet: .SS "\s-1XML\s0 Schema elements partially supported" .IX Subsection "XML Schema elements partially supported" \fIType definition elements\fR .IX Subsection "Type definition elements" .IP "\(bu" 4 simpleContent .Sp simpleContent is only supported with a restriction or extension with a \f(CW\*(C`base\*(C'\fR attribute. simpleContent declarations deriving from a atomic type are not supported (yet). .PP \fIInclusion elements\fR .IX Subsection "Inclusion elements" .IP "\(bu" 4 import .Sp The import inclusion element requires the schemaLocation attribute for resolving the \s-1XML\s0 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. .Sp SOAP::WSDL::Expat::WSDLParser keeps track of included schemas and prevents import loops. .PP \fIFacets\fR .IX Subsection "Facets" .PP The following \s-1XML\s0 Schema declaration elements are supported, but have no effect yet. .IP "\(bu" 4 enumeration .IP "\(bu" 4 fractionDigits .IP "\(bu" 4 length .IP "\(bu" 4 maxExclusive .IP "\(bu" 4 maxInclusiove .IP "\(bu" 4 maxLength .IP "\(bu" 4 minExclusive .IP "\(bu" 4 minInclusive .IP "\(bu" 4 minLength .IP "\(bu" 4 pattern .IP "\(bu" 4 totalDigits .IP "\(bu" 4 whitespace .SS "\s-1XML\s0 Schema elements not implemented" .IX Subsection "XML Schema elements not implemented" \fIDeclaration elements\fR .IX Subsection "Declaration elements" .IP "\(bu" 4 notation .PP \fIContent model definition elements\fR .IX Subsection "Content model definition elements" .IP "\(bu" 4 any .Sp The horror of each \s-1XML\s0 schema implementation: Just anything... .Sp \&\f(CW\*(C`any\*(C'\fR declarations are not supported yet. .IP "\(bu" 4 anyAttribute .IP "\(bu" 4 attributeGroup .Sp \&\f(CW\*(C`attributeGroup\*(C'\fR declarations actually just are macros for \s-1XML\s0 Schema writers: Including an attributeGroup in a declaration has the same effect as including all attributes in the group. .Sp Just not implemented yet. .IP "\(bu" 4 group .Sp The group definition element is not supported yet. .PP \fIIdentity definition elements\fR .IX Subsection "Identity definition elements" .PP These declaration elements don't declare \s-1XML\s0 elements, but apply identity constraints. They have no effect yet. .IP "\(bu" 4 field .IP "\(bu" 4 key .IP "\(bu" 4 keyref .IP "\(bu" 4 selector .IP "\(bu" 4 unique .PP \fIInclusion elements\fR .IX Subsection "Inclusion elements" .IP "\(bu" 4 include .Sp Use of the include inclusion element is forbidden by the WS-I basic profile. It is not supported (yet). .IP "\(bu" 4 redefine .Sp Not supported (yet). .PP \fI* Documentation elements\fR .IX Subsection "* Documentation elements" .IP "\(bu" 4 appinfo .Sp The appinfo documentation element is ignored. .SH "LICENSE" .IX Header "LICENSE" Copyright 2007,2008 Martin Kutter. .PP This file is part of SOAP-WSDL. You may distribute/modify it under the same terms as perl itself .SH "AUTHOR" .IX Header "AUTHOR" Martin Kutter .SH "REPOSITORY INFORMATION" .IX Header "REPOSITORY INFORMATION" .Vb 4 \& $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 $ .Ve