Exposing a File Management Service


This tutorial explains how you can expose a file system connection as a service in Petals ESB.
Such a service wraps usual file commands as service operations.
It can also be used to write JBI exchanges (i.e. Petals messages) in files.

Technically, this tutorial shows the creation of a service-unit for the Petals-BC-FileTransfer component in provides mode.

Level: Easy
Estimated time: 10 minutes the first time, 3 minutes then
Expected skills: -

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 FileTransfer // petals-bc-filetransfer.
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.

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 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.


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"/>

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"/>

And the associated XML type and element are defined as follows:

<xsd:element name="put" type="tns:putRequestType" />
<xsd:complexType name="putRequestType">
		<xsd:any />

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.


petals petals Delete
tutorial tutorial Delete
bc bc Delete
filetransfer filetransfer Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.