小馬哥個人收藏小馬哥私房書advanced frameworks jotm btp

1、JOTM-BTP: a BTP extension for JOTMJeff Mesnil May 15, 2003AbstractThis guide describes the BTP extension of JOTM.Contents1Introduction22Prerequisites23332.4Ant. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Tomcat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Axi

2、s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .JOTM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3talling JOTM-BTP3.1From a package . . . . . . . . . . . . . . . . . . . . . . . . . .3.2 From CVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3344Ant comma

3、nds445556Compile and build JOTM-BTP . . . . . . . . . . . . . . . . .Generate Javadoc . . . . . . . . . . . . . . . . . . . . . . . . .Generate Documentation . . . . . . . . . . . . . . . . . . . .Clean JOTM-BTP . . . . . . . . . . . . . . . . . . . . . . . .Source Structure . . .

4、 . . . . . . . . . . . . . . . . . . . . . .Distribution Structure . . . . . . . . . . . . . . . . . . . . . .5BTP Demonstration6777888895.15.2Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .tallation . . . . . . . . . . . . . . . . . . . . . . . . . . . .5.2.1JOTM and JOTM-BTP .

5、 . . . . . . . . . . . . . . . .5.3Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . ..2Web Services deployment . . . . . . . . . . . . . . .web.xml modification . . . . . . . . . . . . . . . . . .5.45.5Run the demonstration . . . . . . . . . . . . . . . . . . . . . .From CVS

6、. . . . . . . . . . . . . . . . . . . . . . . . . . . . .16JOTM-BTP architecture991010106.1Design goals . . . . . . . . . . . . . . . . . . . . . . . . . . . ..26.1.3Client-side Design. . . . . . . . . . . . . . . . . . . .Server-side Design . . . . . . . . . . . . . . . . . . . .BTP impleme

7、ntation design . . . . . . . . . . . . . . .6.2Example: Message flow of CONTEXT + APLLICATION MESSAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . .Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111111131314.3Participant code example . . . . . . . . . .

8、. . . . . .Deployment descriptor for Axis . . . . . . . . . . . . .Client code example . . . . . . . . . . . . . . . . . . .6.46.5XML marshalling and unmarshalling . . . . . . . . . . . . . .Cohesive coordinators (composers) . . . . . . . . . . . . . . .7Contacts151IntroductionThis guide describes J

9、OTM-BTP, the BTP extension of JOTM. It was con- tributed by Pierre-Yves Gibello and Xavier Spengler of ExperLog.BTP (Business transaction Protocol) is a standard defined by the OASIS Consortium. BTP goal is to define XML-based technology for business transactions on the Internet. Business to busines

10、s interactions on the In- ternet pose unique challenges; including transactions that span multiple enterprises and long lasting transactions. The interdependent workflows among multiple trading partners, which drive business transactions, need to be coordinated to ensure that the outcome of the tran

11、saction is reliable.If you have any questions or comments on this BTP extension, do no hesitate to let us (mailto:) know.2PrerequisitesIn order totall or use this extension, you will need a few Java applicationwhich you may already have:Ant 1.5.x Tomcat 4.1.x Axis 1.0JOTM 1.422.1Ant

12、JOTM-BTP uses Ant (version 1.5) for its build process.Ant can be downloaded from /ant/. See the documentation of Ant to set it up (/ant/manual/).2.2TomcatTomcat is the web container developed by Apache/Jakarta. JOTM-BTP uses Tomcat 4.1.x which can be d

13、ownloaded from http:/jakarta.apache. org/tomcat/. See the documentation of Tomcat 4.1 to set it up (/tomcat/tomcat-4.1-doc/).JOTM-BTP build process relies on the CATALINA HOME environment prop- erty which has to be set to the directory where tomcat is talled:$ export CATALINA

14、_HOME=2.3AxisAxis is a project of Apache/XML which implements the SOAP (Simple Ac- cess Object Protocol). JOTM-BTP uses Axis 1.0 which can be downloadedfrom/axis/releases.html.OnceAxispackagehas been downloaded and unzipped, copy the webapps/axis/ directory into the $CATALINA HOM

15、E/webapps/ directory. JOTM-BTP build process ex- pects to find axis webapp in the $CATALINA HOME/webapps/ directory. If it doesnt, build process will fail.2.4JOTMTo download andtall JOTM, please refer to JOTMtallation guide.3talling JOTM-BTPJOTM-BTP is available under two configurations:a package in

16、cluding jars and examples: jotm-btp-x.y.tgz where x.yis the version of JOTM-BTPfrom CVS3.1From a packageJOTM-BTP package can be downloaded from JOTM SourceForge page (/projects/jotm/).Totall JOTM-BTP from a package, unzip the file with gunzip and taron Unix systems and w

17、inzip on Windows. This will create a new directory jotm-btp-x.y/.33.2From CVSCVS provides network-transaparent source control for groups of developers (more info at ).Working with CVS allows you to do things like cvs status or cvs diff and any other read-only CVS command.To get J

18、OTM from CVS, type:$cvs CVScvs-d :pserver::/cvs/JOTM login password: type Enter-d :pserver::/cvs/JOTM co -P jotm-btpThis will create a working repository of JOTM in the jotm-btp/ directory.4Ant commandsIf youve retrieved JOTM-BTP from CVS, youll ha

19、ve to build it and createa distribution before using it.JOTM-BTP relies on Ant for its build process.All Ant commands are to be typed in the jotm-btp/ directory (i.e. in the same directory than the build.xml file).To have a list and descriptions of all Ant available targets for JOTM, type:$ ant -pro

20、jecthelpBefore executing any Ant commands, be sure that: CATALINA HOME has been set Axiz webapp has been placed in the webapps/ directory of Tomcat The relative path to JOTM distribution is correct in jotm-btp/perties(by default, the path is correct if youre using both JOTM and JOTM- BTP fo

21、rm CVS. Otherwise, you may have to change it)Ant messages will warn you if one of these 3 conditions is not met.4.1Compile and build JOTM-BTPThis step is necessary only if you have modified JOTM-BTP source code oryouve retrieved source files from CVS. You just have to type:$ ant distThis will compil

22、e all JOTM-BTP source files and create all the jar files.A working version of JOTM-BTP is now available in the output/dist/subdirectory (the so-called distribution directory of JOTM-BTP).44.2Generate JavadocTo generate JOTM-BTP Javadoc, simply type:$ ant jdocJavadoc pages are now browsable from the

23、output/dist/jdoc/ subdirec- tory.4.3Generate DocumentationJOTM-BTP documentation is written in LaTeX.We use pdflatex tool to generate PDF files and latex2html to generateHTML files. Since these two tools may not betalled on your system,its up to you to inform Ant that itll have the tools to perform

24、document generation.PDF (resp. HTML) generation is triggered by pdlatex (resp. latex2html) property on the command line. Whats more, for HTML generation a shell script, doc2html, is used. So for the moment, you can generate HTML documentation only from Linux. Sorry. (Anyway, documentation is stillav

25、ailable online at /jotm/doc/ in both and HTML format).PDF If youve pdflatex on your system, you can ask Ant to generate PDF documentation by typing$ ant doc -Dpdflatex=1 If youve latex2html and youre on Linux, you can ask Ant to generate HTML documentation by typing$ and doc -

26、Dlatex2html=1Of course, you can also do both$ and doc -Dpdflatex=1 -Dlatex2html=1Generated document is put in the output/dist/doc/ directory.4.4Clean JOTM-BTPTo remove files generated during compilation or build process, type:$ ant cleanYoull start from a clean working directory again.54.5Source Str

27、uctureWhen you retrieve JOTM-BTP source, the structure of your jotm-btp/directory is the following one:GettingStarted.txt - a reminder of the main Ant targets for JOTM- BTPREADME.txt - the usual README filebuild.xml - the main Ant build file used by JOTM-BTPperties - configuration of Ant pr

28、operties are done in this filedoc/ - all documentation sources are in this directory (e.g. from which this guide has been generated)tall.texexternals/ - some external libraries used by JOTM (which are not part of JOTM, Tomcat or Axis)src/ - source code of JOTM-BTPdemo/ - JOTM-BTP demonstration (base

29、d on booking of hotel and flight) source code4.6Distribution StructureOnce youve built JOTM-BTP (i.e. in the output/dist/ subdirectory) or if you retrieved it from its package, the ditribution structure of JOTM-BTP is the following:README.txt - still the usual README filedoc/ - this directory may co

30、ntain PDF and HTML version of the various documentation files (see section 4.3)demo/ - JOTM-BTP demonstration (binary files, Javadoc)jdoc/ - Javadoc of JOTM-BTPlib/ - JOTM-BTP library directory (it conta and some other used jar files)JOTM-BTP jar file5BTP DemonstrationOnce you have a distribution of

31、 JOTM-BTP, one handy way to be sure that it is working is to run the demonstration (which is in the demo/ directory of the distribution).65.1ScenarioThe BTP demonstration is based on a common transaction example: a travel agency which books both one hotel and one flight in the same transaction. The

32、demonstration is composed of 3 Web services:TravelAgencyHotelReservationFlightReservationThe TravelAgency will contact both HotelReservation and FlightReservationto book them in the same transaction. If a problem occurs (such as no more place in the hotel or in the flight), the transaction will be r

33、olled back for both. Otherwise, a reservation will be kept for both of them under the same transaction ID.In addition to the travel agency client, there are two other servlets which can be used to supervise SOAP messages, transaction messages, hotel and flight reservation,.5.2Beforetallationtalling

34、the demonstration, youll need to have a correcttallationof both Tomcat and Axis (see section 2).5.2.1JOTM and JOTM-BTPFirst, copy into $CATALINA HOME/webapps/axis/WEB-INF/lib/ directory: Jar files from JOTM distribution (in $JOTM HOME/lib/ directory):jotm.jarjotm jrmpstubs.jar jonas timer.jarjta spe

35、c1 0 1.jar (this jar is needed due to internal dependen- cies in JOTM on JTA interfaces) Jar files from JOTM-BTP distribution: jotm-btp.jar kxml2.jar75.3DeploymentStill into $CATALINA HOME/webapps/axis/WEB-INF/lib/ directory, copy: demo/btp-demo.jarCopy into $CATALINA HOME/webapps/axis/: demo/btp.ht

36、ml5.3.1Web Services deploymentYou can find in the demo/ directory 2 .wsdd files (deploy.wsdd and undeploy.wsdd). deploy.wsdd (resp. undeploy.wsdd) is used to deploy (resp. undeploy) our Demonstration Web Service into Axis.To deploy, in the demo/ directory, type:$ java org.apache.axis.client.AdminCli

37、ent deploy.wsddSee Axis documentation to set the CLASSPATH before deploying (so you can find the AdminClient class).After deployment, start Tomcat and browse at http:/localhost:8080/axis/ to check for the deployment status (3 web services, respectively called Trav- elAgency, HotelReservation and Fli

38、ghtReservation should be deployed).5.3.2web.xml modificationThe last step is to modify axis/WEB-INF/web.xml file to add description of our demonstration servlets: ert into this file the content of demo/btp-web.xml, between the lastservlet and the first servlet-mapping tags.Finally restart Tomcat (to

39、 take into account our new servlets).5.4Run the demonstrationStart at the url: http:/localhost:8080/axis/btp.html. This page will give you 3 links the Travel Agency Booking, a travel agency client that books a flight and a hotel the Travel Agency Viewer, a servlet to see what happens on the particip

40、ant side (hotel and flight bookings) the transaction coordinator admervlet to monitor the transactions8You can first book a flight and a hotel using the TravelAgencyServlet, then look at what happens at both the transaction coordinator level (Superi- orServlet ) and transaction participants level (P

41、articipantServlet) during the booking process.To simulate a transaction failure, check the Transaction failure simulation.box in the TravelAgencyServlet home page (will cause one of the participantsto reject the ”prepare” call, then the decider will cancel both participants).5.5From CVSSince all the

42、se tasks are really tedious, if youre using CVS version of JOTM- BTP, there is a simpler way to do.In jotm-btp/ directory, type:$ ant demo.jar$ ant demo.copyIt will create the btp-demo.jar jar files and copy all the needed jars inaxis/WEB-INF/lib/ directory.Then, you still have to manuallyaxis/WEB-I

43、NF/web.xml.ert content of demo/btp-web.xml intoStart Tomcat.In jotm-btp/ directory, type:$ ant demo.deployThats it!You can now try the demonstration from http:/localhost:8080/axis/btp.html.6JOTM-BTP architectureNowthat weve seen an example of JOTM-BTP, let see what is JOTM-BTP.6.1Design goalsAt the

44、beginning of JOTM-BTP, the goals were: to Apache Axis as the target deployment platform, and JOTM asthe transaction manager to provide a simple way (as transparent as possible to the end user,i.e. as simple as JTA and XA) to implement and deploy BTP-enabled web services, on both the client and the s

45、erver side.9 to be as little intrusive as possible wrt JOTM: current implementation of JOTM-BTP did not require any modification of JOTM. (JOTM isembeddedome of our web services - those with a coordinator role- as the transaction manager we rely on, and thats it!).6.1.1Client-side DesignOn the clien

46、t side, JOTM-BTP provides a simple API to exchange BTP and Application messages with web services. For example, it provides methods to perform begin(), confirm transaction(), etc. without having to build, marshal, send, receive and unmarshal XML messages nor to have a fine understanding of BTP messa

47、ges).6.1.2Server-side DesignOn the server side, the programmer just has to extend some of our utilitary classes (for example, Participant to implement a BTP-enabled participant, which is the equivalent to a Resource in JOTM or a XAResource in JTA), and to deploy it as a Web Service on Apache Axis.Th

48、e programmer has to implement callbacks, that inform him of transaction- related events (like transaction boundaries) - so he doesnt have to cope with BTP, just with his application logic.6.1.3BTP implementation designJavaclassesareprovided for each BTP Message (eg. CONTEXT, CONTEXT-REPLY, ENROL, EN

49、ROLLED,.), as well as Related Groups (message compounds, like CONTEXT + APPLICATION).The main Roles defined in the BTP specification (like Participant, Decider or SubCoordinator ) are implemented as java classes, to be deployed as Web Services on Axis. Some embeds a JOTM transaction manager (like De

50、cider or Subcoordinator, that can create and manage transactions), some dont (like Participant, that has some BTP capabilities to be enrolled in a trans- action as a resource, but cant create and manage its own transactions).The transaction-related messages between a coordinator and a participant ar

51、e undertaken by a “BTP Resource” object, enrolled in JOTM as a Resource, and exchanging XML messages with the participant it represents under the control of the transaction manager (eg. a prepare() call on the resource results in a PREPARE BTP message to be sent to the participant, etc.).106.2Exampl

52、e: Message flow of CONTEXT + APLLICA- TION MESSAGEThe Terminator sends a transaction context + application messages to some Participants, which are BTP-enabled web services. The CONTEXT informs the participants that they have to enrol themselves in a trans- action (the CONTEXT was obtained from a pr

53、evious BEGIN issued by the terminator).The participants extract transaction information from the Context (mainly ”superior-address” and ”Transaction-Id”), then determine the address of the Coordinator they have to ENROL in, and send an ENROL message.The Coordinator has an embedded JOTM transaction manager: upon receipt of the ENROL message, it creates a local Resource and registers it on JOTM.The Resource handles all the XML communication (BTP messages) with the Participant, in reaction to the JOTM transaction managers decisions