Author: veithen
Date: Wed Apr 8 21:41:00 2009
New Revision: 763411
URL: http://svn.apache.org/viewvc?rev=763411&view=rev
Log:
Converted the JMS documentation from XDoc to APT.
Added:
webservices/commons/trunk/modules/transport/src/site/apt/jms.apt
Removed:
webservices/commons/trunk/modules/transport/src/site/xdoc/jms.xml
Added: webservices/commons/trunk/modules/transport/src/site/apt/jms.apt
URL:
http://svn.apache.org/viewvc/webservices/commons/trunk/modules/transport/src/site/apt/jms.apt?rev=763411&view=auto
==============================================================================
--- webservices/commons/trunk/modules/transport/src/site/apt/jms.apt (added)
+++ webservices/commons/trunk/modules/transport/src/site/apt/jms.apt Wed Apr 8
21:41:00 2009
@@ -0,0 +1,187 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+JMS Transport
+
+* {Content}
+
+%{toc|section=1|fromDepth=1}
+
+* {Transport configuration}
+
+ Sample axis2.xml:
+
++----------------------------+
+ <transportReceiver name="jms"
class="org.apache.axis2.transport.jms.JMSListener">
+ <parameter name="myTopicConnectionFactory" locked="false">
+ <parameter name="java.naming.factory.initial"
locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter>
+ <parameter name="java.naming.provider.url"
locked="false">tcp://localhost:61616</parameter>
+ <parameter name="transport.jms.ConnectionFactoryJNDIName"
locked="false">TopicConnectionFactory</parameter>
+ </parameter>
+ <parameter name="myQueueConnectionFactory" locked="false">
+ <parameter name="java.naming.factory.initial"
locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter>
+ <parameter name="java.naming.provider.url"
locked="false">tcp://localhost:61616</parameter>
+ <parameter name="transport.jms.ConnectionFactoryJNDIName"
locked="false">QueueConnectionFactory</parameter>
+ </parameter>
+ <parameter name="default" locked="false">
+ <parameter name="java.naming.factory.initial"
locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter>
+ <parameter name="java.naming.provider.url"
locked="false">tcp://localhost:61616</parameter>
+ <parameter name="transport.jms.ConnectionFactoryJNDIName"
locked="false">QueueConnectionFactory</parameter>
+ </parameter>
+ </transportReceiver>
++----------------------------+
+
+ If a connection factory named "default" (as shown above) is defined, this
would be used for services which does
+ not explicitly specify the connection factory that should be used. The
services.xml of a service should indicate
+ the connection factory and the destination name to be associated with. If
a destination is not specified, the
+ implementation would create a JMS Queue with the service name. The JMS
destination should ideally be created
+ and administered through the JMS provider utilities.
+
+* {Service configuration}
+
+ [transport.jms.ConnectionFactory (Optional)]
+ The JMS connection factory definition (from axis2.xml) to be used to
+ listen for messages for this service.
+
+ [transport.jms.Destination (Optional)]
+ The JMS destination name (Defaults to a Queue with the service name).
+
+ [transport.jms.DestinationType (Optional)]
+ The JMS destination type. Accept values 'queue' or 'topic' (default: queue).
+
+ [transport.jms.ReplyDestination (Optional)]
+ The destination where a reply will be posted.
+
+ [transport.jms.ContentType (Optional)]
+ Specifies how the transport listener should determine the content type of
received messages.
+ This can either be a simple string value, in which case the transport
listener assumes that
+ the received messages always have the specified content type, or a set of
rules as in the following example:
+
++--------------------------------------------+
+<parameter name="transport.jms.ContentType">
+ <rules>
+ <jmsProperty>contentType</jmsProperty>
+ <jmsProperty>ctype</jmsProperty>
+ <default>text/xml</default>
+ </rules>
+</parameter>
++--------------------------------------------+
+
+ The rules are evaluated in turn until the first matches. The following rule
types are defined:
+
+ [jmsProperty]
+ Extract the content type from the specified message property.
+
+ [bytesMessage\
+ textMessage]
+ Match the corresponding message type. The content type is specified as the
value of
+ the rule, e.g. <<<\<bytesMessage\>binary/octet-stream\</bytesMessage\>>>>
+
+ [default]
+ Defines the default content type. This rule always matches and should
therefore
+ be the last rule in the rule set.
+
+ If none of the rules matches, an error is triggered and the message is not
processed.
+ The default value for this property corresponds to the following set of
rules:
+
++--------------------------------------------+
+<parameter name="transport.jms.ContentType">
+ <rules>
+ <jmsProperty>Content-Type</jmsProperty>
+ <bytesMessage>application/octet-stream</bytesMessage>
+ <textMessage>text/plain</textMessage>
+ </rules>
+</parameter>
++--------------------------------------------+
+
+ This choice preserves compatibility with previous versions of the JMS
transport. Note however
+ that "Content-Type" is not a valid JMS property name and will not work with
some JMS providers.
+
+ [Wrapper (Optional)]
+ The wrapper element for pure text or binary messages. Note that this
parameter is
+ actually not JMS specific but recognized by the message builders for
text/plain and
+ application/octet-stream (which are the respective default content types for
JMS text
+ and binary messages).
+
+ []
+
+ Sample services.xml:
+
++--------------------------------------------+
+<service name="echo">
+ <transports>
+ ....
+ <transport>jms</transport>
+ </transports>
+ ...
+ <parameter name="transport.jms.ConnectionFactory"
locked="true">myTopicConnectionFactory</parameter>
+ <parameter name="transport.jms.Destination"
locked="true">dynamicTopics/something.TestTopic</parameter>
+</service>
++--------------------------------------------+
+
+* {Endpoint references}
+
++--------------------------------------------+
+jms-epr = "jms:/" jms-dest [ "?" param *( [ "&" param ] ) ]
+param = param-name "=" param-value
++--------------------------------------------+
+
+ [transport.jms.ConnectionFactoryJNDIName]
+ TODO
+
+ [transport.jms.DestinationType]
+ TODO
+
+ [transport.jms.ReplyDestination]
+ TODO
+
+ [transport.jms.ReplyDestinationType]
+ TODO
+
+ [transport.jms.ContentTypeProperty]
+ The name of the message property to store the content type of messages sent
to the endpoint.
+
+ [java.naming.factory.initial]
+ TODO
+
+ [java.naming.provider.url]
+ TODO
+
+ [java.naming.security.principal]
+ TODO
+
+ [java.naming.security.credentials]
+ TODO
+
+* {Content type detection}
+
+ [Incoming requests]
+ The content type of the message is determined according to the settings
specified in
+ the <<<transport.jms.ContentType>>> service parameter.
+
+ [Outgoing responses]
+ If the content type of the request was determined using the value of a
message property, the
+ content type of the response will stored in the same message property.
+
+ [Outgoing requests]
+ The content type will be stored in the message property specified by
+ the <<<transport.jms.ContentTypeProperty>>> message context property or
+ the <<<transport.jms.ContentTypeProperty>>> parameter of the endpoint
reference.
+
+ [Incoming responses]
+ The content type will be extracted from the message property that was used to
+ store the content type of the outgoing request.
