phpman > perldoc > SOAP::Serializer(3pm)

NAME
    SOAP::Serializer - the means by which the toolkit manages the expression 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 creating 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 creates 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)
            $serialize->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)
            $serialize->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 namespace 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_MyModule__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 (':') substituted 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 parameter 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 example above), and the fourth parameter will be
        an empty hash.

    Output
        The encoding subroutine must return an array containing three elements: 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"
    subroutine 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::Serializer" 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 - Autotyping Precedence*.

    *   A subroutine that is capable of providing "SOAP::Serializer" with the information necessary
        to serialize an object of the corresponding data type into XML.

   EXAMPLE 1
    If, for example, you wish to create a new datatype called "uriReference" 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 necessary to encode the value
    passed to it into XML. The encoding subroutine 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 serialized. This array contains the following 3 elements: the name of the XML
    element, a hash containing the attributes to be placed into the element, 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::Serializer::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 "urlReferenceTest" subroutine above. For example:*

      $s->typelookup->{uriReference}
          = [11, sub { $_[0] =~ m!^http://! }, 'as_uriReference'];

    Once complete, "SOAP::Serializer" will be able to serialize the following "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 *Programming 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 AT yahoo.com)

    Randy J. Ray (rjray AT blackperl.com)

    Byrne Reese (byrne AT majordojo.com)