+++ /dev/null
-~~ 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}
-
- Connection factories are configured using parameters in the transport description in
- <<<axis2.xml>>>. The syntax is the same for the transport listener and sender. For example,
- the following configuration sets up the JMS listener with three connection factories:
-
-+----------------------------+
-<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.
-
- For the JMS sender, only the outer element is different:
-
-+----------------------------+
-<transportSender name="jms" class="org.apache.axis2.transport.jms.JMSSender">
- ...
-</transportSender>
-+----------------------------+
-
- As explained below, for the JMS sender configuration it is not mandatory (but recommended) to specify
- connection factories.
-
- The parameters that may appear in a connection factory configuration are defined as follows:
-
- [<<<java.naming.factory.initial>>>]
- REQUIRED - JNDI initial context factory class. The class must implement the java.naming.spi.InitialContextFactory interface.
-
- [<<<java.naming.provider.url>>>]
- REQUIRED - URL of the JNDI provider
-
- [<<<transport.jms.ConnectionFactoryJNDIName>>>]
- REQUIRED - The JNDI name of the connection factory
-
- [<<<java.naming.security.principal>>>]
- JNDI Username
-
- [<<<java.naming.security.credentials>>>]
- JNDI password
-
- [<<<transport.Transactionality>>>]
- Desired mode of transactionality. possible values are 'none', 'local' or 'jta', while it defaults to 'none'
-
- [<<<transport.UserTxnJNDIName>>>]
- JNDI name to be used to require user transaction
-
- [<<<transport.CacheUserTxn>>>]
- Whether caching for user transactions should be enabled or not. Possible values are 'true' or 'false', while the value defaults to 'true'
-
- [<<<transport.jms.SessionTransacted>>>]
- Whether the JMS session be transacted or not. Possible values are 'true' or 'false', while the value defaults to 'true' if the transactionality is 'local'
-
- [<<<transport.jms.SessionAcknowledgement>>>]
- JMS session acknowledgement mode. Possible values are AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE, SESSION_TRANSACTED. Default value is AUTO_ACKNOWLEDGE
-
- [<<<transport.jms.ConnectionFactoryType>>>]
- Type of the connection factory. Possible values are 'queue' or 'topic' while the default value of 'queue'
-
- [<<<transport.jms.JMSSpecVersion>>>]
- JMS API version. Possible values are 1.1 or 1.0.2b, and the default API version is 1.1
-
- [<<<transport.jms.UserName>>>]
- The JMS connection username
-
- [<<<transport.jms.Password>>>]
- The JMS connection password
-
- [<<<transport.jms.DefaultReplyDestination>>>]
- JNDI name of the default reply destination
-
- [<<<transport.jms.DefaultReplyDestinationType>>>]
- Default type of the reply destination, if not provided the destination type will be taken as the reply destination type as well
-
- [<<<transport.jms.MessageSelector>>>]
- Message selector implementation
-
- [<<<transport.jms.SubscriptionDurable>>>]
- Whether the connection factory is subscription durable or not. Possible values are 'true' or 'false', while the value defaults to 'false'
-
- [<<<transport.jms.DurableSubscriberName>>>]
- Name of the durable subscriber. This is required if the above parameter is set to 'true'
-
- [<<<transport.jms.PubSubNoLocal>>>]
- Whether the messages should be published by the same connection they were received. Possible values are 'true' or 'false', while the value defaults to 'false'
-
- [<<<transport.jms.CacheLevel>>>]
- JMS resource cache level. Possible values are 'none', 'connection', 'session', 'consumer', 'producer', 'auto' and defaults to 'auto'
-
- [<<<transport.jms.ReceiveTimeout>>>]
- Time to wait for a JMS message during polling. Set this parameter value to a negative integer to wait indefinitely. Set to zero to prevent waiting and the default value is 1000ms
-
- [<<<transport.jms.ConcurrentConsumers>>>]
- Number of concurrent threads to be started to consume messages when polling. Defaults to 1, and the value should be a positive integer. For topics it has to be always 1
-
- [<<<transport.jms.MaxConcurrentConsumers>>>]
- Maximum number of concurrent threads to use during polling. Defaults to 1, and the value should be a positive integer. For topics it has to be always 1
-
- [<<<transport.jms.IdleTaskLimit>>>]
- The number of idle runs per thread before it dies out, which defaults to 10
-
- [<<<transport.jms.MaxMessagesPerTask>>>]
- The maximum number of successful message receipts per thread. Defaults to -1 meaning the infinity
-
- [<<<transport.jms.InitialReconnectDuration>>>]
- Initial reconnection attempts duration in milliseconds, which defaults to 1000ms
-
- [<<<transport.jms.ReconnectProgressFactor>>>]
- Factor by which the reconnection duration will be increased, which defaults to 2.
-
- [<<<transport.jms.MaxReconnectDuration>>>]
- Maximum reconnection duration in milliseconds, which defaults to 3600000ms (1 hr)
-
-* {Transport listener}
-
-** {JMS connections and message dispatching}
-
- Every deployed service for which the JMS transport is enabled will be associated with a
- destination (queue or topic) according to the following rules:
-
- * If the service has a <<<transport.jms.Destination>>> parameter, its value is interpreted
- as the JNDI name of the destination.
-
- * Otherwise the service name is used as the JNDI name of the destination.
-
- At the same time, the connection factory is determined by looking at the service parameter
- <<<transport.jms.ConnectionFactory>>>. If this parameter is not set, the default value
- <<<default>>> is assumed. The value of this parameter is interpreted as a logical identifier
- for the connection factory configuration defined in the transport configuration (see above).
-
- It follows that JMS destinations are statically bound to services. Therefore the transport
- always predispatches incoming messages to the service the destination is bound to.
-
- The message is dispatched to an operation according to the following rules:
-
- * The transport looks for a service parameter <<<Operation>>>. If this parameter is not present,
- the default value <<<urn:mediate>>> is assumed.
-
- * If the service has an operation with the corresponding name, the transport predispatches
- the message to that operation.
-
- * If no such operation exists, the message will be dispatched by the Axis2 engine using the
- configured dispatchers.
-
- In addition, if the JMS message has a property named <<<SOAPAction>>>, the value of this property
- is interpreted as the SOAP action.
-
-** {Service configuration}
-
- Apart from the following list most of the parameters defined in the global connection factory can be overriden at the service level as well
-
- [<<<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>
-+--------------------------------------------+
-
-** {Message context properties for incoming messages}
-
- For incoming messages, the transport listener will make the following properties available in
- the message context:
-
- [<<<TRANSPORT_HEADERS>>>]
- This property will contain a map with the JMS message properties.
-
-* {Transport sender}
-
-** {Endpoint references}
-
- Endpoint references for the JMS transport must have the following form:
-
-+--------------------------------------------+
-jms-epr = "jms:/" jms-dest [ "?" param *( [ "&" param ] ) ]
-param = param-name "=" param-value
-+--------------------------------------------+
-
- <<<jms-dest>>> is the JNDI name of the destination to send the message to. The parameters are
- defined as follows:
-
- [<<<transport.jms.ConnectionFactory>>> (Optional)]
- The JMS connection factory definition (from <<<axis2.xml>>>) to be used to send messages to
- the endpoint.
-
- [<<<transport.jms.ContentTypeProperty>>>]
- The name of the message property to store the content type of messages sent to the endpoint.
-
- All the above listed parameters under the connection factory configuration are applied to the JMS EPR as well, apart from these.
-
- If no connection factory definition is explicitly specified using the
- <<<transport.jms.ConnectionFactory>>> parameter, the JMS sender will check if the transport
- configuration contains a connection factory compatible with the other settings specified in the
- endpoint URL (<<<transport.jms.ConnectionFactoryJNDIName>>>, <<<java.naming.factory.initial>>>,
- <<<java.naming.provider.url>>>, <<<java.naming.security.principal>>> and
- <<<java.naming.security.credentials>>>). If a matching configuration is found, the
- sender will reuse the cached JMS objects related to that configuration. Otherwise it will
- execute the JNDI lookup and open a new connection. In that case the connection will be closed
- immediately after sending the message.
-
-** {Message context properties for outcoming messages}
-
- For outgoing messages, the transport sender will recognize the following message context
- properties:
-
- [<<<TRANSPORT_HEADERS>>>]
- The transport expects a map as value for this property. The entries of this map will be
- set as properties on the outgoing JMS message.
-
- Note that all the properties are optional.
-
-* {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.
+++ /dev/null
-~~ 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.
-
-TCP Transport
-
-* {Content}
-
-%{toc|section=1|fromDepth=1}
-
-* {Transport listener}
-
-** {Listener configuration}
-
- The TCP transport listener is configured in <<<axis2.xml>>> using the following declaration:
-
-+----------------------------+
-<transportReceiver name="tcp" class="org.apache.axis2.transport.tcp.TCPTransportListener"/>
-+----------------------------+
-
- Depending on how the TCP transport is set up, additional parameters may be required inside the
- <<<transportReceiver>>> element (see next section).
-
-** {Endpoint configuration}
-
- Endpoints can be configured both at the transport level and at the service level. Each endpoint
- opens a TCP server socket for listening. TCP requests received on a port that is configured on a
- service will be pre-dispatched to that service. Packets received by a port that is configured
- at the transport level need to be dispatched using one of the following mechanisms:
-
- [[1]] Using the namespace URI of the first child element of SOAPBody
- (SOAPMessageBodyBasedDispatcher).
-
- [[2]] Using WS-Addressing headers (SOAPActionBasedDispatcher).
-
- Endpoints are configured by adding <<<parameter>>> elements to the <<<transportReceiver>>>
- element in <<<axis2.xml>>> or to a <<<service>>> element in an <<<services.xml>>> file. The
- set of parameters is the same for both scenarios:
-
- [<<<transport.tcp.port>>> (required)]
- The port number over which the TCP server socket should be opened.
-
- [<<<transport.tcp.hostname>>> (optional)]
- The hostname to which the TCP server socket should be bound.
-
- [<<<transport.tcp.contentType>>> (optional, defaults to text/xml)]
- Specifies the content type of the messages received on the endpoint.
-
- [<<<transport.tcp.backlog>>> (optional, defaults to 50)]
- The length of the backlog (queue) supported by the TCP server socket.
-
-* {Transport sender}
-
- The TCP transport sender can be enabled in <<<axis2.xml>>> using the following declaration:
-
-+----------------------------+
-<transportSender name="tcp" class="org.apache.axis2.transport.tcp.TCPTransportSender"/>
-+----------------------------+
-
-* {Examples}
-
-** {Enabling TCP listener at the transport level}
-
- The following declaration in <<<axis2.xml>>> initializes a TCP server socket on port 6060
- and allows all services (for which TCP is in the list of exposed transports) to receive
- messages over that port:
-
-+----------------------------+
-<transportReceiver name="tcp" class="org.apache.axis2.transport.tcp.TCPTransportListener">
- <parameter name="transport.tcp.port">6060</parameter>
-</transportReceiver>
-+----------------------------+
-
- For this to work, WS-Addressing must be enabled, and messages sent to port 6060 must
- have the relevant WS-Addressing headers.
-
-+----------------------------+
-<module ref="addressing"/>
-+----------------------------+
-
- With the configuration shown above, the TCP transport would generate bindings with the
- following EPR:
-
-+----------------------------+
-tcp://localhost:6060/services/Version?contentType=text/xml
-+----------------------------+
-
- Similar EPRs will be generated for services when the transport is configured at service
- level.
-
- The following example shows a message that can be sent to the Version service over TCP:
-
-+----------------------------+
-<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
- xmlns:wsa="http://www.w3.org/2005/08/addressing">
- <SOAP-ENV:Header>
- <wsa:MessageID>1234</wsa:MessageID>
- <wsa:To>tcp://localhost:6060/services/Version?contentType=text/xml</wsa:To>
- <wsa:Action>urn:getVersion</wsa:Action>
- </SOAP-ENV:Header>
- <SOAP-ENV:Body>
- </SOAP-ENV:Body>
-</SOAP-ENV:Envelope>
-+----------------------------+
-
- Axis2 client API can be used to easily send TCP requests to a remote service.
- The following code snippet shows how to do that. The TCP transport sender
- must be enabled in the <<axis2.xml>> in order for this to work.
-
-+------------------------------------------------------+
-
-String url = "tcp://localhost:6060/services/Version?contentType=text/xml";
-OMElement payload = ...
-
-ServiceClient serviceClient = new ServiceClient();
-Options options = new Options();
-EndpointReference targetEPR = new EndpointReference(url);
-options.setTo(targetEPR);
-serviceClient.setOptions(options);
-OMElement response = serviceClient.sendReceive(payload);
-+------------------------------------------------------+
-
- The transport sender that should be invoked is inferred from the targetEPR
- (tcp://...). In this case it is TCP and the listener is also TCP. The SOAP
- message has to be self contained in order to use Addressing.
- The parameter is of the type OMElement, the XML representation of Axis2.
-
- A TCP URL may contain an optional timeout value, as a query parameter, to
- indicate how long (in milliseconds) the client should wait for a response.
- Once this period has expired, the client TCP socket will timeout:
-
-+----------------------------+
-tcp://localhost:6060/services/Version?contentType=text/xml&timeout=10000
-+----------------------------+
-
- If the Axis2 client API is used to send a request to the above URL, the client
- socket will timeout after waiting for 10 seconds, for the response.
\ No newline at end of file
+++ /dev/null
-~~ 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.
-
-UDP Transport
-
-* {Content}
-
-%{toc|section=1|fromDepth=1}
-
-* {Transport listener}
-
-** {Listener configuration}
-
- The UDP transport listener is configured in <<<axis2.xml>>> using the following declaration:
-
-+----------------------------+
-<transportReceiver name="udp" class="org.apache.axis2.transport.udp.UDPListener"/>
-+----------------------------+
-
- Depending on how the UDP transport is set up, additional parameters may be required inside the
- <<<transportReceiver>>> element (see next section).
-
-** {Endpoint configuration}
-
- Endpoints can be configured both at the transport level and at the service level. Each endpoint
- opens a local UDP port for listening. UDP packets received on a port that is configured on a
- service will be pre-dispatched to that service. Packets received by a port that is configured
- at the transport level need to be dispatched using WS-Addressing or some other mechanism
- implemented by a dispatcher configured in Axis2.
-
- Endpoints are configured by adding <<<parameter>>> elements to the <<<transportReceiver>>>
- element in <<<axis2.xml>>> or to a <<<service>>> element in an <<<services.xml>>> file. The
- set of parameters is the same for both scenarios:
-
- [<<<transport.udp.port>>> (required)]
- Specifies the UDP port to bind to.
-
- [<<<transport.udp.contentType>>> (required)]
- Specifies the content type of the messages received on the endpoint. This parameter is
- necessary because in contrast to HTTP, the content type information is not part of the
- information exchanged on the wire.
-
- [<<<transport.udp.maxPacketSize>>> (optional, defaults to 1024)]
- The maximum UDP packet size.
-
-* {Transport sender}
-
- The UDP transport sender can be enabled in <<<axis2.xml>>> using the following declaration:
-
-+----------------------------+
-<transportSender name="udp" class="org.apache.axis2.transport.udp.UDPSender"/>
-+----------------------------+
-
-* {Examples}
-
-** {Enabling SOAP over UDP at the transport level}
-
- The following declaration in <<<axis2.xml>>> enables SOAP over UDP on port 3333 and
- allows all services (for which UDP is in the list of exposed transports) to receive
- messages over that port:
-
-+----------------------------+
-<transportReceiver name="udp" class="org.apache.axis2.transport.udp.UDPListener">
- <parameter name="transport.udp.port">3333</parameter>
- <parameter name="transport.udp.contentType">text/xml</parameter>
- <parameter name="transport.udp.maxPacketSize">4096</parameter>
-</transportReceiver>
-+----------------------------+
-
- For this to work, WS-Addressing must be enabled, and messages sent to port 3333 must
- have the relevant WS-Addressing headers.
-
-+----------------------------+
-<module ref="addressing"/>
-+----------------------------+
-
- With the configuration shown above, the UDP transport would generate bindings with the
- following EPR:
-
-+----------------------------+
-udp://localhost:3333/axis2/services/Version?contentType=text/xml
-+----------------------------+
-
- The following example shows a message that can be sent to the Version service over UDP:
-
-+----------------------------+
-<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
- xmlns:wsa="http://www.w3.org/2005/08/addressing">
- <SOAP-ENV:Header>
- <wsa:MessageID>1234</wsa:MessageID>
- <wsa:To>udp://localhost:3333/axis2/services/Version?contentType=text/xml</wsa:To>
- <wsa:Action>urn:getVersion</wsa:Action>
- </SOAP-ENV:Header>
- <SOAP-ENV:Body>
- </SOAP-ENV:Body>
-</SOAP-ENV:Envelope>
-+----------------------------+
-
- On most Linux/Unix systems (including Mac OS X), the <<<nc>>> utility is available to send
- UDP messages and can be used to test the transport. To do this, save the message into
- <<<test-message.xml>>> and execute the following command:
-
-+----------------------------+
-nc -u 127.0.0.1 3333 < test-message.xml
-+----------------------------+
+++ /dev/null
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<!--
- ~ 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.
- -->
-<document>
- <properties>
- <title>Mail transport</title>
- </properties>
- <body>
- <section name="Introduction">
- <p>The mail transport allows to send and receive messages using MIME compliant mail messages. The transport sender
- transmits outgoing messages using SMTP, while the transport listener connects to one or more mail accounts
- and periodically polls these accounts for new incoming messages. The implementation is based on
- <a href="http://java.sun.com/products/javamail/">JavaMail</a> and therefore supports any mail store protocol
- for which a JavaMail provider is available.</p>
- </section>
- <section name="Transport listener">
- <subsection name="Configuration">
- <pre><![CDATA[ <transportReceiver name="mailto" class="org.apache.axis2.transport.mail.MailTransportListener"/>]]></pre>
- </subsection>
- <subsection name="Endpoint configuration">
- <p>Endpoints can be configured both at the transport level and at the service level. In order to receive messages using
- the mail transport, the listener or the service must be configured with a set of parameters
- to access the corresponding mailbox account. If messages from the mail account should be
- directly dispatched to a given service, than the parameters must be specified on that service.
- If on the other hand messages from that account can't be pre-dispatched to a specific service
- (e.g. because the account is used to receive responses to outgoing messages), then the parameters
- must be added to the <tt>transportReceiver</tt> element in <tt>axis2.xml</tt>.</p>
- <p>All parameters starting with <tt>mail.</tt> are
- interpreted as JavaMail environment properties. The most relevant are <tt>mail.<em><protocol></em>.host</tt>
- and <tt>mail.<em><protocol></em>.user</tt>, where <tt><em><protocol></em></tt> is typically <tt>pop3</tt>
- or <tt>imap</tt>. Assuming that Sun's JavaMail implementation is used, the complete list of supported properties for these
- two protocols can be found <a href="http://java.sun.com/products/javamail/javadocs/com/sun/mail/pop3/package-summary.html">here</a>
- and <a href="http://java.sun.com/products/javamail/javadocs/com/sun/mail/imap/package-summary.html">here</a>.</p>
- <p>In additional to the JavaMail environment properties, the following transport specific service parameters are
- used:</p>
- <table class="bodyTable">
- <tr>
- <th>Parameter</th>
- <th>Required</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>transport.PollInterval</td>
- <td>No</td>
- <td>The poll interval in seconds.</td>
- </tr>
- <tr>
- <td>transport.mail.Address</td>
- <td>Yes</td>
- <td>The address used to calculate the endpoint reference for the service. It is assumed that mails
- sent to this address will be delivered to the mailbox account configured for the service.
- Note that the transport has no means to validate this value and an incorrect address will not
- be detected.</td>
- </tr>
- <tr>
- <td>mail.<em><protocol></em>.password</td>
- <td>Yes</td>
- <td>The password for the mailbox account.</td>
- </tr>
- <tr>
- <td>transport.mail.Protocol</td>
- <td>Yes</td>
- <td>The mail store protocol to be used. The value must be protocol identifier recognized by JavaMail.
- Usual values are <tt>pop3</tt> and <tt>imap</tt>. Note that the SSL variants of these two protocols
- are not considered as distinct protocols. Rather, SSL is configured using the appropriate JavaMail
- environment properties.</td>
- </tr>
- <tr>
- <td>transport.mail.ContentType</td>
- <td>No</td>
- <td>This parameter allows to override the content type of incoming messages. This parameter
- is useful if the service can only receive messages of a single content type and the client
- is known to send incorrect content type information. If this parameter is set, the
- <tt>Content-Type</tt> MIME header in incoming messages is ignored.</td>
- </tr>
- <tr>
- <td>transport.mail.ReplyAddress</td>
- <td>No</td>
- <td>The reply-to address to be used when no From or Reply-To header is present in the
- request message.</td>
- </tr>
- <tr>
- <td>transport.mail.Folder</td>
- <td>No</td>
- <td>The folder to read messages from. Defaults to <tt>INBOX</tt>.</td>
- </tr>
- <tr>
- <td>transport.mail.PreserveHeaders, transport.mail.RemoveHeaders</td>
- <td>No</td>
- <td>These two properties control which MIME headers of the received message will be stored
- in the <tt>TRANSPORT_HEADERS</tt> property of the message context. Both parameters expect a
- comma separated list of header names as value. <tt>transport.mail.PreserveHeaders</tt> specifies
- a whitelist of headers to retain, while <tt>transport.mail.RemoveHeaders</tt> specifies a
- blacklist of headers to remove. Note that the two parameters should not be used simultaneously.</td>
- </tr>
- <tr>
- <td>transport.mail.ActionAfterProcess</td>
- <td>No</td>
- <td>Determines what the transport should do with the message after successful processing.
- Possible values are <tt>MOVE</tt> and <tt>DELETE</tt>. The default value is <tt>DELETE</tt>.</td>
- </tr>
- <tr>
- <td>transport.mail.ActionAfterFailure</td>
- <td>No</td>
- <td>Determines what the transport should do with the message if processing fails.
- Possible values are <tt>MOVE</tt> and <tt>DELETE</tt>. The default value is <tt>DELETE</tt>.
- [FIXME: we should reconsider this; it is dangerous!]</td>
- </tr>
- <tr>
- <td>transport.mail.MoveAfterProcess</td>
- <td>Conditional</td>
- <td>Specifies the destination folder if <tt>transport.mail.ActionAfterProcess</tt>
- is <tt>MOVE</tt>.</td>
- </tr>
- <tr>
- <td>transport.mail.MoveAfterFailure</td>
- <td>Conditional</td>
- <td>Specifies the destination folder if <tt>transport.mail.ActionAfterFailure</tt>
- is <tt>MOVE</tt>.</td>
- </tr>
- <tr>
- <td>transport.mail.MaxRetryCount</td>
- <td>No</td>
- <td>The number of connection attempts. When the maximum number of retries is
- exceeded, a new poll is scheduled after the normal poll interval.
- The default value is 0, i.e. connection failures are simply ignored.</td>
- </tr>
- <tr>
- <td>transport.mail.ReconnectTimeout</td>
- <td>No</td>
- <td>The interval between two connection attempts if the first failed.
- The default value is 0, i.e. a new connection is attempted immediately.
- [FIXME: either it is not implemented as intended or the name of the property is misleading; it is not a timeout, but an interval]</td>
- </tr>
- </table>
- </subsection>
- <subsection name="Content extraction">
- <p>Content is extracted from incoming mails using the following rules:</p>
- <ol>
- <li>If the content type of the message is not <tt>multipart/mixed</tt>, the message is extracted
- from the body of the message.</li>
- <li>If the content type of the message is <tt>multipart/mixed</tt>, the listener will attempt to
- find a MIME part with a content type different from <tt>text/plain</tt> and for which a
- message builder is registered. If a matching part is found, the message will be extracted
- from that part. Otherwise, the listener will extract the message from
- the last <tt>text/plain</tt> part if a message builder is registered for that content type.
- Finally, if no message builder is registered for any of the content types appearing in the multipart
- message, an error is triggered.</li>
- </ol>
- <p>Note that these rules only apply if the content type has not been overridden using the
- <tt>transport.mail.ContentType</tt> property. If this property is set, the message will always be
- extracted from the body of the message and support for <tt>multipart/mixed</tt> is disabled.</p>
- <p>In all cases the transport listener will use the corresponding message builder registered in the
- Axis configuration to build the SOAP infoset from the message.</p>
- <p>The special rules for <tt>multipart/mixed</tt> are designed to enable the following use cases:</p>
- <ul>
- <li>Allow humans to send messages to a Web service using a standard mail client. The user
- can do so by adding the message as attachment to the mail. Note that this only works
- if the mail client correctly sets the <tt>Content-Type</tt> header on the attachment.
- This works best for SOAP 1.1 messages: when attaching a file with suffix <tt>.xml</tt>,
- most mail clients will set the content type to <tt>text/xml</tt>, exactly as required
- for SOAP 1.1.</li>
- <li>Allow clients to send a human readable message together with the actual message.
- This is useful if the message may be read by a human before being processed.</li>
- </ul>
- <p>Note that these rules don't interfere with the support for SOAP with Attachments, because
- SwA uses <tt>multipart/related</tt>.</p>
- </subsection>
- </section>
- <section name="Transport sender">
- <subsection name="Configuration">
- <pre xml:space="preserve"> <transportSender name="mailto" class="org.apache.synapse.transport.mail.MailTransportSender">
- <parameter name="mail.smtp.host">smtp.gmail.com</parameter>
- <parameter name="mail.smtp.port">587</parameter>
- <parameter name="mail.smtp.starttls.enable">true</parameter>
- <parameter name="mail.smtp.auth">true</parameter>
- <parameter name="mail.smtp.user">synapse.demo.0</parameter>
- <parameter name="mail.smtp.password">mailpassword</parameter>
- <parameter name="mail.smtp.from">synapse.demo.0@gmail.com</parameter>
- </transportSender></pre>
- </subsection>
- </section>
- </body>
-</document>
+++ /dev/null
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<!--
- ~ 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.
- -->
-<document>
- <properties>
- <title>XMPP transport</title>
- </properties>
- <body>
- <section name="Introduction">
- <p>The XMPP transport allows to send and receive chat messages.</p>
- </section>
- <section name="Transport listener">
- <subsection name="Configuration">
- <pre xml:space="preserve"><transportReceiver name="xmpp" class="org.apache.axis2.transport.xmpp.XMPPListener">
- <!-- Account details for google talk -->
- <parameter name="GoogleServer">
- <parameter name="transport.xmpp.ServerUrl">talk.google.com</parameter>
- <parameter name="transport.xmpp.ServerAccountUserName">axis2.xmpp.account1</parameter>
- <parameter name="transport.xmpp.ServerAccountPassword">apacheaxis2</parameter>
- <parameter name="transport.xmpp.ServerType">transport.xmpp.ServerType.GoogleTalk</parameter>
- </parameter>
-</transportReceiver></pre>
- </subsection>
- <subsection name="Transport Specific Parameters">
- <p>Following transport specific service parameters are used:</p>
- <table class="bodyTable">
- <tr>
- <th>Parameter</th>
- <th>Required</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>transport.xmpp.ServerUrl</td>
- <td>Yes</td>
- <td>The server url of the XMPP server</td>
- </tr>
- <tr>
- <td>transport.xmpp.ServerAccountUserName</td>
- <td>Yes</td>
- <td>The user name of the XMPP account</td>
- </tr>
- <tr>
- <td>transport.xmpp.ServerAccountPassword</td>
- <td>Yes</td>
- <td>The password for the XMPP account.</td>
- </tr>
- <tr>
- <td>transport.xmpp.ServerType</td>
- <td>Yes</td>
- <td>The type of XMPP server</td>
- </tr>
- </table>
- </subsection>
- </section>
- <section name="Transport sender">
- <subsection name="Configuration">
- <pre xml:space="preserve"><transportSender name="xmpp" class="org.apache.axis2.transport.xmpp.XMPPSender">
-</transportSender></pre>
- </subsection>
- </section>
- </body>
-</document>
projects / axis-axis2-java-transports.git / commitdiff
