=encoding utf8
=head1 NAME
XML::Compile::SOAP11::Encoding - SOAP encoding
=head1 SYNOPSIS
### This module may work for you... but may also
### not work. Progress has been made, but the
### implementation is not complete and not well tested.
# Add this to load the logic
use XML::Compile::SOAP11::Encoding simplify => 1;
# The internals are used by the ::SOAP11 module, and
# probably should not be called by yourself.
=head1 DESCRIPTION
This module loads extra functionality into the L<XML::Compile::SOAP11|XML::Compile::SOAP11>
namespace: all kinds of methods which are used to SOAP-encode data.
=head1 METHODS
=head2 Transcoding
SOAP defines encodings, especially for SOAP-RPC.
=head3 Encoding
=over 4
=item $obj-E<gt>B<array>( <$name|undef>, $item_type, $elements, %options )
Arrays can be a mess: a mixture of anything and nothing. Therefore,
you have to help the generation more than you may wish for. This
method produces an one dimensional array, L<multidim()|XML::Compile::SOAP11::Encoding/"Encoding"> is used for
multi-dimensional arrays.
The $name is the packed type of the array itself. When undef,
the C<< {soap-enc-ns}Array >> will be used (the action soap
encoding namespace will be used).
The $item_type specifies the type of each element within the array.
This type is used to create the C<arrayType> attribute, however
doesn't tell enough about the items themselves: they may be
extensions to that type.
Each of the $elements (passed as ARRAY) must be an XML::LibXML::Node,
either self-constructed, or produced by one of the builder methods in
this class, like L<enc()|XML::Compile::SOAP11::Encoding/"Encoding"> or L<typed()|XML::Compile::SOAP11::Encoding/"Encoding">.
Returned is the XML::LibXML::Element which represents the
array.
-Option --Default
array_type <generated>
id <undef>
nested_array ''
offset 0
slice <all remaining>
=over 2
=item array_type => STRING
The arrayType attribute content. When explicitly set to undef, the
attribute is not created.
=item id => STRING
Assign an id to the array. If not defined, than no id attribute is
added.
=item nested_array => STRING
The ARRAY type should reflect nested array structures if they are
homogeneous. This is a really silly part of the specs, because there
is no need for it on any other comparible place in the specs... but ala.
For instance: C<< nested_array => '[,]' >>, means that this array
contains two-dimensional arrays.
=item offset => INTEGER
When a partial array is to be transmitted, the number of the base
element.
=item slice => INTEGER
When a partial array is to be transmitted, this is the length of
the slice to be sent (the number of elements starting with the C<offset>
element)
=back
=item $obj-E<gt>B<element>($type, $name, $value)
Create an element. The $name is for node, where a namespace component
is translated into a prefix. When you wish for a C<type> attribute,
use L<typed()|XML::Compile::SOAP11::Encoding/"Encoding">.
When the $type does not contain a namespace indication, it is taken
in the selected schema namespace. If the $value already is a
XML::LibXML::Element, then that one is used (and the $name ignored).
=item $obj-E<gt>B<enc>( $local, $value, [$id] )
In the SOAP specification, encoding types are defined: elements
which do not have a distinguishable name but use the type of the
data as name. Yep, ugly!
example:
my $xml = $soap->enc('int', 43);
my $xml = $soap->enc(int => 43);
print $xml->toString;
# <SOAP-ENC:int>43</SOAP-ENC:int>
my $xml = $soap->enc('int', 42, id => 'me');
my $xml = $soap->enc(int => 42, id => 'me');
print $xml->toString;
# <SOAP-ENC:int id="me">42</SOAP-ENC:int>
=item $obj-E<gt>B<href>( $name, $element, [$id] )
Create a reference element with $name to the existing $element. When the
$element does not have an "id" attribute yet, then $id will be used. In
case not $id was specified, then one is generated.
=item $obj-E<gt>B<multidim>( <$name|undef>, $item_type, $elements, %options )
A multi-dimensional array, less flexible than a single dimensional
array, which can be created with L<array()|XML::Compile::SOAP11::Encoding/"Encoding">.
The table of $elements (ARRAY of ARRAYs) must be full: in each of the
dimensions, the length of each row must be the same. On the other
hand, it may be sparse (contain undefs). The size of each dimension is
determined by the length of its first element.
-Option--Default
id undef
=over 2
=item id => STRING
=back
=item $obj-E<gt>B<nil>( [$type], $name )
Create an element with $name which explicitly has the C<xsi:nil> attribute.
If the $name is full (has a namespace to it), it will be translated into
a QNAME, otherwise, it is considered not namespace qualified.
If a $type is given, then an explicit type parameter is added.
=item $obj-E<gt>B<prefixed>( $type|<$ns,$local> )
Translate a $ns-$local combination (which may be represented as
a packed $type) into a prefixed notation.
=item $obj-E<gt>B<startEncoding>(%options)
-Option--Default
doc <created internally with utf8>
=over 2
=item doc => XML::LibXML::Document node
=back
=item $obj-E<gt>B<struct>($type, $childs)
Create a structure, an element with children. The $childs must be fully
prepared XML::LibXML::Element objects.
=item $obj-E<gt>B<typed>($type, $name, $value)
A "typed" element shows its type explicitly, via the "xsi:type" attribute.
The $value will get processed via an auto-generated XML::Compile writer,
so validated. The processing is cashed.
When $value already is an XML::LibXML::Element, then no processing
nor value checking will be performed. The $name will be ignored.
If the $type is not qualified, then it is interpreted as basic type, as
defined by the selected schema. If you explicitly
need a non-namespace typed item, then use an empty namespace. In any
case, the type must be defined and the value is validated.
example:
my $xml = $soap->typed(int => count => 5);
my $xml = $soap->typed(pack_type(SCHEMA1999, 'int'), count => 5);
my $xml = $soap->typed(pack_type('', 'mine'), a => 1);
my $xml = $soap->typed('{}mine'), a => 1); #same
=back
=head3 Decoding
=over 4
=item $obj-E<gt>B<rpcDecode>($xmlnodes)
Decode the elements found in the $xmlnodes (list of XML::LibXML::Node
objects). Use Data::Dumper to figure-out what the produced output is:
it is a guess, so may not be perfect (do not use RPC but document style
soap for good results).
The decoded data is returned. When "simplify" is set, then the returned
data is compact but may be sloppy. Otherwise, a HASH is returned
containing as much info as could be extracted from the tree.
=back
=head1 SEE ALSO
This module is part of XML-Compile-SOAP distribution version 3.20,
built on October 19, 2016. Website: F<http://perl.overmeer.net/xml-compile/>
Please post questions or ideas to the mailinglist at
F<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile> .
For live contact with other developers, visit the C<#xml-compile> channel
on C<irc.perl.org>.
=head1 LICENSE
Copyrights 2007-2016 by [Mark Overmeer]. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>