GenericInputStream(3)

NAME

       SOAP::GenericInputStream - Default handler for SOAP::Parser output

SYNOPSIS

           use SOAP::Parser;

           my $parser = SOAP::Parser->new();

           $parser->parsefile('soap.xml');

           my $headers = $parser->get_headers();
           my $body    = $parser->get_body();

DESCRIPTION

       As you can see from the synopsis, you won't use SOAP::GenericInput-
       Stream directly, but rather the SOAP::Parser will create instances of
       it when necessary to unmarshal SOAP documents.

       The main reason for this documentation is to describe the interface
       exposed from SOAP::GenericInputStream because you need to implement
       this interface if you'd like to have the parser create something more
       exotic than what SOAP::GenericInputStream produces.

       new(TypeUri, TypeName, Resolver)

       TypeUri and TypeName are strings that indicate the type of object being
       unmarshaled. Resolver is a function pointer takes a single argument,
       the resulting object, and you should call through this pointer in your
       implementation of term (which means you need to store it until term is
       called). Here's an example of a minimal implementation, assuming you've
       stored the object reference in $self->{object}:

           sub new {
               my ($class, $typeuri, $typename, $resolver) = @_;
               return bless { resolver => $resolver }, $class;
           }

           sub term {
               my ($self) = @_;
               $self->{resolver}->($self->{object});
           }

       simple_accessor(AccessorUri, AccessorName, TypeUri, TypeName, Content)

       SOAP::Parser calls this function when it encounters a simple (scalar)
       accessor.  You are told the uri and name of both the accessor and any
       xsi:type attribute.  If the packet being unmarshaled doesn't use names-
       paces (this is possible but isn't recommended by the SOAP spec), Acces-
       sorUri will be undefined. Unless there is an explicit xsi:type, TypeUri
       and TypeName will also be undefined. So the only two parameters that
       are guaranteed to be defined are AccessorName and Content.

       AccessorUri and AccessorName gives the namespace and name of the ele-
       ment, and Content contains the scalar content (always a string).

       compound_accessor(AccessorUri, AccessorName, TypeUri, TypeName, IsPack-
       age, Resolver)

       SOAP::Parser calls this function when it encounters a compound accessor
       (e.g., a structured type whose value is inlined under the accessor).
       The first four parameters here are as described in simple_accessor
       above. IsPackage is a hint that tells you that this node is a package
       (generally you can ignore this; SOAP::Parser does all the work to deal
       with packages). Resolver may or may not be defined, and I'll discuss
       how it works shortly.

       NOTE NOTE NOTE: The SOAP "package" attribute was dropped when the SOAP
       spec
                       went from version 1.0 to version 1.1. Use package-
       related
                       functionality at your own risk - you may not interoper-
       ate
                       with other servers if you rely on it. I'll eventually
       remove
                       this feature if it doesn't reappear in the spec soon.

       This function must return a blessed object reference that implements
       the same interface (nothing prohibits you from simply returning $self,
       but since SOAP::Parser keeps track of these object references on a per-
       node basis, it's usually easier just to create a new instance of your
       class and have each instance know how to unmarshal a single object).

       If Resolver is defined, you'll need to call it when the new stream is
       term'd to communicate the resulting object reference to the Parser, so
       be sure to propagate this reference to the new stream you create to do
       the unmarshaling. Since you probably also need to be notified when the
       new object is created, you'll not normally hand Resolver directly to
       the new stream, but rather you'll provide your own implementation of
       Resolver that does something with the object and then chains to the
       Resolver passed in from the parser:

           sub compound_accessor {
               my ($self, $accessor_uri, $accessor_name, $typeuri, $typename, $is_package, $resolver) = @_;

               my $object = $self->{object};

               # create a closure to pass to the new input stream
               my $my_resolver = sub {
                   my ($newly_unmarshaled_object) = @_;

                   # do something with the object yourself
                   $object->{$accessor_name} = $newly_unmarshaled_object;

                   # chain to the Parser's resolver if it's defined
                   $resolver->($child_object) if $resolver;
               };

               return $self->{type_mapper}->get_deserializer($typeuri, $typename, $my_resolver);
           }

       reference_accessor(AccessorUri, AccessorName, Object)

       SOAP::Parser calls this function when it encounters a reference to an
       object that it's already unmarshaled. AccessorUri and AccessorName are
       the same as in simple_accessor, and Object is a reference to a thingy;
       it's basically whatever was resolved when another stream (perhaps one
       that you implemented) unmarshaled the thingy. This could be a blessed
       object reference, or simply a reference to a scalar (in SOAP it is pos-
       sible to communicate pointers to multiref scalars). In any case, you
       should add this new reference to the object graph. Here's a simple
       example:

           sub reference_accessor {
               my ($self, $accessor_uri, $accessor_name, $object) = @_;

               $self->{object}{$accessor_name} = $object;
           }

       forward_reference_accessor(AccessorUri, AccessorName)

       SOAP::Parser calls this function when it encounters a reference to an
       object that has not yet been unmarshaled (a forward reference). You
       should return a function pointer that expects a single argument (the
       unmarshaled object). This can be as simple as creating a closure that
       simply delays a call to reference_accessor on yourself:

           sub forward_reference_accessor {
               my ($self, $accessor_uri, $accessor_name) = @_;

               # return a closure to complete the transaction at a later date
               return sub {
                   my ($object) = @_;
                   $self->reference_accessor($accessor_uri, $accessor_name, $object);
               };
           }

       term()

       SOAP::Parser calls this function when there are no more accessors for
       the given node.  You are expected to call the Resolver you were passed
       at construction time at this point to pass the unmarshaled object ref-
       erence to your parent. Note that due to forward references, the object
       may not be complete yet (it may have oustanding forward references that
       haven't yet been resolved). This isn't a problem, because the parse
       isn't finished yet, and as long as you've provided a resolver that
       fixes up these object references from your implementation of for-
       ward_reference_accessor, by the time the parse is complete, your object
       have all its references resolved by the parser.

       See the description of new() for an example implementation of this
       function.

DEPENDENCIES

       SOAP::TypeMapper

AUTHOR

       Keith Brown

GenericInputStream(3)

NAME

SYNOPSIS

DESCRIPTION

DEPENDENCIES

AUTHOR

SEE ALSO