Hands on Apache ODE
Juli 2010 - Vorige maand hebben we besproken wat de mogelijkheden en beperkingen van Apache ODE zijn. ODE is een snelle open source BPEL-engine die de nieuwste versie van WS-BPEL 2.0 ondersteunt. In dit Whitebook bespreken we het vervolg en zien we een complete setup van Apache ODE. We beginnen met de installatie van ODE, vervolgens gaan we een eerste project creeëren en deployen met behulp van Eclipse BPEL Designer.
Deployment van ODE op Tomcat
Het installeren van Apache ODE is redelijk eenvoudig. Apache ODE wordt als WAR-bestand gedistribueerd en kan op elke JEE-container worden gedeployed. Wij zullen gebuikmaken van Apache Tomcat.
Download en installeer Apache Tomcat, installeer en start de server en open de management console.
Download de laatste WAR distributie van Apache ODE en pak het bestand apache-ode-war-1.3.4.zip uit. Het bestand ode.war kan via de manager van Tomcat worden geïnstalleerd: Selecteer het ode.war bestand onder het kopje "WAR file to deploy" en druk op knop Deploy
In de Tomcat manager is de Apache ODE applicatie zichtbaar:
Eclipse BPEL Visual Designer
Eclipse BPEL Visual Designer Plugin installatie
Download en installeer Eclipse Ganymede verie 3.4.2
N.B.: De BPEL Visual Designer plugin werkt niet met Eclipse versie 3.5.
Start Eclipse en selecteer Help => Software Updates. Klik op Add Site en vul de volgende url in: http://download.eclipse.org/technology/bpel/update-site/
Selecteer de BPEL Visual Designer en klik op Install.
Klik op Finish, hierna moet Eclipse worden herstart.
Apache ODE Server toevoegen aan Eclipse
Selecteer File => New => Other
Selecteer Server => Server en klik Next.
Selecteer de Ode v1.x Server.
Klik Next en geef de ODE en Tomcat home-directory op.
Klik op Finish.
BPEL project
Maak een BPEL project aan
Selecteer File => New => Other => Bpel 2.0 en kies BPEL Project.
Geef een naam op voor het project en selecteer "Apache ODE 1.x Runtime" als Target Runtime. Klik op Modify onder Configuratie en selecteer BPEL 2.0 Facet als Project Facet.
Klik op Finish.
Maak een BPEL Process file
Klik met de rechter muisknop op het HelloWorldBPEL project en kies New => Other => BPEL 2.0 en selecteer New BPEL Process File.
Klik next en geef als naam op voor het proces HelloWorldProcess en geef een namespace op.
N.B.: De naam HelloWorldProcess hebben we straks nodig in de aanroep naar het proces.
Kies als Template Synchronous BPEL Process.
Selecteer het project en klik finish.
Nu verschijnt er een venster met links een grafische weergave van het BPEL proces en rechts een palette met procestools en een schermgedeelte met tools voor het aanmaken van partnerlinks, procesvariabelen, correlatiesets en message exchanges. Deze twee schermen kunnen worden getoond en verborgen door met de muis op de in het volgende plaatje met rood omcirkelde pijltjes te kikken.
Port en Binding toevoegen aan het WSDL bestand
Er zijn twee bestanden aangemaakt, een BPEL bestand en een WSDL bestand. Het WSDL bestand is nog niet compleet. We gaan een Port en een Binding toevoegen. Dubbelklik op het WSDL bestand zodat het bestand wordt geopend. Onderaan het scherm kan worden overgeschakeld naar respectievelijk Design of Source mode. Zorg dat het scherm in design mode staat.
Klik met de rechter muisknop ergens op het scherm en selecteer Add Service. Noem de Service HelloWorldService en hernoem de NewPort naar HelloWorldPort.
Klik met de rechter muisknop op het scherm en selecteer Add Binding. Klik met de rechter muisknop op de niew gecreeërde binding en kies Show properties.
In het Properties window: noem de binding HelloWorldBinding en klik op Generate Binding Content. Kies tns:HelloWorldProcess als Port Type en SOAP als protocol:
Klik vervolgens op Finish.
Klik nu met de rechter muisknop op de HelloWorldPort en kies Show properties.
Klik in het vak bij Binding en selecteer de HelloWorldBinding. Type in het Address veld http://localhost:8080/ode/processes/HelloWorldProcess
Externe Webservice aanroepen
We gaan nu in het proces een externe webservice aanroepen. In dit voorbeeld maken we gebruik van een eenvoudige webservice SimpleService die als .aar file kan worden gedployed in de service folder van ODE.
Download het SimpleService.aar bestand en sla het op in de folder: $ODE_HOME/webapps/ode/WEB-INF/services.
Hieronder staat een kopie van het WSDL bestand. We zullen dit bestand gebruiken om een partnerlink in ons proces te maken. Sla het WSDL bestand op als SimpleService.wsdl in de HelloWorldBPEL folder. (Klik in Eclipse op F5 om de SimpleService.wsdl te zien)
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:ns1="http://org.apache.axis2/xsd"
xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns:ns0="http://demo.whitehorses.nl"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
targetNamespace="http://demo.whitehorses.nl">
<wsdl:documentation>HelloWorldService</wsdl:documentation>
<wsdl:types>
<xs:schema xmlns:ns="http://demo.whitehorses.nl" attributeFormDefault="qualified"
elementFormDefault="qualified"
targetNamespace="http://demo.whitehorses.nl">
<xs:element name="echo">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" name="value" nillable="true" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="echoResponse">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" name="return" nillable="true" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
</wsdl:types>
<wsdl:message name="echoRequest">
<wsdl:part name="parameters" element="ns0:echo"/>
</wsdl:message>
<wsdl:message name="echoResponse">
<wsdl:part name="parameters" element="ns0:echoResponse"/>
</wsdl:message>
<wsdl:portType name="HelloWorldServicePortType">
<wsdl:operation name="echo">
<wsdl:input message="ns0:echoRequest" wsaw:Action="urn:echo"/>
<wsdl:output message="ns0:echoResponse" wsaw:Action="urn:echoResponse"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="HelloWorldServiceSOAP11Binding" type="ns0:HelloWorldServicePortType">
<soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
<wsdl:operation name="echo">
<soap:operation soapAction="urn:echo" style="document"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:binding name="HelloWorldServiceSOAP12Binding" type="ns0:HelloWorldServicePortType">
<soap12:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
<wsdl:operation name="echo">
<soap12:operation soapAction="urn:echo" style="document"/>
<wsdl:input>
<soap12:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap12:body use="literal"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:binding name="HelloWorldServiceHttpBinding" type="ns0:HelloWorldServicePortType">
<http:binding verb="POST"/>
<wsdl:operation name="echo">
<http:operation location="HelloWorldService/echo"/>
<wsdl:input>
<mime:content type="text/xml" part="echo"/>
</wsdl:input>
<wsdl:output>
<mime:content type="text/xml" part="echo"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="HelloWorldService">
<wsdl:port name="HelloWorldServiceSOAP11port_http"
binding="ns0:HelloWorldServiceSOAP11Binding">
<soap:address location="http://localhost:8080/ode/processes/HelloWorldService"/>
</wsdl:port>
<wsdl:port name="HelloWorldServiceSOAP12port_http"
binding="ns0:HelloWorldServiceSOAP12Binding">
<soap12:address location="http://localhost:8080/ode/processes/HelloWorldService"/>
</wsdl:port>
<wsdl:port name="HelloWorldServiceHttpport" binding="ns0:HelloWorldServiceHttpBinding">
<http:address location="http://localhost:8080/ode/processes/HelloWorldService"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>Open het BPEL-proces in de Design-editor en sleep vanuit het Palette onder Actions een Invoke in het proces en plaats het tussen de receiveInput en replyOutput.
Klik in het Properties venster op Details en selecteer Create Global Partner Link.
Geef een naam op en klik OK. Selecteer in het scherm Choose Partner Link, From Project en zet een vinkje bij Show Port Types. Selecteer SimpleServicePortType onder Matches.
Klik op OK.
Geef een Partner Link naam en Role naam op en selecteer SimpleServicePortType als Port Type.
Klik op Finish.
Selecteer nu in het Quick Pick gedeelte van het Properties scherm de echo operatie.
Onder in het scherm is te zien dat er twee variabelen worden aangemaakt. Eén voor het request van de webservice en één voor de response. We zullen nu het request gaan vullen met de input parameter van het proces. Het antwoord van de webservice zullen we kopieeren naar de outputvariabele van het proces.
Het kopieeren (Assignen) van variabelen
We gaan nu de inputvariabele van het process kopieeren naar het request van de SimpleService en de respons van de service kopieeren we naar de output variabele van het proces.
Ga naar het Design-scherm van het BPEL proces en sleep een Assign action van het palette tussen de receiveInput en de Invoke en een tussen de Invoke en de replyOutput.
Klik met de rechter muisknop op de Assign en kies Show in Properties om de waarden van de ene variable in het Properties scherm te kopieeren naar de andere.
Klik in het Properties scherm op Details en vervolgens op New. Verbind de inputvariabele met de NumToStr input variable.
Als er een Initializer window verschijnt kies dan voor Yes.
De initializer van de BPEL Designer werkt niet altijd goed. Als een variabele niet goed wordt geinitialiseerd treedt er een selectionFailure op. Kijk verderop in dit Whitebook onder veel voorkomende problemen voor een oplossing.
Herhaal dit proces voor de tweede Assign en kopieer de respons van de webservice naar de output van het proces. Als het Initializer window verschijnt kies dan weer voor Yes.
Deployment Descriptor aanmaken
Ten slotte moeten we voordat het project kunnen deployen nog een Deployment Descriptor maken.
Selecteer File => New => Other => BPEL 2.0 en kies Apache ODE Deployment Descriptor.
Klik Next en Finish.
Het deploy.xml bestand wordt aangemaakt en geopend in een Editor window. We moeten nu de Inbound en Outbound interface registreren. De Inbound interfaces zijn de interfaces waarmee het proces kan worden aangesproken en de Outbound interfaces zijn de interfaces waarmee externe services worden benaderd.
Kies onder Inbound Interfaces op Associated Port, selecteer de HelloWorldPort en klik op de tab toets.
Kies onder Outbound Interface de SimpleServiceSOAP11port_http
Het proces is nu klaar om te worden gedeployed op de ODE server.
Deployment van het proces
Open het Server window.
Selecteer Window => Show view => Other => Server.
Klik met de rechtermuisknop op de ODE Server en kies Add and Remove Projects.
Kies het HelloWorld project en kies Add.
Klik nogmaals met de rechtermuisknop op de ODE Server en kies Start.
Het proces kan nu worden getest met bijvoorbeeld SoapUI. De URL naar de WSDL is: http://localhost:8080/ode/processes/HelloWorldProcess?wsdl
Veel voorkomende fouten:
Selection Failure
Een selectionFailure komt voor als een variabele niet goed is geinitialiseerd, het kan zijn dat de xml of de namespace niet kloppen met de xsd.
In de eerste assign van ons proces wordt het request van de SimpleService geïnitialiseerd. De code ziet er als het goed is als volgt uit:
<bpel:copy>
<bpel:from>
<bpel:literal xml:space="preserve">
<ns:echo xmlns:ns="http://demo.whitehorses.nl" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ns:value/>
</ns:echo>
</bpel:literal>
</bpel:from>
<bpel:to variable="SimpleServicePartnerLinkRequest" part="parameters"></bpel:to>
</bpel:copy>Uninitialized variable
Een variabele moet voordat er een waarde aan kan worden toegevoegd eerst worden geïnitialiseerd. Als dat niet het geval is treedt er een Uninitialized Variable Exception op. Het initialiseren van een variable wordt door de BPEL Designer automatich gedaan als een nieuwe Assign wordt uitgevoerd op een variabele die nog niet geinitialiseerd is. Controleer altijd of het automatisch initialiseren goed is gegaan. Zo niet, doe het dan handmatig aan de hand van de xsd van de variable (let op de namespaces!).
Uninitialized PartnerRole
Het komt soms voor dat een RartnerRole van een PartnerLink of externe webservice niet goed wordt geïnitialiseerd voordat deze wordt aangeroepen. Door het attribuut initializePartnerRole="yes" toe te voegen aan de partnerlink tag kan dit worden verholpen.
<bpel:partnerLink name="SimpleServicePartnerLink" partnerLinkType="tns:SimpleServiceLinkType" partnerRole="SimplerServiceRole" initializePartnerRole="yes"></bpel:partnerLink>
Samenvatting
In dit Whitebook hebben we uitgelegd hoe je Apache ODE eenvoudig kunt deployen op een JEE server. Vervolgens hebben we met behulp van de Eclipse BPEL Visual Designer een BPEL proces ontwikkeld waarin we een aanroep deden naar een externe webservice. Het aanroepen of orchesteren van services vormt de basis van elk BPEL proces. Een proces kan worden uitgebreid met het aanroepen van andere services en het verder uitwerken van de logica voor de procesflow. Hiermee is de basis gelegd voor het ontwikkelen van een BPEL proces.
Referenties
Waardering:
Print versie
PDF versie
Reacties
Nieuwe reactie inzenden