{section}
{column}

h1. Summary

This tutorial explains how you can create a Petals service that sends emails.
Such a service sends emails by contacting a specified email server.

\\
Technically, this tutorial shows the creation of a service-unit for the [Petals-BC-Mail|petalscomponents:Petals-BC-Mail] component in *provides* mode.

{info}
*Level:* Easy
*Estimated time:* 10 minutes the first time, 3 minutes then
*Expected skills:* \-
{info}
{column}
{column:width=350px}
{panel:title=Table of contents}{toc}{panel}
{column}
{section}


h1. Creating the Service-Unit project

h2. Getting started

A wizard opens up, showing three drop-down lists.

!petals-studio-tuto-provides-mail-1.jpg!

\\
Click *Next*.


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

!petals-studio-tuto-provides-mail-2.jpg!

\\
You only have to complete the service and end-point names.

!petals-studio-tuto-provides-mail-3.jpg!

\\
{note}
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.
{note}

{note}
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.
{note}

\\
Once the fields have been filled-in, click *Next*.


h2. 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-studio-tuto-provides-mail-4.jpg!

\\
{note}
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*
{note}

\\
Then, click *Next*.


h2. 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|petalscomponents:Petals-BC-Mail] component.

\\ !petals-studio-tuto-provides-mail-5.jpg!

{tip}
You can get a short description of the parameters by hovering the parameter name in the wizard.
{tip}

{info}

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

\\ !petals-studio-tuto-provides-mail-7.jpg!


h1. Updating, packaging and deploying

h2. 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|Working with Service Unit projects], you can [package it as any Service-Unit project|Working with Service Unit projects#Export for Petals].
It results in the creation of a Service Assembly for the Petals-BC-Mail component. Its location depends on your export choices.

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

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

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

{code:lang=xml}
<wsdl:operation name="SendMail">
<wsdl:input message="tns:SendMailRequest1" />
</wsdl:operation>
{code}

\\
There is no output message.
The input message of this operation are defined by:

{code:lang=xml}
<wsdl:message name="SendMailRequest1">
<wsdl:part name="mail" element="tns:SendMail" />
</wsdl:message>
{code}

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

{code:lang=xml}
<xsd:element name="SendMail">
<xsd:complexType>
<xsd:sequence>
<xsd:any />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
{code}

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

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

\\
{tip}
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.
{tip}