{section}
{column}
h1. Summary
This tutorial explains how you can expose a Petals service outside the bus, as a Web service.
{tip}
A Petals service being only reachable from inside the bus, you have to expose it outside the bus to call it with any client.
{tip}
\\
In this tutorial, we are going to see how to expose it outside the bus as a Web service.
This will allow us to call this Petals service with a Web Service client, e.g. SoapUI, a Java, PHP or C# application.
\\
Technically, this tutorial shows the creation of a service-unit for the [Petals-BC-SOAP|petalscomponents:Petals-BC-SOAP] component in *consumes* mode.
{info}
*Level:* Easy
*Estimated time:* 10 minutes the first time, 2 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
Start Petals Studio.
In the menu, select *File > New > Petals Service Consumer*.
If you do not see it, go into *File > New > Other...* Then, select *Petals Service Consumer* 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 *SOAP // petals-bc-soap*.
In the *Component Version* list, select the version of the Petals-BC-SOAP that you are using in Petals.
\\
In the scope of this tutorial, we are going to work with the version 4.1 of the SOAP component.
Which gives us:
!petals-studio-tuto-consumes-soap-1.jpg!
\\
Click *Next*.
h2. Identifying the target 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 will be exposed as a Web Service.
!petals-studio-tuto-consumes-soap-2.jpg!
\\
{note}
A service is identified by a triplet, interface, service and end-point names. This triplet is unique in a Petals topology.
When you consume a service, the service is selected in a set. This set is defined by the invocation properties.
If the 3 fields are set in the consume properties, then the set will contain at most 1 result (there can be only 1 service with this ID).
If 2 fields are set, then the third one is considered as a wildcard and the set will larger.
Consume possibilities are the following ones:
* By interface, service and end-point names.
* By interface and service names.
* By interface name only.
{note}
\\
This page also defines the operation to invoke and the Message Exchange Pattern (MEP).
The Message Exchange Pattern (MEP) defines the interactions between the SOAP client and the web service.
In the version 4.0 of the SOAP component, you have to set explicitely the MEP (the operation is deduced from the SOAP message).
In the version 4.1, the operation name and the MEP will be deduced from the SOAP message.
\\
You can obviously fill-in these fields by hand.
However, the most efficient way is to use the [Petals Services explorer|Getting familiar with the Petals Services view] (provided it was populated).
Click *Select a service*. A selection dialog shows up, providing filtering assistance.
!petals-studio-tuto-consumes-soap-2bis.jpg!
\\
When you have selected your service, click *OK*.
The wizard fields are filled-in automatically.
!petals-studio-tuto-consumes-soap-3.jpg!
\\
{note}
The values for the interface, service and end-point names must match the values defined in the jbi.xml of the exposed service.
Indeed, this service must be a Petals service, and thus be described in a jbi.xml.
As a reminder, the jbi.xml values and the WSDL values (if the WSDL exists) of the exposed service must be exactly the same.
For this reason, filling-in the information by hand or modifying it is discouraged.
{note}
\\
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 SOAP 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-consumes-soap-4.jpg!
\\
{note}
Petals service-units have a naming convention.
For a service-unit which consumes (calls) a service, the convention is *su\-*_<Protocol or Technology>_*\-*_<Service name>_*\-consume*
{note}
\\
Then, click *Next*.
h2. Specifying the SOAP parameters
This page defines information which are specific to the Petals SOAP component.
The only one you have to fill-in is the *service-name* field.
It defines the suffix of the URL at which the web service will be available.
{tip}
The exposed Web Service will be reachable at the address [http://_host_:8084/petals/services/_address\_|http://_host_:8084/petals/services/_address_],
where _\_host\__ is the host name (or IP address) and _\_address\__ the value of the *address* field.
{tip}
{tip}
The prefix of the Web Service URL (e.g. _petals/services/_) is defined in the JBI descriptor (jbi.xml) of the SOAP component on which this service-unit will be deployed.
{tip}
\\
The meaning of the other parameters can be read in the documentation of the [Petals-BC-SOAP|petalscomponents:Petals-BC-SOAP] component.
!petals-studio-tuto-consumes-soap-5.jpg!
\\
Click *Finish* to complete the wizard.
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).
There is nothing else in the project.
!petals-studio-tuto-consumes-soap-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 SOAP 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 SOAP 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-SOAP 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-SOAP 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 SOAP component to make it work.
Using the default settings is enough to make the service-unit work.
\\
The Petals service is then reachable as a Web service at [http://_host_:8084/petals/services/_address\_|http://_host_:8084/petals/services/_address_],
where _\_host\__ is the host name (or IP address) and _\_address\__ the value of the *address* field defined in the jbi.xml file.
{column}
h1. Summary
This tutorial explains how you can expose a Petals service outside the bus, as a Web service.
{tip}
A Petals service being only reachable from inside the bus, you have to expose it outside the bus to call it with any client.
{tip}
\\
In this tutorial, we are going to see how to expose it outside the bus as a Web service.
This will allow us to call this Petals service with a Web Service client, e.g. SoapUI, a Java, PHP or C# application.
\\
Technically, this tutorial shows the creation of a service-unit for the [Petals-BC-SOAP|petalscomponents:Petals-BC-SOAP] component in *consumes* mode.
{info}
*Level:* Easy
*Estimated time:* 10 minutes the first time, 2 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
Start Petals Studio.
In the menu, select *File > New > Petals Service Consumer*.
If you do not see it, go into *File > New > Other...* Then, select *Petals Service Consumer* 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 *SOAP // petals-bc-soap*.
In the *Component Version* list, select the version of the Petals-BC-SOAP that you are using in Petals.
\\
In the scope of this tutorial, we are going to work with the version 4.1 of the SOAP component.
Which gives us:
!petals-studio-tuto-consumes-soap-1.jpg!
\\
Click *Next*.
h2. Identifying the target 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 will be exposed as a Web Service.
!petals-studio-tuto-consumes-soap-2.jpg!
\\
{note}
A service is identified by a triplet, interface, service and end-point names. This triplet is unique in a Petals topology.
When you consume a service, the service is selected in a set. This set is defined by the invocation properties.
If the 3 fields are set in the consume properties, then the set will contain at most 1 result (there can be only 1 service with this ID).
If 2 fields are set, then the third one is considered as a wildcard and the set will larger.
Consume possibilities are the following ones:
* By interface, service and end-point names.
* By interface and service names.
* By interface name only.
{note}
\\
This page also defines the operation to invoke and the Message Exchange Pattern (MEP).
The Message Exchange Pattern (MEP) defines the interactions between the SOAP client and the web service.
In the version 4.0 of the SOAP component, you have to set explicitely the MEP (the operation is deduced from the SOAP message).
In the version 4.1, the operation name and the MEP will be deduced from the SOAP message.
\\
You can obviously fill-in these fields by hand.
However, the most efficient way is to use the [Petals Services explorer|Getting familiar with the Petals Services view] (provided it was populated).
Click *Select a service*. A selection dialog shows up, providing filtering assistance.
!petals-studio-tuto-consumes-soap-2bis.jpg!
\\
When you have selected your service, click *OK*.
The wizard fields are filled-in automatically.
!petals-studio-tuto-consumes-soap-3.jpg!
\\
{note}
The values for the interface, service and end-point names must match the values defined in the jbi.xml of the exposed service.
Indeed, this service must be a Petals service, and thus be described in a jbi.xml.
As a reminder, the jbi.xml values and the WSDL values (if the WSDL exists) of the exposed service must be exactly the same.
For this reason, filling-in the information by hand or modifying it is discouraged.
{note}
\\
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 SOAP 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-consumes-soap-4.jpg!
\\
{note}
Petals service-units have a naming convention.
For a service-unit which consumes (calls) a service, the convention is *su\-*_<Protocol or Technology>_*\-*_<Service name>_*\-consume*
{note}
\\
Then, click *Next*.
h2. Specifying the SOAP parameters
This page defines information which are specific to the Petals SOAP component.
The only one you have to fill-in is the *service-name* field.
It defines the suffix of the URL at which the web service will be available.
{tip}
The exposed Web Service will be reachable at the address [http://_host_:8084/petals/services/_address\_|http://_host_:8084/petals/services/_address_],
where _\_host\__ is the host name (or IP address) and _\_address\__ the value of the *address* field.
{tip}
{tip}
The prefix of the Web Service URL (e.g. _petals/services/_) is defined in the JBI descriptor (jbi.xml) of the SOAP component on which this service-unit will be deployed.
{tip}
\\
The meaning of the other parameters can be read in the documentation of the [Petals-BC-SOAP|petalscomponents:Petals-BC-SOAP] component.
!petals-studio-tuto-consumes-soap-5.jpg!
\\
Click *Finish* to complete the wizard.
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).
There is nothing else in the project.
!petals-studio-tuto-consumes-soap-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 SOAP 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 SOAP 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-SOAP 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-SOAP 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 SOAP component to make it work.
Using the default settings is enough to make the service-unit work.
\\
The Petals service is then reachable as a Web service at [http://_host_:8084/petals/services/_address\_|http://_host_:8084/petals/services/_address_],
where _\_host\__ is the host name (or IP address) and _\_address\__ the value of the *address* field defined in the jbi.xml file.