/ 
XML-Compile-SOAP-0.60
River stage two • 30 direct dependents • 35 total dependents
/ XML::Compile::SOAP::Encoding

NAME

XML::Compile::SOAP::Encoding - SOAP encoding

SYNOPSIS

# see t/13enc11.t in the distribution for complex examples

my $client = XML::Compile::SOAP11::Client->new();
$client->startEncoding(...);  # loads this module

# create: <SOAP-ENC:int>41</SOAP-ENC:int>
my $xml = $client->enc(int => 41);

# create: <SOAP-ENC:int id="hhtg">42</SOAP-ENC:int>
my $xml = $client->enc(int => 42, 'hhtg');

# create: <code xsi:type="xsd:int">43</code>
my $int = pack_type SCHEMA2001, 'int';
my $xml = $client->typed(code => $int, 43);

# create: <ref href="#id-1"/>  (xyz get's id if it hasn't)
my $xml = $client->href('ref', $xyz);
my $xml = $client->href('ref', $xyz, 'id-1');  # explicit label

# create: <number>3</number>   (gets validated as well!)
my $xml = $client->element(number => $int, 3);

# create one-dimensional array of ints
my $xml = $client->array(undef, $int, \@xml);
my $xml = $client->array('{myns}mylocal', $int, \@xml);

# create multi-dimensional array
my $xml = $client->multidim(undef, $int, $matrix);
my $xml = $client->multidim('{myns}mylocal', $int, $matrix);

# decode an incoming encoded structure (as far as possible)
my $hash = $client->dec($xml);

DESCRIPTION

This module loads extra functionality into the XML::Compile::SOAP namespace: all kinds of methods which are used to SOAP-encode data.

The loading is triggered by calling startEncoding(). In threaded applications, you may wish to call that method once before the fork(), such that not each threads or forked process needs to compile the code again. Of course, you can also use this package explicitly.

METHODS

Transcoding

SOAP defines encodings, especially for XML-RPC.

Encoding

$obj->array((NAME|undef), ITEM_TYPE, ARRAY-of-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, multidim() is used for multi-dimensional arrays.

    The NAME is the packed type of the array itself. When undef, the {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 arrayType attribute, however doesn't tell enough about the items themselves: they may be extensions to that type.

    Each of the ELEMENTS must be an XML::LibXML::Node, either self-constructed, or produced by one of the builder methods in this class, like enc() or typed().

    Returned is the XML::LibXML::Element which represents the array.

    Option      --Default
id            undef
nested_array  ''
offset        0
slice         <all remaining>

    . id => STRING

      Assign an id to the array.

    . 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: nested_array => '[,]', means that this array contains two-dimensional arrays.

    . offset => INTEGER

      When a partial array is to be transmitted, the number of the base element.

    . 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 offset element)

$obj->element(NAME, TYPE, VALUE)

    Create an element. The NAME is for node, where a namespace component is translated into a prefix.

$obj->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>

$obj->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.

$obj->multidim((NAME|undef), ITEM_TYPE, ARRAY-of-ELEMENTS, OPTIONS)

    A multi-dimensional array, less flexible than a single dimensional array, which can be created with array().

    The array must be square: 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

    . id => STRING

$obj->prefixed(TYPE|(NAMESPACE,LOCAL))

    Translate a NAMESPACE-LOCAL combination (which may be represented as a packed TYPE) into a prefixed notation.

    The complication is that the NAMESPACE may not naturally have a prefixed assigned to it: the produced SOAP message is the result of compilation, and only the namespaces which are registered to be used during compile-time are added to the list on the top-level. See compileMessage(prefixes).

$obj->startEncoding(OPTIONS)

    This needs to be called before any encoding routine, because it initializes the internals. Each call will reset all compiled cached translator routines.

    Option    --Default
doc         <required>
namespaces  <required>

    . doc => XML::LibXML::Document

    . namespaces => HASH

$obj->typed(NAME, TYPE, 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.

Decoding

$obj->dec(XMLNODES)

    Decode the XMLNODES (list of XML::LibXML::Element objects). Use Data::Dumper to figure-out what the produced output is: it is a guess, so may not be perfect (do not use XML-RPC but document style soap for good results).

    In LIST context, the decoded data is returned and a HASH with the id index are returned. In SCALAR context, only the decoded data is returned. When startDecoding(simplify) is true, then the returned data is concise but may be sloppy. Otherwise, a HASH is returned containing as much info as could be extracted from the tree.

$obj->decSimplify(TREE, OPTIONS)

    Simplify the TREE of output produced by dec() to contain only data. Of course, this will remove useful information.

    From each of the HASHes in the tree, the _NAME, _TYPE, id, and any/anyAttribute fields are removed. If only a _ is left over, that related value will replace the HASH as a whole.

$obj->startDecoding(OPTIONS)

    Each call to this method will restart the cache of the decoding internals.

    Currently not supported, is the automatic decoding of elements which inherit from SOAP-ENC:Array. If you encounter these, you have to play with hooks.

    Option     --Default
reader_opts  {}
simplify     <false>

    . reader_opts => HASH

    . simplify => BOOLEAN

      Call decSimplify() automatically at the end of dec(), so producing an easily accessible output tree.

SEE ALSO

This module is part of XML-Compile-SOAP distribution version 0.6, built on November 06, 2007. Website: http://perl.overmeer.net/xml-compile/

LICENSE

Copyrights 2007 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 http://www.perl.com/perl/misc/Artistic.html