AXIS2-5434: Moved the transport docs to Axis2 core.
diff --git a/src/site/apt/jms.apt b/src/site/apt/jms.apt deleted file mode 100644 index 1b710fe..0000000 --- a/src/site/apt/jms.apt +++ /dev/null
@@ -1,343 +0,0 @@ -~~ 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.
diff --git a/src/site/apt/tcp-transport.apt b/src/site/apt/tcp-transport.apt deleted file mode 100644 index 69aa52c..0000000 --- a/src/site/apt/tcp-transport.apt +++ /dev/null
@@ -1,150 +0,0 @@ -~~ 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
diff --git a/src/site/apt/udp.apt b/src/site/apt/udp.apt deleted file mode 100644 index 50f50b6..0000000 --- a/src/site/apt/udp.apt +++ /dev/null
@@ -1,119 +0,0 @@ -~~ 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 -+----------------------------+
diff --git a/src/site/xdoc/mail.xml b/src/site/xdoc/mail.xml deleted file mode 100644 index 92ec83a..0000000 --- a/src/site/xdoc/mail.xml +++ /dev/null
@@ -1,200 +0,0 @@ -<?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>
diff --git a/src/site/xdoc/xmpp.xml b/src/site/xdoc/xmpp.xml deleted file mode 100644 index 753c877..0000000 --- a/src/site/xdoc/xmpp.xml +++ /dev/null
@@ -1,78 +0,0 @@ -<?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>