E-mail
SummaryThis tutorial explains how you can expose a file system connection as a service in Petals ESB.
|
Creating the Service-Unit project
Getting started
Start Petals Studio.
In the menu, select File > New > Service-Unit Project.
If you do not see it, go into File > New > Other... Then, select Service-Unit Project 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 FileTransfer // petals-bc-filetransfer.
In the Component Usage list, select Provide or Import a Service in Petals ESB.
In the Component Version list, select the version of the Petals-BC-FileTransfer that you are using in Petals.
In the scope of this tutorial, we are going to work with the version 3.0 of the File Transfer 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 FileTransfer 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 File Transfer 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 FileTransfer parameters
This page defines information which are specific to the Petals FileTransfer component.
For more details about their meaning, please refer to the documentation of the Petals-BC-FileTransfer component.
Shortly, this component has two usage: either provide a service that write files, or provide a service that reads files.
This page deals wih both cases.
 | You can get a short description of the parameters by hovering the parameter name in the wizard. |
Click Next.
Specifying the CDK parameters
The CDK is the Petals framework to develop JBI components.
The Petals-BC-FileTransfer component was developed with this framework.
This page requires information related to the CDK.
By default, you have nothing to do here.
The meaning of all the CDK parameters for FileTransfer can be found in the documentation of the Petals-BC-FileTransfer component.
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 File Transfer 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 FileTransfer 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 File Transfer 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-FileTransfer 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-FileTransfer 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 File Transfer 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 PUT operation
Let's take a look at the input and output parameters of the put operation.
The FtpInterface defines the following operation:
<wsdl:operation name="put"> <wsdl:input message="tns:putRequest"/> </wsdl:operation>
There is no output message for this operation.
The input message of this operation is defined by:
<wsdl:message name="putRequest"> <wsdl:part name="putRequest" element="tns:put"/> </wsdl:message>
And the associated XML type and element are defined as follows:
<xsd:element name="put" type="tns:putRequestType" /> <xsd:complexType name="putRequestType"> <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 File Transfer 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 File Transfer 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 putRequestType being any type in the first WSDL, and putRequestType 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 File Transfer 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 File Transfer 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 FileTransfer WSDL, change the interface name in the WSDL. Then update your jbi.xml to match the WSDL's content. |