home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _53089e584f7cc711e335ed8fc9035ee5 < prev    next >
Text File  |  2000-03-23  |  7KB  |  155 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>SOAP::EnvelopeMaker - Creates SOAP envelopes</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::EnvelopeMaker - Creates SOAP envelopes</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(outputfcn)"><CODE>new(OutputFcn)</CODE></A></LI>
  28.         <LI><A HREF="#add_header(accessoruri, accessorname, mustunderstand, ispackage, object)">add_header(AccessorUri, AccessorName, MustUnderstand, IsPackage, Object)</A></LI>
  29.         <LI><A HREF="#set_body(accessoruri, accessorname, ispackage, object)">set_body(AccessorUri, AccessorName, IsPackage, Object)</A></LI>
  30.     </UL>
  31.  
  32.     <LI><A HREF="#dependencies">DEPENDENCIES</A></LI>
  33.     <LI><A HREF="#author">AUTHOR</A></LI>
  34.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  35. </UL>
  36. <!-- INDEX END -->
  37.  
  38. <HR>
  39. <P>
  40. <H1><A NAME="name">NAME</A></H1>
  41. <P>SOAP::EnvelopeMaker - Creates SOAP envelopes</P>
  42. <P>
  43. <HR>
  44. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  45. <UL>
  46. <LI>Linux</LI>
  47. <LI>Solaris</LI>
  48. <LI>Windows</LI>
  49. </UL>
  50. <HR>
  51. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  52. <P>use SOAP::EnvelopeMaker;</P>
  53. <P>my $soap_request = '';
  54. my $output_fcn = sub {
  55.     $soap_request .= shift;
  56. };
  57. my $em = SOAP::EnvelopeMaker->new($output_fcn);</P>
  58. <P>my $body = {
  59.     origin => { x => 10, y => 20 },
  60.     corner => { x => 100, y => 200 },
  61. };</P>
  62. <P>$em->set_body(``urn:com-develop-geometry'', ``calculateArea'', 0, $body);</P>
  63. <P>my $endpoint    = ``http://soapl.develop.com/soap?class=Geometry'';
  64. my $method_uri  = ``urn:com-develop-geometry'';
  65. my $method_name = ``calculateArea'';</P>
  66. <P>use SOAP::Transport::HTTP::Client;</P>
  67. <P>my $soap_on_http = SOAP::Transport::HTTP::Client->new();</P>
  68. <P>my $soap_response = $soap_on_http->send_receive($endpoint,
  69.                                                 $method_uri,
  70.                                                 $method_name,
  71.                                                 $soap_request);
  72. use SOAP::Parser;
  73. my $soap_parser = SOAP::Parser->new();
  74. $soap_parser->parsestring($soap_response);</P>
  75. <P>my $area = $soap_parser->get_body()->{area};</P>
  76. <P>print ``The area is: $area\n'';</P>
  77. <P>
  78. <HR>
  79. <H1><A NAME="description">DESCRIPTION</A></H1>
  80. <P>The overall usage pattern of SOAP::EnvelopeMaker is as follows:</P>
  81. <P>1) Determine what you want to do with the resulting SOAP packet
  82.    and create an output function that implements this policy.</P>
  83. <P>2) Create an instance of SOAP::EnvelopeMaker, passing a reference
  84.    to your output function.</P>
  85. <P>(note that somebody may already have done these first two steps
  86.  on your behalf and simply passed you a reference to a pre-initialized
  87.  EnvelopeMaker - see SOAP::Transport::HTTP::Server for an example)</P>
  88. <P>3) (optional) Call add_header one or more times to specify headers.</P>
  89. <P>4) (required) Call set_body to specify the body.</P>
  90. <P>5) Throw away the EnvelopeMaker and do something with the envelope
  91.    that you've collected via your output function (assuming you've
  92.    not simply been piping the output somewhere as it's given to you).</P>
  93. <P>EnvelopeMaker expects that you'll add *all* your headers *before*
  94. setting the body - if you mess this up, the results are undefined.</P>
  95. <P>By the time set_body returns, a complete SOAP envelope will have been
  96. sent to your output function (in one or more chunks). You can</P>
  97. <P>
  98. <H2><A NAME="new(outputfcn)"><CODE>new(OutputFcn)</CODE></A></H2>
  99. <P>OutputFcn should accept a single scalar parameter, and will be called
  100. multiple times with chunks of the SOAP envelope as it is constructed.
  101. You can either append these chunks into a big string, waiting until
  102. the entire envelope is constructed before you do something with it
  103. (like calculate the content-length, for instance), or you can simply
  104. pipe each chunk directly to somebody else.</P>
  105. <P>
  106. <H2><A NAME="add_header(accessoruri, accessorname, mustunderstand, ispackage, object)">add_header(AccessorUri, AccessorName, MustUnderstand, IsPackage, Object)</A></H2>
  107. <P>The first two parameters allow you to specify a QName (qualified name)
  108. for your header. Note that in SOAP, all headers MUST be namespace
  109. qualified. MustUnderstand and IsPackage turn on SOAP features that are
  110. explained in the SOAP spec; if you haven't yet grok'd SOAP packages,
  111. just pass 0 for IsPackage. Finally, Object is whatever you'd like to
  112. serialize into the header (see set_body for notes on what can go here;
  113. headers can contain the same stuff as the body).</P>
  114. <P>
  115. <H2><A NAME="set_body(accessoruri, accessorname, ispackage, object)">set_body(AccessorUri, AccessorName, IsPackage, Object)</A></H2>
  116. <P>The first two parameters allow you to specify a QName (qualified name)
  117. for the body. The name of the accessor is the name of the SOAP method
  118. call you're making. IsPackage says that the body will be a SOAP package;
  119. just pass 0 if you're not sure what this means. Object is whatever you'd
  120. like to serialize. This can be one of the following things:</P>
  121. <P>1) a scalar - the body will contain the scalar content.</P>
  122. <P>2) a hash reference - the body will contain a SOAP serialized version
  123.                       of the contents of the hash.</P>
  124. <P>Note that the SOAP/Perl serialization architecture deals with references
  125. very carefully, so it is possible to pass arbitrary object graphs (although
  126. each ``object reference'' must currently be a non-blessed scalar or hash reference).</P>
  127. <P>In the future, expect to see support for passing blessed object references
  128. (if you want to do this today, see the experimental SOAP::TypeMapper).</P>
  129. <P>One interesting thing SOAP (and SOAP/Perl) support is that the headers
  130. and body can share references. They can point to the same stuff. Also,
  131. cycle detection is a natural part of SOAP/Perl's serialization architecture,
  132. so you can pass linked lists, circular queues, etc. and they will be
  133. rehydrated correctly.</P>
  134. <P>
  135. <HR>
  136. <H1><A NAME="dependencies">DEPENDENCIES</A></H1>
  137. <P>SOAP::Envelope</P>
  138. <P>
  139. <HR>
  140. <H1><A NAME="author">AUTHOR</A></H1>
  141. <P>Keith Brown</P>
  142. <P>
  143. <HR>
  144. <H1><A NAME="see also">SEE ALSO</A></H1>
  145. <P>SOAP::Envelope</P>
  146. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  147. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  148. <STRONG><P CLASS=block> SOAP::EnvelopeMaker - Creates SOAP envelopes</P></STRONG>
  149. </TD></TR>
  150. </TABLE>
  151.  
  152. </BODY>
  153.  
  154. </HTML>
  155.