home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _72c14e60ce1a60aee3bdd9df21699fcc < prev    next >
Text File  |  2000-03-23  |  7KB  |  199 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>SOAP::Parser - Parses SOAP documents</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::Parser - Parses SOAP documents</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(typemapper)"><CODE>new(TypeMapper)</CODE></A></LI>
  28.         <LI><A HREF="#parsestring(string)"><CODE>parsestring(String)</CODE></A></LI>
  29.         <LI><A HREF="#parsefile(filename)"><CODE>parsefile(Filename)</CODE></A></LI>
  30.         <LI><A HREF="#get_headers()"><CODE>get_headers()</CODE></A></LI>
  31.         <LI><A HREF="#get_body()"><CODE>get_body()</CODE></A></LI>
  32.     </UL>
  33.  
  34.     <LI><A HREF="#dependencies">DEPENDENCIES</A></LI>
  35.     <LI><A HREF="#author">AUTHOR</A></LI>
  36.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  37. </UL>
  38. <!-- INDEX END -->
  39.  
  40. <HR>
  41. <P>
  42. <H1><A NAME="name">NAME</A></H1>
  43. <P>SOAP::Parser - Parses SOAP documents</P>
  44. <P>
  45. <HR>
  46. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  47. <UL>
  48. <LI>Linux</LI>
  49. <LI>Solaris</LI>
  50. <LI>Windows</LI>
  51. </UL>
  52. <HR>
  53. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  54. <PRE>
  55.     use SOAP::Parser;
  56. </PRE>
  57. <PRE>
  58.  
  59.     my $parser = SOAP::Parser->new();</PRE>
  60. <PRE>
  61.     $parser->parsefile('soap.xml');</PRE>
  62. <PRE>
  63.     my $headers = $parser->get_headers();
  64.     my $body    = $parser->get_body();</PRE>
  65. <P>
  66. <HR>
  67. <H1><A NAME="description">DESCRIPTION</A></H1>
  68. <P>SOAP::Parser has all the logic for traversing a SOAP packet, including
  69. Envelope, Header, and Body, dealing with namespaces and tracking down
  70. references. It is basically an extension of a SAX-like parser, which
  71. means that it exposes an event-driven interface that you can implement
  72. to get the results of the parse. By default, SOAP/Perl provides
  73. SOAP::GenericInputStream to handle these events, which simply produces
  74. an object graph of hash references. If you want something
  75. different, on a per type URI basis, you can register alternate handlers
  76. so you can produce different output. See SOAP::TypeMapper for details.</P>
  77. <P>The handler needs to implement a set of methods, and these are outlined
  78. in SOAP::GenericInputStream along with descriptions of what the default
  79. behavior is (in other words, what SOAP::GenericInputStream does for each
  80. of these methods).</P>
  81. <P>The benefit of this design is that it avoids using a DOM to parse SOAP
  82. packets; rather, the packet is unmarshaled directly into whatever final
  83. form you need. This is more efficient in space and time than first unmarshaling
  84. into a DOM and then traversing the DOM to create an object graph that is
  85. meaningful to your program. To get the full benefit of this, you may need to
  86. implement a handler that creates your custom object graph from the SOAP packet
  87. (see SOAP::GenericInputStream for details). Since SOAP::Parser does all the
  88. hard work, implementing a handler (or set of handlers) is really pretty
  89. painless.</P>
  90. <P>
  91. <H2><A NAME="new(typemapper)"><CODE>new(TypeMapper)</CODE></A></H2>
  92. <P>Creates a new parser. Be sure *not* to reuse a parser for multiple SOAP
  93. packets - create one, use it, and then throw it away and get a new one if you
  94. need to parse a second SOAP packet.</P>
  95. <P>TypeMapper is an optional parameter that points to an instance of SOAP::TypeMapper
  96. that allows you to register alternate serializers and deserializers for different
  97. classes of objects. See the docs for that class for more details. If you don't
  98. pass this parameter, the system uses a global TypeMapper object.</P>
  99. <P>
  100. <H2><A NAME="parsestring(string)"><CODE>parsestring(String)</CODE></A></H2>
  101. <P>Parses the given string.</P>
  102. <P>
  103. <H2><A NAME="parsefile(filename)"><CODE>parsefile(Filename)</CODE></A></H2>
  104. <P>Parses the given file.</P>
  105. <P>
  106. <H2><A NAME="get_headers()"><CODE>get_headers()</CODE></A></H2>
  107. <P>After parsing, this function returns the array of headers
  108. in the SOAP envelope.</P>
  109. <P>Specifically, this function returns an array reference that
  110. contains zero or more hash references, each
  111. of which always take the following form:</P>
  112. <PRE>
  113.   {
  114.     soap_typeuri  => 'namespace qualification of header',
  115.     soap_typename => 'unqualified name of header',
  116.     content       => <header object>
  117.   }</PRE>
  118. <P>For instance, the following header:</P>
  119. <PRE>
  120.  <f:MyHeader xmlns:f="urn:foo">42 </f:MyHeader></PRE>
  121. <P>would be deserialized in this form:</P>
  122. <PRE>
  123.   {
  124.     soap_typeuri  => 'urn:foo',
  125.     soap_typename => 'MyHeader',
  126.     content       => 42,
  127.   }
  128. </PRE>
  129. <PRE>
  130.  
  131. while this header:</PRE>
  132. <PRE>
  133.  <f:MyHeader xmlns:f="urn:foo">
  134.   <m1>something</m1>
  135.   <m2>something else</m2>
  136.  </f:MyHeader></PRE>
  137. <P>would be deserialized (by default) in this form:</P>
  138. <PRE>
  139.   {
  140.     soap_typeuri  => 'urn:foo',
  141.     soap_typename => 'MyHeader',
  142.     content       => {
  143.         soap_typeuri  => 'urn:foo',
  144.         soap_typename => 'MyHeader',
  145.         m1 => 'something',
  146.         m2 => 'something else',
  147.     },
  148.   }</PRE>
  149. <P>Note the redundancy of the soap_typeuri and soap_typename isn't
  150. strictly necessary in this case because this information is embedded
  151. in the content itself. However, because of the potential (and common
  152. need) for sending scalars as the entirety of the header content,
  153. we need some way of communicating the namespace and typename of the
  154. header. Thus the content, for consistency, is always packaged in
  155. a hash along with explicit type information.</P>
  156. <P>
  157. <H2><A NAME="get_body()"><CODE>get_body()</CODE></A></H2>
  158. <P>After parsing, this function retrieves the body of the SOAP envelope.</P>
  159. <P>Since it doesn't make sense to send just a scalar as the body
  160. of a SOAP request, we don't need the redundancy of packaging the content
  161. inside of a hash along with its type and namespace (as was done above
  162. with headers). For instance:</P>
  163. <PRE>
  164.  <f:MyBody xmlns:f="urn:foo">
  165.   <m1>something</m1>
  166.   <m2>something else</m2>
  167.  </f:MyBody></PRE>
  168. <P>would be deserialized (by default) as the following:</P>
  169. <PRE>
  170.  {
  171.    soap_typeuri  => 'urn:foo',
  172.    soap_typename => 'MyBody',
  173.    m1 => 'something',
  174.    m2 => 'something else',
  175.  }</PRE>
  176. <P>
  177. <HR>
  178. <H1><A NAME="dependencies">DEPENDENCIES</A></H1>
  179. <P>XML::Parser::Expat
  180. SOAP::GenericInputStream
  181. SOAP::Defs</P>
  182. <P>
  183. <HR>
  184. <H1><A NAME="author">AUTHOR</A></H1>
  185. <P>Keith Brown</P>
  186. <P>
  187. <HR>
  188. <H1><A NAME="see also">SEE ALSO</A></H1>
  189. <P>SOAP::GenericInputStream</P>
  190. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  191. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  192. <STRONG><P CLASS=block> SOAP::Parser - Parses SOAP documents</P></STRONG>
  193. </TD></TR>
  194. </TABLE>
  195.  
  196. </BODY>
  197.  
  198. </HTML>
  199.