Added: synapse/site/3_0_2/userguide/transports/vfs.html URL: http://svn.apache.org/viewvc/synapse/site/3_0_2/userguide/transports/vfs.html?rev=1909775&view=auto ============================================================================== --- synapse/site/3_0_2/userguide/transports/vfs.html (added) +++ synapse/site/3_0_2/userguide/transports/vfs.html Fri May 12 16:09:34 2023 @@ -0,0 +1,890 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2023-05-04 + | Rendered using Apache Maven Fluido Skin 1.6 +--> +<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="20230504" /> + <meta http-equiv="Content-Language" content="en" /> + <title>Apache Synapse – Apache Synapse - File Transport</title> + <link rel="stylesheet" href="../../css/apache-maven-fluido-1.6.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.6.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: 2023-05-04<span class="divider">|</span> +</li> + <li id="projectVersion">Version: 3.0.2</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" > + + + <a name="Contents"></a> +<div class="section" id="Contents"> +<h2><a name="File_Transport"></a>File Transport</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><a name="Introduction"></a>Introduction</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><a name="Transport_Configuration"></a>Transport Configuration</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><a name="File_Transport_Listener_VFS_Listener"></a>File Transport Listener (VFS Listener)</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:passw...@example.com/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><a name="File_Transport_Sender_VFS_Sender"></a>File Transport Sender (VFS Sender)</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><a name="File_Locking"></a>File Locking <a name="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><a name="FTP_Passive_Mode"></a>FTP Passive Mode <a name="Passive"></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><a name="Retrying_on_Error"></a>Retrying on Error <a name="Retry"></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><a name="Using_Temporary_Files"></a>Using Temporary Files <a name="transport.vfs.UseTempFile"></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><a name="Appending_to_Files"></a>Appending to Files <a name="Append"></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><a name="Out-only_Message_Exchange_Pattern"></a>Out-only Message Exchange Pattern <a name="OutOnly"></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><a name="Using_SFTP"></a>Using SFTP</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><a name="Known_issues"></a>Known issues</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–2023 +<a href="http://www.apache.org/";>Apache Software Foundation</a>. +All rights reserved.</p> + </div> + </div> + </footer> + </body> +</html>
Added: synapse/site/3_0_2/userguide/upgrading.html URL: http://svn.apache.org/viewvc/synapse/site/3_0_2/userguide/upgrading.html?rev=1909775&view=auto ============================================================================== --- synapse/site/3_0_2/userguide/upgrading.html (added) +++ synapse/site/3_0_2/userguide/upgrading.html Fri May 12 16:09:34 2023 @@ -0,0 +1,578 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2023-05-04 + | Rendered using Apache Maven Fluido Skin 1.6 +--> +<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="20230504" /> + <meta http-equiv="Content-Language" content="en" /> + <title>Apache Synapse – Apache Synapse - Upgrading to the Latest Version</title> + <link rel="stylesheet" href="../css/apache-maven-fluido-1.6.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.6.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: 2023-05-04<span class="divider">|</span> +</li> + <li id="projectVersion">Version: 3.0.2</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 class="active"><a href="#"><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" > + + + <div class="section"> +<h2><a name="Upgrading_to_the_Latest_Version"></a>Upgrading to the Latest Version</h2> + +<p> + If you are using an older version of Synapse (1.x/2.x) and now looking to migrate to + the latest versions (3.x) this document would be a good starting point. This + article provides information on steps that need to be carried out to smoothly + migrate from an older release of Synapse to the latest version. If you are migrating from 1.x version + to 3.x we recommend you follow the 1.x -> 2.x migration followed by the 2.x -> 3.x. + </p> + </div> + +<div class="section"> +<h2><a name="Contents"></a>Contents</h2> + +<ul> + +<li> + <a href="#General_comments">General comments</a> + </li> + +<li> + <a href="#Upgrading_from_2.1_to_3.0">Upgrading from 2.1 to 3.0</a> + +<ul> + +<li> + <a href="#Custom_Extensions_3.0">Custom Extensions</a> + </li> + +<li> + <a href="#New_mediators_3.0">Respond and Loopback Mediators</a> + </li> + </ul> + </li> + +<li> + <a href="#Upgrading_from_1.2_to_2.1">Upgrading from 1.2 to 2.1</a> + +<ul> + +<li> + <a href="#Configuration_file_vs_multi_XML_configuration">Configuration file vs multi XML configuration</a> + </li> + +<li> + <a href="#Endpoint_URLs_for_proxy_services">Endpoint URLs for proxy services</a> + </li> + +<li> + <a href="#Mediator_Deployer">Mediator Deployer</a> + </li> + +<li> + <a href="#Main_Sequence">Main Sequence</a> + </li> + +<li> + <a href="#Filter_Mediator">Filter Mediator</a> + </li> + +<li> + <a href="#Migration_Tool">Migration Tool</a> + </li> + +<li> + <a href="#Custom_Extensions_and_API_changes">Custom Extensions and API changes</a> + </li> + </ul> + </li> + </ul> + </div> + <a name="General_comments"></a> +<div class="section" id="General_comments"> +<h2><a name="General_comments"></a>General comments</h2> + +<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 style="list-style-type: decimal"> + +<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 introducing 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> + </div> + + <a name="Upgrading_from_2.1_to_3.0"></a> +<div class="section" id="Upgrading_from_2.1_to_3.0"> +<h2><a name="Upgrading_from_2.1_to_3.0"></a>Upgrading from 2.1 to 3.0</h2> + <a name="Custom_Extensions_3.0"></a> +<div class="section" id="Custom_Extensions_3.0"> +<h3><a name="Custom_Extensions"></a>Custom Extensions</h3> + +<p> + Synapse 3.0 introduces the PassThrough HTTP Transport which improves HTTP transport performance by removing + intermediary buffer use when there is no requirement to read an HTTP payload (i.e. message is merely passed + through). If you have custom extensions that depend on accessing or reading buffers directly, you + may require to change your code to trigger the PassThrough transport to build the payload. This can + be done using the <a href="../apidocs/org/apache/synapse/transport/passthru/util/RelayUtils.html">RelayUtils#buildMessage()</a> + static methods. + </p> + </div> + <a name="New_mediators_3.0"></a> +<div class="section" id="New_mediators_3.0"> +<h3><a name="Respond_and_Loopback_Mediators"></a>Respond and Loopback Mediators</h3> + +<p> + <a href="mediators.html#Respond">Respond</a> and <a href="mediators.html#Loopback">Loopback</a> + are new mediators introduced in Apache Synapse 3.0. <a href="mediators.html#Respond">Respond</a> provides + a mechanism to send a message back to the client as a response. In older versions of Apache Synapse + we would use the <a href="mediators.html#Send">Send</a> mediator to respond back to a client either + after a message is received from a backend in an out sequence or force a response back to the client + using a series of mediators as follows: + </p> + +<div class="xmlConf"> +<header name="To" action="remove"/> +<property name="RESPONSE" value="true" scope="default" type="STRING"/> +<property name="NO_ENTITY_BODY" scope="axis2" action="remove"/> +<send/> + </div> + +<p> + We can replace above methods with the <a href="mediators.html#Respond">Respond</a> mediator anywhere + in the mediation flow to respond back to the client with the current message. Any mediators residing + after the <a href="mediators.html#Respond">Respond</a> mediator will be ignored. + </p> + + +<p>Similarly the <a href="mediators.html#Loopback">Loopback</a> mediator is used to jump the flow from + an in sequence to the out sequence ignoring any mediators residing after the + <a href="mediators.html#Loopback">Loopback</a> mediator. <a href="mediators.html#Loopback">Loopback</a> + mediator has no effect from inside an out sequence. + </p> + </div> + </div> + + <a name="Upgrading_from_1.2_to_2.1"></a> +<div class="section" id="Upgrading_from_1.2_to_2.1"> +<h2><a name="Upgrading_from_1.2_to_2.1"></a>Upgrading from 1.2 to 2.1</h2> + <a name="Configuration_file_vs_multi_XML_configuration"></a> +<div class="section" id="Configuration_file_vs_multi_XML_configuration"> +<h3><a name="Configuration_file_vs_multi_XML_configuration"></a>Configuration file vs multi XML configuration</h3> + +<p> + In 1.2 you have been using a single synapse.xml file which resides on the + repository/conf directory of the distribution, where as on 2.1 we have structured + this into a configuration repository with multiple directories to have different + artifact types and each and every artifact configuration to reside on a different + files inside the desired repository directory. This repository directory on the 2.1 + release resides in the repository/conf directory too, and named as synapse-config. + The repository directory structure inside the synapse-config directory + looks like follows; + </p> + +<div class="xmlConf">synapse-config + /api + /endpoints + /event-sources + /local-entries + /priority-executors + /proxy-services + /sequences + main.xml + fault.xml + /tasks + /templates + registry.xml + synapse.xml</div> + +<p> + As you can see in the above sketch of the repository though it is a repository based + configuration, it also supports the old style single flat synapse.xml file in which + case it has to reside inside the root of the repository. + </p> + +<p> + So the easiest way to migrate the configuration is to move your already existing + synapse.xml file in repository/conf directory in 1.2 version into the + repository/conf/synapse-config directory of the 2.x version. <i>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.</i> + </p> + </div> + <a name="Endpoint_URLs_for_proxy_services"></a> +<div class="section" id="Endpoint_URLs_for_proxy_services"> +<h3><a name="Endpoint_URLs_for_proxy_services"></a>Endpoint URLs for proxy services</h3> + +<p> + In release 2.1 the endpoint URLs for proxy services have changed from + <tt>/soap</tt> to <tt>/services</tt>. E.g. <tt>http://localhost:8280/services/StockQuote</tt> + should be used instead of <tt>http://localhost:8280/soap/StockQuote</tt>. + </p> + </div> + <a name="Mediator_Deployer"></a> +<div class="section" id="Mediator_Deployer"> +<h3><a name="MediatorDeployer"></a>MediatorDeployer</h3> + +<p> + Release 1.3 has enhanced capabilities for extension deployment. While in 1.2 extension + deployment was limited to mediators bundled as simple JAR files, 1.3 extended this + support to tasks and defined a new archive format (XAR) that allows to bundle + these extensions together with their dependency JARs (see + <a class="externalLink" href="http://issues.apache.org/jira/browse/SYNAPSE-377";>SYNAPSE-377</a> + for more details). Enabling these features requires changes to the <tt>axis2.xml</tt> + configuration file. In 1.2 the deployer was configured as follows: + </p> + +<div class="xmlConf"><deployer extension="jar" directory="mediators" + class="org.apache.synapse.core.axis2.MediatorDeployer"/></div> + +<p> + In 2.1 the suggested configuration is: + </p> + +<div class="xmlConf"><deployer extension="xar" directory="extensions" + class="org.apache.synapse.deployers.ExtensionDeployer"/> </div> + +<p> + It is possible to have multiple configuration entries for the extension deployer + with different settings. For example, if you used the deployer in 1.2 you might + want to have the following configuration: + </p> + +<div class="xmlConf"><deployer extension="jar" directory="mediators" + class="org.apache.synapse.deployers.ExtensionDeployer"/> +<deployer extension="xar" directory="extensions" + class="org.apache.synapse.deployers.ExtensionDeployer"/></div> + </div> + <a name="JMS_transport"></a> +<div class="section" id="JMS_transport"> +<h3><a name="JMS_transport"></a>JMS transport</h3> + +<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> + </div> + <a name="Main_Sequence"></a> +<div class="section" id="Main_Sequence"> +<h3><a name="Main_Sequence"></a>Main Sequence</h3> + +<p> + On Synapse 1.2 you could have mediator configuration on the top level definitions + tag and they were treated as the <b>main</b> 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 + <b>main</b> on the new 2.1 version. + </p> + +<p> + To further explain this lets have a look at the following valid configuration bit + (this is the sample 0 configuration) on the 1.2; + +<div class="xmlConf"><definitions xmlns="http://ws.apache.org/ns/synapse"> + <!-- log all attributes of messages passing through --> + <log level="full"/> + + <!-- Send the message to implicit destination --> + <send/> +</definitions></div> + which needs to be changed to the following configuration on 2.1 + +<div class="xmlConf"><definitions xmlns="http://ws.apache.org/ns/synapse"> + + <sequence name="main"> + <!-- log all attributes of messages passing through --> + <log level="full"/> + + <!-- Send the message to implicit destination --> + <send/> + <sequence/> + +</definitions></div> + </p> + </div> + <a name="Filter_Mediator"></a> +<div class="section" id="Filter_Mediator"> +<h3><a name="Filter_Mediator"></a>Filter Mediator</h3> + +<p> + From 2.1 onwards Synapse filter mediator supports the else close as well, and hence + the filter matching set of mediators has to be enclosed within a <then> element. + </p> + +<p> + If we consider the following sample from the 1.2 version of synapse; + +<div class="xmlConf"><filter source="get-property('To')" regex=".*/StockQuote.*"> + <send> + <endpoint> + <address uri="http://localhost:9000/soap/SimpleStockQuoteService"/> + </endpoint> + </send> + <drop/> +</filter></div> + the equivalent configuration for the 2.1 release is going to be; + +<div class="xmlConf"><filter source="get-property('To')" regex=".*/StockQuote.*"> + <then> + <send> + <endpoint> + <address uri="http://localhost:9000/soap/SimpleStockQuoteService"/> + </endpoint> + </send> + <drop/> + <then/> +</filter></div> + You could also add an else close to this conditional statement as follows on 2.x + which is not possible on 1.2 + +<div class="xmlConf"><filter source="get-property('To')" regex=".*/StockQuote.*"> + <then> + <send> + <endpoint> + <address uri="http://localhost:9000/soap/SimpleStockQuoteService"/> + </endpoint> + </send> + <drop/> + <then/> + <else/> + <log/> + <else/> +</filter></div> + </p> + </div> + <a name="Migration_Tool"></a> +<div class="section" id="Migration_Tool"> +<h3><a name="Migration_Tool"></a>Migration Tool</h3> + +<p> + In general it is recommended to run the configuration through the migration tool + provided with the Synapse 2.x release, on your synapse 1.2 configuration before + using it with the 2.1. + </p> + +<p> + To run the migration tool execute the synapse-config-migrator.sh by passing the + synapse.xml file location of the + 1.2 configuration. Which will create the 2.1 + compatible configuration with the .new suffix. For example; + </p> +<div> +<pre>sh bin/synapse-config-migrator.sh synapse-i1.2/repository/conf/synapse.xml</pre></div> + + </div> + <a name="Custom_Extensions_and_API_changes"></a> +<div class="section" id="Custom_Extensions_and_API_changes"> +<h3><a name="Custom_Extensions_and_API_changes"></a>Custom Extensions and API changes</h3> + +<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 border="0" class="table table-striped"> + +<tr class="a"> + +<th>Class</th> + +<th>Method</th> + +<th>Change Description</th> + </tr> + +<tr class="b"> + +<td> + <a href="../apidocs/org/apache/synapse/config/xml/AbstractMediatorFactory.html">AbstractMediatorFactory</a> + </td> + +<td>createMediator(OMElement)</td> + +<td> + This was the method that you have been overwriting on the 1.2 version to + implement a new custom mediator factory to build the mediator by looking at + the XML configuration. On the 2.1 version you should be extending the + <a href="apidocs/org/apache/synapse/config/xml/AbstractMediatorFactory.html#createSpecificMediatororg.apache.axiom.om.OMElement20java.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#createMediatororg.apache.axiom.om.OMElement20java.util.Properties">createMediator</a> + method has been changed to be final. From a users point of view of this + interface he/she should be using the createMediator method which is what + Synapse does. + </td> + </tr> + +<tr class="a"> + +<td> + <a href="../apidocs/org/apache/synapse/config/xml/AbstractMediatorSerializer.html">AbstractMediatorSerializer</a> + </td> + +<td>serializeMediator(Mediator)</td> + +<td> + This was the method that you have been overwriting on the 1.2 version to + implement a new custom mediator serializer to serialize to the XML + Configuration by walking through the mediator properties. On the 2.1 + version you should be extending the + <a href="apidocs/org/apache/synapse/config/xml/AbstractMediatorSerializer.html#serializeSpecificMediatororg.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#serializeMediatororg.apache.axiom.om.OMElement20org.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#getMediatororg.apache.axiom.om.OMElement20java.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> + </div> + </div> + + + </div> + </div> + </div> + <hr/> + <footer> + <div class="container-fluid"> + <div class="row-fluid"> + <p>Copyright ©2005–2023 +<a href="http://www.apache.org/";>Apache Software Foundation</a>. +All rights reserved.</p> + </div> + </div> + </footer> + </body> +</html> Added: synapse/site/3_0_2/userguide/xpath.html URL: http://svn.apache.org/viewvc/synapse/site/3_0_2/userguide/xpath.html?rev=1909775&view=auto ============================================================================== --- synapse/site/3_0_2/userguide/xpath.html (added) +++ synapse/site/3_0_2/userguide/xpath.html Fri May 12 16:09:34 2023 @@ -0,0 +1,495 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2023-05-04 + | Rendered using Apache Maven Fluido Skin 1.6 +--> +<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="20230504" /> + <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.6.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.6.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: 2023-05-04<span class="divider">|</span> +</li> + <li id="projectVersion">Version: 3.0.2</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" > + + + <a name="Intro"></a> +<div class="section" id="Intro"> +<h2><a name="Introduction"></a>Introduction</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><a name="Contents"></a>Contents</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><a name="Custom_Functions"></a>Custom Functions</h2> + <a name="get_prop"></a> +<div class="section" id="get_prop"> +<h3><a name="get-property_function"></a>get-property function</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><a name="Supported_Scopes"></a> + Supported Scopes + </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><a name="base64Encode_function"></a>base64Encode function</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><a name="base64Decode_function"></a>base64Decode function</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><a name="url-encode_function"></a>url-encode function</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><a name="Variables"></a>Variables</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–2023 +<a href="http://www.apache.org/";>Apache Software Foundation</a>. +All rights reserved.</p> + </div> + </div> + </footer> + </body> +</html>
