E-mail
SummaryThis tutorial explains how you can expose a SFTP connection as a service in Petals ESB.
|
Creating the Service-Unit project
Getting started
Start Petals Studio.
In the menu, select File > New > Petals Service Provider.
If you do not see it, go into File > New > Other... Then, select Petals Service Provider under the Petals category.
A wizard opens, showing three drop-down lists.
In the Use Case list, select Communication.
In the Petals Component list, select SFTP // petals-bc-sftp.
In the Component Version list, select the version of the Petals-BC-SFTP that you are using in Petals.
In the scope of this tutorial, we are going to work with the version 1.3 of the SFTP component.
Which gives us:
Click Next.
Identifying the service
The current page requires you to fill-in the base information to put in the JBI descriptor (META-INF/jbi.xml).
In particular, it defines the interface, service and end-point names of the service that is imported.
The tooling for the Petals SFTP component provides a generic WSDL definition, and thus defines fixed values.
You only have to complete the service and end-point names.
 | The values for the interface, service and end-point names must match the WSDL interface. That is to say there must be a service with this name, implementing the so-called interface at this end-point. The WSDL which is generated on wizard completion respects this rule. |
| The auto-generation of the end-point means the service end-point is generated at deployment time. By deploying a such service-unit on n Petals nodes, you would have n times the same service, implementing the same interface, but available at n different locations. |
Once the fields have been filled-in, click Next.
Defining the project name
This page defines the name and the location of the project that will be created.
Indeed, this wizard will result in the creation of a project containing all the required elements for a SFTP service-unit.
Enter a project name for your project.
If you do not want your project to be created in the default workspace, uncheck Use default location.
Then click Browse... and select the location where the project will be created.
| Petals service-units have a naming convention. For a service-unit which provides a service, the convention is su-<Protocol or Technology>-<Service name>-provide |
Then, click Next.
Specifying the SFTP parameters
This page defines information which are specific to the Petals SFTP component.
Most of these parameters are transparent for SFTP users. The authentication parameters do not need to be all specified.
It depends on the authentication mode (static authentication with a password, or dynamic with a key).
These parameters are described more precisely in the documentation of the Petals-BC-SFTP component.
 | You can get a short description of the parameters by hovering the parameter name in the wizard. |
Click Finish to complete the wizard.
Checking the result
When the wizard has completed, a new project has been created and is visible in your workspace.
It contains a jbi.xml file, located under src/main/jbi.
This hierarchy allows you to work with Apache Maven then (a pom.xml was also created at the root of the project).
In the same directory, you can see the WSDL definition that was generated for this version of the SFTP component.
Updating, packaging and deploying
Further edition and packaging
After completion, the newly created jbi.xml file has been open in the Service-Unit editor.
Regarding SFTP configurations, the wizards are complete and provide all the options.
Thus, you do not need to edit the jbi.xml.
The project contains everything the SFTP component needs.
You can now package it before deploying it.
The created project being a Service-Unit project, you can package it as any Service-Unit project.
It results in the creation of a Service Assembly for the Petals-BC-SFTP component. Its location depends on your export choices.
Deployment
The deployment of the created service assembly can be achieved with the Petals web console.
Or you can do it by dropping the service assembly in the install directory of your Petals installation.
This second option should only be used in development steps.
First, make sure the Petals-BC-SFTP is installed in your Petals environment.
Then, install the service assembly in your Petals, using one of the two ways indicated above.
There is no need to update configuration of the SFTP component to make it work.
Using the default settings is enough to make the service-unit work.
Advanced customization
The WSDL that is generated by this wizard is a default one.
If you take a look at it, there are some parts that you might want to customize.
It mainly concerns the XML types, by replacing the ANY types by precise types.
Example with the GET operation
Let's take a look at the input and output parameters of the get operation.
The SftpInterface port type defines the following operation:
<wsdl:operation name="get"> <wsdl:input message="tns:getRequest" /> <wsdl:output message="tns:getResponse" /> <wsdl:fault name="fault" message="tns:get_ioFaultMsg"/> <wsdl:fault name="fault1" message="tns:get_MissEltFault"/> </wsdl:operation>
The input and output messages of this operation are defined by:
<wsdl:message name="getRequest"> <wsdl:part name="getRequest" element="tns:get" /> </wsdl:message> <wsdl:message name="getResponse"> <wsdl:part name="getResponse" element="tns:getResponse"/> </wsdl:message>
And the associated XML types and elements are defined as follows:
<xsd:element name="get" type="tns:getType"/> <xsd:complexType name="getType"> <xsd:sequence> <xsd:element name="filename" type="xsd:string" maxOccurs="1" minOccurs="1" /> <xsd:element name="connection" type="tns:ConnectionType" maxOccurs="1" minOccurs="0" /> </xsd:sequence> </xsd:complexType> <xsd:element name="getResponse" type="tns:getResponseType"/> <xsd:complexType name="getResponseType"> <xsd:sequence> <xsd:any/> </xsd:sequence> </xsd:complexType>
Customizing the return type
One customization you might want to do, is replacing the any by a precise type.
The interest of such a manipulation resides for the client of this SFTP service.
The result type would be more precise than a simple Object (in the case of a Java or PHP client).
What you must take care of, is not breaking the global coherence of the WSDL definitions in the bus.
Changing only the XML types and not updating the rest of the WSDL will keep you a valid WSDL.
And this would be right if your WSDL was alone.
But when deployed in the bus, it is associated or separated from other services by the triplet (service, interface and end-point names).
Concretely, let's assume you have created another SFTP service, from which you kept the generated WSDL (no customization).
You have two services (different service names), but that would implement the same interface (same qualfiied name).
In one case, the interface definition was not changed. Whereas the second one was changed.
In fact, you would have one XML type with two different definitions.
Using our get example, we would have getResponseType being any type in the first WSDL, and getResponseType being a precise sequence in the second one.
This ambiguity cannot be managed correctly. Petals will choose the definition in a random way (the interface qualified name being the same).
The exact same problem would appear if you wanted to orchestrate your two SFTP services in a BPEL process.
The solution
The solution consists in changing the interface name whenever you update XML types in a WSDL.
It prevents the ambiguity from appearing.
An even more complete solution would consist in changing the target namespace of the interface and service.
But this is not supported by all the versions of the SFTP component.
Changing the local part of the interface name may be enough in most of the cases.
| When you customize XML types in a generated SFTP WSDL, change the interface name in the WSDL. Then update your jbi.xml to match the WSDL's content. |