Petals-SE-Jsr181 1.5.0+

This version must be installed on Petals ESB 5.0.0+

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

Contributors
No contributors found for: authors on selected page(s)

Creating an hard-coded service

This section explains how to create a hard-coded service, that will run on the JSR-181 component.

JSR-181 proposes an easy way to define the service you want to expose via Java annotations.

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

    /**
     * Gets a list of persons.
     */
    @WebMethod
    public List<Person> getPersons() {
        ...
    }
}

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.


If one your method returns a collection of beans, do not forget to annotate the fields of the bean class with @XmlAttribute.
Otherwise, the WSDL generation will be incomplete (missing elements in the XML schemas).


public class Person {

	public enum Sex {
		F ("Female"),M("Male");
		
		private String textToDisplay;
		
		Sex(String text) {
			this.textToDisplay = text;
		}
		
		@Override
		public String toString() {
			return this.textToDisplay;
		}
	}
	
	@XmlElement
	private String firstName;
	
	@XmlElement
	private String surname;
	
	@XmlElement
	private Calendar birthday;
	
	@XmlElement
	private Sex sex;

	public Person() {
		this.firstName = null;
		this.surname = null;
		this.birthday = null;
		this.sex = null;
	}

	public String getFirstName() {
		return firstName;
	}

	public String getSurname() {
		return surname;
	}

	public Calendar getBirthday() {
		return birthday;
	}

	public Sex getSex() {
		return sex;
	}	
}


There are many more annotations to use with JAX-WS.
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

Interceptor

Example of an interceptor configuration:

<?xml version="1.0" encoding="UTF-8"?>
<!--...-->
<petalsCDK:su-interceptors>
  <petalsCDK:send>
    <petalsCDK:interceptor name="myInterceptorName">
      <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
      <petalsCDK:param name="myParamName2">myParamValue2</petalsCDK:param>
    </petalsCDK:interceptor>
  </petalsCDK:send>
  <petalsCDK:accept>
    <petalsCDK:interceptor name="myInterceptorName">
      <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
    </petalsCDK:interceptor>
  </petalsCDK:accept>
  <petalsCDK:send-response>
    <petalsCDK:Interceptor name="myInterceptorName">
      <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
    </petalsCDK:Interceptor>
  </petalsCDK:send-response>
  <petalsCDK:accept-response>
    <petalsCDK:Interceptor name="myInterceptorName">
      <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
    </petalsCDK:Interceptor>
  </petalsCDK:accept-response>
</petalsCDK:su-interceptors>
<!--...-->

Interceptors configuration for SU (CDK)

Parameter Description Default Required
send Interceptor dedicated to send phase, for an exchange sent by a consumer - No
accept Interceptor dedicated to receive phase, for an exchange received by a provider - No
send-response Interceptor dedicated to send phase, for an exchange (a response) received by a consumer - No
accept-response Interceptor dedicated to receive phase, for an exchange sent (a response) by a provider - No
interceptor - name Logical name of the interceptor instance. It can be referenced to add extended parameters by a SU Interceptor configuration. - Yes
param[] - name The name of the parameter to use for the interceptor for this SU - No
param[] The value of the parameter to use for the interceptor for this SU - No

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>
Configuration of the component, CDK part

Parameter Description Default Required Scope
acceptor-pool-size The size of the thread pool used to accept Message Exchanges from the NMR. Once a message is accepted, its processing is delegated to the processor pool thread.
3

Yes

Runtime

acceptor-retry-number Number of tries to submit a message exchange to a processor for processing before to declare that it cannot be processed.
40

No

Installation

acceptor-retry-wait Base duration, in milliseconds, to wait between two processing submission tries. At each try, the new duration is the previous one added by this base duration multiplied by the try number plus a random value between 0 and 10.
250

No

Installation

acceptor-stop-max-wait The max duration (in milliseconds) of the stop of an acceptor before to force it to stop.
500

No

Runtime

message-processor-max-pool-size Max size of the object pool containing message exchange processors.
processor-max-pool-size

No

Runtime

processor-pool-size The size of the thread pool used to process Message Exchanges. Once a message is accepted, its processing is delegated to one of the thread of this pool.
10
Yes

Runtime
processor-max-pool-size The maximum size of the thread pool used to process Message Exchanges. The difference between this size and the processor-pool-size represents the dynamic threads that can be created and destroyed during overhead processing time.
50

No
Runtime

processor-keep-alive-time When the number of processors is greater than the core, this is the maximum time that excess idle processors will wait for new tasks before terminating, in seconds.
300

No
Runtime

processor-stop-max-wait The max duration (in milliseconds) of message exchange processing on stop phase.
15000

No
Runtime

time-beetween-async-cleaner-runs The time (in milliseconds) between two runs of the asynchronous message exchange cleaner.
2000

No
Installation

properties-file Name of the file containing properties used as reference by other parameters. Parameters reference the property name in the following pattern ${myPropertyName}. At runtime, the expression is replaced by the value of the property.

The properties file can be reloaded using the JMX API of the component. The runtime configuration MBean provides an operation to reload these place holders. Check the service unit parameters that support this reloading.

The value of this parameter is :
  • an URL
  • a file relative to the PEtALS installation path
  • an absolute file path
  • an empty value to stipulate a non-using file.
-
No
Installation
monitoring-sampling-period Period, in seconds, of a sample used by response time probes of the monitoring feature.
300

No
Installation

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.

Interceptor

Interceptors can be defined to inject some post or pre processing in the component during service processing.

Using interceptor is very sensitive and must be manipulate only by power users. An non properly coded interceptor engaged in a component can lead to uncontrolled behaviors, out of the standard process.

Example of an interceptor configuration:

<?xml version="1.0" encoding="UTF-8"?>
<!--...-->
<petalsCDK:component-interceptors>
  <petalsCDK:interceptor active="true" class="org.ow2.petals.myInterceptor" name="myInterceptorName">
    <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
    <petalsCDK:param name="myParamName2">myParamValue2</petalsCDK:param>
  </petalsCDK:interceptor>
</petalsCDK:component-interceptors>
<!--...-->

Interceptors configuration for Component (CDK)

Parameter Description Default Required
interceptor - class Name of the interceptor class to implement. This class must extend the abstract class org.ow2.petals.component.common.interceptor.Interceptor. This class must be loadable from the component classloader, or in a dependent Shared Library classloader. - Yes
interceptor - name Logical name of the interceptor instance. It can be referenced to add extended parameters by a SU Interceptor configuration. - Yes
interceptor - active If true, the Interceptor instance is activated for every SU deployed on the component.
If false, the Interceptor can be activated:
-by the InterceptorManager Mbean at runtime, to activate the interceptor for every deployed SU.
-by a SU configuration
- Yes
param[] - name The name of the parameter to use for the interceptor. - No
param[] The value of the parameter to use for the interceptor. - No

Monitoring the component

In this documentation, the term "Allocated threads" must be understood as "Active threads", see PETALSDISTRIB-37. This naming error will be fixed in the next version.

Using metrics

Several probes providing metrics are included in the component, and are available through the JMX MBean 'org.ow2.petals:type=custom,name=monitoring_<component-id>', where <component-id> is the unique JBI identifier of the component.

Common metrics

The following metrics are provided through the Petals CDK, and are common to all components:

Metrics, as MBean attribute Description Detail of the value Configurable
MessageExchangeAcceptorThreadPoolMaxSize The maximum number of threads of the message exchange acceptor thread pool integer value, since the last startup of the component yes, through acceptor-pool-size
MessageExchangeAcceptorThreadPoolCurrentSize The current number of threads of the message exchange acceptor thread pool. Should be always equals to MessageExchangeAcceptorThreadPoolMaxSize. instant integer value no
MessageExchangeAcceptorCurrentWorking The current number of working message exchange acceptors. instant long value no
MessageExchangeAcceptorMaxWorking The max number of working message exchange acceptors. long value, since the last startup of the component no
MessageExchangeAcceptorAbsoluteDurations The aggregated durations of the working message exchange acceptors since the last startup of the component. n-tuple value containing, in nanosecond:
  • the maximum duration,
  • the average duration,
  • the minimum duration.
no
MessageExchangeAcceptorRelativeDurations The aggregated durations of the working message exchange acceptors on the last sample. n-tuple value containing, in nanosecond:
  • the maximum duration,
  • the average duration,
  • the minimum duration,
  • the 10-percentile duration (10% of the durations are lesser than this value),
  • the 50-percentile duration (50% of the durations are lesser than this value),
  • the 90-percentile duration (90% of the durations are upper than this value).
no
MessageExchangeProcessorObjectPoolBorrowedObjectsCurrent The current number of borrowed object of the message exchange processor object pool instant integer value no
MessageExchangeProcessorObjectPoolBorrowedObjectsMax The maximum number of object of the message exchange processor object pool that was borrowed integer value, since the last startup of the component no
MessageExchangeProcessorObjectPoolIdleObjectsCurrent The current number of idel object of the message exchange processor object pool instant integer value no
MessageExchangeProcessorObjectPoolIdleObjectsMax The maximum number of object of the message exchange processor object pool that was idle integer value, since the last startup of the component no
MessageExchangeProcessorObjectPoolMaxSize The maximum size, in objects, of the message exchange processor object pool instant integer value yes, through processor-max-pool-size
MessageExchangeProcessorObjectPoolMinIdleSize The minimum size, in objects (in state idle), of the message exchange processor object pool instant integer value yes, through processor-pool-size
MessageExchangeProcessorObjectPoolExhaustion The number of message exchange processor object pool exhaustions integer counter value, since the last startup of the component no
MessageExchangeProcessorThreadPoolAllocatedThreadsCurrent The current number of allocated threads of the message exchange processor thread pool instant integer value no
MessageExchangeProcessorThreadPoolAllocatedThreadsMax The maximum number of threads of the message exchange processor thread pool that was allocated integer value, since the last startup of the component no
MessageExchangeProcessorThreadPoolIdleThreadsCurrent The current number of idle threads of the message exchange processor thread pool instant integer value no
MessageExchangeProcessorThreadPoolIdleThreadsMax The maximum number of threads of the message exchange processor thread pool that was idle integer value, since the last startup of the component no
MessageExchangeProcessorThreadPoolMaxSize The maximum size, in threads, of the message exchange processor thread pool instant integer value yes, through http-thread-pool-size-max
MessageExchangeProcessorThreadPoolMinSize The minimum size, in threads, of the message exchange processor thread pool instant integer value yes, through http-thread-pool-size-min
MessageExchangeProcessorThreadPoolQueuedRequestsCurrent The current number of enqueued requests waiting to be processed by the message exchange processor thread pool instant integer value no
MessageExchangeProcessorThreadPoolQueuedRequestsMax The maximum number of enqueued requests waiting to be processed by the message exchange processor thread pool that was allocated since the last startup of the component instant integer value no
ServiceProviderInvokations The number of service provider invokations grouped by:
  • interface name, as QName, the invoked service provider,
  • service name, as QName, the invoked service provider,
  • invoked operation, as QName,
  • message exchange pattern,
  • and execution status (PENDING, ERROR, FAULT, SUCCEEDED).
integer counter value since the last startup of the component no
ServiceProviderInvokationsResponseTimeAbs The aggregated response times of the service provider invokations since the last startup of the component grouped by:
  • interface name, as QName, the invoked service provider,
  • service name, as QName, the invoked service provider,
  • invoked operation, as QName,
  • message exchange pattern,
  • and execution status (PENDING, ERROR, FAULT, SUCCEEDED).
n-tuple value containing, in millisecond:
  • the maximum response time,
  • the average response time,
  • the minimum response time.
no
ServiceProviderInvokationsResponseTimeRel The aggregated response times of the service provider invokations on the last sample, grouped by:
  • interface name, as QName, the invoked service provider,
  • service name, as QName, the invoked service provider,
  • invoked operation, as QName,
  • message exchange pattern,
  • and execution status (PENDING, ERROR, FAULT, SUCCEEDED).
n-tuple value containing, in millisecond:
  • the maximum response time,
  • the average response time,
  • the minimum response time,
  • the 10-percentile response time (10% of the response times are lesser than this value),
  • the 50-percentile response time (50% of the response times are lesser than this value),
  • the 90-percentile response time (90% of the response times are upper than this value).
no

Dedicated metrics

No dedicated metric is available.

Receiving alerts

Several alerts are notified by the component through notification of the JMX MBean 'org.ow2.petals:type=custom,name=monitoring_<component-id>', where <component-id> is the unique JBI identifier of the component.

To integrate these alerts with Nagios, see Receiving Petals ESB defects in Nagios.

Common alerts

Defect JMX Notification
A message exchange acceptor thread is dead
  • type: org.ow2.petals.component.framework.process.message.acceptor.pool.thread.dead
  • no user data
No more thread is available in the message exchange acceptor thread pool
  • type: org.ow2.petals.component.framework.process.message.acceptor.pool.exhausted
  • no user data
No more message exchange processor is available in the message exchange processor pool
  • type: org.ow2.petals.component.framework.process.message.processor.object.pool.exhausted
  • no user data
No more thread is available to run a message exchange processor
  • type: org.ow2.petals.component.framework.process.message.processor.thread.pool.exhausted
  • no user data

Dedicated alerts

No dedicated alert is available.

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