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 component in provides mode. Level: Advanced Estimated time: 10 minutes, without counting the XSD edition time Expected skills: -

Table of contents Summary Creating the Service-Unit project Getting started Identifying the service Defining the project name Specifying the Validation parameters Specifying the CDK parameters Checking the result Updating, packaging and deploying Further edition and packaging Editing the XML schema Updating the WSDL definition Packaging the project Deployment

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 up, showing three drop-down lists.
In the Use Case list, select Use a Petals technical service.
In the Petals Component list, select Validation   // petals-se-validation.
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:

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 Validation component provides a generic WSDL definition, and thus defines fixed values.
This WSDL definition is only a basis and may be updated then.

You can simply 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 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 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 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.

You can get more information in the documentation of the Petals-SE-Validation component.
Click Next.

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 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 Validation component.
Eventually, there is a XML schema, which is either the one that was imported, or a default one to complete.

Updating, packaging and deploying

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.

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

Updating the WSDL definition

The WSDL that is generated by this wizard is a default one.

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.

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.

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

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.

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.

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, you can package it as any Service-Unit project.
It results in the creation of a Service Assembly for the Petals-SE-Validation 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-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.