Petals Documentation > Petals ESB > Petals Components > Petals-SE-Jsr181 1.1

Petals-SE-Jsr181 1.1

Features

This service engine allows to create a Petals service from an annotated Java class.
The annotations are the ones defined by the JSR-181 specification, although most of the JAX-WS annotations are supported, Apache Axis2 being used by the component.


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.
Table of contents
Contributors
No contributors found for: authors on selected page(s)

Creating a native Petals service

This section explains how to create a native Petals service, that will run on the JSR-181 component.
We speak of native service because this service is coded in Java and runs inside Petals. It does not need any container or third-party server.

Service-Unit content

A service-unit for this component must contain:

  • One or several JAR files, containing at least one Java annotated class.
  • 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:

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

The Service implementation

The native service is implemented by Java class which must be annotated with JSR-181 annotations (@WebService to be exact).
Every parameter must be a Java bean, with a public zero-argument constructor.
The important thing to take care is the way objects will be marshalled and unmarshalled, i.e. the transformation between the XML messages than come from and to Petals, and the Java objects the service implementation will deal with. This is why all your parameters should respect the Java bean conventions.


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:

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

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.


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.


It is not possible to only provide the Java class.
The component needs the annotated class, the associated WSDL and a JBI descriptor.
This descriptor references WSDL elements. You mandatory need to have generated the WSDL.

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


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 (JSR-181)

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

Data-binding

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:

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


... would result in a response like:

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

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

Configuring the component


The component can be configured through its JBI descriptor: 

<?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-5"
	xmlns:jsr181="http://petals.ow2.org/components/jsr181/version-1">
	
	<jbi:component type="service-engine"
		bootstrap-class-loader-delegation="parent-first">
		<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>
		<jbi:bootstrap-class-name>org.ow2.petals.se.jsr181.Jsr181Bootstrap</jbi:bootstrap-class-name>
		<jbi:bootstrap-class-path><jbi:path-element/></jbi:bootstrap-class-path>
		
		<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:notifications>false</petalsCDK:notifications>
		<petalsCDK:jbi-listener-class-name>org.ow2.petals.se.jsr181.Jsr181JBIListener</petalsCDK:jbi-listener-class-name>
	</jbi:component>
</jbi:jbi>


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


This component has no specific parameter.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.