{section}
{column}
h1. Summary
This tutorial explains how you can create a XML validation service.
Concretely, such a service validates Petals messages against a XML schema.
\\
Technically, this tutorial shows the creation of a service-unit for the [Petals-SE-Validation|petalscomponents:Petals-SE-Validation] component in *provides* mode.
{info}
*Level:* Advanced
*Estimated time:* 10 minutes, without counting the XSD edition time
*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 > 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 up, showing three drop-down lists.
In the *Use Case* list, select *Miscellaneaous*.
In the *Petals Component* list, select *Validation // petals-se-validation*.
In the *Component Usage*, select *Provide or Import a Service in Petals ESB*.
In the *Component Version* list, select the version of the Petals-SE-Validation that you are using in Petals.
\\
In the scope of this tutorial, we are going to work with the version 1.1 of the Validation component.
Which gives us:
!petals-studio-tuto-provides-validation-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 Validation component provides a generic WSDL definition, and thus defines *fixed values*.
This WSDL definition is only a basis and may be updated then.
!petals-studio-tuto-provides-validation-2.jpg!
\\
You can simply complete the service and end-point names.
!petals-studio-tuto-provides-validation-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 Validation 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-validation-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 Validation parameters
This page defines information which are specific to the Petals Validation component.
In fact, only two elements are required:
* A XML schema: you can either import an existing one or create a new one.
* Whether you want to generate a default WSDL or not.
** This WSDL will be synchronized with the XML schema that is created by default.
** If you import an existing XSD, the generated WSDL will not be synchronized with this XML schema.
\\ !petals-studio-tuto-provides-validation-5.jpg!
\\
You can get more information in the documentation of the [Petals-SE-Validation|petalscomponents:Petals-SE-Validation] component.
Click *Next*.
h2. Specifying the CDK parameters
The CDK is the Petals framework to develop JBI components.
The Petals-SE-Validation 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 Validation can be found in the documentation of the [Petals-SE-Validation|petalscomponents:Petals-SE-Validation] component.
\\ !petals-studio-tuto-provides-validation-6.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).
In the same directory, you can see the WSDL definition that was generated for this version of the Validation component.
Eventually, there is a XML schema, which is either the one that was imported, or a default one to complete.
\\ !petals-studio-tuto-provides-validation-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.
This jbi.xml is complete and does not need to be updated. The edition mainly concerns the XML schema and the WSDL definition.
h3. Editing the XML schema
Petals Studio embeds the XSD editor from the Eclipse WTP project.
You can use it to edit the XML schema, using its built-in validation and content assistance (available by pressing *Ctrl + space*).
!petals-studio-tuto-provides-validation-8.jpg!
h3. Updating the WSDL definition
The WSDL that is generated by this wizard is a default one.
\\
{tip}
If you imported an existing XML schema, you imperatively have to edit the WSDL definition.
If you generated a default XML schema and modified it, you imperatively have to edit the WSDL definition.
{tip}
\\
*What can you modify in the generated WSDL?*.
* You can modify the *input* and *output* messages of the *validate* operation.
* You can modify the *input* message of the *filter* operation.
* You can modify the *XML types*.
And that's it. Do not change the rest of the WSDL.
\\
{warning}
If having a WSDL is a too constraining for your service-unit, you can delete the generated one and set the WSDL field to _null_ in the jbi.xml.
This value can be set to _null_ by setting the attribute *xsi:nil="true"* (the xsi prefix should be already defined).
\\
*Note that not providing a WSDL makes your service-unit a Petals end-point, but not a real Petals service.*
It will be registered in the Petals registry, but creating a service consumer for it will be almost impossible.
Service consumers are generally created from WSDL definitions.
Not having a WSDL definition is a bad practice in SOA.
But it is acceptable for integration projects (e.g. combined with Enterprise Integration Patterns).
{warning}
\\
Eventually, if you change any XML type, you have to update the the interface name.
This can be done either by changing the name space URI of the WSDL, or by changing the local part, or by changing both.
{tip}
When you customize XML types in a generated Validation WSDL, change the (interface) port type name in the WSDL.
Then update your jbi.xml to match the WSDL's content.
{tip}
h3. Packaging the project
The project contains everything the Validation 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-SE-Validation 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-Validation 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 Validation 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 create a XML validation service.
Concretely, such a service validates Petals messages against a XML schema.
\\
Technically, this tutorial shows the creation of a service-unit for the [Petals-SE-Validation|petalscomponents:Petals-SE-Validation] component in *provides* mode.
{info}
*Level:* Advanced
*Estimated time:* 10 minutes, without counting the XSD edition time
*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 > 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 up, showing three drop-down lists.
In the *Use Case* list, select *Miscellaneaous*.
In the *Petals Component* list, select *Validation // petals-se-validation*.
In the *Component Usage*, select *Provide or Import a Service in Petals ESB*.
In the *Component Version* list, select the version of the Petals-SE-Validation that you are using in Petals.
\\
In the scope of this tutorial, we are going to work with the version 1.1 of the Validation component.
Which gives us:
!petals-studio-tuto-provides-validation-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 Validation component provides a generic WSDL definition, and thus defines *fixed values*.
This WSDL definition is only a basis and may be updated then.
!petals-studio-tuto-provides-validation-2.jpg!
\\
You can simply complete the service and end-point names.
!petals-studio-tuto-provides-validation-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 Validation 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-validation-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 Validation parameters
This page defines information which are specific to the Petals Validation component.
In fact, only two elements are required:
* A XML schema: you can either import an existing one or create a new one.
* Whether you want to generate a default WSDL or not.
** This WSDL will be synchronized with the XML schema that is created by default.
** If you import an existing XSD, the generated WSDL will not be synchronized with this XML schema.
\\ !petals-studio-tuto-provides-validation-5.jpg!
\\
You can get more information in the documentation of the [Petals-SE-Validation|petalscomponents:Petals-SE-Validation] component.
Click *Next*.
h2. Specifying the CDK parameters
The CDK is the Petals framework to develop JBI components.
The Petals-SE-Validation 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 Validation can be found in the documentation of the [Petals-SE-Validation|petalscomponents:Petals-SE-Validation] component.
\\ !petals-studio-tuto-provides-validation-6.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).
In the same directory, you can see the WSDL definition that was generated for this version of the Validation component.
Eventually, there is a XML schema, which is either the one that was imported, or a default one to complete.
\\ !petals-studio-tuto-provides-validation-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.
This jbi.xml is complete and does not need to be updated. The edition mainly concerns the XML schema and the WSDL definition.
h3. Editing the XML schema
Petals Studio embeds the XSD editor from the Eclipse WTP project.
You can use it to edit the XML schema, using its built-in validation and content assistance (available by pressing *Ctrl + space*).
!petals-studio-tuto-provides-validation-8.jpg!
h3. Updating the WSDL definition
The WSDL that is generated by this wizard is a default one.
\\
{tip}
If you imported an existing XML schema, you imperatively have to edit the WSDL definition.
If you generated a default XML schema and modified it, you imperatively have to edit the WSDL definition.
{tip}
\\
*What can you modify in the generated WSDL?*.
* You can modify the *input* and *output* messages of the *validate* operation.
* You can modify the *input* message of the *filter* operation.
* You can modify the *XML types*.
And that's it. Do not change the rest of the WSDL.
\\
{warning}
If having a WSDL is a too constraining for your service-unit, you can delete the generated one and set the WSDL field to _null_ in the jbi.xml.
This value can be set to _null_ by setting the attribute *xsi:nil="true"* (the xsi prefix should be already defined).
\\
*Note that not providing a WSDL makes your service-unit a Petals end-point, but not a real Petals service.*
It will be registered in the Petals registry, but creating a service consumer for it will be almost impossible.
Service consumers are generally created from WSDL definitions.
Not having a WSDL definition is a bad practice in SOA.
But it is acceptable for integration projects (e.g. combined with Enterprise Integration Patterns).
{warning}
\\
Eventually, if you change any XML type, you have to update the the interface name.
This can be done either by changing the name space URI of the WSDL, or by changing the local part, or by changing both.
{tip}
When you customize XML types in a generated Validation WSDL, change the (interface) port type name in the WSDL.
Then update your jbi.xml to match the WSDL's content.
{tip}
h3. Packaging the project
The project contains everything the Validation 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-SE-Validation 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-Validation 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 Validation component to make it work.
Using the default settings is enough to make the service-unit work.