SOAP::Serializer(3) User Contributed Perl Documentation SOAP::Serializer(3)NAMESOAP::Serializer - the means by which the toolkit manages the expres‐
sion of data as XML
DESCRIPTION
The SOAP::Serializer class is the means by which the toolkit manages
the expression of data as XML. The object that a SOAP::Lite instance
uses by default is generally enough for the task, with no need for the
application to create its own. The main purpose of this class is to
provide a place for applications to extend the serializer by defining
additional methods for handling new datatypes.
METHODS
new(optional key/value pairs)
$serialize = SOAP::Serializer->new( );
This is the constructor method for the class. In addition to creat‐
ing a basic object and initializing it with default values, the
constructor can also take names and values for most of the accessor
methods that the class supports.
envelope(method, data arguments)
$serialize->envelope(fault => $fault_obj);
Provides the core purpose for the SOAP::Serializer class. It cre‐
ates the full SOAP envelope based on the input passed in to it. The
data arguments passed in the list of parameters to the method are
divided into two sublists: any parameters that are SOAP::Header
objects or derivatives of go into one list, while the remainder go
into the other. The nonheader objects are used as the content for
the message body, with the body itself being largely dependent on
the value of the first argument in the list. This argument is
expected to be a string and should be one of the following:
context
$serialize->context->packager();
This provides access to the calling context of "SOAP::Serializer".
In a client side context the often means a reference to an instance
of SOAP::Lite. In a server side context this means a reference to a
SOAP::Server instance.
method
The envelope is being created to encapsulate a RPC-style method
call.
response
The message being created is that of a response stemming from a
RPC-style method call.
fault
For this specifier, the envelope being created is to transmit a
fault.
freeform
This identifier is used as a general-case encoding style for
messages that don't fit into any of the previous cases. The
arguments are encoded into the envelope's Body tag without any
sort of context sensitivity. Any value other than these four
results in an error.
envprefix(optional value)
$serialize->envprefix('env');
Gets or sets the prefix that labels the SOAP envelope namespace.
This defaults to SOAP-ENV.
encprefix(optional value)
$serialize->envprefix('enc');
Gets or sets the prefix that labels the SOAP encoding namespace.
Defaults to SOAP-ENC.
soapversion(optional value)
$serial->soapversion('1.2');
If no parameter is given, returns the current version of SOAP that
is being used as the basis for serializing messages. If a parameter
is given, attempts to set that as the version of SOAP being used.
The value should be either 1.1 or 1.2. When the SOAP version is
being set, the package selects new URNs for envelope and encoding
spaces and also calls the xmlschema method to set the appropriate
schema definition.
xmlschema(optional value)
$serial->xmlschema($xml_schema_1999);
Gets or sets the URN for the schema being used to express the
structure of the XML generated by the serializer. If setting the
value, the input must be the full URN for the new schema and is
checked against the list of known SOAP schemas.
register_ns
The register_ns subroutine allows users to register a global names‐
pace with the SOAP Envelope. The first parameter is the namespace,
the second parameter to this subroutine is an optional prefix. If a
prefix is not provided, one will be generated automatically for
you. All namespaces registered with the serializer get declared in
the <soap:Envelope /> element.
find_prefix
The find_prefix subroutine takes a namespace as a parameter and
returns the assigned prefix to that namespace. This eliminates the
need to declare and redeclare namespaces within an envelope. This
subroutine is especially helpful in determining the proper prefix
when assigning a type to a SOAP::Data element. A good example of
how this might be used is as follows:
SOAP::Data->name("foo" => $inputParams{'foo'})
->type($client->serializer->find_prefix('urn:Foo').':Foo');
CUSTOM DATA TYPES
When serializing an object, or blessed hash reference, into XML,
"SOAP::Serializer" first checks to see if a subroutine has been defined
for the corresponding class name. For example, in the code below,
"SOAP::Serializer" will check to see if a subroutine called "as_MyMod‐
ule__MyPackage" has been defined. If so, then it will pass $foo to that
subroutine along with other data known about the "SOAP::Data" element
being encoded.
$foo = MyModule::MyPackage->new;
my $client = SOAP::Lite
->uri($NS)
->proxy($HOST);
$som = $client->someMethod(SOAP::Data->name("foo" => $foo));
as_TypeName SUBROUTINE REQUIREMENTS
Naming Convention
The subroutine should always be prepended with "as_" followed by
the type's name. The type's name must have all colons (':') substi‐
tuded with an underscore ('_').
Input
The input to "as_TypeName" will have at least one parameter, and at
most four parameters. The first parameter will always be the value
or the object to be encoded. The following three parameters depend
upon the context of the value/object being encoded.
If the value/object being encoded was part of a "SOAP::Data" object
(as in the above example), then the second, third and fourth param‐
eter will be the "SOAP::Data" element's name, type, and attribute
set respectively. If on the other hand, the value/object being
encoded is not part of a "SOAP::Data" object, as in the code below:
$foo = MyModule::MyPackage->new;
my $client = SOAP::Lite
->uri($NS)
->proxy($HOST);
$som = $client->someMethod($foo);
Then the second and third parameters will be the class name of the
value/object being encoded (e.g. "MyModule::MyPackage" in the exam‐
ple above), and the fourth parameter will be an empty hash.
Output
The encoding subroutine must return an array containing three ele‐
ments: 1) the name of the XML element, 2) a hash containing the
attributes to be placed into the element, and 3) the value of the
element.
AUTOTYPING
When the type of an element has not been declared explicitly,
SOAP::Lite must "guess" at the object's type. That is due to the fact
that the only form of introspection that Perl provides (through the use
of the "ref" subroutine) does not provide enough information to
"SOAP::Serializer" to allow SOAP::Lite to determine the exact type of
an element being serialized.
To work around this limitation, the "SOAP::Serializer::typelookup" hash
was created. This hash is populated with all the data types that the
current "SOAP::Serializer" can auto detect. Users and developers are
free to modify the contents of this hash allowing them to register new
data types with the system.
When "SOAP::Serializer" is asked to encode an object into XML, it goes
through the following steps. First, "SOAP::Serializer" checks to see if
a type has been explicitly stated for the current object. If a type has
been provided "SOAP::Serializer" checks to see if an "as_TypeName" sub‐
routine as been defined for that type. If such a subroutine exists,
then "SOAP::Serializer" passes the object to it to be encoded. If the
subroutine does not exist, or the type has not been provided, then
"SOAP::Serializer" must attempt to "guess" the type of the object being
serialized.
To do so, "SOAP::Serializer" runs in sequence a set of tests stored in
the "SOAP::Serializer::typelookup" hash. "SOAP::Serializer" continues
to run each test until one of the tests returns true, indicating that
the type of the object has been detected. When the type of the object
has been detected, then "SOAP::Serializer" passes the object to the
encoding subroutine that corresponds with the test that was passed. If
all the tests fail, and the type was not determined, then "SOAP::Seri‐
alizer" will as a last resort encode the object based on one of the
four basic data types known to Perl: REF, SCALAR, ARRAY and HASH.
The following table contains the set of data types detectable by
"SOAP::Lite" by default and the order in which their corresponding test
subroutine will be run, according to their precedence value.
Table 1 - Autotyping Precedence
TYPENAME PRECEDENCE VALUE
----------------------------
base64 10
int 20
long 25
float 30
gMonth 35
gDay 40
gYear 45
gMonthDay 50
gYearMonth 55
date 60
time 70
dateTime 75
duration 80
boolean 90
anyURI 95
string 100
REGISTERING A NEW DATA TYPE
To register a new data type that can be automatically detected by
"SOAP::Lite" and then serialized into XML, the developer must provide
the following four things:
· The name of the new data type.
· A subroutine that is capable of detecting whether a value passed to
it is of the corresponding data type.
· A number representing the test subroutine's precedence relative to
all the other types' test subroutinestypes. See Table 1 - Autotyp‐
ing Precedence.
· A subroutine that is capable of providing "SOAP::Serializer" with
the information necessary to serialize an object of the correspond‐
ing data type into XML.
EXAMPLE 1
If, for example, you wish to create a new datatype called "uriRefer‐
ence" for which you would like Perl values to be automatically detected
and serialized into, then you follow these steps.
Step 1: Write a Test Subroutine
The test subroutine will have passed to it by "SOAP::Serializer" a
value to be tested. The test subroutine must return 1 if the value
passed to it is of the corresponding type, or else it must return 0.
sub SOAP::Serializer::uriReferenceTest {
my ($value) = @_;
return 1 if ($value =~ m!^http://!);
return 0;
}
Step 2: Write an Encoding Subroutine
The encoding subroutine provides "SOAP::Serializer" with the data nec‐
essary to encode the value passed to it into XML. The encoding subrou‐
tine name's should be of the following format: "as_"<Type Name>.
The encoding subroutine will have passed to it by "SOAP::Serializer"
four parameters: the value to be encoded, the name of the element being
encoded, the assumed type of the element being encoded, and a reference
to a hash containing the attributes of the element being encoded. The
encoding subroutine must return an array representing the encoded
datatype. "SOAP::Serializer" will use the contents of this array to
generate the corresponding XML of the value being encoded, or serial‐
ized. This array contains the following 3 elements: the name of the XML
element, a hash containing the attributes to be placed into the ele‐
ment, and the value of the element.
sub SOAP::Serializer::as_uriReference {
my $self = shift;
my($value, $name, $type, $attr) = @_;
return [$name, {'xsi:type' => 'xsd:uriReference', %$attr}, $value];
}
Step 3: Register the New Data Type
To register the new data type, simply add the type to the "SOAP::Seri‐
alizer::typelookup" hash using the type name as the key, and an array
containing the precedence value, the test subroutine, and the encoding
subroutine.
$s->typelookup->{uriReference}
= [11, \&uriReferenceTest, 'as_uriReference'];
Tip: As a short hand, you could just as easily use an anonymous test
subroutine when registering the new datatype in place of the "urlRefer‐
enceTest" subroutine above. For example:
$s->typelookup->{uriReference}
= [11, sub { $_[0] =~ m!^http://! }, 'as_uriReference'];
Once complete, "SOAP::Serializer" will be able to serialize the follow‐
ing "SOAP::Data" object into XML:
$elem = SOAP::Data->name("someUri" => 'http://yahoo.com')->type('uriReference');
"SOAP::Serializer" will also be able to automatically determine and
serialize the following untyped "SOAP::Data" object into XML:
$elem = SOAP::Data->name("someUri" => 'http://yahoo.com');
ACKNOWLEDGEMENTS
Special thanks to O'Reilly publishing which has graciously allowed
SOAP::Lite to republish and redistribute large excerpts from Program‐
ming Web Services with Perl, mainly the SOAP::Lite reference found in
Appendix B.
COPYRIGHT
Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
AUTHORS
Paul Kulchenko (paulclinger@yahoo.com)
Randy J. Ray (rjray@blackperl.com)
Byrne Reese (byrne@majordojo.com)
perl v5.8.8 2008-06-09 SOAP::Serializer(3)
