axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tom Jordahl <t...@macromedia.com>
Subject RE: JMS URL Syntax proposal
Date Tue, 05 Nov 2002 20:18:18 GMT

David,

This looks reasonable to my JMS-ignorant eyes.

Is the idea that the JMS URL would be embedded in WSDL as an address so a generated stub could
use the address without knowing it was a JMS transport?


--
Tom Jordahl
Macromedia Server Development



-----Original Message-----
From: David Chappell [mailto:chappell@sonicsoftware.com]
Sent: Friday, November 01, 2002 3:14 PM
To: axis-dev@xml.apache.org
Subject: Re: JMS URL Syntax proposal


Sorry, that last attachment was a little messed up.  Try this one
instead.
Dave


> David Chappell wrote:
> 
> The attached html doc contains a proposal for a URL syntax to be used
> by
> the Call object to pass JMS'isms down to the transport layer.  Among
> other things, this removes the necessity to call setTransport() in the
> client code in order to enable the JMS transport.  The details of the
> why and the how are included in the proposal.  Feel free to critique,
> or
> pass it along to your own resident JMS experts to have at it.
> Dave
> 
> --
> Sonic Software - Backbone of the Extended Enterprise
> --
> David Chappell <chappell@sonicsoftware.com> Office: (781)999-7099
> Mobile: (617)510-6566
> Vice President and Chief Technology Evangelist, Sonic Software
> co-author,"Java Web Services", (O'Reilly 2002)
> "The Java Message Service", (O'Reilly 2000)
> "Professional ebXML Foundations", (Wrox 2001)
> --
> 
>     ---------------------------------------------------------------
> 
> JMS URL Syntax For the Apache Axis Project
> 
> 
> 
> <author: Dave Chappell   chappell@sonicsoftware.com>
> 
> <author: Ray Chun           rchun@sonicsoftware.com>
> 
> <author: Jaime Meritt      jmeritt@sonicsoftware.com >
> 
> 
> 
> Summary
> 
> This is a proposal to define a URL syntax for use by the JMS transport
> layer in Axis.  The JMS URL syntax will allow a vendor-neutral way of
> specifying JMS specific details, like Topic and Queue destinations,
> without having to code them specifically into the client application,
> or pass them from a command line.
> 
> 
> 
> Backgrounder
> 
> When one uses the JMS transport layer, it is hidden underneath the
> client API of Axis.  Axis implements the JAX-RPC API. JAX-RPC (and
> Axis) provides multiple models for constructing both static and
> dynamic invocations of a service.   There are 2 flavors of dynamic
> invocation using the Call and Stub interface, and a static model using
> a WSDL2Java stub generation.  Both the Call and Stub interfaces allow
> the use of application-specific properties that get passed down to the
> handlers, including the transport handler.
> 
> 
> 
> Currently the model in 1.0 Axis is to specify the JMS specific
> properties from the command line, or in a properties file.  The client
> application then obtains these and places the JMS specific properties
> into the Call object by calling the setProperty() method.   The
> properties are then passed on to the transport handler, where they are
> extracted and used to perform the appropriate actions in JMS
> nomenclature.  Examples of JMS specific properties are location of a
> ConnectionFactory object, the name of a JMS destination, the type of
> destination (topic or queue), username and password, and message
> delivery options such as persistence.
> 
> 
> 
> Example:
> 
> 
> 
> Service  service = new Service(new XMLStringProvider(wsdd));
> 
> 
> 
> // create the JMS transport
> 
> JMSTransport transport = new JMSTransport(connectorMap, cfMap);
> 
> 
> 
> // create a new Call object
> 
> Call     call    = (Call) service.createCall();
> 
> 
> 
> // populate the call object.  In this case it's a method
> 
> // invocation with a description of the parameter list and
> 
> // the return type.
> 
> call.setOperationName( new QName("urn:xmltoday-delayed-quotes",
> 
>                                        "getQuote") );
> 
> call.addParameter( "symbol",
> 
>                    XMLType.XSD_STRING,
> 
>                    ParameterMode.IN );
> 
> call.setReturnType( XMLType.XSD_FLOAT );
> 
> 
> 
> 
> 
> // set the transport object
> 
> call.setTransport(transport);
> 
> 
> 
> // set some properties.  These will get passed down into the
> 
> // handlers, including the transport handler.
> 
> call.setUsername(username );
> 
> call.setPassword(password );
> 
> call.setProperty(JMSConstants.WAIT_FOR_RESPONSE, Boolean.FALSE);
> 
> call.setProperty(JMSConstants.PRIORITY, new Integer(5));
> 
> call.setProperty(JMSConstants.DELIVERY_MODE,
> 
> new Integer(javax.jms.DeliveryMode.PERSISTENT));
> 
> call.setProperty(JMSConstants.TIME_TO_LIVE, new Long(20000));
> 
> 
> 
> call.setProperty(JMSConstants.DESTINATION, destination);
> 
> 
> 
> ...
> 
> 
> 
> // invoke the call
> 
> res = (Float) call.invoke(...);
> 
> 
> 
> 
> 
> While the current model works well, the ease of plugging in the JMS
> transport can be made much more tenable by being able to specify
> everything in a URL encoding.  The goal is to eliminate the need to do
> anything special in the client application.
> 
> 
> 
> URL Syntax
> 
> Rather than inventing a rigid syntax, it is desirable to use a
> URL-encoded query string in accordance with RFC-1738.  The intent is
> to specify a minimal syntax, allowing for the most flexibility for
> different JMS providers.
> 
> Proposed syntax:  jms:<vendor-uri>:*
> 
> The vendor-uri dictates how the remainder of the URL is encoded.  If
> the vendor-uri is omitted, then secondary lookup of the
> 'connectionfactory' and 'destination' properties is performed using
> JNDI.
> 
> 
> 
> Examples
> 
> Using Sonic:
> 
> With a host and port: jms:<vendor-uri>://host:port/domain?etc...
> 
> 1. jms:sonicmq://localhost:2506/queue?destination=SampleQ1
> 
> With a slightly modified syntax: jms:<vendor-uri>:<domain>:*
> 
> 2. jms:sonicmq:queue://localhost:2506?destination=SampleQ1
> 
> 3.
> jms:sonicmq:queue;brokerurl1=url1;brokerurl2=url2;destination=SampleQ1
> 
> 
> 
> Using JNDI:
> 
> 1. jms:jndi-uri://queue/MyQCF/MyQ?jmspriority=5&...
> 
> 2. jms:jndi-uri://ldap.somewhere.com/queue?initialcontextfactory=icf&
> connectionfactory=MyCF&..
> 
> 3. jms::queue;connectionfactory=MyQCF;destination=MyQ;...
> 
> 
> 
> Alternative syntax:  jms://<vendor-uri>/any...
> 
> Again, omitting a vendor-uri and thus specifying the URL with
> "jms:///..." will by default use JNDI as the secondary lookup.
> 
> 
> 
> Examples
> 
> 1. jms://sonicmq/queue?brokerurl=localhost:2506&destination=SampleQ1&...
> 
> 2. jms:///queue?connectionfactory=MyQCF&destination=MyQ&...
> 
> 3. jms:///queue/MyQCF/MyQ?jmspriority=5...
> 
> 
> 
> The connection factory and destination are string properties that may
> map to a JNDI lookup name.  If the JMS provider supports direct
> instantiation of a CF class, or a named destination, then that is
> allowable as well.  As far as the client application is concerned, the
> CF and destination are just string properties, and the underlying
> implementation of the transport can decide whether or not to use JNDI.
> 
> 
> 
> JMS Properties
> 
> Properties that appear in the query string may be overridden by
> explicitly setting the property via call.setProperty(..).  For
> instance, the username and password, though optional parameters in the
> query string, will likely be specified using the call object's
> setUsername() and setPassword() methods.
> 
> 
> 
> In the short term, the scope of what can be set in the query-string is
> limited to the perspective of  a JMS sender.  The following table
> illustrates the possible settings in the query string.  Depending on
> the syntax chosen, some properties may be set implicitly in the URL
> (for instance, the domain in 'jms:queue:jndi-uri...' is specified
> without a property key).
> 
> 
> 
> Property Name         Example Value                               Comments
> 
> InitialContextFactory "com.sun.jndi.fscontext.RefFSContextFactory"If the secondary
>                                                                   lookup is JNDI
>                       "com.sun.jndi.ldap.LdapCtxFactory"
> JNDIURL               "file:///JNDIStore"                         ""
> 
>                       "ldap://localhost:123"
> ConnectionFactory     "MyCF",                                     May be JNDI lookup
>                       "com.JMSVendor.TopicConnectionFactory"      name or fully
>                                                                   qualified class
>                                                                   name
> Host                  "localhost"                                 May be required by
>                                                                   CF
> Port                  "2506"                                      ""
> Destination           "MyQueue"                                   May be JNDI lookup
>                                                                   name or direct
>                                                                   destination name
> DestinationType or    "Topic" or "Queue"                          Indicates the type
> Domain                                                            of connection
>                                                                   factory and
>                                                                   destination
> ReplyToDestination    "ReplyToQueue"                              May be JNDI lookup
>                                                                   name or direct
>                                                                   destination name
> Username                                                          Required in JMS to
>                                                                   establish a
>                                                                   Connection object
> Password                                                          Required in JMS to
>                                                                   establish a
>                                                                   Connection object
> DeliveryMode          "Persistent", "non-persistent"
> TTL                   "10000"                                     Time-to-live in
>                                                                   milliseconds.
> Priority              0 - 9, in accordance with JMS spec          Message priority
> WAIT_FOR_RESPONSE     "Yes"                                       Can be used in
>                                                                   conjunction with
>                                                                   call.setTimeout()?
> 
> 
> 
> In the not-too-distant future, we will have asynchronous callback
> support and client notification in the client engine and the client
> API.  When this is enabled, we will need to be able to specify a
> listener and listener traits in the query-string.   This is likely to
> change as we evolve the API.  The following table lists the possible
> values:
> 
> 
> 
> Property Name          Example Value             Comments
> 
> 
> ListenerAction         "Subscribe","Unsubscribe",The existence of the
>                                                  ListenerAction
>                        "Open","Close","Retrieve",indicates that a
>                                                  listener should be
>                        "Acknowledge"             created, destroyed,
>                                                  or retrieved from.
>                                                  "Acknowledge" is a
>                                                  special case for
>                                                  CLIENT_ACKNOWLEDGE
>                                                  mode.
> DurableSuscriptionName                           Required to uniquely
>                                                  identify a durable
>                                                  subscription.
>                                                  Specifying this
>                                                  obviates the need to
>                                                  have a separate
>                                                  "durable" setting.
> AcknowledgeMode        "Client","Auto","DUPS_OK"
> 
> 
> 
> 
> 
> The use of a URL to specify properties of a listener is unusual in
> that not all things have a parallel on the send side.  In the send
> scenario, there is only one action to consider-send.  From the
> receiver's perspective, there are separate steps beyond creating a
> listener like deleting a durable subscription (Unsubscribe), and
> explicit acknowledgement of receipt for CLIENT_ACKNOWLEDGE and DUPS_OK
> mode.  An empty Call object could be created with just the URL
> containing the action.  The action could be performed using
> Call.invoke().  In the case of "ListenerAction=Unsubscribe" this would
> not actually invoke anything.  It would simply be a command to tell
> the transport layer to unsubscribe.  When we enhance the API for
> client we will have a more direct way to do this.
> 
> 
> 
> Example: URL-based JMS transport
> 
> Service  service = new Service(new XMLStringProvider(wsdd));
> 
> 
> 
> // create a new Call object
> 
> Call     call    = (Call) service.createCall();
> 
> 
> 
> // populate the call object.  In this case it's a method
> 
> // invocation with a description of the parameter list and
> 
> // the return type.
> 
> call.setOperationName( new QName("urn:xmltoday-delayed-quotes",
> 
>                                  "getQuote") );
> 
> call.addParameter( "symbol",
> 
>                    XMLType.XSD_STRING,
> 
>                    ParameterMode.IN );
> 
> call.setReturnType( XMLType.XSD_FLOAT );
> 
> 
> 
> // set the jms url
> 
> String sampleJmsUrl = "jms:sonicmq://localhost:2506?
> 
>                       "destination=SampleQ1" +
> 
>                       "&deliverymode=persistent" +
> 
>                       "&priority=5" +
> 
>     "&timetolive=10000";
> 
> call.setTargetEndpointAddress(new java.net.URL(sampleJmsUrl));
> 
> 
> 
> // setting properties explicitly is still supported
> 
> // these override properties specified in the url
> 
> call.setUsername(username );
> 
> call.setPassword(password );
> 
> call.setProperty(JMSConstants.TIME_TO_LIVE, new Long(20000));
> 
> 
> 
> ...
> 
> 
> 
> // invoke the call
> 
> res = (Float) call.invoke(...);
> 
> 
> 
> 
> 
> Note that the call to set the JMSTransport is no longer required, as
> the appropriate transport will be selected based on the protocol
> specified in the endpoint address.
> 
> 
> 
> Issues:
> 
> 
> 
> -         Lifecycle.  With references to JMSTransport no longer
> necessary, how will the client application dictate lifecycle?  Via
> commands passed in with the send?
> 
> -         How does one check the JMSRedelivered property on receipt of
> a message?  JMS properties table in call object?
> 
> Futures:
> 
> 
> 
> -         Transaction support
> 
> 
> 
> 

-- 
Sonic Software - Backbone of the Extended Enterprise
--
David Chappell <chappell@sonicsoftware.com> Office: (781)999-7099
Mobile: (617)510-6566
Vice President and Chief Technology Evangelist, Sonic Software
co-author,"Java Web Services", (O'Reilly 2002)
"The Java Message Service", (O'Reilly 2000)
"Professional ebXML Foundations", (Wrox 2001)
--

Mime
View raw message