E-mail
|
Key
This line was removed.
This word was removed. This word was added.
This line was added.
|
Changes (42)
View Page History
...
{section} h1. Feature
The SFTP component is a Binding Component (BC) which supports ftp SFTP command.
This component provide a set of 5 operation:
...* *mput:* Write the JBI message attachments it receives into files.
* *get:* Retrieve *Xml* file corresponding to a pattern, from a folder. Return it as message payload.
* *get:* Retrieve *Xml* file corresponding to a pattern, from a folder. Return it as message payload.
* *getAsAttachment:* Retrieve the first file corresponding to a pattern, from a folder*.\* folder. Return it as message's attachment.(XOP standard)
* *mGet:* Retrieve files corresponding to a pattern, from a folder*.\* folder. Return them as message's attachment.
* *del:* Delete one file.
* *dir:* List the content of a folder.
* *dir:* List the content of a folder.
...h1. Recommend usage
Petals FTP binding component allows JBI consumers to call FTP command. A JBI endpoint is registered into the JBI environment, and is linked to an FTP server, with a configured user/password.To use this service, the consumer has to call explicitely the *{service* *namespace{*}*}get/getAsAttachment/mget/put/mput/dir/del* operations.When the FTP component receives a message exchange from Petals platform, it call the FTP command associate with the jbi operation.
Petals SFTP binding component allows JBI consumers to call SFTP command. A JBI endpoint is registered into the JBI environment, and is linked to an SFTP server, with a configured user/password.
To use this service, the consumer has to call explicitely the *{service* *namespace{*}*}get/getAsAttachment/mget/put/mput/dir/del* operations.When the FTP component receives a message exchange from Petals platform, it call the SFTP command associate with the jbi operation.
h1. Exposing a SFTP connection as a service
...h2. Usage
When using the SFTP service, you can optionnaly define the SFTP connection information in your XML request. If you don't, the service unit parameters are used.
\\
To configure the SFTP connection in your XML message request, you have to provide a connection element.
\\ {code:lang=xml}
...
...
<ver:connection> <!--Optional:-->
<ver:server>?</ver:server>
<ver:port>?</ver:port>
<ver:user>?</ver:user>
<ver:password>?</ver:password>
<!--Optional:-->
<ver:folder>?</ver:folder>
<ver:transfer-type>ascii|binary</ver:transfer-type>
<ver:connection-mode>active|passive (optional, default is active)</ver:connection-mode>
<ver:delete-processed-files>true|false(optional, default is active)</ver:delete-processed-files>
<ver:encoding>?</ver:encoding>
</ver:connection>
<ver:port>?</ver:port>
<ver:user>?</ver:user>
<ver:password>?</ver:password>
<!--Optional:-->
<ver:folder>?</ver:folder>
<ver:transfer-type>ascii|binary</ver:transfer-type>
<ver:connection-mode>active|passive (optional, default is active)</ver:connection-mode>
<ver:delete-processed-files>true|false(optional, default is active)</ver:delete-processed-files>
<ver:encoding>?</ver:encoding>
</ver:connection>
<ver:connection>
<ver:server>?</ver:server>
<ver:port>?</ver:port>
<ver:user>?</ver:user>
<!--Optional:-->
<ver:password>?</ver:password>
<ver:folder>?</ver:folder>
<ver:passphrase>?</ver:passphrase>
<ver:private-key>?</ver:private-key>
</ver:connection>
<ver:server>?</ver:server>
<ver:port>?</ver:port>
<ver:user>?</ver:user>
<!--Optional:-->
<ver:password>?</ver:password>
<ver:folder>?</ver:folder>
<ver:passphrase>?</ver:passphrase>
<ver:private-key>?</ver:private-key>
</ver:connection>
...
{code}
{code}
...{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<ver:put xmlns:ver="http://petals.ow2.org/components/ftp/version-3"> xmlns:ver="http://petals.ow2.org/components/sftp/version-1">
<ver:body>xml body</ver:body>
<ver:filename>file name on the FTP server</ver:filename>
<ver:filename>file name on the FTP server</ver:filename>
...The service does not return a message.
The service might return an error when an element in the request is missing or if the SFTP connection failed.
The available exchange pattern is : *InOnly*.
...h3. MPut Operation
When the mput operation is set on the incoming IN message, the component write the attachments on the SFTP server.
The IN message looks like :
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<ver:mput xmlns:ver="http://petals.ow2.org/components/ftp/version-3"> xmlns:ver="http://petals.ow2.org/components/sftp/version-1">
<ver:attachments>
<ver:filename><xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:test1.xml"/></ver:filename>
<ver:filename><xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:test1.xml"/></ver:filename>
...\\
The service might return an error when an element in the request is missing or if the SFTP connection failed.
The available exchange pattern is : *InOnly*.
...h3. Get Operation
When the get operation is set on the incoming IN message, the component retrieve ONE file from the SFTP server and return it as an XML message content.
\\
...\\
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<ver:get xmlns:ver="http://petals.ow2.org/components/ftp/version-3"> xmlns:ver="http://petals.ow2.org/components/sftp/version-1">
<ver:filename>file name to retrieve</ver:filename>
<!--Optional:-->
<!--Optional:-->
...\\
The service might return a Fault when an element in the request is missing or if the SFTP connection failed
\\
...h3. GetAsAttachment Operation
When the get operation is set on the incoming IN message, the component retrieve ONE file from the SFTP server and return it as an attachment.
The name of the file to retrieve is set in the XML IN content of the message.
...The IN message looks like :
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<ver:getAsAttachment xmlns:ver="http://petals.ow2.org/components/ftp/version-3"> xmlns:ver="http://petals.ow2.org/components/sftp/version-1">
<ver:filename>file name to retrieve</ver:filename>
<!--Optional:-->
<!--Optional:-->
...The OUT message returned to the consumer contains files, as attachments, and an XML message report :
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<tns:getAsAttachmentResponse xmlns:tns="http://petals.ow2.org/components/ftp/version-3"> xmlns:tns="http://petals.ow2.org/components/sftp/version-1">
<tns:attachments>
<tns:filename><xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:test1.xml"/></tns:filename>
<tns:filename><xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:test1.xml"/></tns:filename>
...</tns:getAsAttachmentResponse>
{code}
{code}
The service might return a Fault when an element in the request is missing or if the SFTP connection failed
The available exchange pattern is : *InOut*.
...h3. MGet Operation
When the mget operation is set on the incoming IN message, the component retrieves files from the SFTP server, according to the file names (or filters) set in the XML request.
\\
There is no recursivity, sub folders are ignored.
There is no recursivity, sub folders are ignored.
...\\
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<ver:mget xmlns:ver="http://petals.ow2.org/components/ftp/version-3"> xmlns:ver="http://petals.ow2.org/components/sftp/version-1">
<!--1 or more repetitions:-->
<ver:filename>*.xml</ver:filename>
<ver:filename>*.xml</ver:filename>
...\\
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<tns:mgetResponse xmlns:tns="http://petals.ow2.org/components/ftp/version-3"> xmlns:tns="http://petals.ow2.org/components/sftp/version-1">
<tns:attachments>
<tns:filename><xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:test1.xml"/></tns:filename>
<tns:filename><xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:test1.xml"/></tns:filename>
...</tns:mgetResponse>
{code}
{code}
The service might return a Fault when an element in the request is missing or if the SFTP connection failed
\\
...h3. Dir Operation
When the dir operation is set on the incoming IN message, the component returns the file names listed from the SFTP
server.
The IN message looks like :{code:lang=xml}
The IN message looks like :{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?><ver:dir xmlns:ver="http://petals.ow2.org/components/ftp/version-3> xmlns:ver="http://petals.ow2.org/components/sftp/version-1>
<!--Optional:-->
<ver:connection>
<ver:connection>
...The OUT message returned to the consumer is defined as follow :
{code:lang=xml}<tns:dirResponse xmlns:tns="http://petals.ow2.org/components/ftp/version-3"> xmlns:tns="http://petals.ow2.org/components/sftp/version-1">
<!--Zero or more repetitions:-->
<tns:filename>file1.txt</tns:filename>
<tns:filename>file1.txt</tns:filename>
...</tns:dirResponse>
{code}
{code}
The service might return a Fault when an element in the request is missing or if the SFTP connection failed
The available exchange pattern is : *InOut*.
...{code}
The service does not return a message.
The service does not return a message.
The service might return an Error when an element in the request is missing or if the SFTP connection failed.
The available exchange pattern is : InOnly.
...|| Attribute || Description || Default value || Required ||
| server | IP or DNS name of the server | | {center}Yes{center}\\ {center}except when using FtpService{center} |
| port | the port number of the ftp server | {center}21{center} | {center}No{center} |
| user | the user login name used to connect to the server | | {center}Yes{center}\\ {center}except when using FtpService{center} |
| password | the user password | | {center}Yes{center}\\ {center}except when using FtpService{center} |
| folder | the folder on the FTP server | | {center}No{center} |
| privatekey | the path to the user's private key (on the PEtALS machine) | | Yes (except when using dynamic mode or\\ {center}Yes{center}\\
password authentication) |
{center}except when using dynamic mode or \\
password authentication) {center} |
password authentication) {center} |
| passphrase | the passphrase matching the given private key | | No |
{table-plus}
{table-plus}
...<!-- JBI descriptor for PEtALS' "petals-bc-ftp" (FTP), version 3.3 -->
<jbi:jbi version="1.0"
<jbi:jbi version="1.0"
xmlns:ftp="http://petals.ow2.org/components/ftp/version-3"
xmlns:generatedNs="http://petals.ow2.org/components/ftp/version-3"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<!-- Import a Service into Petals or Expose a Petals Service => use a BC. -->
<jbi:services binding-component="true">
<!-- Import a Service into Petals => provides a Service. -->
<jbi:provides
interface-name="generatedNs:FtpInterface"
service-name="generatedNs:FtpService"
endpoint-name="FtpServiceEndpoint">
<!-- CDK specific elements -->
<petalsCDK:timeout>30000</petalsCDK:timeout>
<petalsCDK:validate-wsdl>true</petalsCDK:validate-wsdl>
<petalsCDK:forward-security-subject>false</petalsCDK:forward-security-subject>
<petalsCDK:forward-message-properties>false</petalsCDK:forward-message-properties>
<petalsCDK:forward-attachments>false</petalsCDK:forward-attachments>
<petalsCDK:wsdl>FtpService.wsdl</petalsCDK:wsdl>
<!-- Component specific elements -->
<ftp:server>myhost</ftp:server>
<ftp:port>21</ftp:port>
<ftp:user>user1</ftp:user>
<ftp:password>password</ftp:password>
<ftp:folder>workingDirectory</ftp:folder>
<ftp:filename>ddd</ftp:filename>
<ftp:transfer-type>ascii</ftp:transfer-type>
<ftp:connection-mode>active</ftp:connection-mode>
<ftp:delete-processed-files>false</ftp:delete-processed-files>
<ftp:encoding>UTF-8</ftp:encoding>
</jbi:provides>
</jbi:services>
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<!-- Import a Service into Petals or Expose a Petals Service => use a BC. -->
<jbi:services binding-component="true">
<!-- Import a Service into Petals => provides a Service. -->
<jbi:provides
interface-name="generatedNs:FtpInterface"
service-name="generatedNs:FtpService"
endpoint-name="FtpServiceEndpoint">
<!-- CDK specific elements -->
<petalsCDK:timeout>30000</petalsCDK:timeout>
<petalsCDK:validate-wsdl>true</petalsCDK:validate-wsdl>
<petalsCDK:forward-security-subject>false</petalsCDK:forward-security-subject>
<petalsCDK:forward-message-properties>false</petalsCDK:forward-message-properties>
<petalsCDK:forward-attachments>false</petalsCDK:forward-attachments>
<petalsCDK:wsdl>FtpService.wsdl</petalsCDK:wsdl>
<!-- Component specific elements -->
<ftp:server>myhost</ftp:server>
<ftp:port>21</ftp:port>
<ftp:user>user1</ftp:user>
<ftp:password>password</ftp:password>
<ftp:folder>workingDirectory</ftp:folder>
<ftp:filename>ddd</ftp:filename>
<ftp:transfer-type>ascii</ftp:transfer-type>
<ftp:connection-mode>active</ftp:connection-mode>
<ftp:delete-processed-files>false</ftp:delete-processed-files>
<ftp:encoding>UTF-8</ftp:encoding>
</jbi:provides>
</jbi:services>
</jbi:jbi>{code}
...