Return-Path: Delivered-To: apmail-xml-axis-dev-archive@xml.apache.org Received: (qmail 36726 invoked by uid 500); 5 Dec 2002 00:49:41 -0000 Mailing-List: contact axis-dev-help@xml.apache.org; run by ezmlm Precedence: bulk Reply-To: axis-dev@xml.apache.org list-help: list-unsubscribe: list-post: Delivered-To: mailing list axis-dev@xml.apache.org Received: (qmail 36717 invoked by uid 500); 5 Dec 2002 00:49:40 -0000 Delivered-To: apmail-xml-axis-cvs@apache.org Date: 5 Dec 2002 00:49:40 -0000 Message-ID: <20021205004940.56469.qmail@icarus.apache.org> From: jmsnell@apache.org To: xml-axis-cvs@apache.org Subject: cvs commit: xml-axis/proposals/async_sonic/src/org/apache/axis/utils axisNLS.properties X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N 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 =================================================================== Axis Asynchronous Client API

Axis Asynchronous Client API

Authors:           Jaime Meritt (Sonic Software Corporation) 

Dave Chappell (Sonic Software Corporation)

James M Snell (IBM)

Version History:

Revision

Date

Comments

0.3

11/22/02

Initial Draft

0.5

12/4/02

Incorporating review feedback from James Snell

 

 

 

 

 

Contents

1         Introduction. 1

1.1      Disclaimer 1

1.2      Purpose. 2

1.3      Scope. 2

1.4       Feature Overview.. 2

2      Phased Delivery. 3

3         Relationship to Existing APIs. 3

3.1      Java Message Service. 3

3.2      JAX-RPC.. 4

3.3      Internal Message Exchange. 4

4         Functional Description. 4

4.1      javax.jms.ConnectionFactory Extension. 5

4.2      javax.jms.Connection Extension. 5

4.3      javax.jms.Session Extension. 5

4.4      javax.jms.Message Extension. 6

4.4.1      Message Body. 6

4.4.1.1  SAAJMessage. 7

4.4.1.2  AxisMessage. 7

4.4.2      Message Headers. 8

4.4.3      Message Properties. 9

4.5      javax.jms.Destination Extension. 10

4.5.1      Features. 10

5         Outstanding Issues. 11

6         References. 11

 

1         Introduction

1.1      Disclaimer

Information contained herein is not finalized.  It is merely a proposal to generate review feedback early on during the scoping process.  A working knowledge of JMS, SAAJ, and JAX-RPC is a prerequisite for reading this document.  Please refer to the references section for related works.   

1.2      Purpose

Apache Axis provides robust support for synchronous style communications with RPC and document-oriented web services.  Support for asynchronous invocation, however, is a feature that is not available in the current release of Axis.  Goals of this proposal are documented in the list below.

  • Ability to receive unsolicited messages asynchronously from the client thus enabling Notification and Solicit/Response operation styles
  • Ability to perform work while the web service interaction is being processed
  • Ability to have multiple invocations outstanding from the same client thread
  • Ability to use different transports for inbound and outbound communications

1.3      Scope

The implementation of an asynchronous API that maps well to web service invocation semantics must resolve the following issues.  The proposed API addresses each of these issues in the sections below.

  • JAX-RPC does not define an asynchronous invocation model.  Therefore any solution that is not standards-based is proprietary and will not be immediately acceptable to the Axis community as a whole
  • Asynchronous programmers are already accustomed to the JMS API for messaging.  Learning an entirely new API for similar capabilities is not desirable.
  • Web service programmers are accustomed to using the JAX-RPC API for interaction with web services.  Once again, the path to achieving asynchronous web service interactions should be evolutionary and not revolutionary.
  • Asynchronous invocation requires the ability to correlate received messages with those that were sent previously.
  • Axis synchronous-style APIs should not change at all.  The asynchronous APIs should be separate from the widely-used JAX-RPC client API.
  • Failure semantics are more complicated in asynchronous invocation models because faults from the web service are not immediately propagated back to the sender.

1.4           Feature Overview

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.  The API does not replace the existing JAX-RPC or JAXM-style APIs that exist today in Axis.  Rather, the API coexists with the current APIs and should be used only where asynchronous interaction is desired.  The list below summarizes the features of this API.

  • Expose a blend of the JMS, SAAJ, and JAX-RPC API to the client to facilitate asynchronous interactions.  This API borrows the asynchronous invocation model from JMS and the web service information from JAX-RPC and SAAJ.
  • Extend the JMS interfaces where appropriate to describe a web service interaction. 

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.

2         Phased Delivery

The list below outlines a iterative development cycle that culminates in the full delivery of the Axis Asynchronous Client API that is addressed herein.  It is useful to note that this proposal attempts to specify tasks 1-5.  The WSDL extensions and server asynchronous API is the subject of a set of upcoming proposals.

  1. Generate all interfaces that comprise the API.  This can be accomplished without providing implementations of these interfaces.  The interfaces can be incorporated into Axis in the proposals directory.
  2. Implement MessageExchange interfaces for the target transports.  The MessageExchange interfaces provided by the org.apache.axis.ime package is a prerequisite for the proposed asynchronous functionality.
  3. Generate an implementation of the API the works with a subset of transports.  Transport selection in this phase will be based on inherent asynchronicity in the transport and the availability of a MessageExchange implementation.  Possible targets are JMS, SMTP, HTTP serveràHTTP server communication. 
  4. Convert remaining transports over to message exchange
  5. Deliver iteration 2 of the API that accounts for new transports.  This is necessary in order to compensate for any new features and API requirements that the recent transport implementations introduce.
  6. Scope and implement WSDL2Java changes to generate asynchronous stubs
  7. Scope and implement Server API

3         Relationship to Existing APIs

3.1      Java Message Service

The Asynchronous API is an implementation of a subset of the interfaces defined by the JMS 1.1 specification.  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.  This unification allows the interfaces defined herein to take advantage of domain agnostic capabilities without implying queue or topic-specific behavior.  The benefits of this approach are summarized in the list below.

  • Don’t reinvent the wheel – JMS defines a mature asynchronous client API that is well known to many developers
  • Reuse existing code – Existing JMS applications can be adapted to work with the Asynchronous API with minor changes.

The JMS interfaces have been extended, where appropriate, to provide SOAP-specific enhancements.  JMS constructs provide low level access to the content in textual or binary form.  In Axis, users are accustomed to high level access to Web Service constructs.  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.

3.2      JAX-RPC

JAX-RPC currently is the main mechanism to access synchronous-style Web Services through Axis.  None of the proposed changes modify this in any way.  The Asynchronous API is intended to coexist with JAX-RPC.  Furthermore, the API makes use of JAX-RPC defined methods and interfaces in its JMS extensions.  The list below summarizes the mapping of JMS constructs to JAX-RPC constructs.

  • ConnectionFactory à ServiceFactory
  • Connection à Service
  • Session à Call
  • Message à Invoke parameters, output parameters, return values, and faults

Clients may choose to use JAX-RPC for synchronous style invocations and the proposed API for asynchronous interaction as the application dictates.  Code that currently works with Axis’ Call API need not be modified when the Asynchronous APIs are included with Axis.  Furthermore, existing synchronous applications can reuse a good deal of code with applications targeted at the new API.

3.3      Internal Message Exchange

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.  The IME is the first step in achieving asynchronous style semantics throughout Axis.  The proposed API documented herein makes use of the IME interfaces to send and receive messages from the various transports.  Furthermore, the API uses the MessageExchange to provide correlation of outgoing requests with incoming responses. 

The Asynchronous API differs from the IME interfaces primarily in its target audience.  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.  Axis clients will directly make use of the client API to interact with web services using asynchronous style semantics.

The IME allows users to implement MessageExchange providers for individual transports.  Therefore the IME defines a pluggability API for transport implementations.  The API proposed herein, however, is transport agnostic.  A separate implementation is not required for individual transports.  The Asynchronous API is a single implementation that works with any transport or handler that supports the MessageExchange interfaces.

The inclusion of two separate APIs with asynchronous capabilities may be confusing to those familiar with the Axis internals.  It may be beneficial to merge the two APIs into a single set of interfaces for the sake of clarity and user accessibility.

4         Functional Description

The contents of this point out the high level issues and features associated with various aspects of the API.  The main reference for this content is the package of java interfaces that is included.  Please refer to the interfaces and examples for more information on the content presented below.

4.1      javax.jms.ConnectionFactory Extension

The AxisConnectionFactory is used to create AxisConnection instances.  The AxisConnection, discussed below, is used to interact with a particular web service.  An AxisConnectionFactory can be configured with a default wsdl location property and a service QName property.  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).  Furthermore, the implementation must be Serializable and Referenceable in order to allow for storage in a JNDI repository. 

It is useful to note that the wsdl location and service QName properties are merely the default values.  If the user requires connections to multiple web services they can pass the appropriate values into the createConnection methods.  Alternately, the user can reset these properties prior to connection creation.  The latter mechanism should only be used in a single-threaded execution as it is not thread-safe.  For multi-threaded access to multiple Web services use the appropriate createConnection method.

4.2      javax.jms.Connection Extension

            The AxisConnection represents a connection to the underlying web service or transport medium.  For transports that support connection semantics and lifecycle, the connection is used as a handle to the underlying MessageExchange.  Lifecycle method invocation is delegated down to transport implementations for all connection oriented transports.  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.  All delegation should be through the MessageExchange interfaces.  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.  The specification of connection support utilizes the feature mechanism detailed below.

            The AxisConnection is associated with a WSDL document and a particular service within the document.  Sessions are created through the AxisConnection and are associated with the service and WSDL document automatically at creation time.  Furthermore, the AxisConnection allows the session to be created that is associated with a particular port and operation name.  All WSDL associations are optional.  An AxisConnection can be created without any WSDL references thus enabling the user to setup the connection at runtime.

           

4.3      javax.jms.Session Extension

The AxisSession interface, constructed by the AxisConnection discussed above is the factory interface for MessageProducer, MessageConsumer, Destination, and Message implementations.  Furthermore it is responsible for maintaining operation state information applicable to all instances constructed from a particular session.

The factory functionality allows the Session to be used to create preconfigured messages, producers and consumers for a particular web service operation.  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.  The session is the primary mechanism of specifying the information about the operation that is being performed.  The following list contains the information that is settable in the session.  The APIs for setting these values will be borrowed from the existing Call and Service interfaces where appropriate. 

·        IN, OUT, and INOUT parameters

·        Operation Name

·        Operation Use and Style

·        Return type

·        SOAP Action Usage

·        Encoding Style

·        Type Mappings

·        Faults

These values can be automatically set if the session is associated with a particular port in a known WSDL document.  If no WSDL document and port is associated with a created session, the session allows explicit calls to methods to setup these values.

An alternative mechanism exists which allows the session to be used when the WSDL and service information is unknown.  The user can explicitly create SAAJMessage instances and use SAAJ APIs to dynamically construct the message content.  Although this mechanism involves more work on the part of the client code it allows for total control over the content of the message.

            The threading model of AxisSession instances is identical to that of JMS.  Sessions cannot be used concurrently by more than one thread.  This includes a restriction on concurrent access to any items created from this session as well.  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.  The reason for this is that the asynchronous listener mechanism creates an internal thread that controls message delivery.  Since this thread is controlled by the underlying framework, there is no mechanism to prevent concurrent access from client code.  This implies that asynchronous listeners should be used on a separate session than other producers.  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.

4.4      javax.jms.Message Extension

The Message interfaces provided with JMS 1.1 provide users with the ability to customize 3 forms of content; body, headers, and properties.  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. 

4.4.1      Message Body

JMS provides support for common message content types such as bytes, text, map, etc.  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.  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.  This is the approach taken in the proposed API.  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.  The proposed API includes a higher level message abstraction that provides web service specific content handling mechanisms.  This is encapsulated in the AxisMessage interface.

4.4.1.1  SAAJMessage

            The SAAJMessage is the base interface of all Message implementations defined herein.  It extends the SAAJ SOAPMessage abstract class and implements javax.jms.Message.  All messages in the proposed API inherit this capability from the SAAJMessage.  The SAAJMessage implementation can be explicitly created and used for SAAJ style message creation and delivery.  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.  For more information on the SAAJMessage please see the attached JavaDoc.

            The SAAJMessage can optionally be correlated with an associated message through the use of the set/getCorrelatedMessage functionality.  This association implies that delivery of the correlated Message caused this SAAJMessage instance to be delivered.  Correlation is required for all bidirectional operation styles such as request-response and solicit-response.  Oneway and notification operation styles are not correlated in this fashion.  Even in bidirectional operations, it is possible that the correlated message will be null.  This may occur when the request message is no longer available in memory due to system restart or timeout expiration.  It is up to the MessageExchange implementation to define correlation and persistence semantics.  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.  Client code should be written to tolerate a lack of correlated message or should provide its own persistence mechanism where appropriate.

4.4.1.2  AxisMessage

The AxisMessage provides access to content of a web service operation request or response through a generic Map-like interface.  This is similar in structure to that of WSIF message.  All parameters, return values, output parameters, and faults will be contained in an AxisMessage part.  For more information on the AxisMessage please see the attached JavaDoc.

The AxisMessage represents a call to a web service or an outbound call from a web service (i.e. a solicitation or notification).  The parameters that are being passed to the operation are the part content.  Each part represents an individual parameter.  The key for the parameter in the part map will be the parameter’s name.  The main usage pattern is to create an AxisMessage using the AxisSession as described above.  This message is preconfigured with a particular operation name, encoding style, output parameters, etc.  Once created, the client code sets the values for the in parameters on the request message and passes it to a producer for delivery.  If a response is required, as dictated by the WSDL for the service, it will be delivered using a MessageConsumer.  On inbound operations the usage pattern is to retrieve the parameters that were passed in by the web service.  If a response is required, an output message or fault can be created and sent back to the requester. 

The AxisMessage also represents the response from a particular invocation of a web service.  It provides a mechanism to get the return and output parameter values that are sent from the web service.  For solicit-response style interactions it provides clients with the ability to set these values.  The return value of an operation invocation must be included as the first part of the message.  Subsequent parts will be interpreted as output parameters.  The response AxisMessage instances should be correlated with the request message that generated them.

The AxisMessage is also used to pass back exception information to the requesting client.  It contains an AxisFault member that is accessible as the content of the first part.  It also contains a utility method containsFault() that allows a user to ascertain if a fault occurred.  The AxisFault contains all of the information that was received in the SOAPFault generated by the web service.  For solicit-response interactions, the AxisFault is set by the client and delivered back to the requesting web service. 

4.4.2      Message Headers

The JMS headers are defined by the JMS specification and are open to vendor extension.  They deal primarily with generic messaging concepts such as correlation and message identity, timestamp, priority, reply destinations, etc.  They are intended to be used in an application agnostic way to control the behavior of the messaging infrastructure.  The proposed API will interpret the invocation of header methods as defined in the list below.

·        CorrelationID – manifests itself as a SOAP header that contains a String or base64Binary value.  Mutation methods change the value of the header or create a new one if it exists.  In a response message this value will be the same as the MessageID of the request message that generated the response.  In a request message this value is undefined.

·        DeliveryMode – modified through the invocation of the send method of the MessageProducer.  Cannot be explicitly set on the message.  Calling getJMSDeliveryMode on a received message will return NON_PERSISTENT by default.  The transport implementation may explicitly set this value if supported.  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.

·        Destination – modified by the send method of MessageProducer.  Cannot be explicitly set on the message.  If getJMSDestination is called on a request message the value will be the default send destination of the AxisSession that created the message.  This is retrieved from the WSDL or explicitly set on the AxisSession as described above.  If getJMSDestination is called on a request message the value will be null.

·        Expiration –It is set through the MessageProducer’s send method.

·        MessageID – manifests itself as a SOAP header present in the message.  If the user explicitly sets this using a generated GUID or another mechanism, the SOAP header will be created and the value set.  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.  Subsequent calls to getJMSMessageID() will return this automatically generated value.

·        Priority - modified by the send method of MessageProducer.  Cannot be explicitly set on the message.  This results in the inclusion of a Soap header in the message.  If getJMSPriority is called on a request message the value will be the DEFAULT_PRIORITY.  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.

·        Redelivered – If the transport layer is able to ascertain if a particular message has been redelivered, this flag will be set.  In cases where redelivery has not occurred or the transport is unable to tell, the getter method will always return false. 

·        ReplyTo – The ReplyTo destination is deeply connected with the request/response mechanism.  It allows the receiver of a request to know the location that responses should be delivered to.  For synchronous communications mechanisms this is required because the response is passed back in the same channel as the request.  For all asynchronous transports the replyTo should be set by the caller.  It manifests itself as a Soap header with a URL as its content.  If the AxisSession that creates the MessageProducer knows the receive destination, the ReplyTo header will automatically be set on all outgoing messages.  If not, the replyTo destination must be explicitly set.

·        Timestamp – Can be set by the transport as a Soap header.  If this header is present its value will be returned.  Setting this header value has no effect.

·        Type – this is a Soap header with a String value.  It will be present in messages only if explicitly set by the user.

4.4.3      Message Properties

Message properties are a mechanism of passing contextual information along with the primary message content.  In some cases, this contextual information is the only message content.  The main benefit of using message properties as opposed to including information in body content is that selectors can be employed to manage subscriptions.  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.  For example, a prospective car buyer can subscribe to an endpoint where new car listings are posted.  Car buyers can be partitioned based on the amount they are willing to spend on a car.  Therefore, if the price were encoded as a message property, the subscribers could specify a selector such as “Price < 20000” to signify that only car listings that are priced at less than $20,000 are acceptable. 

Message properties in the proposed API are an optional feature of transports.  It is up to the transport implementation to specify that properties are explicitly supported.  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.  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.  Furthermore, properties may be supported but selectors may not be.  In these cases it would be possible to provide a client side selection implementation.  The details of such an implementation are out of the scope of this document.  For the sake of simplicity, the first implementation of this functionality will defer to the underlying transport for both property and selector support.  If either feature is missing, calls to set property will throw JMSException instances and calls to getProperty will always return null.

4.5      javax.jms.Destination Extension

JMS defines destinations as a queue or a topic, both of which are unsupported in the proposed API.  The reason for this is that both queues and topics imply a behavior that is inconsistent with web service interactions.  Therefore it is necessary to provide a mechanism to specify web service endpoint addresses as a JMS destination. 

JAX-RPC defines the target endpoint address as a String representing a URL.  Axis adds onto this approach by allowing the explicit creation of a Transport object and the association of said Transport with the Call instance.  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.  Users cannot modify the endpoint referenced in destinations; they must create a new one to reference a separate endpoint.  This restriction is consistent with the JMS API.

Destination instances are created through the AxisSession interface as discussed above.  Once created, the AxisDestination can be queried for a list of supported features and modifications to the enabled features can be made.  These feature modifications are delegated down to the underlying MessageExchange implementation of the transport. 

4.5.1      Features

            The behavior of the proposed API will be modified based on the capabilities, or features, of the underlying transport.  The mechanism for feature acquisition will make use of the MessageExchange interface provided by the IME.  MessageExhange implementations are able to provide a list of supported features using the getSupportedFeatures method.  This will be queried by the API when various features are requested.  The table below summarizes the features that the proposed API can take advantage of and the operations that depend on them.  This table of features is not finalized.  Development will most definitely uncover others.

Feature Name

Required by

org.apache.axis.async.PropertySupport

Any call to setProperty on AxisMessage

org.apache.axis.async.SelectorSupport

Calls to createConsumer that take in a message selector argument

org.apache.axis.async.ConnectionSupport

Signals that the creation of an AxisConnection will create an underlying connection in the transport implementation.  Any lifecycle actions carried out on the AxisConnection will be propagated to the underlying transport

org.apache.axis.async.DeliveryMode.Persistent

Any call to send on a MessageProducer that has the delivery mode set to PERSISTENT

org.apache.axis.async.DeliveryMode.NonPersistent

Any call to send on a MessageProducer that has the delivery mode set to NON_PERSISTENT

org.apache.axis.async.AcknowledgeSupport.Auto

Any call to createSession on the connection that asks for AUTO_ACKNOWLEDGE mode  ackMode

org.apache.axis.async.AcknowledgeSupport.Client

Any call to createSession on the connection that asks for CLIENT_ACKNOWLEDGE mode  ackMode

org.apache.axis.async.AcknowledgeSupport.Dups

Any call to createSession on the connection that asks for DUPS_OK_ACKNOWLEDGE mode  ackMode

org.apache.axis.async.TransactionSupport.Local

Any call to createSession on the connection that asks for a non-XA transacted session

org.apache.axis.async.TransactionSupport.XA

Any call to createSession on the connection that asks for a XA transacted session

Calls made to methods that utilize features that are unavailable in the underlying transport will throw a FeatureNotSupportedException.

5         Outstanding Issues

  • Axis Asynchronous Server API
  • Merge IME and Asynchronous API
  • WSDL2Java Mapping to allow asynchronous API usage
  • Investigate the applicability of ConnectionConsumer functionality in the asynchronous API.
  • JMS message mapping (i.e. what happens when a MapMessage is sent to the producer)
  • Transaction and reliability constraints

6         References

1.1 xml-axis/proposals/async_sonic/AxisAsyncClientAPI.zip <>