Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SOAP::GenericInputStreUser)Contributed Perl DocumenSOAP::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::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

SEE ALSO
       perl(1).

perl v5.24.1			  2000-09-05	   SOAP::GenericInputStream(3)

NAME | SYNOPSIS | DESCRIPTION | DEPENDENCIES | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=SOAP::GenericInputStream&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help