La spécification JBI est basée sur l’état de l’art des Web services et donc utilise WSDL pour la description des services ‘hostés’ ou liés à l’implémentation JBI. Petals ESB implémente (et étend – mais ça sera peut être l’objet d’un autre article sur le pourquoi du comment…) la spécification JBI depuis sa première version. Petals ESB est même certifié compatible JBI par SUN (RIP) après le passage du TCK JBI (Outil de test de compatibilité fournit par SUN). Bref, là n’est pas la question… Les descripteurs JBI servent à beaucoup de choses dans une implémentation JBI mais nous allons particulièrement regarder comment nous nous en servons dans l’exposition de services.

Un service exposé dans le bus fournit donc sa description via un WSDL associé. Ce service est activé dans le bus après le déploiement de ce que l’on appelle communément une ‘SA’ (Service Assembly) qui contient des ‘SU’ (Service Unit). Pour exposer un service dans le bus afin qu’il soit accessible à tout les consommateurs, la SU doit être en mode ‘provide’ ie fournisseur. Elle doit aussi définir le Endpoint, le Service et l’Interface qu’elle veut exposer. Prenons l’exemple du bon vieux service HelloWorld définit par le WSDL suivant :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:definitions name="HelloServiceImplService" targetNamespace="http://sample.petals.ow.org/" xmlns:ns2="http://schemas.xmlsoap.org/wsdl/" xmlns:ns3="http://schemas.xmlsoap.org/wsdl/soap/"
	xmlns:ns9="http://www.w3.org/ns/wsdl/http" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:ns5="http://schemas.xmlsoap.org/wsdl/soap12/" xmlns:ns6="http://schemas.xmlsoap.org/wsdl/http/"
	xmlns:ns10="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:ns7="http://www.w3.org/ns/wsdl" xmlns:ns8="http://www.w3.org/ns/wsdl/soap">
	<ns2:types>
		<xs:schema elementFormDefault="unqualified" attributeFormDefault="unqualified" targetNamespace="http://sample.petals.ow.org/">
			<xs:element name="sayHello" type="tns:sayHello" xmlns:tns="http://sample.petals.ow.org/" />
			<xs:element name="sayHelloResponse" type="tns:sayHelloResponse" xmlns:tns="http://sample.petals.ow.org/" />
			<xs:complexType name="sayHello">
				<xs:sequence>
					<xs:element name="arg0" minOccurs="0" type="xs:string" />
				</xs:sequence>
			</xs:complexType>
			<xs:complexType name="sayHelloResponse">
				<xs:sequence>
					<xs:element name="return" minOccurs="0" type="xs:string" />
				</xs:sequence>
			</xs:complexType>
		</xs:schema>
	</ns2:types>
	<ns2:message name="sayHelloResponse">
		<ns2:part element="tns:sayHelloResponse" name="parameters" xmlns:tns="http://sample.petals.ow.org/" />
	</ns2:message>
	<ns2:message name="sayHello">
		<ns2:part element="tns:sayHello" name="parameters" xmlns:tns="http://sample.petals.ow.org/" />
	</ns2:message>
	<ns2:portType name="HelloService">
		<ns2:operation name="sayHello">
			<ns2:input message="tns:sayHello" name="sayHello" xmlns:tns="http://sample.petals.ow.org/" />
			<ns2:output message="tns:sayHelloResponse" name="sayHelloResponse" xmlns:tns="http://sample.petals.ow.org/" />
		</ns2:operation>
	</ns2:portType>
	<ns2:binding type="tns:HelloService" name="HelloServiceImplServiceSoapBinding" xmlns:tns="http://sample.petals.ow.org/">
		<ns3:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
		<ns2:operation name="sayHello">
			<ns3:operation style="document" soapAction="" />
			<ns2:input name="sayHello">
				<ns3:body use="literal" />
			</ns2:input>
			<ns2:output name="sayHelloResponse">
				<ns3:body use="literal" />
			</ns2:output>
		</ns2:operation>
	</ns2:binding>
	<ns2:service name="HelloServiceImplService">
		<ns2:port binding="tns:HelloServiceImplServiceSoapBinding" name="HelloServiceImplPort" xmlns:tns="http://sample.petals.ow.org/">
			<ns3:address location="http://localhost:9999/sample/HelloService" />
		</ns2:port>
	</ns2:service>
</ns2:definitions>
<pre>

Son descripteur JBI associé sera donc (lié a Petals via le composant Web service dans cet exemple) :

<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0"
        xmlns:generatedNs="http://sample.petals.ow.org/"
        xmlns:jbi="http://java.sun.com/xml/ns/jbi"
	xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
	xmlns:soap="http://petals.ow2.org/components/soap/version-4"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

	<jbi:services binding-component="true">
		<jbi:provides interface-name="generatedNs:HelloService"
			service-name="generatedNs:HelloServiceImplService"
			endpoint-name="HelloServiceImplPort">

			<!-- CDK specific elements -->
			<petalsCDK:timeout>60000</petalsCDK:timeout>
			<petalsCDK:wsdl>Service.wsdl</petalsCDK:wsdl>

			<!-- Component specific elements -->
			<soap:address>http://localhost:9999/sample/HelloService</soap:address>
			<soap:soap-version>11</soap:soap-version>
			<soap:add-root>false</soap:add-root>
			<soap:chunked-mode>false</soap:chunked-mode>
			<soap:cleanup-transport>true</soap:cleanup-transport>
			<soap:mode>SOAP</soap:mode>
		</jbi:provides>
	</jbi:services>
</jbi:jbi>

Où on respecte bien que :

1. JBI ‘endpoint-name‘ = Valeur de l’attribut ‘name’ du Port dans le WSDL
2. JBI ‘service-name‘ = Valeur de l’attribut ‘name’ du Service dans le WSDL (avec JBI Service NameSpace = targetNamespace du WSDL)
3. JBI ‘interface-name‘ = Valeur de l’attribut ‘name’ du PortType dans le WSDL (avec JBI Interface NameSpace = targetNamespace du WSDL)

Petals ESB v3.x ne vous insultera plus lors du déploiement de vos services. Une solution simple pour ne pas se faire insulter, est d’utiliser le Studio Petals qui facilite grandement la vie des développeurs!

If you develop Eclipse plug-ins, you are always brought to run an Eclipse application.
It means that to test your plug-ins, you have to launch a second Eclipse from the one where you develop.

One common problem in this case is the PermGen Space issue.
This is in particular true if you test GMF plug-ins or if there is a lot of class generation.

To solve this, you can modify the permgen space allocated when you run the other Eclipse.
Go into Run > Debug Configurations. Select your Eclipse configration and go into the Arguments tab.
The field to upate is the VM Arguments.

As an example, when running Talend Open Studio in debug, I have to use the following settings.

-Xms256m -Xmx1024m -XX:MaxPermSize=512m

Nous allons donc développer un module qui change dynamiquement l’URL de l’endpoint à appeler (on utilisera bien sûr Maven2 pour nous aider à créer et packager le projet…).

1. Créer le projet

Utilisons Maven2 pour créer un projet :

mvn archetype:generate

et je réponds bêtement a Maven quand il me pose des questions sur le groupId, l’artifactId, etc… Une fois créé, je génère le projet Eclipse associé et je l’importe (Eclipse fait aussi parti de mes grand amis) :

mvn eclipse:eclipse

Ill faut modifier le POM pour dire a Maven que l’on est en train de créer un projet qui n’est pas une librarie Java mais un module Axis2. Ceci est possible en spécifiant le type de projet dans le POM et en déclarant que l’on veut utiliser le plugin MAR fournit par Axis2 :

<project ...>

...

<groupId>foo.bar</groupId>
<artifactId>reroute</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>mar</packaging>

...

<dependencies>
<dependency>
<groupId>org.apache.axis2</groupId>
<artifactId>axis2-kernel</artifactId>
<version>1.5.1</version>
</dependency>
</dependencies>

...

<build>
<plugins>
<plugin>
<groupId>org.apache.axis2</groupId>
<artifactId>axis2-mar-maven-plugin</artifactId>
<version>1.5.1</version>
<extensions>true</extensions>
<configuration>
<moduleXmlFile>src/main/META-INF/module.xml</moduleXmlFile>
<includeDependencies>false</includeDependencies>
</configuration>
</plugin>
</plugins>
</build>
...
</project>

2. Business code

Créons maintenant notre handler (le module est en fait un handler Axis2 packagé dans une archive avec un descripteur de module). Pour faire simple, je vais étendre la classe AbstractHandler pour créer mon Handler de reroutage et remplacer le ‘target EPR’ par le nouveau (bien sûr on peut faire quelque chose de beaucoup plus évolué, on va dire qu’ici tout part vers un seul service) :

package net.chamerling.blog.axis2module.reroute;

import org.apache.axis2.AxisFault;
import org.apache.axis2.addressing.EndpointReference;
import org.apache.axis2.context.MessageContext;
import org.apache.axis2.handlers.AbstractHandler;
import org.apache.axis2.util.LoggingControl;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

/**
 * @author chamerling
 *
 */
public class ReRouteHandler extends AbstractHandler {
	private static final Log log = LogFactory.getLog(AbstractHandler.class);

	private static final String FINAL_EPR_PREFIX = "http://localhost:8082/petals/proxy/";

	/**
	 * {@inheritDoc}
	 */
	public InvocationResponse invoke(MessageContext messageContext)
			throws AxisFault {
		EndpointReference toEPR = messageContext.getOptions().getTo();
		String finalEPR = FINAL_EPR_PREFIX + toEPR.getAddress();

		if (LoggingControl.debugLoggingAllowed && log.isDebugEnabled()) {
			log.debug("Reroute Handler for message : "
					+ messageContext.getMessageID());
			log.debug("Initial ToEPR is " + toEPR.getAddress()
					+ " and is changed to " + finalEPR);
		}

		toEPR.setAddress(finalEPR);
		return InvocationResponse.CONTINUE;
	}
}
<pre>

Avec Axis2 c’est ‘facile’, tout est dans le message context! Je viens de remplacer le service à appeler par le mien en modifiant le champ ‘address’ du ‘EndpointReference’.

3. Packager le module

Pour créer un module avec le Handler que l’on vient de définir, il faut passer par l’écriture du fichier de description du module, le ‘module.xml’. Ici c’est simple :

<module name="reroute">
	<OutFlow>
		<handler name="ReRouteHandler" class="net.chamerling.blog.axis2module.reroute.ReRouteHandler">
			<order phase="reroutePhase" />
		</handler>
	</OutFlow>
</module>
<pre>

Mon module s’appellera donc ‘reroute’ et sera appelé que lors de la phase d’émission de message ‘OutFlow’. Plus d’informations sur ce qui est possible avec ce fichier sur le site d’Axis2.

4. Configurer Axis2

Il y a plusieurs façcons de dire à Axis2 d’utiliser le module que l’on vient de développer. En se basant sur la contrainte de départ, je n’ai pas le droit de modifier mes services donc je ne peux pas modifier le descripteur de service ’service.xml’. Heureusement, j’ai accès au serveur et je peux modifier le fichier de configuration d’Axis2 ‘axis2.xml’ :

...
<!-- Engage the reroute module -->
<module ref="reroute" />
...
<phaseOrder type="OutFlow">
	<!--      user can add his own phases to this area  -->
	<phase name="soapmonitorPhase" />
	<phase name="OperationOutPhase" />
	<!--system predefined phase-->
	<!--these phase will run irrespective of the service-->
	<phase name="PolicyDetermination" />
	<phase name="reroutePhase" />
	<phase name="MessageOut" />
	<phase name="Security" />
</phaseOrder>
<pre>

Je viens d’engager mon module pour tous les services et je l’ai aussi ajouté dans la collection de phases qui est appelé lors de l’émission d’un message. A chaque fois qu’un message est envoyé vers un service, on passe donc dans le module que l’on vient de développer. Je viens donc de modifier les services invoqués sans modifier le code client! Je reviendrais bientôt sur l’utilisation de ce genre de choses dans un vrai cas d’usage avec du REST, du SOAP, des PROXYs, de l’ESB distribué sur le Web (bien sûr avec Petals ESB), etc…

Resources

Le code de ce ‘tutoriel’ est bien sûr disponible sur mon Google Code sous http://code.google.com/p/chamerling/source/browse/#svn/trunk/blog/reroute-axis2.

Bon, comme je le dis souvent « Google est ton ami », mais aujourd’hui Google ne l’est pas (comme le temps dehors, de la neige en Mars a Montpellier, mais ou va-t-on?). Bref, faisons le bêtement :

mvn deploy -DaltDeploymentRepository=chamerling.maven.snapshot::default::ftp://ftpperso.free.fr/maven/repository/snapshot

Je viens de dire a Maven2 de déployer mon artefact sur un repository dont l’ID est chamerling.maven.snapshot (pour rappel, cela veut dire que Maven2 va aller chercher dans mon settings.xml un serveur dont l’ID est chamerling.maven.snapshot pour récupérer le login et le mot de passe) en FTP sur l’URL ftp://ftpperso.free.fr/maven/repository/snapshot. Et c’est la que mon autre ami Maven2 (bon OK je n’ai que des amis virtuels…) me dit :

[INFO] Error retrieving previous build number for artifact 'foo:bar:pom': repository metadata for: 'snapshot foo:bar:1-SNAPSHOT' could not be retrieved from repository: chamerling.maven.snapshot due to an error: Unsupported Protocol: 'ftp': Cannot find wagon which supports the requested protocol: ftp
Component descriptor cannot be found in the component repository: org.apache.maven.wagon.Wagonftp.

Ok bon c’est normal… Wagon est la librairie de transport abstraite utilisée par Maven2 et par défaut FTP n’est pas supporté. D’ailleurs sur le site du plugin deploy de Maven2 on remarque bien qu’il faut normalement définir dans le POM que l’on veut utiliser l’extension FTP de Wagon :

<build>
<extensions>
<!-- Enabling the use of FTP -->
<extension>
<groupId>org.apache.maven.wagon</groupId>
<artifactId>wagon-ftp</artifactId>
<version>1.0-beta-6</version>
</extension>
</extensions>
</build>

Oui mais moi je ne veux pas modifier mon POM! L’astuce c’est de rajouter l’extension FTP-Wagon dans le classpath de Maven2 ie ajouter la librairie Wagon FTP dans M2_HOME/lib et la ‘Oh Miracle’, ca ne marche pas…

[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------

[INFO] Error retrieving previous build number for artifact 'foo:bar:pom': repository metadata for: 'snapshot foo:bar:1-SNAPSHOT' could not be retrieved from repository: chamerling.maven.snapshot due to an error: Unsupported Protocol: 'ftp': Cannot find wagon which supports the requested protocol: ftp
org.apache.commons.net.ProtocolCommandListener
[INFO] ------------------------------------------------------------------------

Normal, Wagon FTP utilise commons-net pour tout ce qui est communication, j’ajoute donc le JAR de commons-net  2.0 dans mon M2_HOME/lib et là ça marche beaucoup mieux :

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------

Son principal avantage : pouvoir assez simplement scripter en java des traitements internes à Petals, éventuellement complexes. Par exemple :

• Consommer des Endpoint, les orchestrer librement en fonction de conditions.
• Faire des traitements spécifiques (comme lire un fichier à un format exotique, le convertir en XML, et l’envoyer à un autre Endpoint)
• Etc…

Le problème, c’est que le POJO est assez peu documenté, à ce jour : la doc est quand même utile, donc lisez-là (http://download.forge.objectweb.org/petals/petals-se-pojo-2.0.2-en.pdf).

Etape 1 : Développer un POJO compatible avec Petals et le SE-POJO

Sous PetalsStudio :

- Créer un projet java “classique”, qui contiendra le code de votre POJO. Ce projet aura besoin de librairies de Petals, notamment celles du CDK (component development kit).

Le meilleur moyen de se les procurer, c’est de dézipper un composant : par exemple, téléchargez le SE-POJO (de toutes façons, vous en aurez besoin), et dézippez-le.

Les librairies dont vous aurez besoin sont les suivantes ([version] désigne les numéros de version, qui peuvent varier… selon la version ! Prenez celles qui sont dans votre composant POJO) :

• petals-jbi-[version].jar
• petals-cdk-jbidescriptor-[version].jar
• petals-cdk-api-[version].jar
• petals-cdk-core-[version].jar

Copiez ces librairies dans un répertoire de votre projet java (par exemple, un répertoire “lib/”), et faites pointer le “Build path” d’Eclipse dessus.

- Créez un package et une classe dans les sources : ce sera l’implémentation de votre POJO.

Voici un exemple (cet exemple consomme un autre EndPoint : dans mon cas, un “FileTransfer” pour enregistrer le message, soit une SU déployée sur le BC-FILETRANSFER. Mais vous pouvez commenter tout le code qui consomme cet Endpoint, et vous contenter d’un POJO genre “Hello world” !) :

package org.ow2.petals.test;

import java.io.StringReader;

import javax.jbi.component.ComponentContext;
import javax.xml.namespace.QName;
import javax.xml.transform.stream.StreamSource;

import org.ow2.petals.component.framework.api.Message.MEPConstants;
import org.ow2.petals.component.framework.api.message.Exchange;
import org.ow2.petals.component.framework.jbidescriptor.generated.Consumes;
import org.ow2.petals.component.framework.listener.AbstractJBIListener;

public class TestPojo {
  AbstractJBIListener jbiListener;
  ComponentContext ctx;

  public void setJBIListener(AbstractJBIListener jbiListener) {
    this.jbiListener = jbiListener;
  }
  public void setComponentContext(ComponentContext ctx) {
    this.ctx = ctx;
  }

  public boolean onExchange(Exchange exchange)
  throws Exception {

    // Consume a "provides" endpoint (referenced by Interface/Service/Endpoint name,
    // as specified in the "provides" endpoint's jbi.xml)
    Consumes ep = new Consumes();
    ep.setInterfaceName(new QName("http://petals.test.com", "WriteContentInterface"));
    ep.setServiceName(new QName("http://petals.test.com", "WriteContent"));
    ep.setEndpointName("TestFileEndpoint");

    System.out.println("POJO: before consume");
    Exchange out =
       jbiListener.createConsumeExchange(ep,MEPConstants.IN_ONLY_PATTERN);
    out.setInMessageContent(
       new StreamSource(new StringReader(
         "<pojo>Hello from Pojo !</pojo>")));

    jbiListener.sendSync(out);
    System.out.println("POJO: consume done");

    // Answer if needed (In[Optional]Out)
    if(exchange.isInOutPattern() || exchange.isInOptionalOutPattern()) {
      System.out.println("POJO: sending response");
      exchange.setOutMessageContent(
         new StreamSource(new StringReader("<pojo>Ok</pojo>")));
    }

    return true;
  }

  public void init() {
    System.out.println("SamplePojo inits.");
  }
}

- Une fois votre POJO prêt, vous devrez le packager sous forme de fichier .jar (File/Export/General/Java/Jar file).
Le fichier .jar résultant pourra ensuite être intégré à votre SU POJO.

Etape 2 : Créer la SU pour y intégrer votre POJO

Sous PetalsStudio : File / New / Project / Petals / Use a Petals Technical Service / Use POJO.

Dans la fenêtre “WSDL File” (etc…)

• Spécifiez des “namespace” identiques pour l’interface et le service (çà doit ressembler à des URL… exemple : http://pojo.test.org).
• Nommez vos Interface / Service / Endpoint à votre convenance.
• Inutile de spécifier un WSDL.

Dans la fenêtre “Jar Files” (etc…)

• Donnez le chemin d’accès vers le jar créé lors de l’étape précédente (bouton “browse”, sélectionnez le fichier jar)
• Faites ensuite “Browse” pour la boîte “Service Class”, vous pourrez y choisir la classe du POJO présent dans votre jar.

Terminez le processus (allez jusqu’à “Finish”, et cliquez dessus).

PetalsStudio va alors générer un projet “su-POJO-<nom-du-projet>-provide, avec un dossier “resources/” contenant le fichier jar du POJO, et un dossier META-INF contenant le descripteur de déploiement Petals (jbi.xml).

Attention : la version 1.0 Beta2 de PetalsStudio comporte un bug… à tout hasard, éditez META-INF/jbi.xml. Si vous y trouvez la chaîne suivante :

“http://petals.ow2.org/components/extensions/version-4.0″

remplacez “4.0″ par “5″, comme ceci :

“http://petals.ow2.org/components/extensions/version-5″

(puis sauvegardez).

Cliquez le projet avec le bouton droit, puis “Petals / Package for Petals”.

Vous aurez alors un fichier “sa-POJO-<nom-du-projet>-provide.zip”, prêt à être déployé dans Petals (comme SU associée au SE-POJO).

Etape 3 : Déploiement sur Petals

• Démarrez Petals
• Déployez le SE-POJO
• Déployez votre SU générée à l’étape 2 (sa-POJO-<nom-du-projet>-provide.zip).

Et voilà le travail !

Le ‘problème’ actuel de Petals ESB est qu’il est pleinement basé sur la spécification JBI, cela veut dire que actuellement, si on veut exposer un service JBI en tant que Web service, il faut créer un fichier de configuration (le fameux JBI.xml), le packager dans une unité de service (Service Unit – SU), et packager cette SU dans un assemblage de services (Service Assembly – SA). Bien sur des outils comme le Petals Studio sont la pour aider les développeurs à intégrer leurs services, moi je me place plus dans la peau du ‘Core Developper’ et je pour le moment je n’ai pas eu l’utilité d’outils graphiques pour configurer Petals.

Dans une de mes taches actuelles, je suis en train d’étendre Petals pour le faire communiquer sur Internet et je développe ce que j’appelle l’API de Monitoring & Management (M&M API) qui est exposée (pour le moment seulement) en Web service. La partie Management de l’API doit permettre à un administrateur de la plateforme, de ‘binder’ des services (Web, REST, …) sans se soucier de la partie JBI.
L’API fournit donc une opération du style bind(URI wsdl). Coté serveur, j’utilise :

1. Une librairie maison de génération de SA
2. Je déploie localement cette SA pour ‘binder’ un Web service au bus.
3. J’expose ce service de management avec la feature expliquée dans ce post

Un exemple d’utilisation de la librairie est donné dans le listing suivant (binder au bus, le Service Web Version de Axis2) :

package org.ow2.petals.tools.generator.jbi;

import java.io.File;
import java.net.URI;
import java.net.URISyntaxException;
import java.util.HashMap;
import java.util.Map;
import org.ow2.petals.tools.generator.jbi.api.JBIGenerationException;
import org.ow2.petals.tools.generator.jbi.ws2jbi.WS2Jbi;

public class BindAxis2Version {

public static void main(String[] args) throws JBIGenerationException, URISyntaxException {

String wsdl = "http://localhost:8080/axis2/services/Version?wsdl";
Map<String, String> map = new HashMap<String, String>();

// let's say that we want to generate SA for SOAP component 4.0
map.put(org.ow2.petals.tools.generator.commons.Constants.COMPONENT_VERSION, "4.0");

URI wsdlURI = new URI(wsdl);

File f = new WS2Jbi(wsdlURI, map).generate();

System.out.println("Service Assembly is available at " + f.getAbsolutePath());

}
}

Pour utiliser WS2Jbi, utilisez dans votre projet Maven, la dépendance :

<dependency>

<groupId>org.ow2.petals.sandbox</groupId>

<artifactId>petals-ws2jbi</artifactId>

<version>1.0-SNAPSHOT</version>

</dependency>

Celle ci est normalement disponible est mise a jour régulièrement sur le repository Maven d’OW2 http://maven.ow2.org/maven2-snapshot/. Les sources sont disponibles dans ma Sandbox Petals.

Heureusement, les gens de chez Maven2 ne sont pas si bêtes, le plugin Help permet de lister le POM effectif du projet courant en lancant la commande

# mvn help:effective-pom

Simple et efficace. Les gens qui se demandent, par exemple, pourquoi ils ne sont pas bien authentifiés lors d’une release peuvent alors verifier dans le POM généré, que leurs login/password ne sont pas définis pour le bon ID de serveur…

This component, based on Apache Axis2, uses a small part of WS-Addressing to provide the proxy feature. ‘Small part’ means that for now, by using Axis2, I need to bypass the mustUnderstand attribute of the WS-Addressing elements. Why? Because I need to use the WSA:To element to specify the Web service I want to finally invoke and I need to set the mustUnderstand attribute to false to bypass one implementation detail on Axis2 which is not ‘friendly’ with my own implementation. Why (again)?… By setting some mustUnderstand attribute to true in the SOAP message header, it means that the SOAP engine (ie Axis2) must understand the header during message processing. A mustUnderstand attribute set to true in the WS-Addressing header means that the SOAP engine must handle the WS-Addressing information and here I do not want to. If I set this attribute to true, I need to add the Axis2 addressing module, which will handle the WS-Addressing header, and will put all the addressing information in the Axis2 message context. I can do that and get the information from this context for for some reason it does not work like I expect… Maybe an Axis2 update will fix this…Need some time to investigate, and for now time is not my friend… So, here is how it work :

1. The SOAP client sends the SOAP message to the Petals SOAP Proxy (by default this service is exposed at http://localhost:8085/petals/services/SOAPProxyWebService). The SOAP message header contains the WS-Addressing information which will be used to reach the final Web service. A SOAP message sample is for example :

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsap="http://wsapi.petals.dsb.soa4all.eu/">
<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
<wsa:Action>http://wsapi.petals.dsb.soa4all.eu/HelloService/sayHello</wsa:Action>
<wsa:To>http://localhost:7600/petals/ws/HelloService</wsa:To>
</soapenv:Header>
<soapenv:Body>
<wsap:sayHello>
<!--Optional:-->
<arg0>Say hello!</arg0>
</wsap:sayHello>
</soapenv:Body>
</soapenv:Envelope>

where http://localhost:7600/petals/ws/HelloService is the final Web service I want to invoke.

2. The SOAP message is handled by the SOAP proxy component, transformed as JBI message and sent to the right JBI endpoint.

3. The JBI endpoint gets the WS-Addressing information from the JBI message, the SOAP message from the JBI message payload and send all of this stuff to the final Web service. Invokcation response is sent back to the initial consumer through the ESB.

A simple schema of what happens with three ESB nodes is given in the figure below :

So, the main question is why using such a proxy and why not invoking the service directly? There are many answers to these questions and since I already said that the time is a missing resource, it will be probably part of a future article…

The first version of the component is available on the OW2 SVN repository under my sandbox (have a look to http://websvn.ow2.org/listing.php?repname=petals&path=%2Fsandbox%2Fchamerling%2Fproxy%2Fpetals-bc-soap%2F#path_sandbox_chamerling_proxy_petals-bc-soap_)

Note : Using SOAPUI for WS-Addressing testing works fine (even if I had some exchanges with SOAPUI guy (http://twitter.com/olensmar) on Twitter…)… Sorry to have doubts on SOAPUI!

Solution : positionner la variable d’environnement GDK_NATIVE_WINDOWS à “true”.

Exemple :
$ GDK_NATIVE_WINDOWS=true PetalsStudio

Ou:
$ export GDK_NATIVE_WINDOWS=true
$ PetalsStudio

In a previous article about WSDM monitoring (http://chamerling.wordpress.com/2009/11/04/petals-esb-live-monitoring-with-wsdm-and-gwt/), I was speaking about adding routing modules to the ESB router to intercept messages and to notify the monitoring system that messages are transmitted and received between service consumers and providers.

In the current article, I am going to show you how you can add modules to the routing layer of the service bus. In short, the routing layer is the component which select the right endpoint(s) to send the current message to. The routing layer has been decomposed into routing modules which are all called when a message is sent or received.

There are two types of routing modules the SenderModule (org.ow2.petals.jbi.messaging.routing.module.SenderModule) and the ReceiverModule (org.ow2.petals.jbi.messaging.routing.module.ReceiverModule) which both have right names . All the sender modules will be called on message emission, the receiver ones will be called at message reception… Here are the Java APIs :

org.ow2.petals.jbi.messaging.routing.module.SenderModule

package org.ow2.petals.jbi.messaging.routing.module;

import java.util.Map;
import org.ow2.petals.jbi.component.context.ComponentContext;
import org.ow2.petals.jbi.messaging.endpoint.ServiceEndpoint;
import org.ow2.petals.jbi.messaging.exchange.MessageExchange;
import org.ow2.petals.jbi.messaging.routing.RoutingException;
import org.ow2.petals.transport.util.TransportSendContext;

public interface SenderModule {

void electEndpoints(final Map<ServiceEndpoint, TransportSendContext> electedEndpoints,

final ComponentContext sourceComponentContext, final MessageExchange exchange)

throws RoutingException;

}

org.ow2.petals.jbi.messaging.routing.module.ReceieverModule

package org.ow2.petals.jbi.messaging.routing.module;

import org.ow2.petals.jbi.component.context.ComponentContext;
import org.ow2.petals.jbi.messaging.exchange.MessageExchange;
import org.ow2.petals.jbi.messaging.routing.RoutingException;

public interface ReceiverModule {

boolean receiveExchange(final MessageExchange exchange,

final ComponentContext sourceComponentContext) throws RoutingException;

}

Implementing and adding modules to the Petals ESB router steps

1. Step one : Create your routing module by implementing the Sender and/or Receiver module interface(s) like, for example, just logging exchange information and date :

package com.googlecode.chamerling.blog.petals.router;

import java.util.Date;

import java.util.Map;

import org.objectweb.fractal.fraclet.annotation.annotations.FractalComponent;

import org.objectweb.fractal.fraclet.annotation.annotations.Interface;

import org.objectweb.fractal.fraclet.annotation.annotations.LifeCycle;

import org.objectweb.fractal.fraclet.annotation.annotations.Monolog;

import org.objectweb.fractal.fraclet.annotation.annotations.Provides;

import org.objectweb.fractal.fraclet.annotation.annotations.type.LifeCycleType;

import org.objectweb.util.monolog.api.Logger;

import org.ow2.petals.jbi.component.context.ComponentContext;

import org.ow2.petals.jbi.messaging.endpoint.ServiceEndpoint;

import org.ow2.petals.jbi.messaging.exchange.MessageExchange;

import org.ow2.petals.jbi.messaging.routing.RoutingException;

import org.ow2.petals.jbi.messaging.routing.module.ReceiverModule;

import org.ow2.petals.jbi.messaging.routing.module.SenderModule;

import org.ow2.petals.transport.util.TransportSendContext;

import org.ow2.petals.util.LoggingUtil;

@FractalComponent

@Provides(interfaces = {

@Interface(name = "logSender", signature = SenderModule.class),

@Interface(name = "logReceiver", signature = ReceiverModule.class) })

public class LogModule implements SenderModule, ReceiverModule {

@Monolog(name = "logger")

private Logger logger;

private LoggingUtil log;

/**

* {@inheritDoc}

*/

public void electEndpoints(

Map<ServiceEndpoint, TransportSendContext> electedEndpoints,

ComponentContext sourceComponentContext, MessageExchange exchange)

throws RoutingException {

this.log.info(LogModule.class.getCanonicalName()

+ " router module is sending a message exchange with ID = "

+ exchange.getExchangeId() + " at " + new Date());

for (ServiceEndpoint endpoint : electedEndpoints.keySet()) {

this.log.info("Selected endpoint : " + endpoint.getEndpointName());

}

// Do what you want...

}

/**

* {@inheritDoc}

*/

public boolean receiveExchange(MessageExchange exchange,

ComponentContext sourceComponentContext) throws RoutingException {

this.log.info(LogModule.class.getCanonicalName()

+ " router module is receiving a message exchange with ID = "

+ exchange.getExchangeId() + " at " + new Date());

// Do what you want...

return false;

}

@LifeCycle(on = LifeCycleType.START)

protected void start() {

this.log = new LoggingUtil(this.logger);

this.log.debug("Starting...");

}

@LifeCycle(on = LifeCycleType.STOP)

protected void stop() {

this.log.debug("Stopping...");

}

}

Note that the Fractal annotations are mandatory!

2. Add the modules to the Fractal descriptor files. The modules MUST be added to the JBI-Messaging.fractal configuration file (located in the src/main/resources of your favorite Petals ESB distribution) :

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE definition PUBLIC "-//ow2.objectweb//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/fractal/adl/xml/standard.dtd">

<definition extends="JBI-MessagingType" name="JBI-Messaging">

<component definition="org.ow2.petals.jbi.messaging.registry.DistributedEndpointRegistryImpl" name="EndpointRegistryImpl"/>

<component definition="org.ow2.petals.jbi.messaging.routing.RouterServiceImpl" name="RouterServiceImpl"/>

<component definition="org.ow2.petals.jbi.messaging.routing.module.TransportResolverModule" name="TransportResolverModule"/>

<component definition="org.ow2.petals.jbi.messaging.routing.module.EndpointResolverModule" name="EndpointResolverModule"/>

<component definition="org.ow2.petals.jbi.messaging.control.JMXExchangeCheckerClientImpl" name="ExchangeCheckerClientImpl"/>

<!-- My logging module -->
<component definition="com.googlecode.chamerling.blog.petals.router.LogModule" name="LogModuleImpl"/>

<!-- Expose -->

<binding client="this.router" server="MonitoringModuleImpl.service"/>

<binding client="this.transportlistener" server="RouterServiceImpl.transportlistener"/>

<binding client="this.endpoint" server="EndpointRegistryImpl.service"/>

<binding client="this.exchangechecker" server="ExchangeCheckerClientImpl.service"/>

<binding client="this.storage" server="MonitoringStorageServiceImpl.service"/>

<binding client="MonitoringModuleImpl.router" server="RouterServiceImpl.service"/>

<binding client="MonitoringModuleImpl.storageService" server="MonitoringStorageServiceImpl.service"/>

<binding client="EndpointRegistryImpl.configuration" server="this.configuration"/>

<binding client="EndpointRegistryImpl.topology" server="this.topology"/>

<!-- Add logging module to router -->

<binding client="RouterServiceImpl.sendermodule-3" server="LogModuleImpl.logSender"/>

<binding client="RouterServiceImpl.receivermodule-1" server="LogModuleImpl.logReceiver"/>

<!-- router -->

<binding client="RouterServiceImpl.transporter-local" server="this.transporter-local"/>

<binding client="RouterServiceImpl.transporter-tcp" server="this.transporter-tcp"/>

<!--the order of collection of bindings is alphabetically inversed -->

<binding client="RouterServiceImpl.sendermodule-2" server="EndpointResolverModule.service"/>

<binding client="RouterServiceImpl.sendermodule-1" server="TransportResolverModule.service"/>

<binding client="EndpointResolverModule.configuration" server="this.configuration"/>

<binding client="EndpointResolverModule.topology" server="this.topology"/>

<binding client="EndpointResolverModule.endpoint" server="EndpointRegistryImpl.service"/>

<binding client="EndpointResolverModule.checker" server="ExchangeCheckerClientImpl.service"/>

<binding client="TransportResolverModule.configuration" server="this.configuration"/>

<binding client="ExchangeCheckerClientImpl.jmx" server="this.jmx"/>
</definition>

Important things here are :

1. Instantiate the component with line

<component definition="com.googlecode.chamerling.blog.petals.router.LogModule" name="LogModuleImpl"/>

2. Adding the module to sender and receiver modules list :

<binding client="RouterServiceImpl.sendermodule-3" server="LogModuleImpl.logSender"/>

<binding client="RouterServiceImpl.receivermodule-1" server="LogModuleImpl.logReceiver"/>

Note that the lists are alphabetically inversed (The logger module « sendermodule-3″ will be called before the sendermodule-2 and the sendermodule-1 modules).

Here we are, the module will be called at each message emission/reception. Note that this is a basic usage of routing modules, you can do many things with these modules like real time monitoring, security check, authentication, endpoint filtering, content based routing, etc etc etc