axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jmsn...@apache.org
Subject cvs commit: xml-axis/proposals/async_sonic/src/org/apache/axis/utils axisNLS.properties
Date Thu, 05 Dec 2002 00:49:40 GMT
jmsnell     2002/12/04 16:49:39

  Added:       proposals/async_sonic AsyncAsyncClient_Note.txt
                        AxisAsyncClientAPI.htm AxisAsyncClientAPI.zip
  Removed:     proposals ASYNC_TODOS.txt AxisInternalMessageExchange.zip
                        README
               proposals/async_sonic build.xml buildSamples.xml
               proposals/async_sonic/src/org/apache/axis/transport/jms
                        QueueConnector.java JMSConnectorFactory.java
                        Subscription.java JMSEndpoint.java
                        JMSConstants.java JMSConnector.java
                        SimpleJMSListener.java JMSSender.java
                        InvokeException.java SonicConstants.java
                        TopicConnector.java InvokeTimeoutException.java
                        SimpleJMSWorker.java JMSTransport.java
                        MapUtils.java
               proposals/async_sonic/samples/jms server-config.wsdd
                        JMSTest.java client_deploy.wsdd build.xml
               proposals/async_sonic/xmls targets.xml
               proposals/async_sonic/src/org/apache/axis/utils
                        axisNLS.properties
  Log:
  * Removed the old JMS Transport proposal since it's now in the main source tree
  * Removed the old IME proposal since it's now in the main source
  * Added the new Async Client API proposal
  
  Revision  Changes    Path
  1.1                  xml-axis/proposals/async_sonic/AsyncAsyncClient_Note.txt
  
  Index: AsyncAsyncClient_Note.txt
  ===================================================================
  Over the past few weeks James Snell, Dave Chappell, and I have been
  talking about ways in which the asynchronicity introduced by the IME
  layer in Axis can be exposed to client code.  Attached to this message
  is a proposal and sample code that addresses this issue.  Dave or James,
  please commit this into the proposals directory at your convenience.
  
  The main characteristics of the proposal are:
  - Expose a blend of the JMS, SAAJ, and JAX-RPC API to the client that
  facilitates asynchronous interactions.  This API borrows the
  asynchronous invocation model from JMS and the web service information
  from JAX-RPC and SAAJ.
  - Support for outbound web service operation styles like solicit
  response and notification
  - A set of samples that show the new API in action
  
  The main difference between this proposal and IME is the target
  audience.  Bear in mind that this will be a public client-facing API as
  opposed to the IME which is strictly for internal use.  An analogy to
  Xerces can be made in that the IME is like XNI - low-level, internal,
  and targeted at framework developers.  The proposed API is like DOM and
  SAX in that it is intended for client code to interact with.
  
  There is a good deal of work involved with implementing this proposal.
  The first steps are already underway with the IME work being done by
  James.  This is not targeted at a near term release.  James and I
  estimated that this could be delivered in the April/May timeframe.
  
  Please review the attached content if possible.  Any suggestions/flames
  will really help us to move this stuff along.  Also, if anyone is
  interested in lending a hand in the implementation that would be MUCH
  appreciated.
  
  Thanks,
  Jaime
  ---
  Jaime Meritt
  Manager, Software Engineering
  Sonic Software Corporation
  http://www.sonicsoftware.com
  
  
  1.1                  xml-axis/proposals/async_sonic/AxisAsyncClientAPI.htm
  
  Index: AxisAsyncClientAPI.htm
  ===================================================================
  <html>
  
  <head>
  <meta http-equiv=Content-Type content="text/html; charset=us-ascii">
  <meta name=Generator content="Microsoft Word 10 (filtered)">
  <title>Axis Asynchronous Client API</title>
  
  <style>
  <!--
   /* Font Definitions */
   @font-face
  	{font-family:Wingdings;
  	panose-1:5 0 0 0 0 0 0 0 0 0;}
   /* Style Definitions */
   p.MsoNormal, li.MsoNormal, div.MsoNormal
  	{margin:0in;
  	margin-bottom:.0001pt;
  	font-size:12.0pt;
  	font-family:"Times New Roman";}
  h1
  	{margin-top:12.0pt;
  	margin-right:0in;
  	margin-bottom:3.0pt;
  	margin-left:.3in;
  	text-indent:-.3in;
  	page-break-after:avoid;
  	font-size:16.0pt;
  	font-family:Arial;}
  h2
  	{margin-top:12.0pt;
  	margin-right:0in;
  	margin-bottom:3.0pt;
  	margin-left:.4in;
  	text-indent:-.4in;
  	page-break-after:avoid;
  	font-size:14.0pt;
  	font-family:Arial;
  	font-style:italic;}
  h3
  	{margin-top:12.0pt;
  	margin-right:0in;
  	margin-bottom:3.0pt;
  	margin-left:.5in;
  	text-indent:-.5in;
  	page-break-after:avoid;
  	font-size:13.0pt;
  	font-family:Arial;}
  h4
  	{margin-top:12.0pt;
  	margin-right:0in;
  	margin-bottom:3.0pt;
  	margin-left:.6in;
  	text-indent:-.6in;
  	page-break-after:avoid;
  	font-size:14.0pt;
  	font-family:"Times New Roman";}
  h5
  	{margin-top:12.0pt;
  	margin-right:0in;
  	margin-bottom:3.0pt;
  	margin-left:.7in;
  	text-indent:-.7in;
  	font-size:13.0pt;
  	font-family:"Times New Roman";
  	font-style:italic;}
  h6
  	{margin-top:12.0pt;
  	margin-right:0in;
  	margin-bottom:3.0pt;
  	margin-left:.8in;
  	text-indent:-.8in;
  	font-size:11.0pt;
  	font-family:"Times New Roman";}
  p.MsoHeading7, li.MsoHeading7, div.MsoHeading7
  	{margin-top:12.0pt;
  	margin-right:0in;
  	margin-bottom:3.0pt;
  	margin-left:.9in;
  	text-indent:-.9in;
  	font-size:12.0pt;
  	font-family:"Times New Roman";}
  p.MsoHeading8, li.MsoHeading8, div.MsoHeading8
  	{margin-top:12.0pt;
  	margin-right:0in;
  	margin-bottom:3.0pt;
  	margin-left:1.0in;
  	text-indent:-1.0in;
  	font-size:12.0pt;
  	font-family:"Times New Roman";
  	font-style:italic;}
  p.MsoHeading9, li.MsoHeading9, div.MsoHeading9
  	{margin-top:12.0pt;
  	margin-right:0in;
  	margin-bottom:3.0pt;
  	margin-left:1.1in;
  	text-indent:-1.1in;
  	font-size:11.0pt;
  	font-family:Arial;}
  p.MsoToc1, li.MsoToc1, div.MsoToc1
  	{margin:0in;
  	margin-bottom:.0001pt;
  	font-size:12.0pt;
  	font-family:"Times New Roman";}
  p.MsoToc2, li.MsoToc2, div.MsoToc2
  	{margin-top:0in;
  	margin-right:0in;
  	margin-bottom:0in;
  	margin-left:12.0pt;
  	margin-bottom:.0001pt;
  	font-size:12.0pt;
  	font-family:"Times New Roman";}
  p.MsoToc3, li.MsoToc3, div.MsoToc3
  	{margin-top:0in;
  	margin-right:0in;
  	margin-bottom:0in;
  	margin-left:24.0pt;
  	margin-bottom:.0001pt;
  	font-size:12.0pt;
  	font-family:"Times New Roman";}
  p.MsoToc4, li.MsoToc4, div.MsoToc4
  	{margin-top:0in;
  	margin-right:0in;
  	margin-bottom:0in;
  	margin-left:.5in;
  	margin-bottom:.0001pt;
  	font-size:12.0pt;
  	font-family:"Times New Roman";}
  a:link, span.MsoHyperlink
  	{color:blue;
  	text-decoration:underline;}
  a:visited, span.MsoHyperlinkFollowed
  	{color:purple;
  	text-decoration:underline;}
  @page Section1
  	{size:8.5in 11.0in;
  	margin:1.0in 1.25in 1.0in 1.25in;}
  div.Section1
  	{page:Section1;}
   /* List Definitions */
   ol
  	{margin-bottom:0in;}
  ul
  	{margin-bottom:0in;}
  -->
  </style>
  
  </head>
  
  <body lang=EN-US link=blue vlink=purple>
  
  <div class=Section1>
  
  <p class=MsoNormal><b><span style='font-size:16.0pt;font-family:Arial'>Axis
  Asynchronous Client API</span></b></p>
  
  <p class=MsoNormal>Authors:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  <a href="mailto:jmeritt@sonicsoftware.com">Jaime Meritt</a> (<a
  href="http://www.sonicsoftware.com/">Sonic Software Corporation</a>)&nbsp;</p>
  
  <p class=MsoNormal style='margin-left:.5in;text-indent:.5in'><a
  href="mailto:chappell@sonicsoftware.com">Dave Chappell</a> (<a
  href="http://www.sonicsoftware.com/">Sonic Software Corporation</a>)</p>
  
  <p class=MsoNormal style='margin-left:.5in;text-indent:.5in'><a
  href="mailto:jasnell@us.ibm.com">James M Snell</a> (<a
  href="http://www.ibm.com/">IBM</a>)</p>
  
  <p class=MsoNormal>Version History:</p>
  
  <table class=MsoNormalTable border=0 cellspacing=0 cellpadding=0
   style='margin-left:-3.85pt;border-collapse:collapse'>
   <tr style='height:16.5pt'>
    <td width=77 colspan=2 valign=top style='width:57.75pt;border:solid windowtext 1.0pt;
    background:#A6A6A6;padding:0in 0in 0in 0in;height:16.5pt'>
    <p class=MsoNormal style='margin-left:3.45pt'><b>Revision</b></p>
    </td>
    <td width=78 valign=top style='width:58.5pt;border:solid windowtext 1.0pt;
    border-left:none;background:#A6A6A6;padding:0in 5.4pt 0in 5.4pt;height:16.5pt'>
    <p class=MsoNormal><b>Date</b></p>
    </td>
    <td width=522 valign=top style='width:391.2pt;border:solid windowtext 1.0pt;
    border-left:none;background:#A6A6A6;padding:0in 5.4pt 0in 5.4pt;height:16.5pt'>
    <p class=MsoNormal><b>Comments</b></p>
    </td>
   </tr>
   <tr style='height:12.0pt'>
    <td width=77 valign=top style='width:57.45pt;border:solid windowtext 1.0pt;
    border-top:none;padding:0in 5.4pt 0in 5.4pt;height:12.0pt'>
    <p class=MsoNormal style='margin-left:3.45pt'>0.3</p>
    </td>
    <td width=78 colspan=2 valign=top style='width:58.8pt;border-top:none;
    border-left:none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
    padding:0in 5.4pt 0in 5.4pt;height:12.0pt'>
    <p class=MsoNormal>11/22/02 </p>
    </td>
    <td width=522 valign=top style='width:391.2pt;border-top:none;border-left:
    none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
    padding:0in 5.4pt 0in 5.4pt;height:12.0pt'>
    <p class=MsoNormal>Initial Draft</p>
    </td>
   </tr>
   <tr style='height:12.0pt'>
    <td width=77 valign=top style='width:57.45pt;border:solid windowtext 1.0pt;
    border-top:none;padding:0in 5.4pt 0in 5.4pt;height:12.0pt'>
    <p class=MsoNormal style='margin-left:3.45pt'>0.5</p>
    </td>
    <td width=78 colspan=2 valign=top style='width:58.8pt;border-top:none;
    border-left:none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
    padding:0in 5.4pt 0in 5.4pt;height:12.0pt'>
    <p class=MsoNormal>12/4/02 </p>
    </td>
    <td width=522 valign=top style='width:391.2pt;border-top:none;border-left:
    none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
    padding:0in 5.4pt 0in 5.4pt;height:12.0pt'>
    <p class=MsoNormal>Incorporating review feedback from James Snell</p>
    </td>
   </tr>
   <tr>
    <td width=78 style='width:58.5pt;padding:0in 0in 0in 0in'>
    <p class=MsoNormal>&nbsp;</p>
    </td>
    <td width=10 style='width:.1in;padding:0in 0in 0in 0in'>
    <p class=MsoNormal>&nbsp;</p>
    </td>
    <td width=78 style='width:58.5pt;padding:0in 0in 0in 0in'>
    <p class=MsoNormal>&nbsp;</p>
    </td>
    <td width=522 style='width:391.5pt;padding:0in 0in 0in 0in'>
    <p class=MsoNormal>&nbsp;</p>
    </td>
   </tr>
  </table>
  
  <p class=MsoNormal>&nbsp;</p>
  
  <p class=MsoNormal><b><span style='font-size:16.0pt;font-family:Arial'>Contents</span></b></p>
  
  <p class=MsoToc1><span class=MsoHyperlink><a href="#_Toc26777058">1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  Introduction<span style='color:windowtext;display:none;text-decoration:none'>.
  1</span></a></span></p>
  
  <p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc26777059">1.1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  Disclaimer<span style='color:windowtext;display:none;text-decoration:none'> 1</span></a></span></p>
  
  <p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc26777060">1.2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  Purpose<span style='color:windowtext;display:none;text-decoration:none'>. 2</span></a></span></p>
  
  <p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc26777061">1.3&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  Scope<span style='color:windowtext;display:none;text-decoration:none'>. 2</span></a></span></p>
  
  <p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc26777062">1.4<span
  style='color:windowtext;text-decoration:none'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Feature Overview<span style='color:windowtext;display:none;text-decoration:
  none'>.. 2</span></a></span></p>
  
  <p class=MsoToc1><span class=MsoHyperlink><a href="#_Toc26777063">2<span
  style='color:windowtext;text-decoration:none'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span>Phased
  Delivery<span style='color:windowtext;display:none;text-decoration:none'>. 3</span></a></span></p>
  
  <p class=MsoToc1><span class=MsoHyperlink><a href="#_Toc26777064">3&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  Relationship to Existing APIs<span style='color:windowtext;display:none;
  text-decoration:none'>. 3</span></a></span></p>
  
  <p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc26777065">3.1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  Java Message Service<span style='color:windowtext;display:none;text-decoration:
  none'>. 3</span></a></span></p>
  
  <p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc26777066">3.2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  JAX-RPC<span style='color:windowtext;display:none;text-decoration:none'>.. 4</span></a></span></p>
  
  <p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc26777067">3.3&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  Internal Message Exchange<span style='color:windowtext;display:none;text-decoration:
  none'>. 4</span></a></span></p>
  
  <p class=MsoToc1><span class=MsoHyperlink><a href="#_Toc26777068">4&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  Functional Description<span style='color:windowtext;display:none;text-decoration:
  none'>. 4</span></a></span></p>
  
  <p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc26777069">4.1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  javax.jms.ConnectionFactory Extension<span style='color:windowtext;display:
  none;text-decoration:none'>. 5</span></a></span></p>
  
  <p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc26777070">4.2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  javax.jms.Connection Extension<span style='color:windowtext;display:none;
  text-decoration:none'>. 5</span></a></span></p>
  
  <p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc26777071">4.3&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  javax.jms.Session Extension<span style='color:windowtext;display:none;
  text-decoration:none'>. 5</span></a></span></p>
  
  <p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc26777072">4.4&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  javax.jms.Message Extension<span style='color:windowtext;display:none;
  text-decoration:none'>. 6</span></a></span></p>
  
  <p class=MsoToc3><span class=MsoHyperlink><a href="#_Toc26777073">4.4.1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  Message Body<span style='color:windowtext;display:none;text-decoration:none'>.
  6</span></a></span></p>
  
  <p class=MsoToc4><span class=MsoHyperlink><a href="#_Toc26777074">4.4.1.1&nbsp;
  SAAJMessage<span style='color:windowtext;display:none;text-decoration:none'>. 7</span></a></span></p>
  
  <p class=MsoToc4><span class=MsoHyperlink><a href="#_Toc26777075">4.4.1.2&nbsp;
  AxisMessage<span style='color:windowtext;display:none;text-decoration:none'>. 7</span></a></span></p>
  
  <p class=MsoToc3><span class=MsoHyperlink><a href="#_Toc26777076">4.4.2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  Message Headers<span style='color:windowtext;display:none;text-decoration:none'>.
  8</span></a></span></p>
  
  <p class=MsoToc3><span class=MsoHyperlink><a href="#_Toc26777077">4.4.3&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  Message Properties<span style='color:windowtext;display:none;text-decoration:
  none'>. 9</span></a></span></p>
  
  <p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc26777078">4.5&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  javax.jms.Destination Extension<span style='color:windowtext;display:none;
  text-decoration:none'>. 10</span></a></span></p>
  
  <p class=MsoToc3><span class=MsoHyperlink><a href="#_Toc26777079">4.5.1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  Features<span style='color:windowtext;display:none;text-decoration:none'>. 10</span></a></span></p>
  
  <p class=MsoToc1><span class=MsoHyperlink><a href="#_Toc26777080">5&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  Outstanding Issues<span style='color:windowtext;display:none;text-decoration:
  none'>. 11</span></a></span></p>
  
  <p class=MsoToc1><span class=MsoHyperlink><a href="#_Toc26777081">6&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  References<span style='color:windowtext;display:none;text-decoration:none'>. 11</span></a></span></p>
  
  <p class=MsoNormal>&nbsp;</p>
  
  <h1><a name="_Toc26777058"></a><a name="_Toc25054250"></a><a name="_Toc25491500"></a>1<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Introduction</h1>
  
  <h2><a name="_Toc26777059"></a><a name="_Toc25054251"></a><a name="_Toc25491501"></a>1.1<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Disclaimer</h2>
  
  <p class=MsoNormal style='text-indent:.4in'>Information contained herein is not
  finalized.&nbsp; It is merely a proposal to generate review feedback early on
  during the scoping process.&nbsp; A working knowledge of JMS, SAAJ, and JAX-RPC
  is a prerequisite for reading this document.&nbsp; Please refer to the
  references section for related works.&nbsp; &nbsp;</p>
  
  <h2><a name="_Toc26777060"></a><a name="_Toc25054252"></a><a name="_Toc25491502"></a>1.2<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Purpose</h2>
  
  <p class=MsoNormal style='text-indent:.25in'>Apache Axis provides robust support
  for synchronous style communications with RPC and document-oriented web
  services.&nbsp; Support for asynchronous invocation, however, is a feature that
  is not available in the current release of Axis.&nbsp; Goals of this proposal
  are documented in the list below.</p>
  
  <ul style='margin-top:0in' type=disc>
   <li class=MsoNormal>Ability to receive unsolicited messages asynchronously
       from the client thus enabling Notification and Solicit/Response operation
       styles</li>
   <li class=MsoNormal>Ability to perform work while the web service interaction
       is being processed</li>
   <li class=MsoNormal>Ability to have multiple invocations outstanding from the
       same client thread</li>
   <li class=MsoNormal>Ability to use different transports for inbound and
       outbound communications</li>
  </ul>
  
  <h2><a name="_Toc26777061"></a><a name="_Toc25054253"></a><a name="_Toc25491503"></a>1.3<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Scope</h2>
  
  <p class=MsoNormal style='text-indent:.25in'>The implementation of an
  asynchronous API that maps well to web service invocation semantics must
  resolve the following issues.&nbsp; The proposed API addresses each of these
  issues in the sections below.</p>
  
  <ul style='margin-top:0in' type=disc>
   <li class=MsoNormal>JAX-RPC does not define an asynchronous invocation
       model.&nbsp; Therefore any solution that is not standards-based is
       proprietary and will not be immediately acceptable to the Axis community
       as a whole</li>
   <li class=MsoNormal>Asynchronous programmers are already accustomed to the JMS
       API for messaging.&nbsp; Learning an entirely new API for similar
       capabilities is not desirable.</li>
   <li class=MsoNormal>Web service programmers are accustomed to using the
       JAX-RPC API for interaction with web services.&nbsp; Once again, the path
       to achieving asynchronous web service interactions should be evolutionary
       and not revolutionary.</li>
   <li class=MsoNormal>Asynchronous invocation requires the ability to correlate
       received messages with those that were sent previously.</li>
   <li class=MsoNormal>Axis synchronous-style APIs should not change at
       all.&nbsp; The asynchronous APIs should be separate from the widely-used
       JAX-RPC client API.</li>
   <li class=MsoNormal>Failure semantics are more complicated in asynchronous
       invocation models because faults from the web service are not immediately
       propagated back to the sender.</li>
  </ul>
  
  <h2 style='margin-left:.5in;text-indent:-.5in'><a name="_Toc26777062"></a><a
  name="_Toc25491504"></a>1.4<span style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Feature Overview</h2>
  
  <p class=MsoNormal style='text-indent:.25in'>The API documented below blends
  the JMS, SAAJ, and JAX-RPC APIs in order to provide standards-based
  asynchronous web service capabilities from the Axis client layer.&nbsp; The API
  does not replace the existing JAX-RPC or JAXM-style APIs that exist today in
  Axis.&nbsp; Rather, the API coexists with the current APIs and should be used
  only where asynchronous interaction is desired.&nbsp; The list below summarizes
  the features of this API.</p>
  
  <ul style='margin-top:0in' type=disc>
   <li class=MsoNormal>Expose a blend of the JMS, SAAJ, and JAX-RPC API to the
       client to facilitate asynchronous interactions.&nbsp; This API borrows the
       asynchronous invocation model from JMS and the web service information
       from JAX-RPC and SAAJ. </li>
   <li class=MsoNormal>Extend the JMS interfaces where appropriate to describe a
       web service interaction.&nbsp; </li>
  </ul>
  
  <p class=MsoNormal>The proposed API described herein does not define the
  server-side manifestation of asynchronicity, nor does it address the WSDL
  syntax for asynchronous web services.</p>
  
  <h1 style='margin-left:22.5pt;text-indent:-22.5pt'><a name="_Toc26777063"></a><a
  name="_Toc25491505"></a>2<span style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Phased Delivery</h1>
  
  <p class=MsoNormal style='text-indent:.25in'>The list below outlines a
  iterative development cycle that culminates in the full delivery of the Axis
  Asynchronous Client API that is addressed herein.&nbsp; It is useful to note
  that this proposal attempts to specify tasks 1-5.&nbsp; The WSDL extensions and
  server asynchronous API is the subject of a set of upcoming proposals.</p>
  
  <ol style='margin-top:0in' start=1 type=1>
   <li class=MsoNormal>Generate all interfaces that comprise the API.&nbsp; This
       can be accomplished without providing implementations of these
       interfaces.&nbsp; The interfaces can be incorporated into Axis in the
       proposals directory.</li>
   <li class=MsoNormal>Implement MessageExchange interfaces for the target
       transports.&nbsp; The MessageExchange interfaces provided by the org.apache.axis.ime
       package is a prerequisite for the proposed asynchronous functionality.</li>
   <li class=MsoNormal>Generate an implementation of the API the works with a
       subset of transports.&nbsp; Transport selection in this phase will be
       based on inherent asynchronicity in the transport and the availability of
       a MessageExchange implementation.&nbsp; Possible targets are JMS, SMTP,
       HTTP server<span style='font-family:Wingdings'>&agrave;</span>HTTP server
       communication.&nbsp; </li>
   <li class=MsoNormal>Convert remaining transports over to message exchange</li>
   <li class=MsoNormal>Deliver iteration 2 of the API that accounts for new
       transports.&nbsp; This is necessary in order to compensate for any new
       features and API requirements that the recent transport implementations
       introduce. </li>
   <li class=MsoNormal>Scope and implement WSDL2Java changes to generate
       asynchronous stubs</li>
   <li class=MsoNormal>Scope and implement Server API</li>
  </ol>
  
  <h1><a name="_Toc26777064"></a><a name="_Toc25054256"></a><a name="_Toc25491506"></a>3<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Relationship to Existing APIs</h1>
  
  <h2><a name="_Toc26777065"></a><a name="_Toc25054257"></a><a name="_Toc25491507"></a>3.1<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Java Message Service</h2>
  
  <p class=MsoNormal style='text-indent:.25in'>The Asynchronous API is an
  implementation of a subset of the interfaces defined by the JMS 1.1
  specification.&nbsp; The 1.1 version was chosen because it introduces a number
  of interface enhancements that unify the JMS Point-to-Point and
  Publish-Subscribe domains.&nbsp; This unification allows the interfaces defined
  herein to take advantage of domain agnostic capabilities without implying queue
  or topic-specific behavior.&nbsp; The benefits of this approach are summarized
  in the list below.</p>
  
  <ul style='margin-top:0in' type=disc>
   <li class=MsoNormal>Don&#8217;t reinvent the wheel &#8211; JMS defines a
       mature asynchronous client API that is well known to many developers</li>
   <li class=MsoNormal>Reuse existing code &#8211; Existing JMS applications can
       be adapted to work with the Asynchronous API with minor changes.</li>
  </ul>
  
  <p class=MsoNormal style='text-indent:.25in'>The JMS interfaces have been
  extended, where appropriate, to provide SOAP-specific enhancements.&nbsp; JMS
  constructs provide low level access to the content in textual or binary
  form.&nbsp; In Axis, users are accustomed to high level access to Web Service
  constructs. &nbsp;Therefore the JMS extensions provide a mechanism to allow
  users to deal with JMS constructs in much the same way as they would deal with
  the current Axis messages.</p>
  
  <h2><a name="_Toc26777066"></a><a name="_Toc25054258"></a><a name="_Toc25491508"></a>3.2<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>JAX-RPC</h2>
  
  <p class=MsoNormal style='text-indent:.25in'>JAX-RPC currently is the main mechanism
  to access synchronous-style Web Services through Axis.&nbsp; None of the
  proposed changes modify this in any way.&nbsp; The Asynchronous API is intended
  to coexist with JAX-RPC.&nbsp; Furthermore, the API makes use of JAX-RPC
  defined methods and interfaces in its JMS extensions.&nbsp; The list below
  summarizes the mapping of JMS constructs to JAX-RPC constructs.</p>
  
  <ul style='margin-top:0in' type=disc>
   <li class=MsoNormal>ConnectionFactory <span style='font-family:Wingdings'>&agrave;</span>
       ServiceFactory</li>
   <li class=MsoNormal>Connection <span style='font-family:Wingdings'>&agrave;</span>
       Service</li>
   <li class=MsoNormal>Session <span style='font-family:Wingdings'>&agrave;</span>
       Call</li>
   <li class=MsoNormal>Message <span style='font-family:Wingdings'>&agrave;</span>
       Invoke parameters, output parameters, return values, and faults</li>
  </ul>
  
  <p class=MsoNormal style='text-indent:.25in'>Clients may choose to use JAX-RPC
  for synchronous style invocations and the proposed API for asynchronous
  interaction as the application dictates.&nbsp; Code that currently works with
  Axis&#8217; Call API need not be modified when the Asynchronous APIs are
  included with Axis.&nbsp; Furthermore, existing synchronous applications can
  reuse a good deal of code with applications targeted at the new API.</p>
  
  <h2><a name="_Toc26777067"></a><a name="_Toc25054259"></a><a name="_Toc25491509"></a>3.3<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Internal Message Exchange</h2>
  
  <p class=MsoNormal style='text-indent:.5in'>The Internal Message Exchange that
  is currently a part of the Axis is responsible for providing an asynchronous
  transport invocation layer that allows the decoupling of the send handler chain
  from the receive handler chain.&nbsp; The IME is the first step in achieving
  asynchronous style semantics throughout Axis.&nbsp; The proposed API documented
  herein makes use of the IME interfaces to send and receive messages from the
  various transports.&nbsp; Furthermore, the API uses the MessageExchange to
  provide correlation of outgoing requests with incoming responses.&nbsp; </p>
  
  <p class=MsoNormal style='text-indent:.5in'>The Asynchronous API differs from
  the IME interfaces primarily in its target audience.&nbsp; Whereas the IME
  interfaces are internal to Axis and affect only those developers that are
  dealing with the low-level constructs such as the AxisEngine and MessageContext,
  the Asynchronous API is user-visible.&nbsp; Axis clients will directly make use
  of the client API to interact with web services using asynchronous style
  semantics.</p>
  
  <p class=MsoNormal style='text-indent:.5in'>The IME allows users to implement MessageExchange
  providers for individual transports.&nbsp; Therefore the IME defines a pluggability
  API for transport implementations.&nbsp; The API proposed herein, however, is
  transport agnostic.&nbsp; A separate implementation is not required for
  individual transports.&nbsp; The Asynchronous API is a single implementation
  that works with any transport or handler that supports the MessageExchange
  interfaces.</p>
  
  <p class=MsoNormal style='text-indent:.5in'>The inclusion of two separate APIs
  with asynchronous capabilities may be confusing to those familiar with the Axis
  internals.&nbsp; It may be beneficial to merge the two APIs into a single set
  of interfaces for the sake of clarity and user accessibility.</p>
  
  <h1><a name="_Toc26777068"></a><a name="_Toc25054260"></a><a name="_Toc25491510"></a>4<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Functional Description</h1>
  
  <p class=MsoNormal style='text-indent:.3in'>The contents of this point out the
  high level issues and features associated with various aspects of the
  API.&nbsp; The main reference for this content is the package of java
  interfaces that is included.&nbsp; Please refer to the interfaces and examples
  for more information on the content presented below.</p>
  
  <h2><a name="_Toc26777069"></a><a name="_Toc25054261"></a><a name="_Toc25491511"></a>4.1<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>javax.jms.ConnectionFactory Extension</h2>
  
  <p class=MsoNormal style='text-indent:.4in'>The AxisConnectionFactory is used
  to create AxisConnection instances.&nbsp; The AxisConnection, discussed below,
  is used to interact with a particular web service.&nbsp; An AxisConnectionFactory
  can be configured with a default wsdl location property and a service QName
  property.&nbsp; Since it is an implementation of javax.jms.ConnectionFactory
  and follows the patterns dictated by the specification, these properties are
  specified using standard JavaBean semantics (i.e. use of
  getters/setters).&nbsp; Furthermore, the implementation must be Serializable
  and Referenceable in order to allow for storage in a JNDI repository.&nbsp; </p>
  
  <p class=MsoNormal style='text-indent:.4in'>It is useful to note that the wsdl
  location and service QName properties are merely the default values.&nbsp; If
  the user requires connections to multiple web services they can pass the
  appropriate values into the createConnection methods.&nbsp; Alternately, the
  user can reset these properties prior to connection creation.&nbsp; The latter
  mechanism should only be used in a single-threaded execution as it is not
  thread-safe.&nbsp; For multi-threaded access to multiple Web services use the
  appropriate createConnection method.</p>
  
  <h2><a name="_Toc26777070"></a><a name="_Toc25054262"></a><a name="_Toc25491512"></a>4.2<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>javax.jms.Connection Extension</h2>
  
  <p class=MsoNormal>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  The AxisConnection represents a connection to the underlying web service or
  transport medium.&nbsp; For transports that support connection semantics and
  lifecycle, the connection is used as a handle to the underlying MessageExchange.&nbsp;
  Lifecycle method invocation is delegated down to transport implementations for
  all connection oriented transports.&nbsp; For example, if the underlying
  transport supports a Connection.close() method, the AxisConnection should
  support a close() method which delegates to the underlying Connection
  object.&nbsp; All delegation should be through the MessageExchange
  interfaces.&nbsp; Therefore, the MessageExchange may have to be extended to
  provide an indication of whether transport implementations support connection
  semantics and to provide delegated methods that wrap such invocations.&nbsp;
  The specification of connection support utilizes the feature mechanism detailed
  below.</p>
  
  <p class=MsoNormal>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  The AxisConnection is associated with a WSDL document and a particular service
  within the document.&nbsp; Sessions are created through the AxisConnection and
  are associated with the service and WSDL document automatically at creation
  time.&nbsp; Furthermore, the AxisConnection allows the session to be created
  that is associated with a particular port and operation name.&nbsp; All WSDL
  associations are optional.&nbsp; An AxisConnection can be created without any
  WSDL references thus enabling the user to setup the connection at runtime.</p>
  
  <p class=MsoNormal>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </p>
  
  <h2><a name="_Toc26777071"></a><a name="_Toc25054263"></a><a name="_Toc25491513"></a>4.3<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>javax.jms.Session Extension</h2>
  
  <p class=MsoNormal style='text-indent:.4in'>The AxisSession interface,
  constructed by the AxisConnection discussed above is the factory interface for MessageProducer,
  MessageConsumer, Destination, and Message implementations.&nbsp; Furthermore it
  is responsible for maintaining operation state information applicable to all
  instances constructed from a particular session.</p>
  
  <p class=MsoNormal style='text-indent:.4in'>The factory functionality allows
  the Session to be used to create preconfigured messages, producers and
  consumers for a particular web service operation.&nbsp; The operation name,
  parameters, and attributes must be set before creation of the aforementioned
  constructs because the created instances do not allow modification of these
  values.&nbsp; The session is the primary mechanism of specifying the
  information about the operation that is being performed.&nbsp; The following
  list contains the information that is settable in the session.&nbsp; The APIs
  for setting these values will be borrowed from the existing Call and Service
  interfaces where appropriate.&nbsp; </p>
  
  <p class=MsoNormal style='margin-left:.9in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>IN, OUT, and INOUT parameters</p>
  
  <p class=MsoNormal style='margin-left:.9in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Operation Name</p>
  
  <p class=MsoNormal style='margin-left:.9in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Operation Use and Style</p>
  
  <p class=MsoNormal style='margin-left:.9in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Return type</p>
  
  <p class=MsoNormal style='margin-left:.9in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>SOAP Action Usage</p>
  
  <p class=MsoNormal style='margin-left:.9in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Encoding Style</p>
  
  <p class=MsoNormal style='margin-left:.9in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Type Mappings</p>
  
  <p class=MsoNormal style='margin-left:.9in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Faults</p>
  
  <p class=MsoNormal style='text-indent:.4in'>These values can be automatically
  set if the session is associated with a particular port in a known WSDL
  document.&nbsp; If no WSDL document and port is associated with a created
  session, the session allows explicit calls to methods to setup these values.</p>
  
  <p class=MsoNormal style='text-indent:.4in'>An alternative mechanism exists
  which allows the session to be used when the WSDL and service information is
  unknown.&nbsp; The user can explicitly create SAAJMessage instances and use
  SAAJ APIs to dynamically construct the message content.&nbsp; Although this
  mechanism involves more work on the part of the client code it allows for total
  control over the content of the message.</p>
  
  <p class=MsoNormal>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  The threading model of AxisSession instances is identical to that of JMS.&nbsp;
  Sessions cannot be used concurrently by more than one thread.&nbsp; This
  includes a restriction on concurrent access to any items created from this
  session as well.&nbsp; An interesting side effect of this is that asynchronous
  listeners (javax.jms.MessageListener) cannot be used on a session that has
  producers associated with it.&nbsp; The reason for this is that the
  asynchronous listener mechanism creates an internal thread that controls message
  delivery.&nbsp; Since this thread is controlled by the underlying framework,
  there is no mechanism to prevent concurrent access from client code.&nbsp; This
  implies that asynchronous listeners should be used on a separate session than
  other producers.&nbsp; This limitation does not exist in the synchronous
  receive model because in this case the user code controls all access to the
  session and the associated constructs.</p>
  
  <h2><a name="_Toc26777072"></a><a name="_Toc25054264"></a><a name="_Toc25491514"></a>4.4<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>javax.jms.Message Extension</h2>
  
  <p class=MsoNormal style='text-indent:.5in'>The Message interfaces provided
  with JMS 1.1 provide users with the ability to customize 3 forms of content;
  body, headers, and properties.&nbsp; This section discusses the interpretation
  of these concepts in the proposed API and the body extensions that allow web
  service information to be encapsulated using a high-level abstraction.&nbsp;</p>
  
  <h3><a name="_Toc26777073"></a><a name="_Toc25054265"></a><a name="_Toc25491515"></a>4.4.1<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Message Body </h3>
  
  <p class=MsoNormal style='text-indent:.5in'>JMS provides support for common
  message content types such as bytes, text, map, etc.&nbsp; These low-level
  content abstractions are appropriate for generic message usage, but are more
  difficult to work with when the content conforms to a more rigid structure,
  like a SOAP envelope.&nbsp; When content is structured, it is better to wrap
  the basic message implementations with high level abstractions that provide
  easy access to the content of the message.&nbsp; This is the approach taken in
  the proposed API.&nbsp; Axis APIs are intended for creating SOAP envelopes, and
  JMS does not officially support a SOAP Envelope message type. Therefore we will
  propose a new message type, the SAAJMessage which extends the base javax.jms.Message
  and the javax.xml.soap.SOAPMessage types yet allows the client API to treat the
  message body as a SOAP envelope with attachments.&nbsp; The proposed API
  includes a higher level message abstraction that provides web service specific
  content handling mechanisms.&nbsp; This is encapsulated in the AxisMessage
  interface.</p>
  
  <h4><a name="_Toc26777074"></a><a name="_Toc25054266"></a><a name="_Toc25491516"></a>4.4.1.1<span
  style='font-size:7.0pt'>&nbsp; </span>SAAJMessage</h4>
  
  <p class=MsoNormal>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  The SAAJMessage is the base interface of all Message implementations defined
  herein.&nbsp; It extends the SAAJ SOAPMessage abstract class and implements javax.jms.Message.
  &nbsp;All messages in the proposed API inherit this capability from the SAAJMessage.&nbsp;
  The SAAJMessage implementation can be explicitly created and used for SAAJ
  style message creation and delivery.&nbsp; The AxisMessage extension of SAAJMessage
  provides a higher level abstraction thus allowing the user to deal with RPC
  style constructs as opposed to low-level SAAJ elements.&nbsp; For more
  information on the SAAJMessage please see the attached JavaDoc.</p>
  
  <p class=MsoNormal>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  The SAAJMessage can optionally be correlated with an associated message through
  the use of the set/getCorrelatedMessage functionality.&nbsp; This association
  implies that delivery of the correlated Message caused this SAAJMessage
  instance to be delivered.&nbsp; Correlation is required for all bidirectional
  operation styles such as request-response and solicit-response.&nbsp; Oneway
  and notification operation styles are not correlated in this fashion.&nbsp;
  Even in bidirectional operations, it is possible that the correlated message
  will be null.&nbsp; This may occur when the request message is no longer
  available in memory due to system restart or timeout expiration.&nbsp; It is up
  to the MessageExchange implementation to define correlation and persistence
  semantics.&nbsp; The contract between the IME and the underlying transport
  binding MAY be responsible for associating the SAAJMessage with the correlated
  Message as part of the inbound processing of the response.&nbsp; Client code
  should be written to tolerate a lack of correlated message or should provide
  its own persistence mechanism where appropriate.</p>
  
  <h4><a name="_Toc26777075"></a><a name="_Toc25054267"></a><a name="_Toc25491517"></a>4.4.1.2<span
  style='font-size:7.0pt'>&nbsp; </span>AxisMessage</h4>
  
  <p class=MsoNormal style='text-indent:.5in'>The AxisMessage provides access to
  content of a web service operation request or response through a generic
  Map-like interface.&nbsp; This is similar in structure to that of WSIF
  message.&nbsp; All parameters, return values, output parameters, and faults
  will be contained in an AxisMessage part.&nbsp; For more information on the AxisMessage
  please see the attached JavaDoc.</p>
  
  <p class=MsoNormal style='text-indent:.5in'>The AxisMessage represents a call
  to a web service or an outbound call from a web service (i.e. a solicitation or
  notification).&nbsp; The parameters that are being passed to the operation are
  the part content.&nbsp; Each part represents an individual parameter.&nbsp; The
  key for the parameter in the part map will be the parameter&#8217;s name.&nbsp;
  The main usage pattern is to create an AxisMessage using the AxisSession as
  described above.&nbsp; This message is preconfigured with a particular
  operation name, encoding style, output parameters, etc.&nbsp; Once created, the
  client code sets the values for the in parameters on the request message and
  passes it to a producer for delivery.&nbsp; If a response is required, as
  dictated by the WSDL for the service, it will be delivered using a MessageConsumer.&nbsp;
  On inbound operations the usage pattern is to retrieve the parameters that were
  passed in by the web service.&nbsp; If a response is required, an output
  message or fault can be created and sent back to the requester.&nbsp; <a
  name="_Toc25491518"></a><a name="_Toc25491519"></a></p>
  
  <p class=MsoNormal style='text-indent:.5in'>The AxisMessage also represents the
  response from a particular invocation of a web service.&nbsp; It provides a
  mechanism to get the return and output parameter values that are sent from the
  web service.&nbsp; For solicit-response style interactions it provides clients
  with the ability to set these values.&nbsp; The return value of an operation
  invocation must be included as the first part of the message.&nbsp; Subsequent
  parts will be interpreted as output parameters.&nbsp; The response AxisMessage
  instances should be correlated with the request message that generated them.</p>
  
  <p class=MsoNormal style='text-indent:.5in'><a name="_Toc25491520"></a>The AxisMessage
  is also used to pass back exception information to the requesting client.&nbsp;
  It contains an AxisFault member that is accessible as the content of the first
  part.&nbsp; It also contains a utility method containsFault() that allows a
  user to ascertain if a fault occurred.&nbsp; The AxisFault contains all of the
  information that was received in the SOAPFault generated by the web
  service.&nbsp; For solicit-response interactions, the AxisFault is set by the
  client and delivered back to the requesting web service.&nbsp; </p>
  
  <h3><a name="_Toc26777076"></a><a name="_Toc25054271"></a><a name="_Toc25491521"></a>4.4.2<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Message Headers</h3>
  
  <p class=MsoNormal style='text-indent:.5in'>The JMS headers are defined by the
  JMS specification and are open to vendor extension.&nbsp; They deal primarily
  with generic messaging concepts such as correlation and message identity,
  timestamp, priority, reply destinations, etc.&nbsp; They are intended to be
  used in an application agnostic way to control the behavior of the messaging
  infrastructure.&nbsp; The proposed API will interpret the invocation of header
  methods as defined in the list below.</p>
  
  <p class=MsoNormal style='margin-left:.75in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span><b>CorrelationID</b> &#8211; manifests itself as a SOAP header that
  contains a String or base64Binary value.&nbsp; Mutation methods change the
  value of the header or create a new one if it exists.&nbsp; In a response
  message this value will be the same as the MessageID of the request message
  that generated the response.&nbsp; In a request message this value is
  undefined.</p>
  
  <p class=MsoNormal style='margin-left:.75in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span><b>DeliveryMode</b> &#8211; modified through the invocation of the send
  method of the MessageProducer.&nbsp; Cannot be explicitly set on the
  message.&nbsp; Calling getJMSDeliveryMode on a received message will return
  NON_PERSISTENT by default.&nbsp; The transport implementation may explicitly
  set this value if supported.&nbsp; The other option is to pass the delivery
  mode as a SOAP header and to set and return its value based on the value of
  said header.</p>
  
  <p class=MsoNormal style='margin-left:.75in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span><b>Destination</b> &#8211; modified by the send method of MessageProducer.&nbsp;
  Cannot be explicitly set on the message.&nbsp; If getJMSDestination is called
  on a request message the value will be the default send destination of the AxisSession
  that created the message.&nbsp; This is retrieved&nbsp;from the WSDL or
  explicitly set on the AxisSession as described above.&nbsp; If getJMSDestination
  is called on a request message the value will be null.</p>
  
  <p class=MsoNormal style='margin-left:.75in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span><b>Expiration</b> &#8211;It is set through the MessageProducer&#8217;s
  send method. </p>
  
  <p class=MsoNormal style='margin-left:.75in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span><b>MessageID</b> &#8211; manifests itself as a SOAP header present in
  the message.&nbsp; If the user explicitly sets this using a generated GUID or
  another mechanism, the SOAP header will be created and the value set.&nbsp; If
  the user does not assign one, the MessageExchange layer is responsible for
  generating a message id and setting it on the message if appropriate in the
  particular transport.&nbsp; Subsequent calls to getJMSMessageID() will return
  this automatically generated value.</p>
  
  <p class=MsoNormal style='margin-left:.75in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span><b>Priority</b> - modified by the send method of MessageProducer.&nbsp;
  Cannot be explicitly set on the message.&nbsp; This results in the inclusion of
  a Soap header in the message.&nbsp; If getJMSPriority is called on a request
  message the value will be the DEFAULT_PRIORITY.&nbsp; If getJMSPriority is
  called on a response message the value will be the value of this header or
  DEFAULT_PRIORITY if it is not explicitly set.</p>
  
  <p class=MsoNormal style='margin-left:.75in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span><b>Redelivered</b> &#8211; If the transport layer is able to ascertain
  if a particular message has been redelivered, this flag will be set.&nbsp; In
  cases where redelivery has not occurred or the transport is unable to tell, the
  getter method will always return false.&nbsp; </p>
  
  <p class=MsoNormal style='margin-left:.75in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span><b>ReplyTo</b> &#8211; The ReplyTo destination is deeply connected with
  the request/response mechanism.&nbsp; It allows the receiver of a request to
  know the location that responses should be delivered to.&nbsp; For synchronous
  communications mechanisms this is required because the response is passed back
  in the same channel as the request.&nbsp; For all asynchronous transports the replyTo
  should be set by the caller.&nbsp; It manifests itself as a Soap header with a
  URL as its content.&nbsp; If the AxisSession that creates the MessageProducer
  knows the receive destination, the ReplyTo header will automatically be set on
  all outgoing messages.&nbsp; If not, the replyTo destination must be explicitly
  set.</p>
  
  <p class=MsoNormal style='margin-left:.75in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span><b>Timestamp &#8211; </b>Can be set by the transport as a Soap
  header.&nbsp; If this header is present its value will be returned.&nbsp;
  Setting this header value has no effect.</p>
  
  <p class=MsoNormal style='margin-left:.75in;text-indent:-.25in'><span
  style='font-family:Symbol'>&middot;</span><span style='font-size:7.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span><b>Type &#8211; </b>this is a Soap header with a String value.&nbsp; It
  will be present in messages only if explicitly set by the user.</p>
  
  <h3><a name="_Toc26777077"></a><a name="_Toc25054272"></a><a name="_Toc25491522"></a>4.4.3<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Message Properties</h3>
  
  <p class=MsoNormal style='text-indent:.5in'>Message properties are a mechanism
  of passing contextual information along with the primary message content.&nbsp;
  In some cases, this contextual information is the only message content.&nbsp;
  The main benefit of using message properties as opposed to including
  information in body content is that selectors can be employed to manage
  subscriptions.&nbsp; Selectors are a boolean algebra syntax that allow users to
  specify subscription filters based on message headers and properties that
  further segment the set of messages that the subscriber is interested in.&nbsp;
  For example, a prospective car buyer can subscribe to an endpoint where new car
  listings are posted.&nbsp; Car buyers can be partitioned based on the amount
  they are willing to spend on a car.&nbsp; Therefore, if the price were encoded
  as a message property, the subscribers could specify a selector such as
  &#8220;Price &lt; 20000&#8221; to signify that only car listings that are
  priced at less than $20,000 are acceptable.&nbsp; </p>
  
  <p class=MsoNormal style='text-indent:.5in'>Message properties in the proposed
  API are an optional feature of transports.&nbsp; It is up to the transport
  implementation to specify that properties are explicitly supported.&nbsp; The
  ability to support properties in any particular transport is dependent on the
  ability of the transport to pass contextual information that is separate from
  message content such as MIME header values.&nbsp; If the transport is not able
  to encode messages in such a fashion, it would be possible to place the
  properties in SOAP header values.&nbsp; Furthermore, properties may be
  supported but selectors may not be.&nbsp; In these cases it would be possible
  to provide a client side selection implementation.&nbsp; The details of such an
  implementation are out of the scope of this document.&nbsp; For the sake of
  simplicity, the first implementation of this functionality will defer to the
  underlying transport for both property and selector support.&nbsp; If either
  feature is missing, calls to set property will throw JMSException instances and
  calls to getProperty will always return null.</p>
  
  <h2><a name="_Toc26777078"></a><a name="_Toc25054273"></a><a name="_Toc25491523"></a>4.5<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>javax.jms.Destination Extension</h2>
  
  <p class=MsoNormal style='text-indent:.5in'>JMS defines destinations as a queue
  or a topic, both of which are unsupported in the proposed API.&nbsp; The reason
  for this is that both queues and topics imply a behavior that is inconsistent
  with web service interactions.&nbsp; Therefore it is necessary to provide a
  mechanism to specify web service endpoint addresses as a JMS destination.&nbsp;
  </p>
  
  <p class=MsoNormal style='text-indent:.5in'>JAX-RPC defines the target endpoint
  address as a String representing a URL.&nbsp; Axis adds onto this approach by
  allowing the explicit creation of a Transport object and the association of
  said Transport with the Call instance.&nbsp; Therefore, the Destinations that
  are provided as a part of the proposed API can be constructed from org.apache.axis.client.Transport,
  java.lang.String, or java.net.URL instances.&nbsp; Users cannot modify the
  endpoint referenced in destinations; they must create a new one to reference a
  separate endpoint.&nbsp; This restriction is consistent with the JMS API.</p>
  
  <p class=MsoNormal style='text-indent:.5in'>Destination instances are created
  through the AxisSession interface as discussed above.&nbsp; Once created, the AxisDestination
  can be queried for a list of supported features and modifications to the
  enabled features can be made.&nbsp; These feature modifications are delegated
  down to the underlying MessageExchange implementation of the transport.&nbsp; </p>
  
  <h3><a name="_Toc26777079"></a><a name="_Toc25054274"></a><a name="_Toc25491524"></a>4.5.1<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Features</h3>
  
  <p class=MsoNormal>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  The behavior of the proposed API will be modified based on the capabilities, or
  features, of the underlying transport.&nbsp; The mechanism for feature
  acquisition will make use of the MessageExchange interface provided by the
  IME.&nbsp; MessageExhange implementations are able to provide a list of
  supported features using the getSupportedFeatures method.&nbsp; This will be
  queried by the API when various features are requested.&nbsp; The table below
  summarizes the features that the proposed API can take advantage of and the
  operations that depend on them.&nbsp; This table of features is not
  finalized.&nbsp; Development will most definitely uncover others.</p>
  
  <table class=MsoNormalTable border=0 cellspacing=0 cellpadding=0
   style='border-collapse:collapse'>
   <tr>
    <td width=322 valign=top style='width:241.8pt;border:solid windowtext 1.0pt;
    background:#A6A6A6;padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>Feature Name</p>
    </td>
    <td width=295 valign=top style='width:221.4pt;border:solid windowtext 1.0pt;
    border-left:none;background:#A6A6A6;padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>Required by</p>
    </td>
   </tr>
   <tr>
    <td width=322 valign=top style='width:241.8pt;border:solid windowtext 1.0pt;
    border-top:none;padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>org.apache.axis.async.PropertySupport</p>
    </td>
    <td width=295 valign=top style='width:221.4pt;border-top:none;border-left:
    none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
    padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>Any call to setProperty on AxisMessage</p>
    </td>
   </tr>
   <tr>
    <td width=322 valign=top style='width:241.8pt;border:solid windowtext 1.0pt;
    border-top:none;padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>org.apache.axis.async.SelectorSupport</p>
    </td>
    <td width=295 valign=top style='width:221.4pt;border-top:none;border-left:
    none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
    padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>Calls to createConsumer that take in a message selector
    argument</p>
    </td>
   </tr>
   <tr>
    <td width=322 valign=top style='width:241.8pt;border:solid windowtext 1.0pt;
    border-top:none;padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>org.apache.axis.async.ConnectionSupport</p>
    </td>
    <td width=295 valign=top style='width:221.4pt;border-top:none;border-left:
    none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
    padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>Signals that the creation of an AxisConnection will create
    an underlying connection in the transport implementation.&nbsp; Any lifecycle
    actions carried out on the AxisConnection will be propagated to the
    underlying transport</p>
    </td>
   </tr>
   <tr>
    <td width=322 valign=top style='width:241.8pt;border:solid windowtext 1.0pt;
    border-top:none;padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>org.apache.axis.async.DeliveryMode.Persistent</p>
    </td>
    <td width=295 valign=top style='width:221.4pt;border-top:none;border-left:
    none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
    padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>Any call to send on a MessageProducer that has the
    delivery mode set to PERSISTENT </p>
    </td>
   </tr>
   <tr>
    <td width=322 valign=top style='width:241.8pt;border:solid windowtext 1.0pt;
    border-top:none;padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>org.apache.axis.async.DeliveryMode.NonPersistent</p>
    </td>
    <td width=295 valign=top style='width:221.4pt;border-top:none;border-left:
    none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
    padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>Any call to send on a MessageProducer that has the
    delivery mode set to NON_PERSISTENT</p>
    </td>
   </tr>
   <tr>
    <td width=322 valign=top style='width:241.8pt;border:solid windowtext 1.0pt;
    border-top:none;padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>org.apache.axis.async.AcknowledgeSupport.Auto</p>
    </td>
    <td width=295 valign=top style='width:221.4pt;border-top:none;border-left:
    none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
    padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>Any call to createSession on the connection that asks for
    AUTO_ACKNOWLEDGE mode &nbsp;ackMode</p>
    </td>
   </tr>
   <tr>
    <td width=322 valign=top style='width:241.8pt;border:solid windowtext 1.0pt;
    border-top:none;padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>org.apache.axis.async.AcknowledgeSupport.Client</p>
    </td>
    <td width=295 valign=top style='width:221.4pt;border-top:none;border-left:
    none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
    padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>Any call to createSession on the connection that asks for
    CLIENT_ACKNOWLEDGE mode &nbsp;ackMode</p>
    </td>
   </tr>
   <tr>
    <td width=322 valign=top style='width:241.8pt;border:solid windowtext 1.0pt;
    border-top:none;padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>org.apache.axis.async.AcknowledgeSupport.Dups</p>
    </td>
    <td width=295 valign=top style='width:221.4pt;border-top:none;border-left:
    none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
    padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>Any call to createSession on the connection that asks for
    DUPS_OK_ACKNOWLEDGE mode &nbsp;ackMode</p>
    </td>
   </tr>
   <tr>
    <td width=322 valign=top style='width:241.8pt;border:solid windowtext 1.0pt;
    border-top:none;padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>org.apache.axis.async.TransactionSupport.Local</p>
    </td>
    <td width=295 valign=top style='width:221.4pt;border-top:none;border-left:
    none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
    padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>Any call to createSession on the connection that asks for a
    non-XA transacted session</p>
    </td>
   </tr>
   <tr>
    <td width=322 valign=top style='width:241.8pt;border:solid windowtext 1.0pt;
    border-top:none;padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>org.apache.axis.async.TransactionSupport.XA</p>
    </td>
    <td width=295 valign=top style='width:221.4pt;border-top:none;border-left:
    none;border-bottom:solid windowtext 1.0pt;border-right:solid windowtext 1.0pt;
    padding:0in 5.4pt 0in 5.4pt'>
    <p class=MsoNormal>Any call to createSession on the connection that asks for
    a XA transacted session</p>
    </td>
   </tr>
  </table>
  
  <p class=MsoNormal>Calls made to methods that utilize features that are unavailable
  in the underlying transport will throw a FeatureNotSupportedException.</p>
  
  <h1><a name="_Toc26777080"></a><a name="_Toc25054275"></a><a name="_Toc25491525"></a>5<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>Outstanding Issues</h1>
  
  <ul style='margin-top:0in' type=disc>
   <li class=MsoNormal>Axis Asynchronous Server API</li>
   <li class=MsoNormal>Merge IME and Asynchronous API</li>
   <li class=MsoNormal>WSDL2Java Mapping to allow asynchronous API usage</li>
   <li class=MsoNormal>Investigate the applicability of ConnectionConsumer
       functionality in the asynchronous API.</li>
   <li class=MsoNormal>JMS message mapping (i.e. what happens when a MapMessage
       is sent to the producer)</li>
   <li class=MsoNormal>Transaction and reliability constraints</li>
  </ul>
  
  <h1><a name="_Toc26777081"></a><a name="_Toc25054276"></a><a name="_Toc25491526"></a>6<span
  style='font-size:7.0pt;font-family:"Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  </span>References</h1>
  
  <ul style='margin-top:0in' type=disc>
   <li class=MsoNormal><a href="http://java.sun.com/products/jms/docs.html">Java
       Message Service 1.1 Specification</a></li>
   <li class=MsoNormal><a href="http://java.sun.com/xml/jaxrpc/index.html">Java(TM)
       API for XML-based RPC (JAX-RPC)</a></li>
  </ul>
  
  </div>
  
  </body>
  
  </html>
  
  
  
  1.1                  xml-axis/proposals/async_sonic/AxisAsyncClientAPI.zip
  
  	<<Binary file>>
  
  

Mime
View raw message