Features

This Service Engine allows to expose an annotated POJO as a JBI Service in the bus.

This component is based on the Petals ESB Component Development Kit and on Apache Axis2 for invocation and marshalling.

If you want more details about jsr181, you can consult this the specification on the Java Community Process portal : http://jcp.org/en/jsr/detail?id=181

Component Configuration

The component can be configured through its JBI descriptor file like this :

<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0" xmlns:jbi="http://java.sun.com/xml/ns/jbi"
    xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-4.0"
    xmlns:jsr181="http://petals.ow2.org/components/jsr181/version-1.0>

  <jbi:component type="service-engine" bootstrap-class-loader-delegation="parent-first">
    <jbi:identification>
      <jbi:name>petals-se-jsr181</jbi:name>
      <jbi:description> The jsr181 Service Engine (based on Axis2)</jbi:description>
    </jbi:identification>
    <jbi:component-class-name>org.ow2.petals.se.jsr181.Component</jbi:component-class-name>
    <jbi:component-class-path>...</jbi:component-class-path>
    <jbi:bootstrap-class-name>org.ow2.petals.se.jsr181.Bootstrap</jbi:bootstrap-class-name>
    <jbi:bootstrap-class-path>...</jbi:bootstrap-class-path>

    <!-- Component Development Kit Parameters -->
    <petalsCDK:acceptor-pool-size>5</petalsCDK:acceptor-pool-size>
    <petalsCDK:processor-pool-size>10</petalsCDK:processor-pool-size>
    <petalsCDK:ignored-status>DONE_AND_ERROR_IGNORED</petalsCDK:ignored-status>
    <petalsCDK:properties-file />
    <petalsCDK:performance-notifications>false</petalsCDK:performance-notifications>
  </jbi:component>
</jbi:jbi>

Note
Actually, nothing is configurable in this JBI descriptor, so leave it as it is.

Node
The class name values in italic should not be modified by the user.

Unable to render {include} Couldn't find a page to include called: 0 CDK Component Configuration Table

Unable to render {include} Couldn't find a page to include called: 0 CDK Interceptor configuration for SU

Service Configuration

PROVIDE SERVICE : Expose an Java Class as Service in the JBI environment.

The petals-se-jsr181 component can expose a Java Class as JBI ServiceEndpoint. This is done by deploying a Service Unit on it.

When a message is received on a JSR181 linked endpoint from the JBI environment, it is mapped to an Axis2 message and sent to the Axis2 runtime. The linked Java Class is called and the response is processed and returned to the JBI environment.

Service Unit descriptor

The Service Unit descriptor file ( jbi.xml ) looks like this :

<?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-4.0"
    xmlns:helloworld="http://petals.ow2.org/helloworld"
    xmlns:jsr181="http://petals.ow2.org/components/jsr181/version-1.0">

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

Definition of CDK parameter scope :

Installation: The parameter can be set during the installation of the component, by using the installation MBean (see JBI specifications for details about the installation sequence). If the parameter is optional and has not been defined during the development of the component, it is not available at installation time.
Runtime: The paramater can be set during the installation of the component and during runtime. The runtime configuration can be changed using the CDK custom MBean named RuntimeConfiguration. If the parameter is optional and has not been defined during the development of the component, it is not available at installation and runtime times.

Configuration of a Service Unit to provide a service (JBI)

Parameter	Description	Default	Required
provides	Describe the JBI service that will be exposed into the JBI bus. Interface (QName), Service (QName) and Endpoint (String) attributes are required.	-	Yes

Configuration of a Service Unit to provide a service (CDK)

Parameter	Description	Default	Required
timeout	Timeout in milliseconds of a synchronous send. This parameter is used by the method `sendSync` (Exchange exchange) proposes by the CDK `Listeners` classes. Set it to 0 for an infinite timeout.	30000	No
exchange-properties	This sections defines the list of properties to set to the JBI exchange when processing a service.	-	No
message-properties	This sections defines the list of properties to set to the JBI message when processing a service.	-	No
validate-wsdl	Activate the validation of the WSDL when deploying a service unit.	true	No
wsdl	Path to the WSDL document describing services and operations exposed by the provided JBI endpoints defined in the SU. The value of this parameter is : an URL a file relative to the root of the SU package If not specified, a basic WSDL description is automaticaly provided by the CDK.	-	No
forward-attachments	Defines if attachment will be forwarded from IN message to OUT message.	false	No
forward-message-properties	Defines if the message properties will be forwarded from IN message to OUT message.	false	No
forward-security-subject	Defines if the security subject will be forwarded from IN message to OUT message.	false	No

Configuration of a Service Unit to provide a service (JSR181)

Parameter	Description	Default	Required
class	The JSR181 annotated class which will provide the Service.This class must be available in the Service Unit class loader.	-	Yes

Annotated class

The following class is a sample of JSR181 annotated class (taken from the Petals usecase sources) :

package org.ow2.petals.usecase.jsr181;

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

/**
 *
 * @author chamerling - eBM WebSourcing
 *
 *
 * NOTE : The
 * @WebService parameters are not used by the component, the service name is
 *             defined in the service unit. Need to modify the CDK to be able to
 *             create the endpoint from these values...
 */
@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 say me " + str;
    }

    /**
     * Get 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 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");
    }
}

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 see as a JBI operation. You can specialize the operation name and more with the annotation parameters.

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

Before sending the JBI message to the Axis2 service, the JBI Service Engine will check if :

If the requested operation exists. 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 will be returned in the JBI message exchange.

With the previous code samples, you can now call the {http://petals.ow2.org/helloworld}HelloworldService and operation sayHello with an InOut MEP with a JBI message payload like :

<sayHello>
  <param0>Hey!!!</param0>
</sayHello>

and you will get a response like :

<dlwmin:sayHelloResponse
    xmlns:dlwmin="http://petals.ow2.org"
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <return>You say me Hey!!!</return>
</dlwmin:sayHelloResponse>

Samples

The jsr181 service engine samples are available as use cases section. You can find them in the project sources repository.

We recommend you to check this source code to create the JSR181 class and the Service Unit.

Limitations

The WSDL description is not dynamically generated from the Java class at runtime. This is due to an Axis2 and Petals ESB class loader issue. You can find an example on how to generate and include the WSDL description from the Java class with some
Maven2 plugins in the usecases related to this component.
The JBI Component Context is not available on the POJO so you can not access to the JBI Delivery Channel to do some light orchestration. This feature will be added soon !

Table of contents