Added: synapse/site/userguide/transports/vfs.html URL: http://svn.apache.org/viewvc/synapse/site/userguide/transports/vfs.html?rev=1777276&view=auto ============================================================================== --- synapse/site/userguide/transports/vfs.html (added) +++ synapse/site/userguide/transports/vfs.html Wed Jan 4 10:30:06 2017 @@ -0,0 +1,1128 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia at 2017-01-04 + | Rendered using Apache Maven Fluido Skin 1.4 +--> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="Date-Revision-yyyymmdd" content="20170104" /> + <meta http-equiv="Content-Language" content="en" /> + <title>Apache Synapse - + Apache Synapse - File Transport</title> + <link rel="stylesheet" href="../../css/apache-maven-fluido-1.4.min.css" /> + <link rel="stylesheet" href="../../css/site.css" /> + <link rel="stylesheet" href="../../css/print.css" media="print" /> + + + <script type="text/javascript" src="../../js/apache-maven-fluido-1.4.min.js"></script> + + + </head> + <body class="topBarDisabled"> + + + + <div class="container-fluid"> + <div id="banner"> + <div class="pull-left"> + <div id="bannerLeft"> + <h2>Apache Synapse</h2> + </div> + </div> + <div class="pull-right"> </div> + <div class="clear"><hr/></div> + </div> + + <div id="breadcrumbs"> + <ul class="breadcrumb"> + + + <li id="publishDate">Last Published: 2017-01-04 + <span class="divider">|</span> + </li> + <li id="projectVersion">Version: 3.0.0 + </li> + + + + + </ul> + </div> + + + <div class="row-fluid"> + <div id="leftColumn" class="span2"> + <div class="well sidebar-nav"> + + + <ul class="nav nav-list"> + <li class="nav-header">Main Menu</li> + + <li> + + <a href="../../index.html" title="Home"> + <span class="none"></span> + Home</a> + </li> + + <li> + + <a href="../../download.html" title="Download"> + <span class="none"></span> + Download</a> + </li> + + <li> + + <a href="../../history.html" title="History"> + <span class="none"></span> + History</a> + </li> + + <li> + + <a href="http://www.apache.org/licenses/LICENSE-2.0"; class="externalLink" title="License"> + <span class="none"></span> + License</a> + </li> + + <li> + + <a href="http://www.apache.org/foundation/thanks.html"; class="externalLink" title="Thanks"> + <span class="none"></span> + Thanks</a> + </li> + + <li> + + <a href="http://www.apache.org/foundation/sponsorship.html"; class="externalLink" title="Sponsorship"> + <span class="none"></span> + Sponsorship</a> + </li> + + <li> + + <a href="http://www.apache.org/security/"; class="externalLink" title="Security"> + <span class="none"></span> + Security</a> + </li> + <li class="nav-header">Documentation</li> + + <li> + + <a href="../../userguide/installation.html" title="Installation Guide"> + <span class="none"></span> + Installation Guide</a> + </li> + + <li> + + <a href="../../userguide/quick_start.html" title="Quick Start Guide"> + <span class="none"></span> + Quick Start Guide</a> + </li> + + <li> + + <a href="../../userguide/samples/setup/index.html" title="Samples Setup Guide"> + <span class="none"></span> + Samples Setup Guide</a> + </li> + + <li> + + <a href="../../userguide/samples.html" title="Samples Catalog"> + <span class="none"></span> + Samples Catalog</a> + </li> + + <li> + + <a href="../../userguide/config.html" title="Configuration Language"> + <span class="none"></span> + Configuration Language</a> + </li> + + <li> + + <a href="../../userguide/mediators.html" title="Mediators Catalog"> + <span class="none"></span> + Mediators Catalog</a> + </li> + + <li> + + <a href="../../userguide/transports.html" title="Transports Catalog"> + <span class="none"></span> + Transports Catalog</a> + </li> + + <li> + + <a href="../../userguide/properties.html" title="Properties Catalog"> + <span class="none"></span> + Properties Catalog</a> + </li> + + <li> + + <a href="../../userguide/xpath.html" title="XPath functions and Variables"> + <span class="none"></span> + XPath functions and Variables</a> + </li> + + <li> + + <a href="../../userguide/extending.html" title="Extending Synapse"> + <span class="none"></span> + Extending Synapse</a> + </li> + + <li> + + <a href="../../userguide/template_library.html" title="Synapse Template Libraries"> + <span class="none"></span> + Synapse Template Libraries</a> + </li> + + <li> + + <a href="../../userguide/upgrading.html" title="Upgrading"> + <span class="none"></span> + Upgrading</a> + </li> + + <li> + + <a href="../../userguide/deployment.html" title="Deployment"> + <span class="none"></span> + Deployment</a> + </li> + + <li> + + <a href="../../apidocs/" title="Javadocs"> + <span class="none"></span> + Javadocs</a> + </li> + + <li> + + <a href="../../userguide/faq.html" title="FAQ"> + <span class="none"></span> + FAQ</a> + </li> + <li class="nav-header">Developer Resources</li> + + <li> + + <a href="../../dev/developer-guide.html" title="Developer Guide"> + <span class="none"></span> + Developer Guide</a> + </li> + + <li> + + <a href="../../dev/best-practices.html" title="Development Best Practices"> + <span class="none"></span> + Development Best Practices</a> + </li> + + <li> + + <a href="../../dev/release-process.html" title="Release Process"> + <span class="none"></span> + Release Process</a> + </li> + <li class="nav-header">Project Details</li> + + <li> + + <a href="../../project-info.html" title="Overview"> + <span class="none"></span> + Overview</a> + </li> + + <li> + + <a href="../../mail-lists.html" title="Mailing Lists"> + <span class="none"></span> + Mailing Lists</a> + </li> + + <li> + + <a href="../../source-repository.html" title="Source Repository"> + <span class="none"></span> + Source Repository</a> + </li> + + <li> + + <a href="../../issue-tracking.html" title="Issue Tracking"> + <span class="none"></span> + Issue Tracking</a> + </li> + + <li> + + <a href="../../dependency-management.html" title="Dependencies"> + <span class="none"></span> + Dependencies</a> + </li> + + <li> + + <a href="../../team-list.html" title="Project Team"> + <span class="none"></span> + Project Team</a> + </li> + </ul> + + + + <hr /> + + <div id="poweredBy"> + <div class="clear"></div> + <div class="clear"></div> + <div class="clear"></div> + <div class="clear"></div> + <a href="http://maven.apache.org/"; title="Built by Maven" class="poweredBy"> + <img class="builtBy" alt="Built by Maven" src="../../images/logos/maven-feather.png" /> + </a> + </div> + </div> + </div> + + + <div id="bodyColumn" class="span10" > + + <!-- ~ 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. --> + + <a name="Contents"></a> +<div class="section" id="Contents"> +<h2>File Transport<a name="File_Transport"></a></h2> + +<ul> + +<li> + <a href="#Introduction">Introduction</a> + </li> + +<li> + <a href="#Configuration">Transport Configuration</a> + +<ul> + +<li><a href="#Listener">File Transport Listener (VFS Listener)</a></li> + +<li> + <a href="#Sender">File Transport Sender (VFS Sender)</a> + +<ul> + +<li><a href="#Locking">File Locking</a></li> + +<li><a href="#Passive">FTP Passive Mode</a></li> + +<li><a href="#Retry">Retrying on Error</a></li> + +<li><a href="#transport.vfs.UseTempFile">Using Temporary Files</a></li> + +<li><a href="#Append">Appending to Files</a></li> + +<li><a href="#OutOnly">Out-only Message Exchange Pattern</a></li> + </ul> + </li> + </ul> + </li> + +<li> + <a href="#SFTP">Using SFTP</a> + </li> + +<li> + <a href="#Issues">Known Issues</a> + </li> + </ul> + </div> + <a name="Introduction"></a> +<div class="section" id="Introduction"> +<h2>Introduction<a name="Introduction"></a></h2> + +<p> + The file transport, also known as the VFS (Virtual File System) transport, can be + used to read, mediate and write file content using Synapse. This transport allows + Synapse to interface with the local file system and remote file systems via + file transfer protocols such as FTP. + </p> + +<p> + The file transport is based on <a class="externalLink" href="http://commons.apache.org/proper/commons-vfs/";>Apache Commons VFS</a>, + and supports all the file transfer protocols supported by Commons VFS. This includes + interactions with the local file system, HTTP, HTTPS, FTP and SFTP (i.e. file transfer + over SSH). + </p> + +<p> + There is a fundamental difference between the file transport and transports such as + HTTP, and it is important to understand this difference to be able to use the file + 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 appropriate service based on the request URI. On the other hand, + the file transport only receives the payload of a message (i.e. the file), 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. For Synapse this means that the VFS transport + listener can only be used in conjunction with proxy services. The relevant service + parameters are specified in the proxy service configuration 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 the above example the file system location file:///var/spool/synapse/in is + explicitly bound to MyVFSService. Any file dropped in that location will be + pre-dispatched to MyVFSService, bypassing any other configured dispatch mechanisms + that would normally apply to messages received via HTTP. + </p> + +<p><a href="#Contents">[Back to top]</a></p> + </div> + <a name="Configuration"></a> +<div class="section" id="Configuration"> +<h2>Transport Configuration<a name="Transport_Configuration"></a></h2> + +<p> + The file transport consists of a transport listener component and a transport sender + component. Proxy services can read files using the file transport listener, and they + can write file content using the file transport sender. Following sections describe + how to configure these two components of the transport. + </p> + <a name="Listener"></a> +<div class="section" id="Listener"> +<h3>File Transport Listener (VFS Listener)<a name="File_Transport_Listener_VFS_Listener"></a></h3> + +<p> + Before a proxy service can read files, the VFS listener must be enabled in the + SYNAPSE_HOME/repository/conf/axis2.xml file of Synapse. Look + for the following XML configuration in the axis2.xml file, and uncomment it if + it's commented out. + </p> + +<div class="xmlConf"><transportReceiver name="vfs" class="org.apache.synapse.transport.vfs.VFSTransportListener"/></div> + +<p> + To configure a proxy service to receive messages via the VFS listener (i.e. read + files from some local or remote location), set the "transports" attribute on the + proxy service element to "vfs": + </p> + +<div class="xmlConf"><proxy name="MyVFSService" transports="vfs"> + ... +</proxy></div> + +<p> + It's also possible to expose a proxy service on VFS transport and several other + transports. Simply specify the required transports as a space-separated list in + the "transports" attribute: + </p> + +<div class="xmlConf"><proxy name="MyVFSService" transports="vfs http https"> + ... +</proxy></div> + +<p> + A proxy service configured with the VFS listener, can be further customized by + setting a number of parameters (some of which are required). Following table + lists all the supported service parameters. Please refer <a href="../samples/sample254.html">sample 254</a> + for an example that demonstrates how to use some of these settings. + </p> + +<table border="0" class="table table-striped"> + +<tr class="a"> + +<th>Parameter Name</th> + +<th>Description/Example</th> + +<th>Required</th> + +<th>Default</th> + </tr> + +<tr class="b"> + +<td>transport.vfs.FileURI</td> + +<td> + The primary location to read the file contents from. This must be + specified as a valid URI and it may point to a file or a directory. If + a directory location is specified, the transport will attempt to read + any file dropped into the directory. + +<div class="xmlConf"><parameter name="transport.vfs.FileURI">file:///home/user/test/in</parameter></div> + +<div class="xmlConf"><parameter name="transport.vfs.FileURI">sftp://bob:[email protected]/logs</parameter></div> + </td> + +<td>Yes</td> + +<td>N/A</td> + </tr> + +<tr class="a"> + +<td>transport.vfs.ContentType</td> + +<td> + The expected content type for files retrieved for this service. The VFS + transport uses this information to select the appropriate message builder. + +<div class="xmlConf"><parameter name="transport.vfs.ContentType">text/xml</parameter></div> + </td> + +<td>Yes</td> + +<td>N/A</td> + </tr> + +<tr class="b"> + +<td>transport.vfs.FileNamePattern</td> + +<td> + A file name regex pattern to match when fetching files from a directory + specified by the FileURI. + +<div class="xmlConf"><parameter name="transport.vfs.FileNamePattern">.*.xml</parameter></div> + </td> + +<td>No</td> + +<td>N/A</td> + </tr> + +<tr class="a"> + +<td>transport.PollInterval</td> + +<td> + The polling interval in seconds. + +<div class="xmlConf"><parameter name="transport.PollInterval">10</parameter></div> + </td> + +<td>No</td> + +<td>300</td> + </tr> + +<tr class="b"> + +<td>transport.vfs.ActionAfterProcess</td> + +<td> + Once a file has been read and successfully processed by Synapse (i.e. + without any errors and runtime exceptions), the file should be + either moved or deleted to prevent Synapse from processing the file for + a second time. This parameter specifies which of the above actions + should be taken. Allowed values are MOVE or DELETE. + +<div class="xmlConf"><parameter name="transport.vfs.ActionAfterProcess">MOVE</parameter></div> + </td> + +<td>No</td> + +<td>DELETE</td> + </tr> + +<tr class="a"> + +<td>transport.vfs.MoveAfterProcess</td> + +<td> + Specify the location to which the files should be moved after successfully + processing them. Required if transport.vfs.ActionAfterProcess is set to + MOVE. Ignored otherwise. Value must be a valid URI (local or remote). + +<div class="xmlConf"><parameter name="transport.vfs.MoveAfterProcess">file:///home/test/original</parameter></div> + </td> + +<td>No</td> + +<td>N/A</td> + </tr> + +<tr class="b"> + +<td>transport.vfs.ActionAfterFailures</td> + +<td> + If Synapse encounters an error while processing a file, the file should be + either moved or deleted to prevent Synapse from processing the file for + a second time. This parameter specifies which of the above actions + should be taken. Allowed values are MOVE or DELETE. + +<div class="xmlConf"><parameter name="transport.vfs.ActionAfterFailure">MOVE</parameter></div> + </td> + +<td>No</td> + +<td>DELETE</td> + </tr> + +<tr class="a"> + +<td>transport.vfs.MoveAfterFailure</td> + +<td> + Specify the location to which the files should be moved after a failure. R + equired if transport.vfs.ActionAfterFailure is set to + MOVE. Ignored otherwise. Value must be a valid URI (local or remote). + +<div class="xmlConf"><parameter name="transport.vfs.MoveAfterFailure">file:///home/user/test/error</parameter></div> + </td> + +<td>No</td> + +<td>N/A</td> + </tr> + +<tr class="b"> + +<td>transport.vfs.ReplyFileURI</td> + +<td> + Specify the reply file location as a URI, in case the proxy service + should generate a response message (file) after processing an input file. + +<div class="xmlConf"><parameter name="transport.vfs.ReplyFileURI">file:///home/user/test/out</parameter></div> + </td> + +<td>No</td> + +<td>N/A</td> + </tr> + +<tr class="a"> + +<td>transport.vfs.ReplyFileName</td> + +<td> + Name of the response file that should be generated by the proxy service. + +<div class="xmlConf"><parameter name="transport.vfs.ReplyFileName">file:///home/user/test/out</parameter></div> + </td> + +<td>No</td> + +<td>response.xml or response.dat depending on the content type of the response</td> + </tr> + +<tr class="b"> + +<td>transport.vfs.MoveTimestampFormat</td> + +<td> + Must be a timestamp format string compatible with + <a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html";>java.text.SimpleDateFormat</a>. + If specified, Synapse will append a timestamp in the specified format to + all the file names, whenever a file is moved to a new location (i.e. when + moving a file after processing it or after a failure). + +<div class="xmlConf"><parameter name="transport.vfs.MoveTimestampFormat">yy-MM-dd:HHmmss</parameter></div> + </td> + +<td>No</td> + +<td>N/A</td> + </tr> + +<tr class="a"> + +<td>transport.vfs.Locking</td> + +<td> + File locking makes sure that each file is accessed by only one proxy + service at any given instant. This is important when multiple proxy + services are reading files from the same location or when one proxy service + is configured to read the files written by another proxy service. + By default file locking is globally enabled in the VFS transport, and + this parameter lets you configure the locking behavior on a per service + basis. Possible values are enable or disable, and both these values are + important because locking can be disabled at the global level by + specifying that at the transport receiver configuration (in axis2.xml) and + selectively enable locking only for a set of services. To configure + global locking behavior, set this parameter in the axis2.xml under the + VFS transport receiver configuration. + +<div class="xmlConf"><parameter name="transport.vfs.Locking">disable</parameter></div> + </td> + +<td>No</td> + +<td>enable</td> + </tr> + +<tr class="b"> + +<td>transport.vfs.Streaming</td> + +<td> + If this parameter is set to true, the transport will attempt to use a + javax.activation.DataSource (instead of a java.io.InputStream ) 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. + This allows processing of the message without storing the entire content in memory. + It also has two other side effects: + +<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> + 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. + +<div class="xmlConf"><parameter name="transport.vfs.Streaming">true</parameter></div> + </td> + +<td>No</td> + +<td>false</td> + </tr> + +<tr class="a"> + +<td>transport.vfs.MaxRetryCount</td> + +<td> + If the file transport listener encounters an error while trying to + read a file, it will try to read the file again after some time. This + parameter sets the maximum number of times the listener should retry + before giving up. Use the <a href="#transport.vfs.ReconnectTimeout">transport.vfs.ReconnectTimeout</a> + parameter to set the time duration between retries. + +<div class="xmlConf"><parameter name="transport.vfs.MaxRetryCount">3</parameter></div> + </td> + +<td>No</td> + +<td>3</td> + </tr> + +<tr class="b"> + +<td>transport.vfs.ReconnectTimeout <a name="transport.vfs.ReconnectTimeout"></a></td> + +<td> + The amount of time (in seconds) the current polling task should be + suspended for after a failed attempt to resolve a file. + +<div class="xmlConf"><parameter name="transport.vfs.ReconnectTimeout">30000</parameter></div> + </td> + +<td>No</td> + +<td>30</td> + </tr> + +<tr class="a"> + +<td>transport.vfs.FailedRecordsFileName <a name="transport.vfs.FailedRecordsFileName"></a></td> + +<td> + Once a file has been fully processed, it will be moved to a new + location or deleted. If this operation fails, a log entry with the + failure details can be written to a separate log file. This parameter + controls the name of this failure log file. + +<div class="xmlConf"><parameter name="transport.vfs.FailedRecordsFileName">move-errors.txt</parameter></div> + </td> + +<td>No</td> + +<td>vfs-move-failed-records.properties</td> + </tr> + +<tr class="b"> + +<td>transport.vfs.FailedRecordsFileDestination</td> + +<td> + Once a file has been fully processed, it will be moved to a new + location or deleted. If this operation fails, a log entry with the + failure details can be written to a separate log file. This parameter + controls the location (directory path) of this failure log file. To set + the name of the log file use the <a href="#transport.vfs.FailedRecordsFileName">transport.vfs.FailedRecordsFileName</a> + parameter. + +<div class="xmlConf"><parameter name="transport.vfs.FailedRecordsFileDestination">logs/</parameter></div> + </td> + +<td>No</td> + +<td>repository/conf</td> + </tr> + +<tr class="a"> + +<td>transport.vfs.FailedRecordNextRetryDuration</td> + +<td> + When a move operation has failed, the operation will be retried after this + amount of time (configured in milliseconds). + +<div class="xmlConf"><parameter name="transport.vfs.FailedRecordNextRetryDuration">5000</parameter></div> + </td> + +<td>No</td> + +<td>3000</td> + </tr> + +<tr class="b"> + +<td>transport.vfs.MoveAfterFailedMove</td> + +<td> + The destination to move the file after a failed move attempt. + +<div class="xmlConf"><parameter name="transport.vfs.MoveAfterFailedMove">repository/move-errors</parameter></div> + </td> + +<td>No</td> + +<td>N/A</td> + </tr> + +<tr class="a"> + +<td>transport.vfs.MoveFailedRecordTimestampFormat</td> + +<td> + The time stamp format to use when reporting failed move operations in + the log. + +<div class="xmlConf"><parameter name="transport.vfs.MoveFailedRecordTimestampFormat">HH:mm:ss</parameter></div> + </td> + +<td>No</td> + +<td>dd/MM/yyyy/ HH:mm:ss</td> + </tr> + </table> + +<p><a href="#Contents">[Back to top]</a></p> + </div> + <a name="Sender"></a> +<div class="section" id="Sender"> +<h3>File Transport Sender (VFS Sender)<a name="File_Transport_Sender_VFS_Sender"></a></h3> + +<p> + The file transport sender allows writing outgoing messages to local or remote + files. To activate the file transport sender, simply uncomment the following + transport sender configuration in the <b>SYNAPSE_HOME/repository/conf/axis2.xml</b> + file. + </p> + +<div class="xmlConf"><transportSender name="vfs" class="org.apache.synapse.transport.vfs.VFSTransportSender"/></div> + +<p> + To send a message using the file transport, define a Synapse endpoint with an + address that starts with the prefix 'vfs:'. The rest of the address should be a + valid local or remote file URI. An example is shown below: + </p> + +<div class="xmlConf"><endpoint> + <address uri="vfs:file:///var/spool/synapse/out"/> +</endpoint></div> + +<p> + Some more example file URIs are listed below. Remember to prefix each + URI with the string 'vfs:' when using these to define Synapse endpoints. + Refer <a class="externalLink" href="http://commons.apache.org/vfs/filesystems.html";>http://commons.apache.org/vfs/filesystems.html</a> + for a complete list of Commons VFS supported protocols and their corresponding + URI formats. + </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</tt> + </li> + </ul> + + +<div class="section"> +<h4>File Locking <a name="Locking"></a><a name="File_Locking"></a></h4> + +<p> + By default file locking is globally enabled for the file transport sender. + This behavior can be overridden at the endpoint level by specifying + <tt>transport.vfs.Locking</tt> as a URL query parameter with the appropriate value + (enable/disable) on a given endpoint: + </p> + +<div class="xmlConf"><endpoint> + <address uri="vfs:file:///var/spool/synapse/out?transport.vfs.Locking=disable"/> +</endpoint></div> + +<p> + You may also change the global locking behavior by setting the <tt>transport.vfs.Locking</tt> + parameter in the file transport sender configuration in axis2.xml file. + </p> + + </div> +<div class="section"> +<h4>FTP Passive Mode <a name="Passive"></a><a name="FTP_Passive_Mode"></a></h4> + +<p> + When writing to remote file locations using a protocol such as FTP, you might + want Synapse to communicate with the FTP server in the passive mode. To + configure this behavior, simply add the query parameter <tt>vfs.passive</tt> to the + endpoint address: + </p> + +<div class="xmlConf"><endpoint> + <address uri="vfs:ftp://myusername:mypassword@somehost/pub/downloads/somefile.tgz?vfs.passive=true"/> +</endpoint></div> + + </div> +<div class="section"> +<h4>Retrying on Error <a name="Retry"></a><a name="Retrying_on_Error"></a></h4> + +<p> + When the file transport sender encounters an error while trying to write a file, + it can retry after some time. This is useful to recover from certain types of + transient I/O errors and network connectivity issues. Following parameters + can be configured as URL query parameters on the file (vfs) endpoints to + make use of this feature. + </p> + +<table border="0" class="table table-striped"> + +<tr class="a"> + +<th>Parameter Name</th> + +<th>Description/Example</th> + +<th>Required</th> + +<th>Default</th> + </tr> + +<tr class="b"> + +<td>transport.vfs.MaxRetryCount</td> + +<td> + Maximum number of retries to perform before giving up. + </td> + +<td>No</td> + +<td>3</td> + </tr> + +<tr class="a"> + +<td>transport.vfs.ReconnectTimeout</td> + +<td> + Time duration (in seconds) between retry attempts. + </td> + +<td>No</td> + +<td>30</td> + </tr> + </table> + + </div> +<div class="section"> +<h4>Using Temporary Files <a name="transport.vfs.UseTempFile"></a><a name="Using_Temporary_Files"></a></h4> + +<p> + The file transport sender does not write file content atomically. Therefore a + process reading a file updated by Synapse, may read partial + content. To get around this limitation, the temporary file support can be + activated on the target file (vfs) endpoint: + </p> + +<div class="xmlConf"><endpoint> + <address uri="vfs:file:///var/spool/synapse/out?transport.vfs.UseTempFile=true"/> +</endpoint></div> + +<p> + This forces the file transport sender to write the data to a temporary file and + then move the temporary file to the actual destination configured in the file + endpoint. On most operating systems (e.g. Unix/Linux, Windows), this delivers the + desired atomic file update behavior. When the file endpoint points to a remote + file system, the temporary files will be created on the remote file system, thus + preserving the atomic update behavior. + </p> + + </div> +<div class="section"> +<h4>Appending to Files <a name="Append"></a><a name="Appending_to_Files"></a></h4> + +<p> + When updating an existing file, the file transport sender usually overwrites the + old content. To get append behavior instead, set transport.vfs.Append parameter + on the target endpoint: + </p> + +<div class="xmlConf"><endpoint> + <address uri="vfs:file:///var/spool/synapse/out?transport.vfs.Append=true"/> +</endpoint></div> + + </div> +<div class="section"> +<h4>Out-only Message Exchange Pattern <a name="OutOnly"></a><a name="Out-only_Message_Exchange_Pattern"></a></h4> + +<p> + It should be noted that by its nature, the file transport sender doesn't support + synchronous responses and should only be invoked using the out-only message + exchange pattern. In a Synapse mediation (sequence/proxy/API), this can be forced + using the following mediator: + </p> + +<div class="xmlConf"><property name="OUT_ONLY" value="true"/></div> + +<p><a href="#Contents">[Back to top]</a></p> + </div></div> + </div> + <a name="SFTP"></a> +<div class="section" id="SFTP"> +<h2>Using SFTP<a name="Using_SFTP"></a></h2> + +<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> + </div> + <a name="Issues"></a> +<div class="section" id="Issues"> +<h2>Known issues<a name="Known_issues"></a></h2> + +<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. + Use the <a href="#transport.vfs.UseTempFile">transport.vfs.UseTempFile</a> endpoint + parameter to get around this issue. + </p> + </div> + + + </div> + </div> + </div> + + <hr/> + + <footer> + <div class="container-fluid"> + <div class="row-fluid"> + <p >Copyright © 2005–2017 + <a href="http://www.apache.org/";>Apache Software Foundation</a>. + All rights reserved. + + </p> + </div> + + + </div> + </footer> + </body> +</html>
Added: synapse/site/userguide/xpath.html URL: http://svn.apache.org/viewvc/synapse/site/userguide/xpath.html?rev=1777276&view=auto ============================================================================== --- synapse/site/userguide/xpath.html (added) +++ synapse/site/userguide/xpath.html Wed Jan 4 10:30:06 2017 @@ -0,0 +1,730 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia at 2017-01-04 + | Rendered using Apache Maven Fluido Skin 1.4 +--> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="Date-Revision-yyyymmdd" content="20170104" /> + <meta http-equiv="Content-Language" content="en" /> + <title>Apache Synapse - + Apache Synapse - XPath Functions and Variables</title> + <link rel="stylesheet" href="../css/apache-maven-fluido-1.4.min.css" /> + <link rel="stylesheet" href="../css/site.css" /> + <link rel="stylesheet" href="../css/print.css" media="print" /> + + + <script type="text/javascript" src="../js/apache-maven-fluido-1.4.min.js"></script> + + + </head> + <body class="topBarDisabled"> + + + + <div class="container-fluid"> + <div id="banner"> + <div class="pull-left"> + <div id="bannerLeft"> + <h2>Apache Synapse</h2> + </div> + </div> + <div class="pull-right"> </div> + <div class="clear"><hr/></div> + </div> + + <div id="breadcrumbs"> + <ul class="breadcrumb"> + + + <li id="publishDate">Last Published: 2017-01-04 + <span class="divider">|</span> + </li> + <li id="projectVersion">Version: 3.0.0 + </li> + + + + + </ul> + </div> + + + <div class="row-fluid"> + <div id="leftColumn" class="span2"> + <div class="well sidebar-nav"> + + + <ul class="nav nav-list"> + <li class="nav-header">Main Menu</li> + + <li> + + <a href="../index.html" title="Home"> + <span class="none"></span> + Home</a> + </li> + + <li> + + <a href="../download.html" title="Download"> + <span class="none"></span> + Download</a> + </li> + + <li> + + <a href="../history.html" title="History"> + <span class="none"></span> + History</a> + </li> + + <li> + + <a href="http://www.apache.org/licenses/LICENSE-2.0"; class="externalLink" title="License"> + <span class="none"></span> + License</a> + </li> + + <li> + + <a href="http://www.apache.org/foundation/thanks.html"; class="externalLink" title="Thanks"> + <span class="none"></span> + Thanks</a> + </li> + + <li> + + <a href="http://www.apache.org/foundation/sponsorship.html"; class="externalLink" title="Sponsorship"> + <span class="none"></span> + Sponsorship</a> + </li> + + <li> + + <a href="http://www.apache.org/security/"; class="externalLink" title="Security"> + <span class="none"></span> + Security</a> + </li> + <li class="nav-header">Documentation</li> + + <li> + + <a href="../userguide/installation.html" title="Installation Guide"> + <span class="none"></span> + Installation Guide</a> + </li> + + <li> + + <a href="../userguide/quick_start.html" title="Quick Start Guide"> + <span class="none"></span> + Quick Start Guide</a> + </li> + + <li> + + <a href="../userguide/samples/setup/index.html" title="Samples Setup Guide"> + <span class="none"></span> + Samples Setup Guide</a> + </li> + + <li> + + <a href="../userguide/samples.html" title="Samples Catalog"> + <span class="none"></span> + Samples Catalog</a> + </li> + + <li> + + <a href="../userguide/config.html" title="Configuration Language"> + <span class="none"></span> + Configuration Language</a> + </li> + + <li> + + <a href="../userguide/mediators.html" title="Mediators Catalog"> + <span class="none"></span> + Mediators Catalog</a> + </li> + + <li> + + <a href="../userguide/transports.html" title="Transports Catalog"> + <span class="none"></span> + Transports Catalog</a> + </li> + + <li> + + <a href="../userguide/properties.html" title="Properties Catalog"> + <span class="none"></span> + Properties Catalog</a> + </li> + + <li class="active"> + + <a href="#"><span class="none"></span>XPath functions and Variables</a> + </li> + + <li> + + <a href="../userguide/extending.html" title="Extending Synapse"> + <span class="none"></span> + Extending Synapse</a> + </li> + + <li> + + <a href="../userguide/template_library.html" title="Synapse Template Libraries"> + <span class="none"></span> + Synapse Template Libraries</a> + </li> + + <li> + + <a href="../userguide/upgrading.html" title="Upgrading"> + <span class="none"></span> + Upgrading</a> + </li> + + <li> + + <a href="../userguide/deployment.html" title="Deployment"> + <span class="none"></span> + Deployment</a> + </li> + + <li> + + <a href="../apidocs/" title="Javadocs"> + <span class="none"></span> + Javadocs</a> + </li> + + <li> + + <a href="../userguide/faq.html" title="FAQ"> + <span class="none"></span> + FAQ</a> + </li> + <li class="nav-header">Developer Resources</li> + + <li> + + <a href="../dev/developer-guide.html" title="Developer Guide"> + <span class="none"></span> + Developer Guide</a> + </li> + + <li> + + <a href="../dev/best-practices.html" title="Development Best Practices"> + <span class="none"></span> + Development Best Practices</a> + </li> + + <li> + + <a href="../dev/release-process.html" title="Release Process"> + <span class="none"></span> + Release Process</a> + </li> + <li class="nav-header">Project Details</li> + + <li> + + <a href="../project-info.html" title="Overview"> + <span class="none"></span> + Overview</a> + </li> + + <li> + + <a href="../mail-lists.html" title="Mailing Lists"> + <span class="none"></span> + Mailing Lists</a> + </li> + + <li> + + <a href="../source-repository.html" title="Source Repository"> + <span class="none"></span> + Source Repository</a> + </li> + + <li> + + <a href="../issue-tracking.html" title="Issue Tracking"> + <span class="none"></span> + Issue Tracking</a> + </li> + + <li> + + <a href="../dependency-management.html" title="Dependencies"> + <span class="none"></span> + Dependencies</a> + </li> + + <li> + + <a href="../team-list.html" title="Project Team"> + <span class="none"></span> + Project Team</a> + </li> + </ul> + + + + <hr /> + + <div id="poweredBy"> + <div class="clear"></div> + <div class="clear"></div> + <div class="clear"></div> + <div class="clear"></div> + <a href="http://maven.apache.org/"; title="Built by Maven" class="poweredBy"> + <img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /> + </a> + </div> + </div> + </div> + + + <div id="bodyColumn" class="span10" > + + <!-- ~ 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. --> + + <a name="Intro"></a> +<div class="section" id="Intro"> +<h2>Introduction<a name="Introduction"></a></h2> + +<p> + Apache Synapse supports standard XPath functions and variables through its + underlying XPath + engine. Apart from standard XPath functions, there are several custom XPath + functions + and variables defined by Synapse to retrieve various message context properties. + </p> + </div> + +<div class="section"> +<h2>Contents<a name="Contents"></a></h2> + +<ul> + +<li> + <a href="#functions">Functions</a> + +<ul> + +<li> + <a href="#get_prop">get-property</a> + </li> + </ul> + +<ul> + +<li> + <a href="#base64_encode">base64Encode</a> + </li> + </ul> + +<ul> + +<li> + <a href="#base64_decode">base64Decode</a> + </li> + </ul> + +<ul> + +<li> + <a href="#url_encode">url-encode</a> + </li> + </ul> + </li> + +<li> + <a href="#var">Variables</a> + +<ul> + +<li> + <a href="#axis2">axis2</a> + </li> + </ul> + +<ul> + +<li> + <a href="#trp">trp</a> + </li> + </ul> + +<ul> + +<li> + <a href="#ctx">ctx</a> + </li> + </ul> + +<ul> + +<li> + <a href="#url">url</a> + </li> + </ul> + +<ul> + +<li> + <a href="#body">body</a> + </li> + </ul> + +<ul> + +<li> + <a href="#header">header</a> + </li> + </ul> + </li> + </ul> + </div> + + <a name="functions"></a> +<div class="section" id="functions"> +<h2>Custom Functions<a name="Custom_Functions"></a></h2> + <a name="get_prop"></a> +<div class="section" id="get_prop"> +<h3>get-property function<a name="get-property_function"></a></h3> + +<p> + Get property function retrieves a property from the message context at the given + scope. + If the scope is not specified, property is retrieved from the default synapse + scope. + </p> + +<p>Syntax:</p> + +<div class="xmlConf">get-property(String scope, String propertyName) +get-property(String propertyName)</div> + + +<div class="section"> +<h4> + Supported Scopes + <a name="Supported_Scopes"></a></h4> + +<ul> + +<li>default</li> + +<li>axis2</li> + +<li>transport</li> + +<li>registry</li> + +<li>system</li> + </ul> + + </div> +<div class="section" id="default_scope"> +<h4 id="default_scope">Default scope</h4> + +<p> + Message context properties residing in Synapse scope can be retrieved from the + default scope. These are the properties directly set on the Synapse MessageContext + instance. + Apart from user defined properties, following special properties can also be + retrieved from the default scope. + </p> + +<table class="table table-striped" border="1" cellpadding="1" cellspacing="1"> + <tbody> + +<tr class="a"> + +<td>Name</td> + +<td>Return Value</td> + </tr> + +<tr class="b"> + +<td>To</td> + +<td>Incoming URL as a String or empty string if a To address is + not defined. + </td> + </tr> + +<tr class="a"> + +<td>From</td> + +<td>From address as a String or empty string if a From address + is not defined + </td> + </tr> + +<tr class="b"> + +<td>Action</td> + +<td>SOAP Action header value as a String or empty string + if a Action is not defined + </td> + </tr> + +<tr class="a"> + +<td>FaultTo</td> + +<td>SOAP FautTo header value as a String or empty string if a + FaultTo address is not defined + </td> + </tr> + +<tr class="b"> + +<td>ReplyTo</td> + +<td>ReplyTo header value as a String or empty string if a + ReplyTo address is not defined + </td> + </tr> + +<tr class="a"> + +<td>MessageID</td> + +<td>A unique identifier (UUID) for the message as a String . + This id is guaranteed to be unique. + </td> + </tr> + +<tr class="b"> + +<td>FAULT</td> + +<td>TRUE if the message has a fault or empty string if message doesn't + have a + fault + </td> + </tr> + +<tr class="a"> + +<td>MESSAGE_FORMAT</td> + +<td>Returns pox, get, soap11, soap12 depending on the message. If a + message type + is unknown this returns soap12 + </td> + </tr> + +<tr class="b"> + +<td>OperationName</td> + +<td>Operation name corresponding to the message. + </td> + </tr> + </tbody> + </table> + + </div> +<div class="section" id="axis2_scope"> +<h4 id="axis2_scope">Axis2 scope</h4> + +<p> + Message context properties residing in axis2 scope can be retrieved from the axis2 + scope. These are the properties set on the underlying Axis2 MessageContext object. + </p> + + </div> +<div class="section" id="transport_scope"> +<h4 id="transport_scope">Transport scope</h4> + +<p> + Message context properties residing in transport scope can be retrieved from the + transport scope. These are the transport headers set on the MessageContext. + </p> + + </div> +<div class="section" id="reg_scope"> +<h4 id="reg_scope">Registry scope</h4> + +<p>Properties residing in registry can be retrieved from the registry scope.</p> + + </div> +<div class="section" id="system_scope"> +<h4 id="system_scope">System scope</h4> + +<p>Java System properties can be retrieved from the system scope.</p> + + </div></div> + <a name="base64_encode"></a> +<div class="section" id="base64_encode"> +<h3>base64Encode function<a name="base64Encode_function"></a></h3> + +<p>Returns the base64 encoded value of the argument.</p> + +<p>Syntax:</p> + +<div class="xmlConf">base64Encode(String value)</div> + </div> + <a name="base64_decode"></a> +<div class="section" id="base64_decode"> +<h3>base64Decode function<a name="base64Decode_function"></a></h3> + +<p>Returns the base64 decoded value of the argument.</p> + +<p>Syntax:</p> + +<div class="xmlConf">base64Decode(String value)</div> + </div> + <a name="url_encode"></a> +<div class="section" id="url_encode"> +<h3>url-encode function<a name="url-encode_function"></a></h3> + +<p>Returns the URL encoded value of the argument.</p> + +<p>Syntax:</p> + +<div class="xmlConf">url-encode(String value)</div> + </div> + </div> + <a name="var"></a> +<div class="section" id="var"> +<h2>Variables<a name="Variables"></a></h2> + +<p>There are several XPath variables supported by Synapse. These are used for + accessing + various + properties from the message context + </p> + +<ul> + +<li>$axis2</li> + +<li>$trp</li> + +<li>$ctx</li> + +<li>$url</li> + +<li>$body</li> + +<li>$header</li> + </ul> + + +<p>These XPath variables get the properties at various scopes.</p> + + +<div class="section"> +<div class="section" id="ctx"> +<h4 id="ctx">$ctx</h4> + +<p>Variable prefix for accessing the MessageContext properties in default scope.</p> + +<p>i.e To get the property named 'foo' at the default scope use the following XPath + expression + </p> + +<div class="xmlConf">$ctx:foo</div> + + </div> +<div class="section" id="axis2"> +<h4 id="axis2">$axis2</h4> + +<p>Variable prefix for accessing the axis2 MessageContext properties</p> + +<p>i.e. To get the property named 'messageType' use the following XPath expression</p> + +<div class="xmlConf">$axis2:messageType</div> + + </div> +<div class="section" id="trp"> +<h4 id="trp">$trp</h4> + +<p>Variable prefix for accessing transport headers of the message</p> + +<p>i.e. To get the transport header named Content-Type use the following XPath + expression + </p> + +<div class="xmlConf">$trp:Content-Type</div> + + </div> +<div class="section" id="url"> +<h4 id="url">$url</h4> + +<p>Variable prefix for accessing URL parameters of the message</p> + + +<p>i.e. To get the URL parameter named 'bar' use the following XPth expression</p> + +<div class="xmlConf">$url:bar</div> + + </div> +<div class="section" id="body"> +<h4 id="body">$body</h4> + +<p>Get the message body</p> + + </div> +<div class="section" id="header"> +<h4 id="header">$header</h4> + +<p>Get the soap header</p> + </div></div></div> + + + </div> + </div> + </div> + + <hr/> + + <footer> + <div class="container-fluid"> + <div class="row-fluid"> + <p >Copyright © 2005–2017 + <a href="http://www.apache.org/";>Apache Software Foundation</a>. + All rights reserved. + + </p> + </div> + + + </div> + </footer> + </body> +</html>
