{section}
{column}

h1. Features

This component can only expose services in Petals ESB.
The invocation of Petals services from the annotated class is experimental and will not be discussed here.
{column}
{column:width=350px}
{panel:title=Table of contents}{toc}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list}{panel}
{column}
{section}

* A WSDL definition, that is coherent with the Java class. The best way to ensure that is to generate the WSDL from the annotated class.
* A JBI descriptor.

\\
The directory structure of a SU for the Petals-SE-Jsr81 looks like this:

{noformat}
su-jsr181-ServiceName-provide.zip
+ META-INF
- jbi.xml
+ Service.wsdl
+ ServiceImplementation.jar (one or several)
{noformat}

\\
The service operation will be the class methods.
You are strongly encouraged to annotate every element of the class, so that the generated WSDL is easy to read.
The WSDL should be generated from the annotated class. Tools like *wsgen* make this task easy (or you can use Petals Studio too).

\\
Here is a sample annotated class:

{code:lang=java}
package org.ow2.petals.usecase.jsr181;

import java.text.SimpleDateFormat;
import java.util.Date;
import javax.jws.WebMethod;
import javax.jws.WebService;

/**
* @author Christophe Hamerling - EBM WebSourcing
*/
@WebService(serviceName = "Hello", name = "MyService", targetNamespace = "http://petals.ow2.org")
public class TestService {

/**
* Say hello to the world!
*/
@WebMethod
public String sayHello( String str ) {
System.out.println( "Hey! This is the sayHello operation." );
return "You told me: " + str;
}


/**
* Gets a person from its id only to test 'complex' data binding.
*
* @param id
* @return
*/
@WebMethod
public Person getPerson( int id ) {
System.out.println( "Get person " + id );
return new Person( id, "Christophe", "Hamerling", 29, "France" );
}


/**
*
* @return
*/
@WebMethod
public String getTime() {
System.out.println( "Get time" );
return new SimpleDateFormat().format( new Date( System.currentTimeMillis()));
}


/**
* NOP
*/
@WebMethod
public void voidvoid() {
System.out.println( "The Void operation" );
}


/**
* The final WSDL operation will be 'specializedOperation'
*/
@WebMethod(operationName = "specializedOperation")
public void operation() {
System.out.println( "The specialized operation" );
}


/**
*
* @throws Exception
*/
@WebMethod
public String iAmThrowingAnException() throws Exception {
System.out.println( "throw exception" );
throw new Exception( "This is a server side Exception" );
}
}
{code}

The main annotations you may use are:
* The *@WebService* annotation is *mandatory* and is used by the Axis2 engine to build the service. You can specialize the service name, target namespace and more with the annotation parameter.
* The *@WebMethod* annotation is used to delare the that the method will be seen as a JBI operation. You can specialize the operation name and more with the annotation parameters.
* The *@WebParam* annotation is used to configure an operation parameter.

More information is available on the [Apache Axis2 page|http://ws.apache.org/axis2/].

\\
In fact, for each annotated class, the Petals Jsr181 component creates an Axis2 service.
The messages that are received from the bus are then forwarded to the right Axis2 service the component holds.
Before forwarding the JBI message to the Axis2 service, the service engine checks that :
* The requested operation exists in the Axis2 service. If not, an error will be returned in the JBI message exchange.
* The JBI Message Exchange Pattern (MEP) is compatible with the target operation. For example, in the previous code snippet, an InOut MEP is not compatible with the 'voidvoid' operation and an error would be returned in the JBI message exchange.

\\

h2. Service-Unit descriptor

The service-unit descriptor file (jbi.xml) looks like this:
\\
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:helloworld="http://petals.ow2.org/helloworld"
xmlns:jsr181="http://petals.ow2.org/components/jsr181/version-1">

<jbi:services binding-component="false">
<jbi:provides
interface-name="helloworld:Helloworld"
service-name="helloworld:HelloworldService"
endpoint-name="HelloworldEndpoint">
<petalsCDK:wsdl>Service.wsdl</petalsCDK:wsdl>
<jsr181:class>org.ow2.petals.usecase.jsr181.TestService</jsr181:class>
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}

\\
{include:0 CDK SU Provide Configuration}
\\
*Configuration of a Service Unit to provide a service (JSR-181)*

The data-binding is the process that transforms XML messages into Java objects, and vice-versa.
The Jsr181 component delegates this task to Axis2.

As an example, invoking the *sayHello* operation of the previous service, with a message payload like:
{code:lang=xml}
<sayHello>
<param0>Hey!!!</param0>
</sayHello>
{code}

\\
... would result in a response like:
{code:lang=xml}
<dlwmin:sayHelloResponse
xmlns:dlwmin="http://petals.ow2.org"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<return>You told me: Hey!!!</return>
</dlwmin:sayHelloResponse>
{code}

Obviously, we assume the operation was invoked with the right MEP (*InOut* here).


h1. Configuring the component

\\
The component can be configured through its JBI descriptor:
\\
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0" xmlns:jbi="http://java.sun.com/xml/ns/jbi"

<jbi:identification>
<jbi:name>petals-se-jsr181</jbi:name>
<jbi:description> The JSR-181 Service Engine (based on Axis2)</jbi:description>
</jbi:identification>
<jbi:component-class-name>org.ow2.petals.se.jsr181.Jsr181Se</jbi:component-class-name>
<jbi:component-class-path><jbi:path-element/></jbi:component-class-path>

<petalsCDK:ignored-status>DONE_AND_ERROR_IGNORED</petalsCDK:ignored-status>
<petalsCDK:notifications>false</petalsCDK:notifications>
<petalsCDK:jbi-listener-class-name>org.ow2.petals.se.jsr181.Jsr181JBIListener</petalsCDK:jbi-listener-class-name>
</jbi:component>
</jbi:jbi>