This version must be installed on [Petals ESB 5.4.0]+ Previous service units are no more compliant with this component version and must be migrated. See Migrating service units developed for previous versions Exposing a Java class as a POJO service (Provides mode) Usage The POJO that you want to develop must follow certain constraints : no specific interface implementation is required. if a public setComponentContext(ComponentContext context) setter method is defined, the component set its ComponentContext instance with this method at the initialization of the Service Unit. if a public setDeliveryChannel(DeliveryChannel channel) setter method is defined, the component set its DeliveryChannel instance with this method at the initialization of the Service Unit. if a public setLogger(Logger logger) setter method is defined, the component set its Logger instance with this method at the initialization of the Service Unit. if a public void init() method is defined, the component invoke it at the initialization of the Service Unit. a public boolean onExchange(Exchange exchange, Optional<Boolean> currentFlowTracingActivation, AbstractJBIListener jbiLIstener) MUST be provided. a public boolean onAsyncExchange(Exchange subExchange, AsyncContext asyncContext, AbstractJBIListener jbiListener) CAN be provided, optionally. a public void onExpiredAsyncExchange(Exchange subExchange, AsyncContext asyncContext, AbstractJBIListener jbiListener) CAN be provided, optionally. all methods can throw exceptions. FaultException is used to represent business faults (as declared in the WSDL contract): the XML content of the Fault is passed to the constructor of the exception, only one instance of the POJO class is instanciated by the component, so the POJO must be state-less and thread-safe, to prevent memory leak, using of the singleton pattern is to prohibit. When building such a Service Unit using Maven, the classes ComponentContext and DeliveryChannel are provided by the dependency petals-jbi, AbstractJBIListener and AsyncContext by petals-cdk-core, and Exchange by petals-cdk-api. These dependencies must be defined using the scope provided as they are provided by the container.

Table of contents 1 Exposing a Java class as a POJO service (Provides mode) 1.1 Usage 1.1.1 Process a service in the synchronous way 1.1.2 Process a service in the asynchronous way 1.1.3 Invoking a service provider from your POJO 1.1.4 Accessing placeholders 1.2 Service provider configuration 1.2.1 Configuration 1.2.2 Placeholder 1.2.2.1 CDK parameters defining service provider implementation 1.2.2.2 CDK parameters driving interceptors 1.2.2.3 Dedicated configuration 1.2.2.4 Service Unit content 1.2.2.5 Example 2 Configuring the component 2.1 CDK parameters 2.2 Interception configuration 2.3 Dedicated configuration 3 Monitoring the component 3.1 Using metrics 3.1.1 Common metrics 3.1.2 Dedicated metrics 3.2 Receiving alerts 3.2.1 Common alerts 3.2.2 Dedicated alerts 4 Business monitoring 4.1 MONIT traces 4.2 Flow tracing activation 4.3 Flow tracing propagation 5 Migration guide 5.1 Migrating service units developed for previous versions 5.1.1 From 2.7.x to 2.8.x 5.1.2 From 2.6.x to 2.7.x Contributors No contributors found for: authors on selected page(s)

Process a service in the synchronous way

A sample class following the above rules for processing service in the synchronous way:

package test;
import java.util.logging.Level;
[...]
import org.ow2.petals.component.framework.listener.AbstractJBIListener;

public class SamplePojoService {
  Logger logger;
  ComponentContext ctx;

  public void setComponentContext(ComponentContext ctx) {
    this.ctx = ctx;
  }
  public void setLogger(Logger logger) {
    this.logger = logger;
  }

  public boolean onExchange(Exchange exchange, Optional<Boolean> currentFlowTracingActivation, AbstractJBIListener jbiListener)
    throws MessagingException {
    [...]
    jbiListener.sendSync(anotherExchange);
    [...]
    return true;
  }

  public void init() {
    logger.log(Level.INFO, "Sample Pojo inits.");
  }
}

The method onExchange(Exchange exchange, Optional<Boolean> currentFlowTracingActivation, AbstractJBIListener jbiListener) is invoked when an exchange is received from the component that is addressed to the current POJO endpoint.
The POJO must process the service in that method.
The POJO can invoke any 'sub-service' during its processing by synchronous invocations using the jbiListener instance.
If the POJO service must reply with a message OUT or FAULT, according to the MEP, the method must build and set the message to the current exchange.
Then, the method must return true to delegate the effective send back of the response or acknowledgment (according to the MEP) to the CDK.
The exceptions should be handled properly during the processing of the method, and set accordingly as error or fault to the exchange.
However, mishandled exceptions will be handled by the CDK as generic exceptions.

Process a service in the asynchronous way

A sample class following the above rules for processing service in the asynchronous way:

package test;
import java.util.logging.Level;
[...]
import org.ow2.petals.component.framework.listener.AbstractJBIListener;

public class SamplePojoService {
  Logger logger;
  ComponentContext ctx;

  public void setComponentContext(ComponentContext ctx) {
    this.ctx = ctx;
  }
  public void setLogger(Logger logger) {
    this.logger = logger;
  }

  public boolean onExchange(Exchange exchange, Optional<Boolean> currentFlowTracingActivation, AbstractJBIListener jbiListener)
    throws MessagingException {
    [...]
    MyAsyncContext myAsyncContext = new MyAsyncContext(...);
    [...]
    jbiListener.sendASync(anotherExchange, myAsyncContext);
    [...]
    return false;
  }

  public boolean onAsyncExchange(Exchange subExchange, AsyncContext asyncContext, AbstractJBIListener jbiListener)
    throws MessagingException {
    [...]
    Exchange originalExchange = asyncContext.getOriginalExchange();
    [...]
    jbiListener.send(originalExchange);
    [...]
    return true;
  }

  public void onExpiredAsyncExchange(Exchange subExchange, AsyncContext asyncContext, AbstractJBIListener jbiListener)
    throws MessagingException {
    [...Handle here the subExchange timeout...]
  }

  public void init() {
    logger.log(Level.INFO, "Sample Pojo Async inits.");
  }
}

Processing a service in asynchronous way is the best approach when targeting performance, but it's more tedious to develop, and demands an average level in Petals development.
Basically, all is in the data that permit to correlate asynchronous sent exchange and their asynchronous response.
The original exchange is the received by the component and the process of the service start in the onExchange(Exchange exchange, AbstractJBIListener jbiListener) method.
The method create an asynchronous context, to set the data.
The method can create any 'sub-exchange' and send then asynchronously, with the asynchronous context as parameter.
Then the onExchange(Exchange exchange, Optional<Boolean> currentFlowTracingActivation, AbstractJBIListener jbiListener) returns false, as the response or the acknowledgment of the original exchange is not yet ready to be sent back.
Any asynchronous response from the 'sub-exchange' comes back in the onAsyncExchange(Exchange subExchange, AsyncContext asyncContext, AbstractJBIListener jbiListener) method. During the process of this method, the 'sub-exchange' must be handled according to the MEP, and the returns true of the method let the CDK send the 'sub-exchange' to the partner.
Once all 'sub-exchanges' are received, the 'original' exchange can be retrieve from the asynchronous context and the response or acknowledgement send back explicitly.
If a 'sub-service' do not response at time, the onExpiredAsyncExchange(...) method will be invoked automatically. You must handle the timeout of the 'sub-exchange' in this method.
Note that once a sendAsync(...) has expired, the POJO does not have the ownership of the exchange anymore (because it was sent but never came back) and can't access anything else than the exchangeId and the exchange status! The AsyncContext, which can be subclassed when needed, is there to store needed information in these situations.

Invoking a service provider from your POJO

A service provider can be invoked from your POJO when processing the incoming request in method onExchange(Exchange exchange, Optional<Boolean> currentFlowTracingActivation, AbstractJBIListener jbiListener).

First you should retrieve the service consumer associated to the service provider to invoke as following:

final Consumes consume = jbiListener.getComponent().getServiceUnitManager().getConsumesFromDestination(CONSUMED_ENDPOINT, CONSUMED_SERVICE, CONSUMED_INTERFACE, CONSUMED_OPERATION);

Next, you can create the exchange as following:

final Exchange subExchange = jbiListener.createExchange(consume, MEPPatternConstants.IN_OUT, currentFlowTracingActivation);

where jbiListener and currentFlowTracingActivation are parameters of method onExchange(...).

Accessing placeholders

If some configuration parameters are needed for your service provider, you will use properties defined in the properties file configured at component level (see parameter properties-file).

And so your properties can be accessed through the following API:

jbiListener.getComponent().getPlaceHolders().getProperty("your-property-name")

where jbiListener is the JBI listener transmitted through methods onExchange(...), onAsyncExchange(...) or onExpiredAsyncExchange(...) of your POJO class.

Service provider configuration

The POJO used as service provider implementation is defined and configured in a service unit descriptor.

The POJO JBI descriptor must contain a Provides section for each POJO to expose, and it is recommend to add a Consumes section for each service provider invoked from the POJO service.

Configuration

All needed information must be defined in the service-unit JBI descriptor. This JBI descriptor is configured through parameters divided in following groups:

• JBI parameters that defines the service provider identification,
• CDK parameters that are parameters driving the service provider implementation at CDK layer,
• CDK interceptor parameters that are parameters driving interceptors at CDK layer,
• Dedicated parameters that are parameters driving the service provider implementation at component layer.

Placeholder

A placeholder is a specific value that is resolved at runtime against a property available in the property file set at component level. It is mainly used in the service unit JBI descriptor to be able to configure your service providers and/or your service consumers.

<service-unit-parameter>${dgfip.quotient-familial.base-url}</service-unit-parameter>

Its syntax is: '${placeholder-name[:default-value]}',

• if no property with name 'placeholder-name' exists in the component property file, the default value 'default-value' is used. If no default value is defined, the literal value '${placeholder-name}' is used,
• if a placeholder name must contain the character ':' (colon), it must be escaped by the character '\', example: ${placeholder-name-with-\:-colon:default-value}',
• if a placeholder default value must contain the character ':' (colon), it must be escaped by the character '\', example: ${placeholder-name:default-value-with-\:-colon}'.
• the escape character can be escaped by itself.

Placeholders are not supported for each service unit parameter, check your documentation before to use them.
It is also possible to change a placeholder value at runtime reloading the component property file. It is not sufficient, the parameter associated to the placeholder must be changeable at runtime. So check component documentation to know that.

CDK parameters defining service provider implementation

The following parameters correspond to the CDK configuration of the service provider implementation.

The service provider is defined into the section 'provides' of the JBI descriptor, containing:

CDK parameters driving interceptors

The following parameters drive interceptors at CDK layer.

Interceptors can be defined to inject some post or pre-processing in the service provider processing or service consumer processing.

Using interceptor is very sensitive and must be manipulated only by power users. A 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"?>
<jbi:jbi xmlns:jbi="http://java.sun.com/xml/ns/jbi" xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5">
   <jbi:services>
      <jbi:provides|consumes>
         <!--...-->
         <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>
         <!--...-->
      </jbi:provides|consumes>
      <!--...-->
   </jbi:services>
</jbi:jbi>

Dedicated configuration

Service Unit content

The POJO class(es) and their depending libraries must be set as JAR(s) file(s) at the root directory of the POJO service unit package.

The service unit must contain the following elements, packaged in the archive:

• the META-INF/jbi.xml descriptor file as described above,
• it is also highly recommended to provide a WSDL description for service provider embedded in the service-unit,
• at least one JAR containing the POJO class to expose.

service-unit.zip
  + META-INF
    - jbi.xml (as defined above)
  - mypojoclasses.jar (as defined above)
  - service.wsdl (recommended)

Example

An example of a Service Unit descriptor to provide a POJO service:

<?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:pojo="http://petals.ow2.org/components/pojo/version-2.0"
   xmlns:cdk="http://petals.ow2.org/components/extensions/version-4.0"
   xmlns:generatedNs="http://petals.ow2.org/pojo"
   xmlns:notifyService="http://petals.ow2.org/samples/notifyService">

   <jbi:services binding-component="false">

      <jbi:provides endpoint-name="POJOServiceEndpoint"
          interface-name="generatedNs:POJO" service-name="generatedNs:POJOService">

         <!-- CDK specific elements -->
         <cdk:wsdl>MyFileTransferService.wsdl</cdk:wsdl>
         <cdk:validate-wsdl>true</cdk:validate-wsdl>

         <!-- Component specific elements -->
         <pojo:class-name>test.SamplePojoService</pojo:class-name>
      </jbi:provides>

      <!-- A service consumer declared to invoked another ervice provider from the POJO servcice -->
      <jbi:consumes
           interface-name="notifyService:emailNotifyTravelRequest"
           service-name="notifyService:emailNotifyTravelRequestService">
         <cdk:mep>InOnly</cdk:mep>
         <cdk:operation>notifyService:travelRequestApproved</cdk:operation>
         <cdk:timeout>${email.notifications.timeout}</cdk:timeout>
      </jbi:consumes>
   </jbi:services>
</jbi:jbi>

Configuring the component

The component can be configured through the parameters of its JBI descriptor file. These parameters are divided in following groups:

• JBI parameters that have not to be changed otherwise the component will not work,
• CDK parameters that are parameters driving the processing of the CDK layer,
• Dedicated parameters that are parameters specific to this component.

CDK parameters

The component configuration includes the configuration of the CDK. The following parameters correspond to the CDK configuration.

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

Interception configuration

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 manipulated only by power users. A 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"?>
<jbi:jbi xmlns:jbi="http://java.sun.com/xml/ns/jbi" xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5" ...>
   <jbi:component>
      <!--...-->
      <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>
      <!--...-->
   </jbi:component>
</jbi:jbi>

Dedicated configuration

No dedicated configuration parameter is available.

Monitoring the component

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:

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

Dedicated alerts

No dedicated alert is available.

Business monitoring

MONIT traces

Each service provider implemented is able to log MONIT traces with following information:

• on service provider invocation, when receiving an incoming request, with following attributes:
  • traceCode set to provideFlowStepBegin,
  • flowInstanceId set to the flow instance identifier retrieved from the incoming request,
  • flowStepId set to an UUID value,
  • flowStepInterfaceName set to the service provider interface name,
  • flowStepServiceName set to the service provider service name,
  • flowStepOperationName set to the operation of the invoked service provider,
  • flowStepEndpointName set to the service provider endpoint name,
  • flowPreviousStepId set to the step identifier of the previous step, retrieved from the incoming request.
• on service provider termination, when returning the outgoing response, with following attributes:
  • traceCode set to provideFlowStepEnd or provideFlowStepFailure,
  • flowInstanceId set to the flow instance identifier retrieved from the incoming request,
  • flowStepId set to the flow step identifier defined on incoming request receipt.

Flow tracing activation

The flow tracing (ie. MONIT traces generation) is defined according to the property 'org.ow2.petals.monitoring.business.activate-flow-tracing' of the incoming JBI request. If the property does not exist, the parameter activate-flow-tracing of the service provider definition will be inspected. If no parameter is defined at service provider level, the component configuration parameter 'activate-flow-tracing' is used. Finally, by default, the flow tracing is enabled.

Flow tracing propagation

The flow tracing propagation from a service provider implemented with this component to another service provider is driven by the parameter propagate-flow-tracing-activation of the service consumer definition. If no parameter is defined at service consumer level, the component configuration parameter 'propagate-flow-tracing-activation' is used. Finally, by default, the flow tracing propagation is enabled.

Migration guide

Migrating service units developed for previous versions

To be deployed on this version of the Petals SE POJO, the Petals SE POJO service units must be migrated. Please follow the following chapters to know which changes must be applied.

From 2.7.x to 2.8.x

Please apply the following changes in your Petals SE POJO service unit to migrate them from Petals SE POJO 2.7.x to Petals SE POJO 2.8.x:

• in your unit tests:
  • JUnit 5 is now required for your unit tests,
  • move Java EE package to Jakarta EE 9+ package:
    • javax.activation -> jakarta.activation
    • javax.mail -> jakarta.mail
    • javax.xml.bind -> jakarta.xml.bind
    • ...
  • to generate your beans from an XSD or WSDL definition, use the Maven plugin 'org.patrodyne.jvnet:hisrc-higherjaxb-maven-plugin' instead of 'org.jvnet.jaxb2.maven2:maven-jaxb2-plugin'

From 2.6.x to 2.7.x

Please apply the following changes in your Petals SE POJO service unit to migrate them from Petals SE POJO 2.7.x to Petals SE POJO 2.8.x:

• the following expected POJO API has been changed:
  • onExchange(Exchange exchange, AbstractJBIListener jbiLIstener) --> onExchange(Exchange exchange, Optional<Boolean> currentFlowTracingActivation, AbstractJBIListener jbiLIstener)
• Placeholders are no more defined through Properties but through Placeholders.