E-mail
SummaryThis tutorial explains how you can create a Petals service that sends emails.
|
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 Provide or Import a Service into Petals.
In the Petals Component list, select Mail // petals-bc-mail.
In the Component Version list, select the version of the Petals-BC-Mail that you are using in Petals.
In the scope of this tutorial, we are going to work with the version 3.1 of the Mail 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 Mail 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 Mail 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 Mail parameters
This page defines information which are specific to the Petals Mail component.
Most of these parameters are transparent for Mail users. For more details about their meaning, please refer to the documentation of the Petals-BC-Mail component.
 | You can get a short description of the parameters by hovering the parameter name in the wizard. |
 | Such a definition means the email content is static. The Petals Mail component exposes a native emailing service, that can be used to send dynamic messages. Please, refer to the documentation of the [Petals-BC-Mail] component for more information about the native email service. |
Click Next.
Specifying the CDK parameters
The CDK is the Petals framework to develop JBI components.
The Petals-BC-Mail 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 Mail can be found in the documentation of the Petals-BC-Mail 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 Mail 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 Mail 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 Mail 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-Mail 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-Mail 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 Mail 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.
The SendMail operation
Let's take a look at the input and output parameters of the SendMail operation.
The Mail port type defines the following operation:
<wsdl:operation name="SendMail"> <wsdl:input message="tns:SendMailRequest1" /> </wsdl:operation>
There is no output message.
The input message of this operation are defined by:
<wsdl:message name="SendMailRequest1"> <wsdl:part name="mail" element="tns:SendMail" /> </wsdl:message>
And the associated XML type and element are defined as follows:
<xsd:element name="SendMail"> <xsd:complexType> <xsd:sequence> <xsd:any /> </xsd:sequence> </xsd:complexType> </xsd:element>
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 Mail 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 Mail 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.
In the case of the SendMail operation, we would have the SendMail element being any type in the first WSDL, and the SendMail element 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 Mail 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 Mail 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 Mail WSDL, change the interface name in the WSDL. Then update your jbi.xml to match the WSDL's content. |