{section}
{column}
h1. Summary
This tutorial explains how you can implement a Petals service with an annotated Java class, with a bottom-up approach.
Unlike services that are only configured or proxyfied in Petals, such a service is literally executed in the bus.
The approach presented here aims at creating a Java implementation first, and only then a WSDL definition.
\\
Technically, this tutorial shows the creation of a service-unit for the [Petals-SE-Jsr181|petalscomponents:Petals-SE-Jsr181] component in *provides* mode.
{info}
*Level:* Easy
*Estimated time:* 10 minutes
*Expected skills:* develop in Java
{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 Provider*.
If you do not see it, go into *File > New > Other...* Then, select *Petals Service Provider* under the *Petals* category.
\\
A wizard opens up, showing three drop-down lists.
In the *Use Case* list, select *Manual Implementation*.
In the *Petals Component* list, select *Jsr-181 // petals-se-jsr181*.
In the *Component Version* list, select the version of the Petals-SE-Jsr181 that you are using in Petals.
\\
In the scope of this tutorial, we are going to work with the version 1.2 of the Jsr181 component.
Which gives us:
!petals-studio-tuto-jsr181-1.jpg!
\\
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 Jsr181 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-jsr181-2.jpg!
!petals-studio-tuto-jsr181-3.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 creation mode
With the Jsr181 tooling, there are two approaches: a top-down one and a bottom-up one.
Since we want to start from a Java implementation, we will choose the bottom-up one.
Select the radio button *Start with a Java implementation* and provide the fully qualified name of a Java class.
A fully qualified name is made up of the package name (entirely in lower case) and the simple classe name (starts with an upper-case letter).
\\ !petals-studio-tuto-jsr181-java-1.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).
Notice that there is no other file in the directory. And the jbi.xml is marked with a warning, saying there is no WSDL file. This WSDL file will be generated once the Java implementation is complete.
And obviously, there is an annotated Java class, whose name is the one given in the wizard.
This class contains a base of definition, showing some of the available annotations.
\\
!petals-studio-tuto-jsr181-java-2.jpg!
h1. Updating, packaging and deploying
h2. Further edition and packaging
After completion, the service implementation has been open in the Java editor.
Add method declarations, implementations and annotations. The main class must be annotated with _@WebService_.
Other annotations are optional, but recommended to generate a WSDL that will ease the creation of clients (e.g. avoid arg0, arg1 as parameter names).
!petals-studio-tuto-jsr181-java-3.jpg!
\\
Once the Java implementation is complete, it is time to generate the associated WSDL.
To do that, right-click the project and select *Petals > Generate WSDL(s)*.
\\
!petals-studio-tuto-jsr181-java-4.jpg!
\\
A dialog shows up, asking whether a new jbi.xml should be generated.
Clicking *No* only generates WSDL definitions from the classes that are annotated with _@WebService_. The jbi.xml will have to be edited manually.
Clicking *Yes* will in addition generate a new jbi.xml that references the WSDL.
!petals-studio-tuto-jsr181-5.jpg!
\\
{info}
Be careful, all the WSDL definitions of the *jbi* directory will be deleted.
And take note that the new jbi.xml will erase the previous one, thus loosing hand-made modifications.
{info}
{info}
It is possible to define several _@WebService_ annotated classes in a same project.
When generating the WSDL(s), a WSDL will be created for each class. If a new jbi.xml is also generated, there will be one _provides_ block per annotated class.
{info}
\\
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-SE-Jsr181 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-SE-Jsr181 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 Jsr181 component to make it work.
Using the default settings is enough to make the service-unit work.
{column}
h1. Summary
This tutorial explains how you can implement a Petals service with an annotated Java class, with a bottom-up approach.
Unlike services that are only configured or proxyfied in Petals, such a service is literally executed in the bus.
The approach presented here aims at creating a Java implementation first, and only then a WSDL definition.
\\
Technically, this tutorial shows the creation of a service-unit for the [Petals-SE-Jsr181|petalscomponents:Petals-SE-Jsr181] component in *provides* mode.
{info}
*Level:* Easy
*Estimated time:* 10 minutes
*Expected skills:* develop in Java
{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 Provider*.
If you do not see it, go into *File > New > Other...* Then, select *Petals Service Provider* under the *Petals* category.
\\
A wizard opens up, showing three drop-down lists.
In the *Use Case* list, select *Manual Implementation*.
In the *Petals Component* list, select *Jsr-181 // petals-se-jsr181*.
In the *Component Version* list, select the version of the Petals-SE-Jsr181 that you are using in Petals.
\\
In the scope of this tutorial, we are going to work with the version 1.2 of the Jsr181 component.
Which gives us:
!petals-studio-tuto-jsr181-1.jpg!
\\
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 Jsr181 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-jsr181-2.jpg!
!petals-studio-tuto-jsr181-3.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 creation mode
With the Jsr181 tooling, there are two approaches: a top-down one and a bottom-up one.
Since we want to start from a Java implementation, we will choose the bottom-up one.
Select the radio button *Start with a Java implementation* and provide the fully qualified name of a Java class.
A fully qualified name is made up of the package name (entirely in lower case) and the simple classe name (starts with an upper-case letter).
\\ !petals-studio-tuto-jsr181-java-1.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).
Notice that there is no other file in the directory. And the jbi.xml is marked with a warning, saying there is no WSDL file. This WSDL file will be generated once the Java implementation is complete.
And obviously, there is an annotated Java class, whose name is the one given in the wizard.
This class contains a base of definition, showing some of the available annotations.
\\
!petals-studio-tuto-jsr181-java-2.jpg!
h1. Updating, packaging and deploying
h2. Further edition and packaging
After completion, the service implementation has been open in the Java editor.
Add method declarations, implementations and annotations. The main class must be annotated with _@WebService_.
Other annotations are optional, but recommended to generate a WSDL that will ease the creation of clients (e.g. avoid arg0, arg1 as parameter names).
!petals-studio-tuto-jsr181-java-3.jpg!
\\
Once the Java implementation is complete, it is time to generate the associated WSDL.
To do that, right-click the project and select *Petals > Generate WSDL(s)*.
\\
!petals-studio-tuto-jsr181-java-4.jpg!
\\
A dialog shows up, asking whether a new jbi.xml should be generated.
Clicking *No* only generates WSDL definitions from the classes that are annotated with _@WebService_. The jbi.xml will have to be edited manually.
Clicking *Yes* will in addition generate a new jbi.xml that references the WSDL.
!petals-studio-tuto-jsr181-5.jpg!
\\
{info}
Be careful, all the WSDL definitions of the *jbi* directory will be deleted.
And take note that the new jbi.xml will erase the previous one, thus loosing hand-made modifications.
{info}
{info}
It is possible to define several _@WebService_ annotated classes in a same project.
When generating the WSDL(s), a WSDL will be created for each class. If a new jbi.xml is also generated, there will be one _provides_ block per annotated class.
{info}
\\
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-SE-Jsr181 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-SE-Jsr181 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 Jsr181 component to make it work.
Using the default settings is enough to make the service-unit work.