Added: synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports.xml URL: http://svn.apache.org/viewvc/synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports.xml?rev=1302321&view=auto ============================================================================== --- synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports.xml (added) +++ synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports.xml Mon Mar 19 08:41:05 2012 @@ -0,0 +1,820 @@ +<?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>Apache Synapse - Transports Catalog</title> + </properties> + <body> + <section name="Transports Catalog" id="Introduction"> + <p> + The Synapse project has developed a set of transport implementations that provide + protocol support and/or features that go beyond what is provided out of the box by + Axis2: + </p> + <ul> + <li> + A non blocking HTTP transport that gives better performance in a highly + asynchronous environment like Synapse. + </li> + <li> + A VFS transport that can read messages from files and write outgoing messages to + a file system. The file system can be local or remote, and several remote + protocols are supported, such as FTP, SSH, WebDAV, etc. + </li> + <li> + A transport supporting the + <a class="externalLink" href="http://www.fixprotocol.org";>Financial Information eXchange</a> + protocol. FIX is a public-domain messaging standard developed specifically for + the real-time electronic exchange of securities transactions. It has a large user + base and is developed by the collaborative effort of banks, broker-dealers, + exchanges, industry utilities and associations, institutional investors, and IT + providers around the world. + </li> + </ul> + <p>Note that while these transports are developed as part of the Synapse project, + they can be used with any Axis2 based application. + </p> + <p> + The Synapse distribution also comes bundled with the following transports from + the <a class="externalLink" href="http://axis.apache.org/axis2/java/transports/index.html";>Axis2 Transport</a> + project: + </p> + <ul> + <li> + A + <a class="externalLink" href="http://axis.apache.org/axis2/java/transports/jms.html";>JMS transport</a> + supporting any JMS 1.0 or 1.1 provider. + </li> + <li> + A + <a class="externalLink" href="http://axis.apache.org/axis2/java/transports/mail.html";>Mail transport</a> + able to send messages using SMTP and poll messages from a POP3 or IMAP account. + <p> + Apache Synapse is also compatible with the following transport implementations + from the Apache Axis2 Transports project: + </p> + </li> + <li> + <a class="externalLink" href="http://axis.apache.org/axis2/java/transports/tcp-transport.html";>TCP transport</a> + </li> + <li> + <a class="externalLink" href="http://axis.apache.org/axis2/java/transports/sms.html";>SMS transport</a> + </li> + <li>UDP transport</li> + <li> + XMPP transport + <p> + These transports are not shipped with Apache Synapse by default and hence they + should be + <a class="externalLink" href="http://axis.apache.org/axis2/java/transports/download.cgi";>downloaded separately</a> + from the Axis2 transport website and installed in the Synapse runtime. + </p> + </li> + </ul> + </section> + <section name="Content" id="Content"> + <ul> + <li> + <a href="#Introduction">Introduction</a> + </li> + <li> + <a href="#Contents">Contents</a> + </li> + <li> + <a href="#Non-blocking_HTTP_transport">Non-blocking HTTP transport</a> + <ul> + <li> + <a href="#Example_configurations">Example configurations</a> + </li> + <li> + <a href="#Transport_listener_parameters">Transport listener parameters</a> + </li> + <li> + <a href="#Transport_sender_parameters">Transport sender parameters</a> + </li> + </ul> + </li> + <li> + <a href="#VFS_transport">VFS transport</a> + <ul> + <li> + <a href="#Transport_listener">Transport listener</a> + </li> + <li> + <a href="#Transport_sender">Transport sender</a> + </li> + <li> + <a href="#Using_SFTP">Using SFTP</a> + </li> + <li> + <a href="#Known_issues">Known issues</a> + </li> + </ul> + </li> + <li> + <a href="#FIX_transport">FIX transport</a> + <ul> + <li> + <a href="#Setting_up_the_FIX_Transport">Setting up the FIX Transport</a> + </li> + <li> + <a href="#FIX_Transport_Parameters">FIX Transport Parameters</a> + </li> + </ul> + </li> + </ul> + </section> + <section name="Non-blocking HTTP transport" id="Non-blocking_HTTP_transport"> + <subsection name="Example configuration" id="Example_configurations"> + <div class="xmlConf"><transportReceiver name="http" class="org.apache.synapse.transport.nhttp.HttpCoreNIOListener"> + <parameter name="port">8280</parameter> + <parameter name="non-blocking">true</parameter> +</transportReceiver> + +<transportReceiver name="https" class="org.apache.synapse.transport.nhttp.HttpCoreNIOSSLListener"> + <parameter name="port" locked="false">8243</parameter> + <parameter name="non-blocking" locked="false">true</parameter> + <parameter name="keystore" locked="false"> + <KeyStore> + <Location>lib/identity.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + <KeyPassword>password</KeyPassword> + </KeyStore> + </parameter> + <parameter name="truststore" locked="false"> + <TrustStore> + <Location>lib/trust.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + </TrustStore> + </parameter> +</transportReceiver> + +<transportSender name="http" class="org.apache.synapse.transport.nhttp.HttpCoreNIOSender"> + <parameter name="non-blocking" locked="false">true</parameter> + <parameter name="warnOnHTTP500" locked="false">*</parameter> +</transportSender> + +<transportSender name="https" class="org.apache.synapse.transport.nhttp.HttpCoreNIOSSLSender"> + <parameter name="non-blocking" locked="false">true</parameter> + <parameter name="warnOnHTTP500" locked="false">*</parameter> + <parameter name="keystore" locked="false"> + <KeyStore> + <Location>lib/identity.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + <KeyPassword>password</KeyPassword> + </KeyStore> + </parameter> + <parameter name="truststore" locked="false"> + <TrustStore> + <Location>lib/trust.jks</Location> + <Type>JKS</Type> + <Password>password</Password> + </TrustStore> + </parameter> +</transportSender></div> + </subsection> + <subsection name="Transport listener parameters" id="Transport_listener_parameters"> + <p>The following parameters are supported by both the HTTP and the HTTPS listener:</p> + <dl> + <dt> + <tt>port</tt> + </dt> + <dd>The TCP port to bind the listener to.</dd> + <dt> + <tt>bind-address</tt> + </dt> + <dd> + The IP address to bind the listener to. This can be used on hosts that have + more than one network interface or IP address to run multiple Synapse instances + listening to the same port. If this parameter is not specified, the + listener will accept connections on any IP address. + </dd> + <dt> + <tt>hostname</tt> + </dt> + <dd> + The host name to use when computing endpoint references in generated WSDL files. + The default value is the host name as provided by the operation system or + <tt>localhost</tt> if the host name can't be determined. The value of this + parameter is ignored if <tt>WSDLEPRPrefix</tt> is specified. + </dd> + <dt> + <tt>WSDLEPRPrefix</tt> + </dt> + <dd> + The URL prefix to use when computing endpoint references in generated WSDL files. + The value must be a valid URL with at least a protocol and host. If this value + is unspecified, endpoint references will be computed based on the listener type + (HTTP or HTTPS) and <tt>hostname</tt> and <tt>port</tt> parameters. + <p> + This parameter should be used if clients connect to Synapse through a frontend + server, e.g. a (load balancing) Apache, and these clients rely on the address + information in the WSDL documents exposed through <tt>...?wsdl</tt> URLs. + </p> + </dd> + </dl> + <p>The following parameters are specific to the HTTPS listener: </p> + <dl> + <dt> + <tt>keystore</tt> + </dt> + <dd> + The keystore configuration. The value of this parameter must be a + <tt><KeyStore></tt> + element as shown in the example configurations above. + </dd> + <dt> + <tt>truststore</tt> + </dt> + <dd> + The truststore configuration. The value of this parameter must be a + <tt><TrustStore></tt> + element as shown in the example configurations above. + </dd> + <dt> + <tt>SSLVerifyClient</tt> + </dt> + <dd> + This parameter has the same meaning as the corresponding + <a class="externalLink" href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslverifyclient";>mod_ssl directive</a> + and sets the desired certificate verification level for client authentication: + <ul> + <li> + <tt>none</tt> (default): no client certificate is required at all + </li> + <li> + <tt>optional</tt>: the client may present a valid certificate, but is + not required to do so + </li> + <li> + <tt>require</tt>: the client has to present a valid certificate, + otherwise the connection request will be terminated during SSL handshake + </li> + </ul> + </dd> + </dl> + </subsection> + <subsection name="Transport sender parameters" id="Transport_sender_parameters"> + <p> + The following property can be used to control based on content-types whether the + HTTP/HTTPS sender shall output a warning for responses with HTTP status code 500. + </p> + <dl> + <dt> + <tt>warnOnHTTP500</tt> + </dt> + <dd> + A list of content-types for which Synapse shall output a warning when receiving + an HTTP 500 response (each value each separated by a |). By default Synapse + outputs a warning for any HTTP 500 response, irrespective of the content-type. + Consequently, also for each SOAP fault a warning will be logged. If only for + specific content-types a warning shall be logged, please provide a |-separated + list. To output the warning for messages which do not have a content-type set, + please use the value 'none'. + <p> + Example value: x-application/hessian|none + </p> + </dd> + </dl> + <p> + The following properties can be used to configure the HTTP sender to use a proxy. + They can be specified either as transport parameters in declared in + <tt><transportSender></tt> or as system properties. + </p> + <dl> + <dt> + <tt>http.proxyHost</tt> + </dt> + <dd>The host name or address of the proxy server.</dd> + <dt> + <tt>http.proxyPort</tt> + </dt> + <dd>The TCP port of the proxy server.</dd> + <dt> + <tt>http.nonProxyHosts</tt> + </dt> + <dd> + The hosts to which the HTTP sender should connect directly and not through + the proxy server. The value can be a list of hosts, each separated by a |, and + in addition a wildcard character (*) can be used for matching. + <p> + Example value: + <tt>*.foo.com|localhost</tt> + </p> + </dd> + </dl> + <p>Note that the HTTPS sender has no proxy support yet.</p> + <p>The following parameters are specific to the HTTP sender:</p> + <dl> + <dt> + <tt>keystore</tt> + </dt> + <dd> + The keystore configuration. The value of this parameter must be a + <tt><KeyStore></tt> element as shown in the example configurations + above. + </dd> + <dt> + <tt>truststore</tt> + </dt> + <dd> + The truststore configuration. The value of this parameter must be a + <tt><TrustStore></tt> + element as shown in the example configurations above. + </dd> + <dt> + <tt>novalidatecert</tt> + </dt> + <dd> + When set to <tt>true</tt>, this parameter disables server certificate + validation (trust). The default value is <tt>false</tt>. This parameter will + be ignored if <tt>truststore</tt> is set. + <p> + Setting his parameter to <tt>true</tt> + is useful in development and test environments, but should not be used in + production environments. If validation is disabled, a warning message will + be logged at startup. + </p> + </dd> + <dt> + <tt>HostnameVerifier</tt> + </dt> + <dd> + This optional parameter specifies the policy to apply when checking that the + hostname of the server matches the names stored inside the X.509 certificate + presented by the server. Possible values are <tt>Strict</tt>, <tt>AllowAll</tt> + and <tt>DefaultAndLocalhost</tt>. See the + <a href="../apidocs/org/apache/synapse/transport/nhttp/HostnameVerifier.html">HostnameVerifier Javadoc</a> + for more details. + </dd> + </dl> + </subsection> + </section> + <section name="VFS transport" id="VFS_transport"> + <subsection name="Transport listener" id="Transport_listener"> + + <p> + The VFS transport listener receives messages dropped in a given local or remote file + system location. The location is specified by a URL that either identifies a single + file or a directory. The transport listener will periodically poll the specified + location and process any file(s) found. After a file has been processed it will be + deleted or moved to another location. Note that this is absolutely mandatory to + prevent the listener from processing files multiple times. Therefore the VFS transport + listener can only be used in situations where it has write access to the file system + location and where deleting or moving the dropped files is acceptable. + </p> + <p> + The transport is based on + <a class="externalLink" href="http://commons.apache.org/vfs/";>Apache Commons VFS</a> + and supports any protocol for which a VFS provider is available. The transport is + pre-configured with providers for local files ( + <tt>file:</tt> + scheme), HTTP, HTTPS, FTP and SFTP (i.e. file transfer over SSH). + </p> + <p> + There is a fundamental difference between the VFS transport and transports such as + HTTP and it is important to understand this difference to be able to use the VFS + transport correctly. The HTTP transport binds to a single protocol endpoint, i.e. + a TCP port on which it accepts incoming HTTP requests. These requests are then + dispatched to the right service based on the request URI. On the other hand, the + VFS transport only receives the payload of a message, but no additional information + that could be used to dispatch the message to a service. This means that file system + locations must be explicitly mapped to services. This is done using a set of service + parameters. + </p> + <p>For Synapse this means that the VFS transport listener can only be used in + conjunction with proxy services. The relevant service parameters are then specified + as follows: + </p> + <div class="xmlConf"><proxy name="MyVFSService" transports="vfs"> + <parameter name="transport.vfs.FileURI">file:///var/spool/synapse/in</parameter> + <parameter name="transport.vfs.ContentType">application/xml</parameter> + ... + <target> + ... + </target> +</proxy></div> + <p> + In this example the file system location + <tt>file:///var/spool/synapse/in</tt> + is explicitly bound to + <tt>MyVFSService</tt> + , i.e. any message dropped in that location will be predispatched to that service, bypassing any other configured + dispatch mechanisms that would apply to messages received through HTTP. + </p> + <p>The VFS transport recognizes the following service parameters:</p> + <dl> + <dt> + <tt>transport.vfs.FileURI</tt>(Required) + </dt> + <dd> + The primary File (or Directory) URI in the vfs* transport format, for this + service + </dd> + <dt> + <tt>transport.vfs.ContentType</tt> (Required) + </dt> + <dd> + The expected content type for files retrieved for this service. The VFS + transport uses this information to select the appropriate message builder. + <p>Examples:</p> + <ul> + <li> + <tt>text/xml</tt> for plain XML or SOAP + </li> + <li> + <tt>text/plain; charset=ISO-8859-1</tt> for text files + </li> + <li> + <tt>application/octet-stream</tt> for binary data + </li> + </ul> + </dd> + <dt> + <tt>transport.vfs.FileNamePattern</tt> + (Optional) + </dt> + <dd> + A file name regex pattern to match files against a directory specified by + the FileURI + </dd> + <dt> + <tt>transport.PollInterval</tt> (Optional) + </dt> + <dd> The poll interval (in seconds)</dd> + <dt> + <tt>transport.vfs.ActionAfterProcess</tt> (Optional) + </dt> + <dd> DELETE or MOVE</dd> + <dt> + <tt>transport.vfs.MoveAfterProcess</tt> (Optional) + </dt> + <dd> + The directory to move files after processing (i.e. all files process + successfully) + </dd> + <dt> + <tt>transport.vfs.ActionAfterErrors</tt> (Optional) + </dt> + <dd> DELETE or MOVE</dd> + <dt> + <tt>transport.vfs.MoveAfterErrors</tt> (Optional) + </dt> + <dd> + The directory to move files after errors (i.e. some of the files succeed + but some fail) + </dd> + <dt> + <tt>transport.vfs.ActionAfterFailure</tt> (Optional) + </dt> + <dd> DELETE or MOVE</dd> + <dt> + <tt>transport.vfs.MoveAfterFailure</tt> (Optional) + </dt> + <dd> The directory to move after failure (i.e. all files fail)</dd> + <dt> + <tt>transport.vfs.ReplyFileURI</tt> (Optional) + </dt> + <dd> Reply file URI</dd> + <dt> + <tt>transport.vfs.ReplyFileName</tt> (Optional) + </dt> + <dd> Reply file name (defaults to response.xml)</dd> + <dt> + <tt>transport.vfs.MoveTimestampFormat</tt> (Optional) + </dt> + <dd> + Timestamp prefix format for processed file name. java.text.SimpleDateFormat + compatible string. e.g. yyMMddHHmmss'-' + </dd> + <dt> + <tt>transport.vfs.Locking</tt> (Optional) + </dt> + <dd> + By-default file locking is turned on in the VFS transport, and this parameter + lets you configure the locking behaviour on a per service basis. Possible values are + <tt>enable</tt> or <tt>disable</tt>, and both these values are important because + the locking can be disabled at the global level by specifying that at the + receiver level and selectively enable locking only for a set of services. + </dd> + <dt> + <tt>transport.vfs.Streaming</tt> (Optional) + </dt> + <dd> + If this parameter is set to <tt>true</tt>, the transport will attempt to use a + <tt>javax.activation.DataSource</tt> (instead of a <tt>java.io.InputStream</tt> + ) object to pass the content of the file to the message builder. Note that this + is only supported by some message builders, e.g. for plain text and binary. + <p> + This allows processing of the message without storing the entire content + in memory. It also has two other side effects: + </p> + <ul> + <li> + The incoming file (or connection in case of a remote file) will only + be opened on demand. + </li> + <li> + Since the data is not cached, the file might be read several times. + </li> + </ul> + <p> + This option can be used to achieve streaming of large payloads. Note that + this feature is still somewhat experimental and might be superseded by a + more flexible mechanism in a future release. + </p> + </dd> + </dl> + <p> + Note that since the VFS endpoints are configured at the level of the service, the + only parameter that is available at the listener is the file locking configuration + parameter which is optional and the transport listener is enabled in + <tt>axis2.xml</tt> + simply as follows: + </p> + <div class="xmlConf"><transportReceiver name="vfs" class="org.apache.synapse.transport.vfs.VFSTransportListener"> + <parameter name="transport.vfs.Locking">enable | disable</parameter> ? +</transportReceiver></div> + </subsection> + <subsection name="Transport sender" id="Transport_sender"> + <p> + The VFS transport sender allows to write outgoing messages to local or remote files. + As with the listener, the transport sender supports any protocol for which there + is a VFS provider. + </p> + <p> + The sender is enabled be the following directive in + <tt>axis2.xml</tt> file locking which is by-default enabled can be configured + using the <tt>transport.vfs.Locking</tt> parameter: + </p> + <div class="xmlConf"><transportSender name="vfs" class="org.apache.synapse.transport.vfs.VFSTransportSender"> + <parameter name="transport.vfs.Locking">enable | disable</parameter> ? +</transportSender></div> + <p> + To send a message using the VFS transport, the destination URI must start with + <tt>vfs:</tt> followed by a valid VFS URL. For example, in a Synapse mediation, + one would use: + </p> + <div class="xmlConf"><endpoint> + <address uri="vfs:file:///var/spool/synapse/out"/> +</endpoint></div> + <p> + Other examples of valid VFS URLs are (see + <a class="externalLink" href="http://commons.apache.org/vfs/filesystems.html";>http://commons.apache.org/vfs/filesystems.html</a> + for more samples): + </p> + <ul> + <li> + <tt>file:///directory/filename.ext</tt> + </li> + <li> + <tt>file:////somehost/someshare/afile.txt</tt> + </li> + <li> + <tt>jar:../lib/classes.jar!/META-INF/manifest.mf</tt> + </li> + <li> + <tt>jar:zip:outer.zip!/nested.jar!/somedir</tt> + </li> + <li> + <tt>ftp://myusername:mypassword@somehost/pub/downloads/somefile.tgz[?vfs.passive=true]</tt> + </li> + </ul> + <p> + The global configuration of the file locking can be overriden by providing the + <tt>transport.vfs.Locking</tt> as a URL parameter with the appropriate value ( + <tt>enable</tt>, or <tt>disable</tt>) on a given endpoint. + </p> + <p> + It should be noted that by its nature, the VFS transport sender doesn't support + synchronous responses and should only be invoked using the out-only message + exchange pattern. In a Synapse mediation, this can be forced using the + following mediator: + </p> + <div class="xmlConf"><property action="set" name="OUT_ONLY" value="true"/></div> + </subsection> + <subsection name="Using SFTP" id="Using_SFTP"> + <p> + To avoid man-in-the-middle attacks, SSH clients will only connect to hosts with + a known host key. When connecting for the first time to an SSH server, a typical + command line SSH client would request confirmation from the user to add the + server and its fingerprint to the list of known hosts. + </p> + <p> + The VFS transports supports SFTP through the + <a class="externalLink" href="http://www.jcraft.com/jsch/";>JSch</a> + library and this library also requires a list of known hosts. Since Synapse is + not an interactive process, it can't request confirmation from the user and is + therefore unable to automatically add a host to the list. This implies that the + list of known hosts must be set up manually before the transport can connect. + </p> + <p> + Jsch loads the list of known hosts from a file called <tt>known_hosts</tt> in + the <tt>.ssh</tt> sub-directory of the user's home directory, i.e. <tt>$HOME/.ssh</tt> + in Unix and <tt>%HOMEPATH%\.ssh</tt> in Windows. The location and format of this + file are compatible with the <a class="externalLink" href="http://www.openssh.com/";>OpenSSH</a> + client. + </p> + <p> + Since the file not only contains a list of host names but also the fingerprints + of their host keys, the easiest way to add a new host to that file is to simply + use the OpenSSH client to open an SSH session on the target host. The client will + then ask to add the credentials to the <tt>known_hosts</tt> file. Note that if + the SSH server is configured to only allow SFTP sessions, but no interactive + sessions, the connection will actually fail. Since this doesn't rollback the + change to the <tt>known_hosts</tt> file, this error can be ignored. + </p> + </subsection> + <subsection name="Known issues" id="Known_issues"> + <p> + The VFS listener will start reading a file as soon as it appears in the configured + location. To avoid processing half written files, the creation of these files should + be made atomic. On most platforms this can be achieved by writing the data to a + temporary file and then moving the file to the target location. Note however that + a move operation is only atomic if the source and destination are on the same + physical file system. The location for the temporary file should be chosen with + that constraint in mind. + </p> + <p> + It should also be noted that the VFS transport sender doesn't create files atomically. + </p> + </subsection> + </section> + <section name="FIX transport" id="FIX_transport"> + <p>A general overview about the FIX transport can be found in the following articles:</p> + <ul> + <li> + <a class="externalLink" href="http://wso2.org/library/3449";>Apache Synapse FIX'ed</a> + </li> + <li> + <a class="externalLink" href="http://wso2.org/library/3837";>Using the WSO2 ESB and FIX</a> + (also applies to Synapse) + </li> + </ul> + <subsection name="Setting up the FIX Transport" id="Setting_up_the_FIX_Transport"> + <p> + To use the FIX transport, you need a local + <a class="externalLink" href="http://www.quickfixj.org";>Quickfix/J</a> + installation. Download Quickfix/J from + <a class="externalLink" href="http://www.quickfixj.org/downloads";>http://www.quickfixj.org/downloads</a> + . + </p> + <p> + To enable the FIX transport, you need to uncomment the FIX transport sender and + FIX transport receiver configurations in the SYNAPSE_HOME/repository/conf/axis2.xml. + Simply locate and uncomment the FIXTransportSender and FIXTransportListener sample + configurations. Also add the following jars to the Synapse class path + (SYNAPSE_HOME/lib directory). + </p> + <ul> + <li>quickfixj-core.jar</li> + <li>quickfixj-msg-fix40.jar</li> + <li>quickfixj-msg-fix41.jar</li> + <li>quickfixj-msg-fix42.jar</li> + <li>quickfixj-msg-fix43.jar</li> + <li>quickfixj-msg-fix44.jar</li> + <li>mina-core.jar</li> + <li>slf4j-api.jar</li> + <li>slf4j-jdk14.jar</li> + </ul> + <p>All these jars are shipped with the Quickfix/J binary distribution.</p> + </subsection> + <subsection name="FIX Transport Parameters" id="FIX_Transport_Parameters"> + <p> + This is the list of all parameters accepted by the FIX transport. Refer the + sample 257 and 258 to see how some of them are used in practice. + </p> + <dl> + <dt> + <tt>transport.fix.AcceptorConfigURL</tt> + </dt> + <dd> + If a service needs to listen to incoming FIX messages from a remote initiator + then Synapse needs to create an acceptor. This parameter should contain the + URL of the file which contains the FIX configuration for the acceptor. + (See sample 257) + </dd> + <dt> + <tt>transport.fix.InitiatorConfigURL</tt> + </dt> + <dd> + If a service needs to send FIX messages to a remote acceptor Synapse should + create an initiator. This parameter should contain the URL of the file which + contains the FIX configuration for the initiator. (See sample 257) + </dd> + <dt> + <tt>transport.fix.AcceptorMessageStore</tt> + </dt> + <dd> + The type of message store to be used with the acceptor. Allowed values for + this parameter are 'file', 'jdbc', 'memory' and 'sleepycat'. If not specified + memory based message store will be used by default. Additional parameters + required to configure each of the message stores should be specified in the + acceptor configuration file. + </dd> + <dt> + <tt>transport.fix.InitiatorMessageStore</tt> + </dt> + <dd> + Same as the above but applies only for the initiators. Additional parameters + required to configure each of the message stores should be specified in the + initiator configuration file. + </dd> + <dt> + <tt>transport.fix.AcceptorLogFactory</tt> + </dt> + <dd> + Specifies the transport level log factory to be used to log messages going + through the acceptor. FIX messages are logged without putting them in SOAP + envelopes at this level. Accepted values are 'console', 'file' and 'jdbc'. + If not specified no logging will be done at the transport level. Additional + parameters required to configure each of the lof factories should be specified + in the acceptor configuration file. + </dd> + <dt> + <tt>transport.fix.InitiatorLogFactory</tt> + </dt> + <dd> + Specifies the transport level log factory to be used to log messages going + through the initiator. Functionality is similar to the above. Additional + parameters required to configure each of the lof factories should be specified + in the initiator configuration file. + </dd> + <dt> + <tt>transport.fix.ResponseDeliverToCompID</tt> + </dt> + <dd> + If a response FIX message sent from Synapse to a remote FIX engine should be + forwarded from the remote engine to another party this parameter can be used + to set the DeliverToCompID field of the messages at Synapse. + </dd> + <dt> + <tt>transport.fix.ResponseDeliverToSubID</tt> + </dt> + <dd> + If a response FIX message sent from Synapse to a remote FIX engine should be + forwarded from the remote engine to another party this parameter can be used + to set the DeliverToSubID field of the messages at Synapse. + </dd> + <dt> + <tt>transport.fix.ResponseDeliverToLocationID</tt> + </dt> + <dd> + If a response FIX message sent from Synapse to a remote FIX engine should be + forwarded from the remote engine to another party this parameter can be used + to set the DeliverToLocationID field of the messages at Synapse. + </dd> + <dt> + <tt>transport.fix.ServiceName</tt> + </dt> + <dd> + Used when messages coming over a different protocol has to be forwarded over + FIX. The value must be equal to the name of the service and the scope must be + 'axis2-client' (See sample 258) + </dd> + <dt> + <tt>transport.fix.SendAllToInSequence</tt> + </dt> + <dd> + When there are multiple responses to a FIX request and when we need only one + of them to be sent to the original requester this parameter has to be set to + 'false'. This mostly comes handy when the original requester is communicating + over a different protocol (like HTTP). If this parameter is not set to 'false' + at such scenarios messages might get into a loop. (See sample 258) + </dd> + <dt> + <tt>transport.fix.BeginStringValidation</tt> + </dt> + <dd> + When the FIX messages sent to Synapse should not be forwarded to a FIX session + with a different BeginString value this parameter can be set to 'true'. Setting + this parameter to 'true' will enforce this restriction. + </dd> + </dl> + </subsection> + </section> + + </body> +</document> \ No newline at end of file
Added: synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/upgrading.xml URL: http://svn.apache.org/viewvc/synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/upgrading.xml?rev=1302321&view=auto ============================================================================== --- synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/upgrading.xml (added) +++ synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/upgrading.xml Mon Mar 19 08:41:05 2012 @@ -0,0 +1,352 @@ +<?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>Apache Synapse - Upgrading to the Latest Version</title> + </properties> + <body> + <section name="Upgrading to the Latest Version"> + <p> + If you are using an older version of Synapse (1.x) and now looking to migrate to + the latest versions (2.x) this document would be a good starting point. This + article provides information on steps that need to be carried out to smoothly + migrate from an older release of Synapse to the latest version. + </p> + </section> + <section name="Contents"> + <ul> + <li> + <a href="#General_comments">General comments</a> + </li> + <li> + <a href="#Upgrading_from_1.2_to_2.1">Upgrading from 1.2 to 2.1</a> + <ul> + <li> + <a href="#Configuration_file_vs_multi_XML_configuration">Configuration file vs multi XML configuration</a> + </li> + <li> + <a href="#Endpoint_URLs_for_proxy_services">Endpoint URLs for proxy services</a> + </li> + <li> + <a href="#Mediator_Deployer">Mediator Deployer</a> + </li> + <li> + <a href="#Main_Sequence">Main Sequence</a> + </li> + <li> + <a href="#Filter_Mediator">Filter Mediator</a> + </li> + <li> + <a href="#Migration_Tool">Migration Tool</a> + </li> + <li> + <a href="#Custom_Extensions_and_API_changes">Custom Extensions and API changes</a> + </li> + </ul> + </li> + </ul> + </section> + <section name="General comments" id="General_comments"> + <p> + If you are using custom extensions (mediators, startups, etc.) implemented in Java and + depending on Synapse APIs, you should go through the following process before upgrading + to a new release: + </p> + <ol type="1"> + <li> + Compile the extension with the libraries from the Synapse release you are + currently using and check for any deprecation warnings. You should change your + code to eliminate all those warnings. In general the Javadoc of the + deprecated class or method gives you a hint on how to change your code. Test all + your changes with your current Synapse release. + </li> + <li> + Recompile and test the extension with the libraries from the new Synapse release. + We try to avoid to introduce incompatible changes to Synapse's core APIs between + releases (except if the related classes or methods were deprecated in the previous + release). However, it is not always possible to maintain compatibility. In addition + your code might depend on features that are not part of the core API. Therefore, + even if you don't use deprecated methods and classes, there is no guarantee that + your code will not break when upgrading to a new release and you always need to + recompile and test them before deploying to the new release. + </li> + <li> + Upgrade your Synapse installation and deploy the new version of your extensions. + </li> + </ol> + <p> + If you are skipping releases when upgrading your installation, you might nevertheless + want to go through the first step for all the intermediate releases. This will make + the migration easier. + </p> + </section> + + <section name="Upgrading from 1.2 to 2.1" id="Upgrading_from_1.2_to_2.1"> + <subsection name="Configuration file vs multi XML configuration" id="Configuration_file_vs_multi_XML_configuration"> + <p> + In 1.2 you have been using a single synapse.xml file which resides on the + repository/conf directory of the distribution, where as on 2.1 we have structured + this into a configuration repository with multiple directories to have different + artifact types and each and every artifact configuration to reside on a different + files inside the desired repository directory. This repository directory on the 2.1 + release resides in the repository/conf directory too, and named as synapse-config. + The repository directory structure inside the synapse-config directory + looks like follows; + </p> + <div class="xmlConf">synapse-config + /api + /endpoints + /event-sources + /local-entries + /priority-executors + /proxy-services + /sequences + main.xml + fault.xml + /tasks + /templates + registry.xml + synapse.xml</div> + <p> + As you can see in the above sketch of the repository though it is a repository based + configuration, it also supports the old style single flat synapse.xml file in which + case it has to reside inside the root of the repository. + </p> + <p> + So the easiest way to migrate the configuration is to move your already existing + synapse.xml file in repository/conf directory in 1.2 version into the + repository/conf/synapse-config directory of the 2.x version. <em>Note: When doing this + migration you should also delete the main.xml and fault.xml files which are there on the + sequences directory of the repository, otherwise there will be 2 main and fault + sequences one coming from the sequences directory and the other coming from your just + copied synapse.xml file.</em> + </p> + </subsection> + <subsection name="Endpoint URLs for proxy services" id="Endpoint_URLs_for_proxy_services"> + <p> + In release 2.1 the endpoint URLs for proxy services have changed from + <tt>/soap</tt> to <tt>/services</tt>. E.g. <tt>http://localhost:8280/services/StockQuote</tt> + should be used instead of <tt>http://localhost:8280/soap/StockQuote</tt>. + </p> + </subsection> + <subsection name="MediatorDeployer" id="Mediator_Deployer"> + <p> + Release 1.3 has enhanced capabilities for extension deployment. While in 1.2 extension + deployment was limited to mediators bundled as simple JAR files, 1.3 extended this + support to tasks and defined a new archive format (XAR) that allows to bundle + these extensions together with their dependency JARs (see + <a class="externalLink" href="http://issues.apache.org/jira/browse/SYNAPSE-377";>SYNAPSE-377</a> + for more details). Enabling these features requires changes to the <tt>axis2.xml</tt> + configuration file. In 1.2 the deployer was configured as follows: + </p> + <div class="xmlConf"><deployer extension="jar" directory="mediators" + class="org.apache.synapse.core.axis2.MediatorDeployer"/></div> + <p> + In 2.1 the suggested configuration is: + </p> + <div class="xmlConf"><deployer extension="xar" directory="extensions" + class="org.apache.synapse.deployers.ExtensionDeployer"/> </div> + <p> + It is possible to have multiple configuration entries for the extension deployer + with different settings. For example, if you used the deployer in 1.2 you might + want to have the following configuration: + </p> + <div class="xmlConf"><deployer extension="jar" directory="mediators" + class="org.apache.synapse.deployers.ExtensionDeployer"/> +<deployer extension="xar" directory="extensions" + class="org.apache.synapse.deployers.ExtensionDeployer"/></div> + </subsection> + <subsection name="JMS transport" id="JMS_transport"> + <p> + The way the JMS transport determines the content type of incoming messages has + slightly changed between Synapse 1.2 and 2.x. The mechanism is also more flexible. + See SYNAPSE-304 and SYNAPSE-424 for the reasons of this change and refer to the + <a class="externalLink" href="http://ws.apache.org/commons/transport/";>WS-Commons Transport project</a> + for documentation. + </p> + </subsection> + <subsection name="Main Sequence" id="Main_Sequence"> + <p> + On Synapse 1.2 you could have mediator configuration on the top level definitions + tag and they were treated as the <strong>main</strong> sequence if there is no + main sequence defined in the configuration. How ever removing the conflict of having + top level mediators and a main sequence leading the synapse to fail to start on + 2.x Synapse configuration builder simply ignores the top level mediators. So you + need to wrap the top level mediators, if there are any, with the sequence named + <strong>main</strong> on the new 2.1 version. + </p> + <p> + To further explain this lets have a look at the following valid configuration bit + (this is the sample 0 configuration) on the 1.2; + <div class="xmlConf"><definitions xmlns="http://ws.apache.org/ns/synapse"> + <!-- log all attributes of messages passing through --> + <log level="full"/> + + <!-- Send the message to implicit destination --> + <send/> +</definitions></div> + which needs to be changed to the following configuration on 2.1 + <div class="xmlConf"><definitions xmlns="http://ws.apache.org/ns/synapse"> + + <sequence name="main"> + <!-- log all attributes of messages passing through --> + <log level="full"/> + + <!-- Send the message to implicit destination --> + <send/> + <sequence/> + +</definitions></div> + </p> + </subsection> + <subsection name="Filter Mediator" id="Filter_Mediator"> + <p> + From 2.1 onwards Synapse filter mediator supports the else close as well, and hence + the filter matching set of mediators has to be enclosed within a <then> element. + </p> + <p> + If we consider the following sample from the 1.2 version of synapse; + <div class="xmlConf"><filter source="get-property('To')" regex=".*/StockQuote.*"> + <send> + <endpoint> + <address uri="http://localhost:9000/soap/SimpleStockQuoteService"/> + </endpoint> + </send> + <drop/> +</filter></div> + the equivalent configuration for the 2.1 release is going to be; + <div class="xmlConf"><filter source="get-property('To')" regex=".*/StockQuote.*"> + <then> + <send> + <endpoint> + <address uri="http://localhost:9000/soap/SimpleStockQuoteService"/> + </endpoint> + </send> + <drop/> + <then/> +</filter></div> + You could also add an else close to this conditional statement as follows on 2.x + which is not possible on 1.2 + <div class="xmlConf"><filter source="get-property('To')" regex=".*/StockQuote.*"> + <then> + <send> + <endpoint> + <address uri="http://localhost:9000/soap/SimpleStockQuoteService"/> + </endpoint> + </send> + <drop/> + <then/> + <else/> + <log/> + <else/> +</filter></div> + </p> + </subsection> + <subsection name="Migration Tool" id="Migration_Tool"> + <p> + In general it is recommended to run the configuration through the migration tool + provided with the Synapse 2.x release, on your synapse 1.2 configuration before + using it with the 2.1. + </p> + <p> + To run the migration tool execute the synapse-config-migrator.sh by passing the + synapse.xml file location of the + 1.2 configuration. Which will create the 2.1 + compatible configuration with the .new suffix. For example; + <pre>sh bin/synapse-config-migrator.sh synapse-i1.2/repository/conf/synapse.xml</pre> + </p> + </subsection> + <subsection name="Custom Extensions and API changes" id="Custom_Extensions_and_API_changes"> + <p> + Even though there is a migration tool it just takes care of your configuration and not + custom extensions that you have done for example like CustomMediators or Tasks + and so forth. There are some API changes that affect your custom extensions + unfortunately. This section tries to list all the public API changes which affects + the backward compatibility of the custom extensions that you have been running + with the 1.2 version of Synapse. + </p> + <table class="bodyTable"> + <tr class="a"> + <th>Class</th> + <th>Method</th> + <th>Change Description</th> + </tr> + <tr class="b"> + <td> + <a href="../apidocs/org/apache/synapse/config/xml/AbstractMediatorFactory.html">AbstractMediatorFactory</a> + </td> + <td>createMediator(OMElement)</td> + <td> + This was the method that you have been overwriting on the 1.2 version to + implement a new custom mediator factory to build the mediator by looking at + the XML configuration. On the 2.1 version you should be extending the + <a href="apidocs/org/apache/synapse/config/xml/AbstractMediatorFactory.html#createSpecificMediator(org.apache.axiom.om.OMElement,%20java.util.Properties)">createSpecificMediator(OMElement, Properties)</a> + . Note that in the process of changing the method to be extended, the method + <a href="apidocs/org/apache/synapse/config/xml/AbstractMediatorFactory.html#createMediator(org.apache.axiom.om.OMElement,%20java.util.Properties)">createMediator</a> + method has been changed to be final. From a users point of view of this + interface he/she should be using the createMediator method which is what + Synapse does. + </td> + </tr> + <tr class="a"> + <td> + <a href="../apidocs/org/apache/synapse/config/xml/AbstractMediatorSerializer.html">AbstractMediatorSerializer</a> + </td> + <td>serializeMediator(Mediator)</td> + <td> + This was the method that you have been overwriting on the 1.2 version to + implement a new custom mediator serializer to serialize to the XML + Configuration by walking through the mediator properties. On the 2.1 + version you should be extending the + <a href="apidocs/org/apache/synapse/config/xml/AbstractMediatorSerializer.html#serializeSpecificMediator(org.apache.synapse.Mediator)">serializeSpecificMediator(Mediator)</a> + . Note that in the process of changing the method to be extended, the method + <a href="apidocs/org/apache/synapse/config/xml/AbstractMediatorSerializer.html#serializeMediator(org.apache.axiom.om.OMElement,%20org.apache.synapse.Mediator)">serializeMediator</a> + method has been changed to be final. From a users point of view of this + interface he/she should be using the serializeMediator method which is + what Synapse does. + </td> + </tr> + </table> + <p> + Further to that if you have been using + <a href="../apidocs/org/apache/synapse/ServerManager.html">ServerManager</a> + class you may have noticed that the class is no more a singleton and doesn't have + the static getInstance method. Also note that the common utilities like data + sources JMX and RMI registration stuff have been moved to a new module with + org.apache.synapse.commons package name. + </p> + <p> + On the configuration building front all entities are given a properties map to + construct its instance and that has been used to pass in any additional information + required like RESOLVE_ROOT, or SYNAPSE_HOME startup parameters. For example if you + look at the + <a href="../apidocs/org/apache/synapse/config/xml/MediatorFactoryFinder.html">MediatorFactoryFinder</a> + class the + <a href="../apidocs/org/apache/synapse/config/xml/MediatorFactoryFinder.html#getMediator(org.apache.axiom.om.OMElement,%20java.util.Properties)">getMediator</a> + method is expecting a properties map apart from the OMElement argument. + It is safe to pass in a empty properties map if you are using these methods for + any testing purposes or even in cases where you do not resolve dependencies. + </p> + </subsection> + </section> + </body> +</document> \ No newline at end of file
