home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _dd9de901f456de6556eda5f70724be0d < prev    next >
Text File  |  2000-03-23  |  10KB  |  206 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>SOAP::GenericInputStream - Default handler for SOAP::Parser output</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> SOAP::GenericInputStream - Default handler for SOAP::Parser output</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <UL>
  26.  
  27.         <LI><A HREF="#new(typeuri, typename, resolver)">new(TypeUri, TypeName, Resolver)</A></LI>
  28.         <LI><A HREF="#simple_accessor(accessoruri, accessorname, typeuri, typename, content)">simple_accessor(AccessorUri, AccessorName, TypeUri, TypeName, Content)</A></LI>
  29.         <LI><A HREF="#compound_accessor(accessoruri, accessorname, typeuri, typename, ispackage, resolver)">compound_accessor(AccessorUri, AccessorName, TypeUri, TypeName, IsPackage, Resolver)</A></LI>
  30.         <LI><A HREF="#reference_accessor(accessoruri, accessorname, object)">reference_accessor(AccessorUri, AccessorName, Object)</A></LI>
  31.         <LI><A HREF="#forward_reference_accessor(accessoruri, accessorname)">forward_reference_accessor(AccessorUri, AccessorName)</A></LI>
  32.         <LI><A HREF="#term()"><CODE>term()</CODE></A></LI>
  33.     </UL>
  34.  
  35.     <LI><A HREF="#dependencies">DEPENDENCIES</A></LI>
  36.     <LI><A HREF="#author">AUTHOR</A></LI>
  37.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  38. </UL>
  39. <!-- INDEX END -->
  40.  
  41. <HR>
  42. <P>
  43. <H1><A NAME="name">NAME</A></H1>
  44. <P>SOAP::GenericInputStream - Default handler for SOAP::Parser output</P>
  45. <P>
  46. <HR>
  47. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  48. <UL>
  49. <LI>Linux</LI>
  50. <LI>Solaris</LI>
  51. <LI>Windows</LI>
  52. </UL>
  53. <HR>
  54. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  55. <PRE>
  56.     use SOAP::Parser;
  57. </PRE>
  58. <PRE>
  59.  
  60.     my $parser = SOAP::Parser->new();</PRE>
  61. <PRE>
  62.     $parser->parsefile('soap.xml');</PRE>
  63. <PRE>
  64.     my $headers = $parser->get_headers();
  65.     my $body    = $parser->get_body();</PRE>
  66. <P>
  67. <HR>
  68. <H1><A NAME="description">DESCRIPTION</A></H1>
  69. <P>As you can see from the synopsis, you won't use SOAP::GenericInputStream
  70. directly, but rather the SOAP::Parser will create instances of it when
  71. necessary to unmarshal SOAP documents.</P>
  72. <P>The main reason for this documentation is to describe the interface
  73. exposed from SOAP::GenericInputStream because you need to implement this
  74. interface if you'd like to have the parser create something more exotic
  75. than what SOAP::GenericInputStream produces.</P>
  76. <P>
  77. <H2><A NAME="new(typeuri, typename, resolver)">new(TypeUri, TypeName, Resolver)</A></H2>
  78. <P>TypeUri and TypeName are strings that indicate the type of object being
  79. unmarshaled. Resolver is a function pointer takes a single argument,
  80. the resulting object, and you should call through this pointer in your
  81. implementation of term (which means you need to store it until term is
  82. called). Here's an example of a minimal implementation, assuming you've
  83. stored the object reference in $self->{object}:</P>
  84. <PRE>
  85.     sub new {
  86.         my ($class, $typeuri, $typename, $resolver) = @_;
  87.         return bless { resolver => $resolver }, $class;
  88.     }</PRE>
  89. <PRE>
  90.     sub term {
  91.         my ($self) = @_;
  92.         $self->{resolver}->($self->{object});
  93.     }</PRE>
  94. <P>
  95. <H2><A NAME="simple_accessor(accessoruri, accessorname, typeuri, typename, content)">simple_accessor(AccessorUri, AccessorName, TypeUri, TypeName, Content)</A></H2>
  96. <P>SOAP::Parser calls this function when it encounters a simple (scalar) accessor.
  97. You are told the uri and name of both the accessor and any xsi:type attribute.
  98. If the packet being unmarshaled doesn't use namespaces (this is possible but isn't
  99. recommended by the SOAP spec), AccessorUri will be undefined. Unless there is an
  100. explicit xsi:type, TypeUri and TypeName will also be undefined. So the only two
  101. parameters that are guaranteed to be defined are AccessorName and Content.</P>
  102. <P>AccessorUri and AccessorName gives the namespace and name of the element,
  103. and Content contains the scalar content (always a string).</P>
  104. <P>
  105. <H2><A NAME="compound_accessor(accessoruri, accessorname, typeuri, typename, ispackage, resolver)">compound_accessor(AccessorUri, AccessorName, TypeUri, TypeName, IsPackage, Resolver)</A></H2>
  106. <P>SOAP::Parser calls this function when it encounters a compound accessor (e.g.,
  107. a structured type whose value is inlined under the accessor). The first four
  108. parameters here are as described in simple_accessor above. IsPackage is a hint
  109. that tells you that this node is a package (generally you can ignore this; SOAP::Parser
  110. does all the work to deal with packages). Resolver may or may not be defined,
  111. and I'll discuss how it works shortly.</P>
  112. <P>This function must return a blessed object reference that implements the
  113. same interface (nothing prohibits you from simply returning $self, but since SOAP::Parser
  114. keeps track of these object references on a per-node basis, it's usually easier just
  115. to create a new instance of your class and have each instance know how to unmarshal
  116. a single object).</P>
  117. <P>If Resolver is defined, you'll need to call it when the new stream is term'd to
  118. communicate the resulting object reference to the Parser, so be sure to propagate
  119. this reference to the new stream you create to do the unmarshaling. Since you probably
  120. also need to be notified when the new object is created, you'll not normally hand Resolver
  121. directly to the new stream, but rather you'll provide your own implementation of Resolver
  122. that does something with the object and then chains to the Resolver passed in from the
  123. parser:</P>
  124. <PRE>
  125.     sub compound_accessor {
  126.         my ($self, $accessor_uri, $accessor_name, $typeuri, $typename, $is_package, $resolver) = @_;</PRE>
  127. <PRE>
  128.         my $object = $self->{object};</PRE>
  129. <PRE>
  130.         # create a closure to pass to the new input stream
  131.         my $my_resolver = sub {
  132.             my ($newly_unmarshaled_object) = @_;</PRE>
  133. <PRE>
  134.             # do something with the object yourself
  135.             $object->{$accessor_name} = $newly_unmarshaled_object;</PRE>
  136. <PRE>
  137.             # chain to the Parser's resolver if it's defined
  138.             $resolver->($child_object) if $resolver;
  139.         };</PRE>
  140. <PRE>
  141.         return $self->{type_mapper}->get_deserializer($typeuri, $typename, $my_resolver);
  142.     }</PRE>
  143. <P>
  144. <H2><A NAME="reference_accessor(accessoruri, accessorname, object)">reference_accessor(AccessorUri, AccessorName, Object)</A></H2>
  145. <P>SOAP::Parser calls this function when it encounters a reference to an object that
  146. it's already unmarshaled. AccessorUri and AccessorName are the same as in simple_accessor,
  147. and Object is a reference to a thingy; it's basically whatever was resolved when
  148. another stream (perhaps one that you implemented) unmarshaled the thingy. This could
  149. be a blessed object reference, or simply a reference to a scalar (in SOAP it is possible
  150. to communicate pointers to multiref scalars). In any case, you should add this new
  151. reference to the object graph. Here's a simple example:</P>
  152. <PRE>
  153.     sub reference_accessor {
  154.         my ($self, $accessor_uri, $accessor_name, $object) = @_;</PRE>
  155. <PRE>
  156.         $self->{object}{$accessor_name} = $object;
  157.     }</PRE>
  158. <P>
  159. <H2><A NAME="forward_reference_accessor(accessoruri, accessorname)">forward_reference_accessor(AccessorUri, AccessorName)</A></H2>
  160. <P>SOAP::Parser calls this function when it encounters a reference to an object that
  161. has not yet been unmarshaled (a forward reference). You should return a function
  162. pointer that expects a single argument (the unmarshaled object). This can be as simple
  163. as creating a closure that simply delays a call to reference_accessor on yourself:</P>
  164. <PRE>
  165.     sub forward_reference_accessor {
  166.         my ($self, $accessor_uri, $accessor_name) = @_;</PRE>
  167. <PRE>
  168.         # return a closure to complete the transaction at a later date
  169.         return sub {
  170.             my $object = @_;
  171.             $self->reference_accessor($accessor_uri, $accessor_name, $object);
  172.         };
  173.     }</PRE>
  174. <P>
  175. <H2><A NAME="term()"><CODE>term()</CODE></A></H2>
  176. <P>SOAP::Parser calls this function when there are no more accessors for the given node.
  177. You are expected to call the Resolver you were passed at construction time at this point
  178. to pass the unmarshaled object reference to your parent. Note that due to forward
  179. references, the object may not be complete yet (it may have oustanding forward references
  180. that haven't yet been resolved). This isn't a problem, because the parse isn't finished
  181. yet, and as long as you've provided a resolver that fixes up these object references
  182. from your implementation of forward_reference_accessor, by the time the parse is complete,
  183. your object have all its references resolved by the parser.</P>
  184. <P>See the description of <CODE>new()</CODE> for an example implementation of this function.</P>
  185. <P>
  186. <HR>
  187. <H1><A NAME="dependencies">DEPENDENCIES</A></H1>
  188. <P>SOAP::TypeMapper</P>
  189. <P>
  190. <HR>
  191. <H1><A NAME="author">AUTHOR</A></H1>
  192. <P>Keith Brown</P>
  193. <P>
  194. <HR>
  195. <H1><A NAME="see also">SEE ALSO</A></H1>
  196. <P>perl(1).</P>
  197. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  198. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  199. <STRONG><P CLASS=block> SOAP::GenericInputStream - Default handler for SOAP::Parser output</P></STRONG>
  200. </TD></TR>
  201. </TABLE>
  202.  
  203. </BODY>
  204.  
  205. </HTML>
  206.