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::GenericInputStream 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 namespaces (this is possible but isn't recommended by the SOAP spec), AccessorUri 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 element, and Content contains the scalar content (always a string).

compound_accessor(AccessorUri, AccessorName, TypeUri, TypeName, IsPackage, 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 interoperate 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 possible 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 reference 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 forward_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