SOAP::GenericInputStreUser)Contributed Perl DocumenSOAP::GenericInputStream(3)NAMESOAP::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
SEE ALSOperl(1).
perl v5.8.8 2000-09-05 SOAP::GenericInputStream(3)
