Author: hiranya
Date: Sat Aug 17 17:56:42 2013
New Revision: 1515024
URL: http://svn.apache.org/r1515024
Log:
Adding documentation on vfs transport
Added:
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/vfs.xml
Added:
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/vfs.xml
URL:
http://svn.apache.org/viewvc/synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/vfs.xml?rev=1515024&view=auto
==============================================================================
---
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/vfs.xml
(added)
+++
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/vfs.xml
Sat Aug 17 17:56:42 2013
@@ -0,0 +1,298 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+<document>
+ <properties>
+ <title>Apache Synapse - File Transport</title>
+ </properties>
+ <body>
+ <section name="File Transport" id="Contents">
+ <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>
+ </ul>
+ </li>
+ </ul>
+ </section>
+ <section name="Introduction" id="Introduction">
+ <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
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>
+ </section>
+ <section name="Transport Configuration" id="Configuration">
+ <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>
+ <subsection name="File Transport Listener (VFS Listener)"
id="Listener">
+ <p>
+ Before a proxy service can read files, the VFS listener
must be enabled in the
+ <string>SYNAPSE_HOME/repository/conf/axis2.xml</string>
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.
+ </p>
+ <table>
+ <tr>
+ <th>Parameter Name</th>
+ <th>Description/Example</th>
+ <th>Required</th>
+ <th>Default</th>
+ </tr>
+ <tr>
+ <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]/test/in</parameter></div>
+ </td>
+ <td>Yes</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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/user/test/original</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <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>
+ <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>
+ <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>
+ <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>
+ <td>transport.vfs.MoveTimestampFormat</td>
+ <td>
+ Must be a timestamp format string compatible with
+ <a
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>
+ <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>
+ <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>
+ </table>
+ <p><a href="#Contents">[Back to top]</a></p>
+ </subsection>
+ </section>
+ </body>
+</document>
\ No newline at end of file
