Hide Show 430 lines of Pod
=head1 NAME
XML::Compile::SOAP11::Encoding - SOAP encoding
=head1 SYNOPSIS
my
$client
= XML::Compile::SOAP11::Client->new();
$client
->startEncoding(...);
my
$xml
=
$client
->enc(
int
=> 41);
my
$xml
=
$client
->enc(
int
=> 42,
'hhtg'
);
my
$int
= pack_type SCHEMA2001,
'int'
;
my
$xml
=
$client
->typed(
$int
,
code
=> 43);
my
$xml
=
$client
->href(
'ref'
,
$xyz
);
my
$xml
=
$client
->href(
'ref'
,
$xyz
,
'id-1'
);
my
$xml
=
$client
->element(
$int
,
number
=> 3);
my
$xml
=
$client
->array(
undef
,
$int
, \
@xml
);
my
$xml
=
$client
->array(
'{myns}mylocal'
,
$int
, \
@xml
);
my
$xml
=
$client
->multidim(
undef
,
$int
,
$matrix
);
my
$xml
=
$client
->multidim(
'{myns}mylocal'
,
$int
,
$matrix
);
my
$hash
=
$client
->dec(
$xml
);
=head1 DESCRIPTION
This module loads extra functionality into the L<XML::Compile::SOAP|XML::Compile::SOAP>
namespace: all kinds of methods which are used to SOAP-encode data.
The loading is triggered by calling L<startEncoding()|XML::Compile::SOAP11::Encoding/
"Encoding"
>. 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 C<
use
> this
package
explicitly .
=head1 METHODS
=head2 Transcoding
SOAP defines encodings, especially
for
SOAP-RPC.
=head3 Encoding
$obj
-E<gt>B<array>((NAME|
undef
), ITEM_TYPE, ARRAY-of-ELEMENTS, OPTIONS)
=over 4
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 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>
.
array_type
=> STRING
=over 4
The arrayType attribute content. When explicitly set to
undef
, the
attribute is not created.
=back
.
id
=> STRING
=over 4
Assign an id to the array. If not
defined
, than
no
id attribute is
added.
=back
.
nested_array
=> STRING
=over 4
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.
=back
.
offset
=> INTEGER
=over 4
When a partial array is to be transmitted, the number of the base
element.
=back
.
slice
=> INTEGER
=over 4
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
=back
$obj
-E<gt>B<element>(TYPE, NAME, VALUE)
=over 4
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).
=back
$obj
-E<gt>B<enc>(LOCAL, VALUE, [ID])
=over 4
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;
my
$xml
=
$soap
->enc(
'int'
, 42,
id
=>
'me'
);
my
$xml
=
$soap
->enc(
int
=> 42,
id
=>
'me'
);
print
$xml
->toString;
=back
$obj
-E<gt>B<encAddNamespace>(PAIRS)
=over 4
Convenience alternative
for
L<encAddNamespaces()|XML::Compile::SOAP11::Encoding/
"Encoding"
>.
=back
$obj
-E<gt>B<encAddNamespaces>(PAIRS)
=over 4
Add prefix definitions
for
this one encoding cyclus. Each
time
L<startEncoding()|XML::Compile::SOAP11::Encoding/
"Encoding"
> is called, the table is
reset
. The namespace
table is returned.
=back
$obj
-E<gt>B<href>(NAME, ELEMENT, [ID])
=over 4
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.
=back
$obj
-E<gt>B<multidim>((NAME|
undef
), ITEM_TYPE, ARRAY-of-ELEMENTS, OPTIONS)
=over 4
A multi-dimensional array, less flexible than a single dimensional
array, which can be created
with
L<array()|XML::Compile::SOAP11::Encoding/
"Encoding"
>.
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
=back
$obj
-E<gt>B<nil>([TYPE], NAME)
=over 4
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.
=back
$obj
-E<gt>B<prefixed>(TYPE|(NAMESPACE,LOCAL))
=over 4
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.
=back
$obj
-E<gt>B<startEncoding>(OPTIONS)
=over 4
This needs to be called
before
any encoding routine, because it
initializes the internals. Each call will
reset
all compiled
cached translator routines.
When you
use
the standard RPC-encoded interface, this will be
called
for
you.
Option --Default
doc <required>
namespaces {}
prefixes {}
.
doc
=> XML::LibXML::Document
.
namespaces
=> HASH|ARRAY
=over 4
Pre release 0.74 name
for
option C<prefixes>.
=back
.
prefixes
=> HASH|ARRAY
=over 4
Like L<XML::Compile::Schema::compile(prefixes)|XML::Compile::Schema/
"Compilers"
>, this can
be a HASH (see example) or an ARRAY
with
prefix-uri pairs.
=back
example:
my
%ns
;
$ns
{
$MYNS
} = {
uri
=>
$MYNS
,
prefix
=>
'm'
};
$soap
->startEncoding(
doc
=>
$doc
,
prefixes
=> \
%ns
);
$soap
->startEncoding(
doc
=>
$doc
,
prefixes
=> [
m
=>
$MYNS
]);
=back
$obj
-E<gt>B<struct>(TYPE, CHILDS)
=over 4
Create a structure, an element
with
childs. The CHILDS must be fully
prepared XML::LibXML::Element objects.
=back
$obj
-E<gt>B<typed>(TYPE, NAME, VALUE)
=over 4
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);
=back
=head3 Decoding
$obj
-E<gt>B<dec>(XMLNODES)
=over 4
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
RPC but document style soap
for
good results).
The decoded data is returned. When L<startDecoding(simplify)|XML::Compile::SOAP11::Encoding/
"Decoding"
> is true,
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
$obj
-E<gt>B<decSimplify>(TREE, OPTIONS)
=over 4
Simplify the TREE of output produced by L<dec()|XML::Compile::SOAP11::Encoding/
"Decoding"
> to contain only
data. Of course, this will remove useful information.
From
each
of the HASHes in the tree, the C<_NAME>, C<_TYPE>, C<id>,
and any/anyAttribute fields are removed. If only a C<_> is left over,
that related value will replace the HASH as a whole.
=back
$obj
-E<gt>B<startDecoding>(OPTIONS)
=over 4
Each call to this method will restart the cache of the decoding
internals.
Currently B<not supported>, is the automatic decoding of elements which
I<inherit> from C<SOAP-ENC:Array>. If you encounter these, you have to
play
with
hooks.
Option --Default
reader_opts {}
simplify <false>
.
reader_opts
=> HASH
=over 4
Extend or overrule the
default
reader options. Available options
are shown in L<XML::Compile::Schema::compile()|XML::Compile::Schema/
"Compilers"
>.
=back
.
simplify
=> BOOLEAN
=over 4
Call L<decSimplify()|XML::Compile::SOAP11::Encoding/
"Decoding"
> automatically at the end of L<dec()|XML::Compile::SOAP11::Encoding/
"Decoding"
>, so producing
an easily accessible output tree.
=back
=back
=head1 SEE ALSO
This module is part of XML-Compile-SOAP distribution version 2.16,
All modules in this suite:
L<XML::Compile>,
L<XML::Compile::SOAP>,
L<XML::Compile::SOAP12>,
L<XML::Compile::SOAP::Daemon>,
L<XML::Compile::SOAP::WSA>,
L<XML::Compile::Tester>,
L<XML::Compile::Cache>,
L<XML::Compile::Dumper>,
L<XML::Compile::RPC>,
and
L<XML::Rewrite>,
L<XML::ExistDB>,
L<XML::LibXML::Simple>.
Please post questions or ideas to the mailinglist at
For life contact
with
other developers, visit the C<
on C<irc.perl.org>.
=head1 LICENSE
Copyrights 2007-2010 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.