You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@synapse.apache.org by hi...@apache.org on 2011/12/21 06:10:43 UTC
svn commit: r1221612 [2/2] - in
/synapse/trunk/scratch/hiranya/website/src/site: ./ xdoc/userguide/
xdoc/userguide/samples/ xdoc/userguide/samples/setup/
Added: synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/transports.xml
URL: http://svn.apache.org/viewvc/synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/transports.xml?rev=1221612&view=auto
==============================================================================
--- synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/transports.xml (added)
+++ synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/transports.xml Wed Dec 21 05:10:42 2011
@@ -0,0 +1,817 @@
+<?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>
+ <body>
+ <section name="Introduction" 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/scratch/hiranya/website/src/site/xdoc/userguide/upgrading.xml
URL: http://svn.apache.org/viewvc/synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/upgrading.xml?rev=1221612&view=auto
==============================================================================
--- synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/upgrading.xml (added)
+++ synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/upgrading.xml Wed Dec 21 05:10:42 2011
@@ -0,0 +1,342 @@
+<?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>
+ <body>
+ <section name="Content">
+ <ul>
+ <li>
+ <a href="#General_comments">General comments</a>
+ </li>
+ <li>
+ <a href="#Upgrading_from_1.2_to_2.0.0">Upgrading from 1.2 to 2.0.0</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.0.0" id="Upgrading_from_1.2_to_2.0.0">
+ <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.0.0 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.0.0
+ 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.0.0 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.0.0 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.0.0 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.0.0
+ <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.0.0 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.0.0 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.0.0.
+ </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.0.0
+ 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.0.0 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.0.0
+ 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