Web Methods Integration Server JMS Client Developer's Guide 7.1

TitlePage
Integration Server
Version 7.1
webMethods Integration Server JMS Client Developers Guide
Copyright & Docu mentID
Cerebra,Glue,InfravioXBroker,InfravioXRegistry,Infravio,MywebMethodsServer,MywebMethods,webMethodsAccess,webMethodsAdministrator, webMethodsBroker,webMethodsCentralConfiguration,webMethodsDashboard,webMethodsDesigner,webMethodsDeveloper,webMethodsFabric, webMethodsGlue,webMethodsInfrastructureDataCollector,webMethodsInfravioXBroker,webMethodsInfravioXRegistry,webMethodsInstaller, webMethodsIntegrationServer,webMethodslogo,webMethodsMainframe,webMethodsManager,webMethodsModeler,webMethodsMonitor, webMethodsOptimizeforInfrastructure,webMethodsOptimizeforProcess,webMethodsOptimize,webMethodsPortal,webMethodsProcessEngine, webMethodsServicenet,webMethodsTaskEngine,webMethodsTradingNetworks,webMethodsWorkflow,andwebMethodsareeitherregistered trademarksortrademarksofwebMethods,Inc. Acrobat,Acrobat,andReaderareregisteredtrademarksofAdobeSystemsIncorporated.AmdocsandClarifyCRMareregisteredtrademarksofAmdocs. AribaisaregisteredtrademarkofAriba,Inc.BEA,BEAWebLogicServer,Jolt,andTuxedoareregisteredtrademarks,andBEAWebLogicPlatformisa trademarkofBEASystems,Inc.ActionRequestSystem,BMCSoftware,PATROL,andRemedyareregisteredtrademarksofBMCSoftware,Inc.BroadVision isaregisteredtrademarkofBroadVision,Inc.ChemeStandardsandCIDXaretrademarksofCIDX,TheChemicalIndustryDataExchange.SiteMinderand UnicenterareregisteredtrademarksofCA,Inc.PopChartisaregisteredtrademarkofCORDATechnologies,Inc.KenanandArborareregisteredtrademarks ofAlcatelLucent.DataConnectionandSNAPIXareregisteredtrademarksofDataConnectionCorporation.D&BandDUNSareregisteredtrademarksof Dun&BradstreetCorporation.EclipseisatrademarkofEclipseFoundation,Inc.EntrustisaregisteredtrademarkofEntrust,Inc.papiNetisaregistered trademarkoftheEuropeanUnionandtheUnitedStates.FinancialInformationeXchange,F.I.X,andF.I.XProtocolaretrademarksofFIXProtocolLtd. UCCnetandeBusinessReadyareregisteredtrademarks,and1SYNCandTransoraaretrademarksofGS1US.HewlettPackard,HP,HPUX,OpenView,PA RISC,andSNAplus2aretrademarksofHewlettPackardCompany.i2isaregisteredtrademarkofi2Technologies,Inc.AIX,AS/400,CICS,ClearCase,DB2, Domino,IBM,Informix,Infoprint,Lotus,LotusNotes,MQSeries,OS/390,OS/400,RACF,RS/6000,SQL/400,S/390,System/390,VTAM,andWebSphere,and z/OSareregisteredtrademarks;andCommunicationsSystemforWindowsNT,DB2UniversalDatabase,IMS,MVS,andSQL/DSaretrademarksofIBM Corporation.InnoDBisatrademarkofInnobaseOy.ItaniumisaregisteredtrademarkofIntelCorporation.LinuxisaregisteredtrademarkofLinus Torvalds.W3Cisaregisteredtrademark,andXWindowSystemisatrademarkoftheMassachusettsInstituteofTechnology.MetaSolvisaregistered trademarkofMetasolvSoftware,Inc.ActiveX,Microsoft,Outlook,VisualBasic,VisualSourceSafe,Windows,WindowsNT,andWindowsServerare registeredtrademarksofMicrosoftCorporation.SixSigmaisaregisteredtrademarkofMotorola,Inc.FirefoxandMozillaareregisteredtrademarksofthe MozillaFoundation.MySQLisaregisteredtrademarkofMySQLAB.nCipherisatrademarkofnCipherCorporationLtd.EclipseisatrademarkofEclipse Foundation,Inc.EntrustisaregisteredtrademarkofEntrust,Inc.papiNetisaregisteredtrademarkoftheEuropeanUnionandtheUnitedStates.Financial InformationeXchange,F.I.X,andF.I.XProtocolaretrademarksofFIXProtocolLtd.UCCnetandeBusinessReadyareregisteredtrademarks,and1SYNCand TransoraaretrademarksofGS1US.HewlettPackard,HP,HPUX,OpenView,PARISC,andSNAplus2aretrademarksofHewlettPackardCompany.i2isa registeredtrademarkofi2Technologies,Inc.AIX,AS/400,CICS,ClearCase,DB2,Domino,IBM,Informix,Infoprint,Lotus,LotusNotes,MQSeries,OS/390, OS/400,RACF,RS/6000,SQL/400,S/390,System/390,VTAM,andWebSphere,andz/OSareregisteredtrademarks;andCommunicationsSystemforWindows NT,DB2UniversalDatabase,IMS,MVS,andSQL/DSaretrademarksofIBMCorporation.InnoDBisatrademarkofInnobaseOy.Itaniumisaregistered trademarkofIntelCorporation.TeradataisaregisteredtrademarkofNCRCorporation.NetscapeisaregisteredtrademarkofNetscapeCommunications Corporation.ServletExecisaregisteredtrademark,andNewAtlantaisatrademarkofNewAtlantaCommunications,LLC.SUSEisaregisteredtrademark ofNovell,Inc.AppiaisaregisteredtrademarkandJavelinTechnologiesisatrademarkofNYFIX,Inc.CORBAisaregisteredtrademarkofObject ManagementGroup,Inc.JDEdwards,OneWorld,Oracle,PeopleSoft,Siebel,andVantiveareregisteredtrademarks;andInfranet,PeopleSoftPureInternet Architecture,Portal,andWorldSoftwarearetrademarksofOracleCorporation.PerforceisatrademarkofPerforceSoftware.JBossandRedHatare registeredtrademarksofRedHat,Inc.PIPandRosettaNetaretrademarksofRosettaNet,anonprofitorganization.SAPandR/3areregisteredtrademarks ofSAPAG.PVCSisaregisteredtrademarkofSerenaSoftware,Inc.SWIFTandSWIFTNetareregisteredtrademarksofSocietyforWorldwideInterbank FinancialTelecommunicationSCRL.SPARCandSPARCStationareregisteredtrademarksofSPARCInternational,Inc.BAANandSSAareregistered trademarks;andSSAGlobalisatrademarkofSSAGlobalTechnologies,Inc.EJB,EnterpriseJavaBeans,Java,JavaServer,JDBC,JSP,J2EE,Solaris,Sun,and SunMicrosystemsareregisteredtrademarks;andJavaNamingandDirectoryInterface,JavaServerPages,SOAPwithAttachmentsAPIforJava,andSunSoft aretrademarksofSunMicrosystems,Inc.SybaseisaregisteredtrademarkofSybase,Inc.VERITASisaregisteredtrademark,andVERITASClusterServeris atrademarkofSymantecCorporation.UNIXisaregisteredtrademarkofTheOpenGroup.UnicodeisatrademarkofUnicode,Inc.VeriSignisaregistered trademarkofVerisign,Inc. SoftwareAGandallSoftwareAGproductnamesareeithertrademarksorregisteredtrademarksofSoftwareAG. Otherproductandcompanynamesmentionedhereinmaybethetrademarksoftheirrespectiveowners. Copyright2007webMethods,Inc.Allrightsreserved. Copyright2007SoftwareAGand/oritssuppliers,Uhlandstrasse12,64297Darmstadt,Germany.Allrightsreserved.
Document ID: DEV-JMS-DG-71-20070928
Contents
Contents
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
8 8
Chapter 1. Configuring Integration Server for JMS Messaging . . . . . . . . . . . . . . . . . . . . .

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with JNDI Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a JNDI Provider Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing a JNDI Provider Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting a JNDI Provider Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing a Test Lookup for a JNDI Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with JMS Connection Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a JMS Connection Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying a Retry Interval for Failed Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying a Keep Alive Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing a JMS Connection Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling and Disabling a JMS Connection Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting a JMS Connection Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Administered Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Load Balancing Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9
10 10 10 12 13 13 13 14 17 18 18 19 19 20 20
Chapter 2. JMS Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

JMS Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Messaging Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Point-to-point (PTP) Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Publish-Subscribe Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Durable Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Non-durable Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMS API Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Administered Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Types of Administered Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connection Factories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Producer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Consumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
21
22 22 22 23 24 24 24 24 25 25 25 26 26 26 26
webMethods Integration Server JMS Client Developers Guide Version 7.1
Contents
Message Selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Acknowledgment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26 27 27 28
Chapter 3. Sending and Receiving JMS Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The JMS Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Send a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending a JMS Message and Waiting for a Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Send a Request Message and Wait for a Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Replying to a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Send a Reply Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiving a JMS Message Using Built-In Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Actively Receive a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending a JMS Message as Part of a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Send a JMS Message within a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Properties in a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning an Activation to a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting the UUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
30 30 30 34 35 38 39 39 40 44 45 46 46 47
Chapter 4. Working with JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Building a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMS Trigger Service Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Message Selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Local Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling or Disabling a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting an Acknowledgment Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting a Join Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Join Time-outs for All (AND) Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Join Time-outs for Only One (XOR) Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting a Join Time-out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Execution User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Message Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Serial Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Concurrent Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Processing and Message Consumers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Processing Messages in Batches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Message Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
49
50 50 50 51 56 56 57 58 59 59 60 60 61 62 62 62 63 63 64
Contents
Handling Fatal Errors for Non-Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Handling Transient Errors for Non-Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Retry Behavior for Trigger Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Service Requirements for Retrying a Trigger Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Handling Retry Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Throw Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Suspend and Retry Later . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Transient Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating Events for JMS Retrieval Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Debugging a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building JMS Triggers with Multiple Routing Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
65 66 67 67 68 68 69 70 72 73 74
Chapter 5. Building a Transacted JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

What Is a Transacted JMS Trigger? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Building a Transacted JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prerequisites for a Transacted JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Properties for Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Steps for Building a Transacted JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Handling Fatal Errors for Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Handling Transient Errors for Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Recover Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Suspend and Recover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Transient Error Handling for a Transacted JMS Trigger . . . . . . . . . . . . . . . . . . . . .
77
78 78 79 79 80 80 82 83 84 85
Chapter 6. Exactly-Once Processing for JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . .

Overview of Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Duplicate Detection Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Delivery Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document History Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Happens When the Document History Database Is Not Available? . . . . . . . . . . . . . Managing the Size of the Document History Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Resolver Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Resolver Service and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Extenuating Circumstances for Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exactly-Once Processing and Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Considerations for Configuring Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Exactly-Once Processing for a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Document Resolver Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Exactly-Once Processing Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
87
88 88 91 92 94 95 96 97 97 99 99 100 100 101 101 102
Contents
Chapter 7. Managing JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Thread Usage for JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Thread Usage for JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Increasing or Decreasing Thread Usage for JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling, Disabling, and Suspending JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 104 104 104 106
Appendix A. JMS Server Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 watt.server.jms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Appendix B. Building a Resource Monitoring Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Service Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Appendix C. Transaction Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Transaction Management Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XA Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implicit and Explicit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implicit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Explicit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Built-In Transaction Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 118 118 119 119 119 120 121
About This Guide
About This Guide
ThewebMethodsIntegrationServerJMSClientDevelopersGuideisdesignedforthe developerwhoisresponsiblefordevelopingsolutionsthatusewebMethodsIntegration ServertosendandreceivemessagesusingJavaMessagingService(JMS). Thisguidedoesthefollowing: ExplainshowtoestablishconnectionstooneormoreJMSproviders. DescribeshowtobuildaJMStriggertouseforreceivingJMSmessages. ExplainshowtobuildservicesthatsendandreceiveJMSmessagesusingbuiltin services. Thisguideassumesthatyouarefamiliarwiththefollowing: BasicconceptsofwebMethodsarchitectureandterminology. UsageofwebMethodsDevelopertocreateelementsandbuildservices. Generalknowledgeofprogramming,theJavaprogramminglanguage,andtheJMS API. Note: Anindepthtreatmentofmessagingarchitectureisbeyondthescopeofthisguide, butisavailableelsewhere.ForinformationabouttheJMSAPI,pleaserefertotheJava MessageService,Version1.1specificationontheSunMicrosystemsJavaMessageService (JMS)Website. Note: WithwebMethodsDeveloper,youcancreateBroker/localtriggersandJMStriggers. ABroker/localtriggeristriggerthatsubscribestoandprocessesdocuments published/deliveredlocallyortotheBroker.AJMStriggerisatriggerthatreceives messagesfromadestination(queueortopic)onaJMSproviderandthenprocessesthose messages.ThisguidediscussesdevelopmentanduseofJMStriggersonly.Wheretheterm triggersappearsinthisguide,itreferstoJMStriggers.Forinformationaboutcreating Broker/localtriggers,seethePublishSubscribeDevelopersGuide.
About This Guide
Document Conventions
Convention Bold Italic Description Identifieselementsonascreen. Identifiesvariableinformationthatyoumustsupplyorchange basedonyourspecificsituationorenvironment.Identifiestermsthe firsttimetheyaredefinedintext.Alsoidentifiesserviceinputand outputvariables. IdentifiesstoragelocationsforservicesonthewebMethods IntegrationServerusingtheconventionfolder.subfolder:service. Identifiescharactersandvaluesthatyoumusttypeexactlyor messagesthatthesystemdisplaysontheconsole. Identifieskeyboardkeys.Keysthatyoumustpresssimultaneously arejoinedwiththe+symbol. Directorypathsusethe\directorydelimiterunlessthesubjectis UNIXspecific. Optionalkeywordsorvaluesareenclosedin[].Donottypethe[] symbolsinyourowncode.
Narrow font
Typewriter font
UPPERCASE \ []
Additional Information
ThewebMethodsAdvantageWebsiteathttp://advantage.webmethods.comprovidesyou withimportantsourcesofinformationaboutwebMethodsproducts: Troubleshooting Information.ThewebMethodsKnowledgeBaseprovides troubleshootinginformationformanywebMethodsproducts. Documentation Feedback.ToprovidefeedbackonwebMethodsdocumentation,goto theDocumentationFeedbackFormonthewebMethodsBookshelf. Additional Documentation.Startingwith7.0,youhavetheoptionofdownloadingthe documentationduringproductinstallationtoasingledirectorycalled _documentation,locatedbydefaultunderthewebMethodsinstallationdirectory.In addition,youcanfinddocumentationforallwebMethodsproductsonthe webMethodsBookshelf.
Chapter 1. Configuring Integration Server for JMS Messaging
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Working with JNDI Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Working with JMS Connection Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Creating Administered Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Load Balancing Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
1. Configuring Integration Server for JMS Messaging
Overview
ToconfigureIntegrationServerforJMSmessaging,youneedto: CreateoneormoreJNDIprovideraliasestospecifywhereIntegrationServercanlook upadministeredobjectswhenitneedscreateaconnectiontoJMSproviderorspecify adestinationforsendingorreceivingmessages. CreateoneormoreconnectionaliasesthatencapsulatethepropertiesthatIntegration ServerneedstocreateaconnectionwiththeJMSprovider. IntegrationServeralsoincludesvariousserverconfigurationpropertiesthatyoucanuse tochangethedefaultserverbehavior.Foralistofserverconfigurationparametersrelated toJMS,seeAppendix A,JMSServerConfigurationParameters.
Working with JNDI Providers

EachJMSprovidercanstoreJMSadministeredobjectsinastandardizenamespacecalled theJavaNamingandDirectoryInterface(JNDI).JNDIisaJavaAPIthatprovidesnaming anddirectoryfunctionalitytoJavaapplications. AstheJMSclient,IntegrationServerusesaJNDIprovideraliastoencapsulatethe informationneededtolookupanadministeredobject.WhenyoucreateaJMSconnection alias,youcanspecifytheJNDIprovideraliasthatIntegrationServershouldusetolookup administeredobjects(i.e.,ConnectionFactoriesandDestinations). Note: IfyouconnectdirectlytothewebMethodsJMSProviderusingnativewebMethods API,youdonotneedtouseaJNDIprovider.Instead,youcancreateDestinationsdirectly onthewebMethodsBroker.YoudonotneedtocreateConnectionFactoriesifyouusethe nativewebMethodsAPI.
Creating a JNDI Provider Alias

UsethefollowingproceduretocreateanaliastoaJNDIprovider. To create a JNDI provider alias 1 2 3 4 5 OpenIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. UnderJMSConfiguration,clickJNDI Settings. ClickCreate JNDI Provider Alias. SpecifythefollowinginformationfortheJNDIprovideralias:
10
In this field... JNDI Alias Name Description Predefined JNDI Templates
Specify... ThealiasnamethatyouwanttoassigntothisJNDIprovider. AdescriptionforthisJNDIalias. TheJNDItemplatethatyouwanttouse. TheJNDItemplatesprovideinformationthatyoucanuseto completealiasconfigurationforaspecificprovider. Note: AfteryoucreateaJNDIprovider,IntegrationServer AdministratordisplaysCurrentSettingsasthevalueofthe Predefined JNDI Templates field.ThisindicatesthatIntegration ServerusesthecurrentlyspecifiedsettingsfortheJNDI provideralias.
Initial Context Factory
TheclassnameoftheJNDIprovider.TheJNDIprovideruses theinitialcontextasthestartingpointforresolvingnamesfor naminganddirectoryoperations. IfyouselectedapredefinedJNDItemplate,IntegrationServer displaystheinitialcontextfactoryfortheprovider.
Provider URL
TheURLoftheinitialcontextforsessionswiththeJNDI provider.TheURLspecifiestheJNDIdirectoryinwhichthe JNDIproviderstoresJMSadministeredobjects. IfyouselectedapredefinedJNDItemplate,replacethe placeholderinformationinbrackets<<>>withinformation specifictoyourconfiguration.
Security Principal
Theprincipalname,orusernamesuppliedbyIntegration ServertotheJNDIprovider,iftheproviderrequiresonefor accessingtheJNDIdirectory ForinformationaboutwhetherornottheJNDIprovider requiressecurityprincipalinformation,consulttheproduct documentationfortheJNDIprovider.
11
In this field... Security Credentials
Specify... Thecredentials,orpassword,thatIntegrationServerprovides totheJNDIprovider,iftheproviderrequiressecurity credentialstoaccesstheJNDIdirectory. ForinformationaboutwhetherornottheJNDIprovider requiressecuritycredentials,consulttheproduct documentationfortheJNDIprovider.
Other Properties
AnyadditionalpropertiestheJNDIproviderrequiresfor configuration.Forexample,youmightneedtospecifythe classpathforanyadditional.jarorclassfilesthattheJNDI providerneedstoconnecttotheJNDI. WhenyouselectapredefinedJNDItemplate,Integration Serverpopulatesthisfieldwithanyadditionalpropertiesand placeholderinformationrequiredbytheJNDIprovider. Formoreinformationaboutadditionalpropertiesorclasses requiredbyaJNDIproviderandthelocationofthosefiles,see theproductdocumentationfortheJNDIprovider.
ClickSave Changes.
Editing a JNDI Provider Alias

UsethefollowingproceduretoeditanexistingJNDIprovideralias. To edit a JNDI provider alias 1 2 3 4 OpenIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. UnderJMSConfiguration,clickJNDI Settings. IntheJNDIProviderAliasDefinitionslist,selecttheJNDIprovideraliasthatyou wanttoedit.IntegrationServerAdministratordisplaysdetailsabouttheJNDI provideralias. ClickEdit JNDI Provider Alias. EditthepropertiesoftheJNDIprovideralias. Formoreinformationaboutthefields,seeTocreateaJNDIprovideraliason page 10. 7 ClickSave Changes.
5 6
12
Deleting a JNDI Provider Alias

UsethefollowingproceduretodeleteaJNDIprovideralias. Important! WhenyoudeleteaJNDIprovideralias,anyserviceorJMStriggerthatusesa JMSconnectionaliasthatreliesontheJNDIprovideraliaswillfail.
To delete a JNDI provider alias 1 2 3 4 OpenIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. UnderJMSConfiguration,clickJNDI Settings. Locatethealiasyouwanttodeleteandclickthe iconintheDeletefield.Integration Serverdisplaysadialogboxthatpromptsyoutoverifyyouraction.ClickOKtoverify thatyouwanttodeletetheJNDIprovideralias.
Performing a Test Lookup for a JNDI Provider

UsingIntegrationServerAdministrator,youcanperformatestlookupforaJNDI provideralias.ThetestlookuplistsalloftheObjectsintheJNDInamespacereferencedby thealias. To perform a test lookup for a JNDI provider 1 2 3 4 OpenIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. UnderJMSConfiguration,clickJNDI Settings. Locatethealiasyouwanttodeleteandclickthe iconintheTest Lookupfield.
IntegrationServerreturnsalistoftheObjectslocatedintheJNDInamespace.
Working with JMS Connection Aliases

AJMSconnectionaliasspecifiestheinformationthatIntegrationServerneedstoestablish anactiveconnectionbetweenIntegrationServerandtheJMSprovider.IntegrationServer usesaJMSconnectionaliastosendmessagestoandreceivemessagesfromtheJMS provider.
13
Creating a JMS Connection Alias

WhenyoucreateaJMSconnectionalias,keepthefollowingpointsinmind: YoucanuseJNDItoretrieveadministeredobjects(ConnectionFactoriesand Destinations)andthenusetheConnectionFactorytocreateaconnection.Ifyou intendtouseaJNDIprovider,youneedtoconfigureoneormoreJNDIprovider aliasesbeforecreatingaJMSconnectionalias. or YoucanusethenativewebMethodsAPItocreatetheconnectiondirectlyonthe webMethodsJMSProvider.YoucanalsocreateDestinationsatthewebMethods Broker.IfyouintendtousethenativewebMethodsAPI,youdonotneedtoconfigure aJNDIprovideralias. Eachconnectionaliashasanassociatedtransactiontype.WithinIntegrationServer, certainfunctionalitymustbecompletedwithinanontransactedsession.Forexample, touseIntegrationServertosendorreceivelargemessagestreams,youmustspecifya JMSconnectionaliaswhosetransactiontypeissettoNO_TRANSACATION.For moreinformationabouttransactiontypes,seeTransactionTypesonpage 118. To create a JMS connection alias 1 2 3 4 5 OpenIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. UnderJMSConfiguration,clickJMS Settings. ClickCreate JMS Connection Alias. SetthefollowingGeneral SettingsfortheJMSconnectionalias: For this field... Connection Alias Name Description Transaction Type Specify... Nameoftheconnectionalias.Eachconnectionaliasrepresents aconnectionfactorytoaspecificJMSprovider. AdescriptionoftheJMSconnectionalias. WhethersessionsthatusethisJMSconnectionaliaswillbe transacted. Select... NO_TRANSACTION To... Indicatethatsessionsthatusethis JMSconnectionaliasarenot transacted.
14
For this field...
Specify... LOCAL_TRANSACTION Indicatethatsessionsthatusethis JMSconnectionaliasarepartofalocal transaction. Indicatethatsessionsthatusethis JMSconnectionaliasarepartofanXA transaction.
XA_TRANSACTION
Connection Client ID User (optional)
TheJMSclientidentifierassociatedwiththeconnections establishedbythisJMSconnectionalias. Usernameneededtoacquireaconnectionfromthe connectionfactory. FormoreinformationaboutwhetherornottheJMSprovider requiresausernameandpasswordtoobtainaconnection, refertotheproductdocumentationfortheJMSprovider.
Password (optional)
Passwordneededtoacquireaconnectionfromtheconnection factory. FormoreinformationaboutwhetherornottheJMSprovider requiresausernameandpasswordtoobtainaconnection, refertotheproductdocumentationfortheJMSprovider.
InCreate Connection Usinglist,selectoneofthefollowingtoindicatehowadministered objects(connectionfactoriesanddestinations)willbelookedup: IfyouintendtouseaJNDIprovider,selectJNDI Lookup andproceedtostep7. IfyouintendtousethenativewebMethodsAPItocreatetheconnectiondirectly onthewebMethodsJMSProvider,selectNative webMethods APIandproceedto step8.
IfyouselectedJNDI Lookupinstep6,dothefollowingintheremainingfieldsunder Connection Protocol Settings: a IntheJNDI Provider Alias Namefield,selectthealiastotheJNDIproviderthatyou wanttothisJMSconnectionaliastousetolookupadministeredobjects.For informationaboutcreatingaJNDIprovideralias,seeCreatingaJNDIProvider Aliasonpage 10. IntheConnection Factory Lookup Namefield,specifythelookupnameforthe connectionfactorythatyouwanttousetocreateaconnectiontotheJMSprovider specifiedinthisJMSconnectionalias.
Ifyouselected Native webMethods APIinstep6,dothefollowingintheremainingfields underConnection Protocol Settings:
15
ConfiguretheconnectiontotheBrokerServerthatyouwanttouseasthe webMethodsJMSProviderforthisJMSconnectionalias.Forinformationabout configuringaconnectiontoaBrokerServer,seethewebMethodsIntegrationServer AdministratorsGuide. IntheClient Groupfield,specifythenameoftheclientgrouptowhichyouwant IntegrationServertobelongwhenitactsasaJMSclient.Theclientgroupthatyou specifymustalreadyexistontheBrokerServer.ThedefaultisISJMS. IntheBroker Listfield,specifyacommadelimitedlistofBrokerServersonwhich theconnectionbetweentheIntegrationServer(actingastheJMSclient)andthe webMethodsJMSProvidercanexist.Thisprovidesconnectionfailover.Ifa connectionfailureoccurstothefirstBrokerServerinthelist,aconnectionattempt willbemadetothenextBrokerServerlisted.Usethefollowingformatforeach Broker: {BrokerName]@<host>[:port] Note: IfaconnectiontoaBrokerServerisalreadyconfigured(viaSettings > Messaging > Broker Settings),IntegrationServerpopulatesthefieldsunder ConnectionProtocolSettingswithinformationaboutthatBrokerServer.Ifthat BrokerServerfunctionsasthewebMethodsJMSProvider,youmaynotneedto editanyinformation.However,makesurethattheClientGroupfieldspecifies theclientgrouptowhichyouwantIntegrationServertobelongwhenitfunctions asaJMSclient.
UnderAdvanced Settings,specifythefollowinginformationfortheJMSconnection alias: For this field... Class Loader Specify... Thenameoftheclassloaderthatyouwanttousewiththis JMSconnectionalias.IntegrationServerwillusethespecified classloaderwhenperformingcertainactivitieswiththeJMS connectionalias(sendamessage,receiveamessage,createa connection,createadestination,etc.) Bydefault,IntegrationServerusestheserverclassloader. However,youcanspecifytheclassloaderforapackage instead.Thismaybehelpfulwhenworkingwiththirdparty JMSproviders.Forexample,youmightplacethethirdparty jarsneededforeachJMSproviderinseparatepackages, specifically,inthe IntegrationServer_directory/packageName/code/jarsdirectory. Thiscanhelppreventconflictsbetweenthejarsrequiredfor differentJMSproviders.
16
For this field... Maximum CSQ Size (number of documents)
Specify... Themaximumnumberofmessagesthatcanexistintheclient sidequeueforthisJMSconnectionalias.IntegrationServer writesmessagestotheclientsidequeueiftheJMSprovideris notavailablewhenmessagesaresent.EachJMSconnection aliashasitsownclientsidequeue. Specify1ifyouwanttheclientsidequeuetobeableto containanunlimitednumberofmessages.Thatis,specify1if youdonotwanttosetamaximumlimit. Ifyouspecify0,IntegrationServerwillnotwritemessagesto theclientsidequeueforthisJMSconnectionalias.
Drain CSQ in Order
WhetherIntegrationServerdrainstheclientsidequeueby sendingthemessagestotheJMSproviderinthesameorderin whichIntegrationServerplacedthemessagesintheclientside queue. SelectthecheckboxifyouwantIntegrationServertosend messagesfromtheclientsidequeueinthesameorderin whichIntegrationServeroriginallyplacedthemessagesinthe clientsidequeue. WhentheDrain CSQ in Ordercheckboxisselected,afterthe connectiontotheJMSproviderisreestablished,Integration Servercontinuestowritenewmessagestotheclientside queueuntiltheclientsidequeueiscompletelydrained.Ifthe Drain CSQ in Ordercheckboxisnotselected,aftertheconnection totheJMSproviderisreestablished,IntegrationServersends newmessagesdirectlytotheJMSproviderwhileitdrainsthe clientsidequeue. Note: YoucanalsospecifythenumberofmessagesIntegration Serverretrievesfromtheclientsidequeuefordeliverytothe JMSprovideratonetime.Bydefault,IntegrationServersends 25messagesatatime.Formoreinformationaboutthe watt.server.jms.csq.batchProcessingSize property,see Appendix A,JMSServerConfigurationParameters.
10 ClickSave Changes.
Specifying a Retry Interval for Failed Connections

WhenaconnectionbetweenIntegrationServerandtheJMSproviderfails,Integration Serverattemptstoreestablishtheconnectionautomaticallyaftera20seconddelay.You canconfigurehowlongIntegrationServerwaitsbetweenattemptstoreestablishthe
17
connectionbychangingthevalueofthewatt.server.jms.connection.retryPeriod property.Formoreinformationaboutthisproperty,seeAppendix A,JMSServer ConfigurationParameters.Forinformationaboutmodifyingextendedsettingsusing IntegrationServerAdministrator,seethewebMethodsIntegrationServerAdministrators Guide.
Specifying a Keep Alive Interval

IntegrationServerperiodicallypingstheJMSprovidertokeeptheconnectionbetweenthe IntegrationServerandtheJMSprovideractive.Thepingactsasakeepaliverequest.By default,IntegrationServerpingstheJMSproviderevery300seconds.Youcanconfigure howfrequentlyIntegrationServerpingstheJMSproviderbychangingthevalueofthe watt.server.jms.connection.pingPeriodproperty.Formoreinformationaboutthis property,seeAppendix A,JMSServerConfigurationParameters.Forinformationabout modifyingextendedsettingsusingIntegrationServerAdministrator,seethewebMethods IntegrationServerAdministratorsGuide.
Editing a JMS Connection Alias

AfteryoucreateaJMSconnectionalias,youmightneedtomodifypropertiesofthealias. Forexample,youmightwanttoreducetheamountofmemorythattheclientsidequeue canoccupybydecreasingthemaximumnumberofmessagesthatcanbeplacedinthe clientsidequeue.YoucaneditanypropertiesofaJMSconnectionaliaswiththeexception ofthealiasnameandthemethodusedtolookupadministeredobjects(Create Connection Usingfield). YoumustdisableaJMSconnectionaliasbeforeyoucaneditit. To edit a JMS connection alias 1 2 3 4 OpenIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. UnderJMSConfiguration,clickJMS Settings. IntheJMSConnectionAliasDefinitionslist,selecttheJMSconnectionaliasthatyou wanttoedit.IntegrationServerAdministratordisplaysdetailsabouttheconnection alias. ClickEdit JMS Connection Alias. Editthepropertiesoftheconnectionalias.Formoreinformationaboutthefields,see TocreateaJNDIprovideraliasonpage 10.NotethattheConnection Alias Nameand Create Connection Usingfieldscannotbemodified. ClickSave Changes.
5 6
18
Enabling and Disabling a JMS Connection Alias

WhenaJMSconnectionaliasisenabled,IntegrationServercanusethealiastoobtain connections,sendmessages,andreceivemessagesonbehalfofservicesandJMStriggers. Whenaconnectionaliasisdisabled,IntegrationServerstopsallJMStriggersthatusethe alias.Additionally,anyservicesthatuseadisabledJMSconnectionaliastosendorreceive messageswillendinerror. To enable or disable a JMS connection alias 1 2 3 4 5 OpenIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. UnderJMSConfiguration,clickJMS Settings. IntheJMSConnectionAliasDefinitionslist,disablethealiasifitisnotalready disabled. IntheJMSConnectionAliasDefinitionslist,dooneofthefollowingintheEnabled column: ClickNoifthealiasisdisabledandyouwanttoenableit. IfIntegrationServercannotenablethealias,itdisplaysamessageunderthealias indicatingwhyIntegrationServercannotenablethealias. ClickYesifthealiasisenabledandyouwanttodisableit.
Deleting a JMS Connection Alias

BeforeyoudeleteaJMSconnectionalias,makesureofthefollowing: TheJMSconnectionaliasisdisabled. NoservicesorJMStriggersrelyontheJMSconnectionalias.IfaJMStriggerusesa JMSconnectionalias,IntegrationServerwillpreventtheJMSconnectionaliasfrom beingdeleted To delete a JMS connection alias 1 2 3 4 OpenIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. UnderJMSConfiguration,clickJMS Settings. IntheJMSConnectionAliasDefinitionslist,disablethealiasifitisnotalready disabled.
19
Locatethealiasyouwanttodeleteandclickthe iconintheDeletefield.Integration Serverdisplaysadialogboxthatpromptsyoutoverifyyouraction.ClickOKtoverify thatyouwanttodeletetheJMSconnectionalias.
Creating Administered Objects

TheJMSproviderthatyouselectshouldprovideyouwiththetoolstocreateand configureadministeredobjectsinaJNDInamespace.IntegrationServercannotbeusedto createandconfigureadministeredobjects.Formoreinformationaboutworkingwith administeredobjects,refertotheproductdocumentationforyourchosenJMSprovider.
Load Balancing Topics

WiththewebMethodsJMSProvideryoucanallowmultipleJMSclients,eachusingits ownsession,toprocessmessagesfromasingletopicinparallel,onafirstcome,firstserve basis. Toallowloadbalancingoftopicsacrossclusters,thefollowingmustbetrue: Tobeloadbalanced,eachtopicmustbeconfiguredtosharestate.Thisallows multipleconnectionstosharethesameconnectionclientID. Thewmjms.propertiesfilemustcontainthefollowingsystemproperty: com.webmethods.jms.clientIDsharing=true Thewmjms.propertiesfilemustbeplacedintheIntegrationServerclasspath. Adurablesubscribermustbeusedtoreceivemessagesfromthetopic. ForinformationaboutcreatingaJMStopicattheBrokerandconfiguringittobeashared stateclient,seethewebMethodsBrokerAdministratorsGuide.Formoreinformationabut creatingawmjms.propertiesfiletocontainJMSproviderspecificproperties,seethe webMethodsMessagingProgrammersGuide.
20
Chapter 2. JMS Basics
JMS Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Messaging Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 JMS API Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
21
2. JMS Basics
JMS Messaging
TheJavaMessageService(JMS)isaJavaAPIthatallowsapplicationstocommunicate witheachotherusingacommonsetofinterfaces.JMSispartoftheJava2Platform, EnterpriseEdition(J2EE)suite.TheJMSAPIprovidesmessaginginterfaces,butnotthe implementations. AJMSprovider,suchasthewebMethodsJMSProvider,isamessagingsystemthat implementstheJMSmessageinterfacesandprovidesadministrativeandcontrolfeatures. ItsupportsroutinganddeliveryofmessagesthroughtheimplementationoftheJMSAPI ontheclient.AgoalofJMSistomaximizetheportabilityofJMSapplicationsacross differentJMSproviders. JMSclientsaretheprogramsorcomponents,writteninJava,thatproduceandconsume messages.
Messaging Styles
Amessagingstylereferstohowmessagesareproducedandconsumed.JMSsupportsthe publishsubscribe(pubsub)andpointtopoint(PTP)messagingstyles.
Point-to-point (PTP) Messaging

Inpointtopoint(PTP)messaging,messageproducersandconsumersareknownas sendersandreceivers. ThecentralconceptinPTPmessagingisadestinationcalledaqueue.Aqueuerepresentsa singlereceiver.Messagesenderssubmitmessagestoaspecificqueueandanotherclient receivesthemessagesfromthequeue. InthePTPmodel,aqueuemayreceivemessagesfrommanydifferentsendersandmay delivermessagestomultiplereceivers;howevereachmessageisdeliveredtoonlyone receiver.
22
2. JMS Basics
Sending Clients
Integration Server (Sender)
JMS Provider
Receiving Client
Integration Server
Integration Server (Sender)
Queue
JMS Trigger (Receiver)
Order Entry Program (Sender)
Publish-Subscribe Messaging
Inpublishsubscribemessaging,messageproducersandconsumersareknownas publishersandsubscribers. Thecentralconceptinthepublishsubscribemessagingisadestinationcalledatopic. Messagepublisherssendmessagesofspecifiedtopics.Clientsthatwanttoreceivethat typeofmessagesubscribetothetopic. Thepublishersandsubscribersnevercommunicatewitheachotherdirectly.Instead,they communicatebyexchangingmessagesthroughaJMSprovider
Publishing Clients
Integration Server (Publisher)
Subscribing Clients
Integration Server JMS Trigger (Subscriber)
JMS Provider
Integration Server Integration Server (Publisher) Topic JMS Trigger (Subscriber)
Integration Server Order Entry Program (Publisher) JMS Trigger (Subscriber)
23
2. JMS Basics
Publishersandsubscribershaveatimingdependency.Clientsthatsubscribetoatopiccan consumeonlymessagespublishedaftertheclienthascreatedasubscription.Inaddition, thesubscribermustcontinuetobeactivetoconsumemessages. ThemessagingAPIsrelaxthisdependencybymakingadistinctionbetweendurable subscriptionsandnondurablesubscriptions.
Durable Subscriptions
Durablesubscriptionsallowsubscriberstoreceiveallthemessagespublishedonatopic, includingthosepublishedwhilethesubscriberisinactive.Whenthesubscribing applicationsarenotrunning,themessagingproviderholdsthemessagesinnonvolatile storage.Itretainsthemessagesuntileither: Thesubscribingapplicationbecomesactive,identifiesitselftotheprovider,andsends anacknowledgmentofreceiptofthemessage. Theexpirationtimeforthemessagesisreached.
Non-durable Subscriptions
Nondurablesubscriptionsallowsubscriberstoreceivemessagesontheirchosentopic,only ifthemessagesarepublishedwhilethesubscriberisactive.Yougenerallyusethistypeof subscriptionforanykindofdatathatistimesensitive,suchasfinancialinformation.
JMS API Programming Model

ThefollowingsectionsummarizesthemostimportantcomponentsoftheJMSAPI. ThebuildingblocksofaJMSapplicationconsistofthefollowing: Administeredobjects(connectionfactoriesanddestinations) Connections Sessions Messageproducers Messageconsumers Messages
Administered Objects
Administeredobjectsarepreconfiguredobjectsthatanadministratorcreatesforusewith JMSclientprograms.Administeredobjectsserveasthebridgebetweentheclientcode andtheJMSprovider.
24
2. JMS Basics
Bydesign,themessagingAPIsseparatethetaskofconfiguringadministeredobjectsfrom theclientcode.Thisarchitecturemaximizesportability:theproviderspecificworkis delegatedtotheadministratorratherthantotheclientcode.However,the implementationmustsupplyitsownsetofadministrativetoolstoconfigurethe administeredobjects. JMSadministeredobjectsarestoredinastandardizednamespacecalledtheJavaNaming andDirectoryInterface(JNDI).JNDIisaJavaAPIthatprovidesnaminganddirectory functionalitytoJavaapplications.JNDIprovidesawaytostoreandretrieveobjectsbya usersuppliedname.
Types of Administered Objects

Therearetwotypesofadministeredobjects:connectionfactoriesanddestinations. Connection Factories AconnectionfactoryistheobjectaclientusestocreateaconnectionwithaJMSprovider.It encapsulatesthesetofconfigurationparametersthataJMSadministratordefinesfora connection. Thetypeofconnectionfactorydetermineswhetheraconnectionismadetoatopic(ina publishsubscribeapplication),aqueue(inapointtopointapplication),orcanbemade toboth(genericconnection),andwhethermessagesaremanagedlikeelementsina distributedtransactionintheclientapplication. YouuseXAbasedconnectionfactoriesinJMSapplicationsmanagedbyaJ2EE applicationserver,inthecontextofadistributedtransaction. Destinations Destinationsaretheobjectsthataclientusestospecifythetargetofmessagesitproduces andthesourceofmessagesitconsumes.Theseobjectsspecifytheidentityofadestination toaJMSAPImethod.Therearefourtypesofdestinations;onlythefirsttwo(queuesand topics)areadministeredobjects: Queue.Aqueueobjectcoversaproviderspecificqueuename,andishowaclient specifiestheidentityofaqueuetoJMSmethods. Topic.Atopicobjectcoversaproviderspecifictopicname,andishowaclient specifiestheidentityofatopictoJMSmethods. TemporaryQueue.Aqueueobjectcreatedforthedurationofaparticularconnection(or QueueConnection).Itcanonlybeconsumedbytheconnectionfromwhichitwas created. TemporaryTopic.Atopicobjectthatiscreatedforthedurationofaparticular connection(orTopicConnection).Itcanonlybeconsumedbytheconnectionfrom whichitwascreated.
25
2. JMS Basics
Connections
AconnectionobjectisanactiveconnectionfromaclienttoitsJMSprovider.InJMS, connectionssupportconcurrentuse.Aconnectionservesthefollowingpurposes: AconnectionencapsulatesanopenconnectionwithaJMSprovider.Ittypically representsanopenTCP/IPsocketbetweenaclientandtheserviceprovidersoftware. Thecreationofaconnectionobjectisthepointwhereclientauthenticationtakesplace. Aconnectionobjectcanspecifyauniqueclientidentifier. AconnectionobjectsupportsausersuppliedExceptionListenerobject. Aconnectionshouldalwaysbeclosedonceitsuseisnolongerrequired.
Sessions
Asessionobjectisasinglethreadedcontextforproducingandconsumingmessages.Ifa clientusesdifferentthreadsfordifferentpathsofmessageexecution,thenasessionmust becreatedforeachofthethreads. Asessionisusedtocreatemessageproducers,messageconsumers,temporarytopics,and temporaryqueues;italsosuppliesprovideroptimizedmessagefactories. InJMS,asessionprovidesthecontextforgroupingasetofsendandreceivemessagesinto atransactionalunit.
Message Producer
Amessageproducerisanobjectthatasessioncreatestosendmessagestoadestination(a topicoraqueue).
Message Consumer
Amessageconsumerisanobjectthatasessioncreatestoreceivemessagessenttoa destination.Amessageconsumerallowsaclienttoregisterinterestinadestination, whichmanagesthedeliveryofmessagestotheregisteredconsumersofthatdestination.
Message Selector
Aclientmaywanttoreceivesubsetsofmessages.Amessageselectorallowsaclienttofilter themessagesitwantstoreceivebyuseofaSQL92stringexpressioninthemessage header.Thatexpressionisappliedtopropertiesinthemessageheader(nottothemessage bodycontent)containingthevaluetobefiltered. IftheSQLexpressionevaluatestotrue,themessageissenttotheclient;iftheSQL expressionevaluatestofalse,itdoesnotsendthemessage.
26
2. JMS Basics
Messages
Messagesareobjectsthatcommunicateinformationbetweenclientapplications.Following aredescriptionsofseveralkeyconceptsrelatedtoJMSmessages.
Message Structure
Messagesarecomposedofthefollowingparts: Header.Allmessagessupportthesamesetofheaderfields.Headerfieldscontain predefinedvaluesthatallowclientsandproviderstoidentifyandroutemessages. Eachofthefieldssupportsitsownsetandgetmethodsformanagingdata;some fieldsaresetautomaticallybythesendandpublishmethods,whereasothersmust besetbytheclient. Examplesofheaderfieldsinclude:
JMSDestination,whichholdsadestinationobjectrepresentingthe
destinationtowhichthemessageistobesent.
JMSMessageID,whichholdsauniquemessageidentifiervalueandisset
automatically.
JMSCorrelationID,whichisusedtolinkareplymessagewithitsrequesting
message.Thisvalueissetbytheclientapplication.
JMSReplyTo,whichissetbytheclientandtakesasavalueaDestinationobject
representingwherethereplyisbeingsent.Ifnoreplyisbeingsent,thisfieldisset tonull. SeethedescriptionoftheMessageinterfaceintheJavaMessageService,Version1.1 specificationforinformationaboutthecompletesetofmessageheaderfieldsandthe methodsforsettingandgettingtheirdata. Properties (optional).Propertiesareusedtoaddoptionalfieldstothemessageheader. Thereareseveraltypesofmessagepropertyfields. Applicationspecificpropertiesaretypicallyusedtoholdmessageselectorvalues. Messageselectorsareusedtofilterandroutemessages. Standardproperties.TheAPIprovidessomepredefinedpropertynamesthata providermaysupport.SupportfortheJMSXGroupIDandJMSXGroupSeqis required;however,supportforallotherstandardpropertiesisoptional. Providerspecificpropertiesareuniquetothemessagingproviderandtypicallyrefer tointernalvalues. Body (optional).JMSdefinesvarioustypesofmessagebodyformatsthatarecompatible withmostmessagingstyles.Eachformisdefinedbyamessageinterface:
StreamMessage.AmessagewhosebodycontainsastreamofJavaprimitive values.Itisfilledandreadsequentially.
27
2. JMS Basics
MapMessage.Amessagewhosebodycontainsasetofnamevaluepairswhere namesareStringsandvaluesareJavaprimitivetypes.Theentriescanbeaccessed sequentiallybyenumeratororrandomlybyname.Theorderoftheentriesis undefined. TextMessage.Amessagewhosebodycontainsajava.lang.String. ObjectMessage.AmessagethatcontainsaSerializableJavaobject. BytesMessage.Amessagethatcontainsastreamofuninterpretedbytes.This messagetypeisforliterallyencodingabodytomatchanexistingmessage format.Inmanycases,itwillbepossibletouseoneoftheother,selfdefining, messagetypesinstead.
BothStreamMessageandMapMessagesupportthesamesetofprimitivedatatypes. Conversionsfromonedatatypetoanotherarepossible.
Message Acknowledgment
Amessageisnotconsideredtobesuccessfullyconsumeduntilitisacknowledged. Dependingonthesessionacknowledgmentmode,themessagingprovidermaysenda messagemorethanoncetothesamedestination.Thereareseveralmessage acknowledgmentconstants: Value
AUTO_ACKNOWLEDGE
Description Automaticallyacknowledgesthesuccessfulreceiptofa message. Acknowledgesthereceiptofamessagewhentheclient callsthemessagesacknowledge()method. Instructsthesessiontoautomatically,lazily acknowledgethereceiptofmessages,whichreduces systemoverheadbutmayresultinduplicatemessages beingsent.
CLIENT_ACKNOWLEDGE
DUPS_OK_ACKNOWLEDGE
28
Chapter 3. Sending and Receiving JMS Messages
The JMS Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Sending a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Sending a JMS Message and Waiting for a Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Replying to a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Receiving a JMS Message Using Built-In Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Sending a JMS Message as Part of a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Setting Properties in a JMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
29
3. Sending and Receiving JMS Messages
The JMS Services

UsingthefollowingJMSservices,youcancreateservicesthatsendand/orreceiveJMS messages.TheJMSservicesarelocatedintheWmPublicpackage. Service pub.jms:acknowledge pub.jms:createConsumer pub.jms:receive pub.jms:reply pub.jms:send pub.jms:sendAndWait pub.jms:waitForReply Description SendsanacknowledgmentforamessagetotheJMSprovider. Createsamessageconsumertoreceivemessagesfrom destinationsontheJMSprovider. Synchronouslyreceivesamessagefromaqueueortopicon theJMSprovider. Sendsareplymessagetoarequestingclient. SendsaJMSmessagetotheJMSprovider. SendsarequestintheformofaJMSmessagetotheJMS providerandoptionally,waitsforareply. Retrievesthereplymessageforanasynchronousrequest.
Sending a JMS Message

WhenyoubuildaservicethatsendsaJMSmessage,youspecifyhowIntegrationServer connectstotheJMSprovider,themessagedestination,andwhetherornotaclientside queueshouldbeused.
How to Send a JMS Message

ThefollowingdescribesthegeneralstepsyoutaketosendaJMSmessagetoaJMS provider. 1 2 Create an empty flow service. Create the message body. Howyoubuildthemessagebodydependsontheformatthatyouwanttouseforthe message.Forexample,ifyouwanttouseaStringasthemessagebody,createafield oftypeStringandthenaddcontenttotheStringfield.IfyouwanttouseaDocument (IData)asthemessagebody,createadocumentandthenaddcontenttothe document.NotethataDocument(IData)shouldonlybeusedwhensendingaJMS messagefromoneIntegrationServertoanother Ifyouwantmorecontrolovertheactualjavax.jms.MessagethatIntegrationServer sendstotheJMSprovider,youcancreateaJavaservicethatcallsthe
30
com.wm.app.b2b.server.jms.producer.ProducerFacadeclass,whichwillcreatea javax.jms.Message.See: com.wm.app.b2b.server.jms.producer.ProducerFacade.createBytesMessage(String) com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String) com.wm.app.b2b.server.jms.producer.ProducerFacade.createObjectMessage(String)

com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String)
com.wm.app.b2b.server.jms.producer.ProducerFacade.createTextMessage(String) TheJavaservicecallingthisAPImustreturnanObjectoftypejavax.jms.Message, whichcanthenbemappedtotheJMSMessage/body/messageinputparameterofthe pub.jms:sendservice. Whencreatingthejavax.jms.Messagewiththe com.wm.app.b2b.server.jms.producer.ProducerFacade,youcanusethe javax.jms.Messagesettermethodstosetthevaluesofthemessageheadersand propertiesdirectly.Youcanalsosetthevalueofmessageheadersandproperties usingtheinputparametersofthepub.jms* servicethatyouusetosendthemessage.If yousetthemessageheadersandpropertiesbothways,thevaluesprovidedtothe pub.jms* servicetakeprecedence. Software AGrecommendsthatyouuseapub.jms*servicetocreateandsendtheJMS message.Thismayprovidebetterperformanceonaverage.However,ifyouwantto sendaStreamMessageoraMapMessage,youneedtousetheappropriate com.wm.app.b2b.server.jms.producer.ProducerFacadeAPI. 3 Invoke pub.jms:send.ThisservicecreatesaJMSmessage(javax.jms.Message)basedon inputprovidedtotheserviceortakesanexistingJMSmessageandsendsittotheJMS provider. Specify the JMS connection alias.TheJMSconnectionaliasindicateshowIntegration ServerconnectstotheJMSprovider. Name connectionAliasName Description NameoftheJMSconnectionaliasthatyouwanttouseto sendthemessage.
Specify the destination to which you want to send the message. IftheJMSconnectionaliasyouspecifiedinstep4usesthenativewebMethodsAPIto createtheconnectiondirectlyonthewebMethodsJMSProvider,youneedtospecify thedestinationNameaswellasthedestinationType
31
Name destinationName
Description NameorlookupnameoftheDestinationtowhichyouwantto sendthemessage. SpecifythelookupnameoftheDestinationobjectwhen theJMSconnectionaliasusesJNDItoretrieve administeredobjects. SpecifytheproviderspecificnameoftheDestination whentheJMSconnectionaliasusesthenative webMethodsAPItoconnectdirectlytothewebMethods JMSProvider.
destinationType
SpecifieswhethertheDestinationisaqueueoratopic.The defaultisqueue.
Set values for the header fields in the JMS message.Alloftheheaderfieldsareoptional. Name deliveryMode Description Specifiesthemessagedeliverymodeforthemessage.Specify oneofthefollowing:
PERSISTENT providesonceandonlyoncedeliveryforthe message.ThemessagewillnotbelostifaJMSprovider failureoccurs. NON_PERSISTENT providesatmostoncedeliveryforthe message.Themessagehasnoguaranteeofbeingsavedifa JMSproviderfailureoccurs.
ThedefaultisPERSISTENT priority Specifiesthemessagepriority.JMSdefinesprioritylevelsfrom 0to9,with0asthelowestpriorityand9asthehighest. Thedefaultis4. timeToLive Specifiesthelengthoftime,inmilliseconds,thattheJMS providerretainsthemessage. Thedefaultis0,meaningthatthemessagedoesnotexpire. JMSType Messagetypeidentifierforthemessage.
Ifyoucreatedajavax.jms.Messageandyousetthemessageheaderfieldsusingthe javax.jms.Messagesettermethods,youdonotneedtoprovideinputstothefieldsin JMSMessage/header.Ifyoudosetmessageheaderfieldsusingbothapproaches, IntegrationServerusesthevaluesprovidedasinputtothepub.jms:sendservice.
32
Set values for the Integration Server-specific properties. Thepropertiesfieldsareoptional fieldsaddedtothemessageheaderandareoftenusedtoholdmessageselector values.IntegrationServeraddsthefollowingpropertiestoJMSmessagesitsends. Youcansetthesevaluesasfollows. Name activation Description SpecifiestheactivationIDforthemessage.AJMStriggeruses theactivationIDtojointogethermessagesitreceives.For moreinformationaboutsettingtheactivation,seeAssigning anActivationtoaJMSMessageonpage 46. Specifiesauniversallyuniqueidentifierforamessage.For moreinformationaboutsettingaUUID,seeSettingthe UUIDonpage 47.
uuid
Ifyoucreatedajavax.jms.Messageandyousetthemessagepropertyfieldsusingthe javax.jms.Messagesettermethods,youdonotneedtoprovideinputstothefieldsin JMSMessage/properties.Ifyoudosetmessagepropertyfieldsusingbothapproaches, IntegrationServerusesthevaluesprovidedasinputtothepub.jms:sendservice. 8 Add any custom properties to the JMS message. ToaddanewpropertytoJMSMessage/properties,click onthePipelinetab. Selectadatatypeforthepropertyandassignitaname.Makesuretoplacethenew propertyintheJMSMessage/propertiesfield. Assignavaluetoanycustompropertiesthatyouadd. 9 Map data to the body of the JMSMessage document. Specifically,mapthefieldthatcontains thedatayouwanttoincludedinthemessagebodytothefieldinJMSMessage/body withtheappropriatedatatype. Map to this field... string bytes object data If you... UsedafieldoftypeStringforthemessagebodycontent Usedaonedimensionalbytearrayforthemessagebody content. UsedaSerializableJavaobjectforthemessagebodycontent. UsedaDocument(IData)fortheJMSmessagebodycontent. KeepinmindthattheIDatamessageformatcanonlybeused whensendingaJMSmessagefromoneIntegrationServerto another. UsedaJavaservicetocreateanobjectoftype javax.jms.Message.
message
33
10 Specify client side queueing. Whenclientsidequeueingisenabled,IntegrationServer placesmessagesintheclientsidequeueiftheJMSproviderisnotavailableatthetime thepub.jms:send serviceexecutes. Name useCSQ Description IndicateswhetherIntegrationServerplacesthesentmessage intheclientsidequeueiftheJMSproviderisnotavailableat thetimethemessageissent
TruespecifiesthatIntegrationServerwritesmessagesto theclientsidequeueiftheJMSproviderisnotavailableat thetimethisserviceexecutes.WhentheJMSprovider becomesavailable,IntegrationServersendsmessages fromtheclientsidequeuetotheJMSprovider. FalseindicatesthatIntegrationServerthrowsan
ISRuntimeExceptioniftheJMSproviderisnotavailableat thetimethisserviceexecutes ThedefaultisTrue.
Sending a JMS Message and Waiting for a Reply

IntegrationServerprovidesthepub.jms:sendAndWaitservice,whichyoucanusetosenda messageandwaitforareply. Youcanusethepub.jms:sendAndWaitservicetoissuearequest/replyinasynchronousor asynchronousmanner. Inasynchronousrequest/reply,theservicethatsendstherequeststopsexecuting whileitwaitsforareply.Whentheservicereceivesareplymessage,theservice resumesexecution.Ifthetimeoutelapsesbeforetheservicereceivesareply, IntegrationServerendstherequest,andtheservicereturnsanullmessagethat indicatesthattherequesttimedout.IntegrationServerthenexecutesthenextstepin theflowservice. Inanasynchronousrequest/reply,theservicethatsendstherequestcontinues executingthestepsintheserviceaftersendingthemessage.Toretrievethereply,the requestingflowservicemustinvokethepub.jms:waitForReplyservice.Ifthetimeout elapsesbeforethepub.jms:waitForReplyservicereceivesareply,thepub.jms:waitForReply servicereturnsanulldocumentindicatingthattherequesttimedout. Aservicethatcontainsmultipleasynchronoussendandwaitinvocationsallowsthe servicetosendalltherequestsbeforecollectingthereplies.Thisapproachcanbemore efficientthansendingarequest,waitingforareply,andthensendingthenextrequest.
34
How to Send a Request Message and Wait for a Reply

Thefollowingdescribesthegeneralstepsyoutaketobuildaservicethatsendsarequest messageandthenwaitsforareply. 1 2 3 Create an empty flow service. Create the message body.Formoreinformationaboutcreatingcontentforthebodyofa JMSmessage,seestep 2inthesectionHowtoSendaJMSMessageonpage 30. Invoke pub.jms:sendAndWait.ThisservicecreatesaJMSmessage(javax.jms.Message) basedoninputprovidedtotheserviceortakesanexistingJMSmessageandsendsit totheJMSprovider. Specify the JMS connection alias.TheJMSconnectionaliasindicateshowIntegration ServerconnectstotheJMSprovider. Name connectionAliasName Description NameoftheJMSconnectionaliasthatyouwanttouseto sendthemessage.
Specify the destination to which you want to send the message. IftheJMSconnectionaliasyouspecifiedinstep 4usesthenativewebMethodsAPIto createtheconnectiondirectlyonthewebMethodsJMSProvider,youneedtospecify thedestinationNameaswellasthedestinationType. Name destinationName Description NameorlookupnameoftheDestinationtowhichyouwantto sendthemessage. SpecifythelookupnameoftheDestinationobjectwhen theJMSconnectionaliasusesJNDItoretrieve administeredobjects. SpecifytheproviderspecificnameoftheDestination whentheJMSconnectionaliasusesthenative webMethodsAPItoconnectdirectlytothewebMethods JMSProvider. destinationType SpecifieswhethertheDestinationisaqueueoratopic.The defaultisqueue.
Specify the destination to which message recipients should send the reply message. (Optional) Ifyoudonotspecifyadestinationforreplymessages,IntegrationServerusesa temporaryQueuetoreceivethereply.AtemporaryQueueisaqueueobjectcreatedfor thedurationofaparticularconnection.
35
IftheJMSconnectionaliasyouspecifiedinstep 4usesthenativewebMethodsAPIto createtheconnectiondirectlyonthewebMethodsJMSProvider,youneedtospecify thedestinationNameReplyToaswellasthedestinationTypeReplyTo. Name destinationNameReplyTo Description NameorlookupnameoftheDestinationtowhichyou wantthereplymessagesent. SpecifythelookupnameoftheDestinationobject whentheJMSconnectionaliasusesJNDItoretrieve administeredobjects. Specifytheproviderspecificnameofthe DestinationwhentheJMSconnectionaliasusesthe nativewebMethodsAPItoconnectdirectlytothe webMethodsJMSProvider. destinationTypeReplyTo SpecifieswhethertheDestinationisaqueueoratopic. Thedefaultisqueue.
Set the request timeout. ThetimeoutindicateshowlongIntegrationServerwaitsfora replymessage.Thetimeoutparameteronlyappliestosynchronoussendandwait requests. Name timeout Description Timetowait(inmilliseconds)fortheresponsetoarrive.If novalueisspecified,theservicedoesnotwaitatall.
8 9
Populate the JMS message. TopopulatetheJMSmessageheader,properties,andbody, followsteps59inthesectionHowtoSendaJMSMessageonpage 30. Determine whether the request is synchronous or asynchronous. Thepub.jms:sendAndWait providesaparameterthatyoucansettoindicatewhethertherequestissynchronous orasynchronous.Bydefault,therequestissynchronous.
36
Name async
Description Flagspecifyingwhetherthisisanasynchronousor synchronousrequest/reply.

Trueindicatesthatthisisanasynchronous request/reply.Aftersendingthemessage, IntegrationServerexecutesthenextstepintheflow serviceimmediately.TheIntegrationServerdoes notwaitforareplybeforecontinuingservice execution. Falseindicatesthatthisisasynchronous
request/reply.Aftersendingthemessage, IntegrationServerwaitsforareplybeforeexecuting thenextstepintheflowservice. ThedefaultisFalse. 10 Specify client side queueing. Whenclientsidequeueingisenabled,IntegrationServer placesmessagesintheclientsidequeueiftheJMSproviderisnotavailableatthetime thepub.jms:send serviceexecutes. Clientsidequeueingcanbeusedwithasynchronousrequestsonly. Name useCSQ Description IndicateswhetherIntegrationServerplacesthesentmessage intheclientsidequeueiftheJMSproviderisnotavailableat thetimethemessageissent
TruespecifiesthatIntegrationServerwritesmessagesto theclientsidequeueiftheJMSproviderisnotavailableat thetimethisserviceexecutes.WhentheJMSprovider becomesavailable,IntegrationServersendsmessages fromtheclientsidequeuetotheJMSprovider. FalseindicatesthatIntegrationServerthrowsan
ISRuntimeExceptioniftheJMSproviderisnotavailableat thetimethisserviceexecutes ThedefaultisTrue. 11 Invoke pub.jms:waitForReply.Ifyouconfiguredpub.jms:sendAndWaitasanasynchronous request/reply,youneedtoinvokethepub.jms:waitForReplyservicetoretrievethereply message.
37
Specifythefollowinginputvaluesforthepub.jms:waitForReplyservice. Name correlationID Description Auniqueidentifierusedtoassociatethereplymessagewith theinitialrequest.IntegrationServerusesthevalueoftheuuid orJMSMessageIDfieldsintherequestingJMSmessageto correlatetheresponsetotherequest IfyousettheuuidintheJMSmessagerequest,youcan linkthevalueoftheuuidfieldfromtheJMSMessage producedbypub.jms:sendAndWaittothecorrelationID. Ifyoudidnotspecifyauuid,youcanlinkthe JMSMessageIDfieldfromtheJMSMessageproducedby pub.jms:sendAndWaittothecorrelationID. timeout Optional.Timetowait(inmilliseconds)forthereplytoarrive. Ifnovalueisspecified,theservicedoesnotwaitforareply.
12 Process the reply message.Thepub.jms:sendAndWait(orpub.jms:waitForReply)service producestheoutputparameterJMSReplyMessage,whichcontainstheJMSmessage receivedasareply. IfIntegrationServerdoesnotreceiveareplybeforethespecifiedtimeoutvalue elapses,theJMSReplyMessageisnull.Besuretocodeyourservicetohandlethis situation.
Replying to a JMS Message

Youcancreateaservicethatsendsareplymessageinresponsetoareceivedrequest message.Thereplymessagemightbeasimpleacknowledgementormightcontain informationrequestedbythesender. Whenyousendareplymessage,IntegrationServerusesinformationintherequest messagetodeterminethereplydestination.TheJMSReplyTofieldintherequestmessage issetbythesendingclientandindicatesthedestinationtowhichthereplywillbesent. ThereplyingIntegrationServerautomaticallysetsthisvaluewhenitexecutesthe pub.jms:replyservice. Whenreplyingtoamessage,IntegrationServeralsoautomaticallysetsthe JMSCorrelationIDinthereplymessage.IntegrationServer,andmanyJMSclients,usethe JMSCorrelationIDtocorrelatethereplymessagewiththerequestmessage.Integration ServerusesthevalueofeithertheuuidorJMSMessageIDfieldsintherequestingJMS messagetocorrelatetherequestandtheresponse. Ifthesenderoftherequestmessagespecifiedtheuuid,thereplyingIntegrationServer willusetheuuidastheJMSCorrelationIDofthereplymessage.
38
Ifthesenderoftherequestmessagedidnotspecifyauuid,thereplyingIntegration ServerusestheJMSMessageIDfromtherequestmessageastheJMSCorrelationIDof thereplymessage.
How to Send a Reply Message

Thefollowingdescribesthegeneralstepsyoutaketobuildaservicethatsendsareply message. 1 Open or create the service that will send the reply.IfaJMStriggerreceivedthemessage, thismightbethetriggerserviceoraserviceinvokedbythetriggerservice.Ifyouused thepub.jms:receiveservicetoretrievethemessagefromtheJMSprovider,youmight replytothemessagewithinthesameserviceorinanotherserviceinvokedbythe sametoplevelservice. Invoke pub.jms:reply.Thisservicetakesthereplymessageyoucreatedanddeliversitto thedestinationspecifiedintheJMSReplyTofieldintheheaderoftherequestmessage. Populate the JMS message. IfaJMStriggerreceivedthemessage,populatetheJMS messageheader,properties,andbody,followsteps59inthesectionHowtoSenda JMSMessageonpage 30. Specify the consumer and message. Ifyoureceivedthemessageusingthepub.jms:receive service,youmustspecifythemessageconsumerusedtoreceivethemessageandthe requestmessage.YoudonotneedtospecifythisinformationifaJMStriggerreceived themessage. Name consumer Description Themessageconsumerobjectusedtoreceivetherequest messagefromtheJMSprovider.IntegrationServeruses informationfromtheconsumertocreateamessageproducer thatwillsendthereplymessage. Ajavax.jms.Messageobjectthatcontainstherequestmessage. YoucanmaptheJMSMessage/body/messagefieldintherequest messagetothepub.jms:replymessageinputparameter.The pub.jms:reply serviceusestherequestmessagetodeterminethe replyTodestination.
2 3
message
Receiving a JMS Message Using Built-In Services

Attimes,youmightnotwanttowaitforaJMStriggertoexecutetoreceiveamessage. Instead,youmightwanttoreceiveamessagefromtheJMSproviderondemand. ReceivingamessageondemandprovidesmorecontroloverwhenandhowIntegration Serverreceivesamessage;however,itmaynotbeasefficientorpracticalasusingaJMS
39
triggertolistenforandthenreceivethemessage.Youcanusethepub.jms:receiveservice toretrievemessagesondemandfromtheJMSprovider. Tolistenformessagesandreceivethemwhentheyareavailable,createaJMStriggerthat listenstothedestination.FormoreinformationaboutcreatingaJMStrigger,see Chapter 4,WorkingwithJMSTriggers
How to Actively Receive a JMS Message

Thefollowingdescribesthegeneralstepsyoutaketobuildaservicethatreceivesa messagefromtheJMSprovider. 1 2 Create a new service. Invoke pub.jms:createConsumer.Thisservicecreatesamessageconsumerthatreceives messagessenttoaparticulardestination. Usethefollowingstepstocreatethemessageconsumer. a Specify the JMS connection alias.TheJMSconnectionaliasindicateshowIntegration ServerconnectstotheJMSprovider. Name connectionAliasName Description NameoftheJMSconnectionaliasthatyouwanttouse toreceivethemessage.
Specify the destination from which you want to receive the message.Specifythe messagesthatyouwanttheconsumertoreceivebyselectingadestinationandby creatingamessageselector.Amessageselectorisanfilterthatisevaluatedbythe JMSprovider.Ifamessagedoesnotmeetthecriteriaspecifiedinthefilter,the consumerdoesnotreceivethemessage.Useamessageselectorreceiveasubsetof messagesfromadestination.
40
Name destinationName
Description NameorlookupnameoftheDestinationfromwhich youwanttoreceivethemessage. SpecifythelookupnameoftheDestinationobject whentheJMSconnectionaliasusesJNDIto retrieveadministeredobjects. Specifytheproviderspecificnameofthe DestinationwhentheJMSconnectionaliasuses thenativewebMethodsAPItoconnectdirectlyto thewebMethodsJMSProvider.
destinationType
SpecifieswhethertheDestinationisaqueueoratopic. Thedefaultisqueue. IftheJMSconnectionaliasyouspecifiedinstep2a usesthenativewebMethodsAPItocreatethe connectiondirectlyonthewebMethodsJMSProvider, youneedtospecifythedestinationNameaswellasthe destinationType.
messageSelector
OptionalSpecifiesafilterusedtoreceiveasubsetof messagesfromthespecifieddestination. Themessageselectormustusethemessageselector syntaxspecifiedintheJavaMessageService SpecificationVersion1.1 Formoreinformationaboutmessageselectors,see CreatingaMessageSelectoronpage 56.
durableSubscriberName
Optional.Nameofthedurablesubscriberthatyou wantthisservicetocreate/useontheJMSprovider.A durablesubscribercreatesadurablesubscriptionon theJMSprovider.Ifadurablesubscriberofthisname alreadyexistsontheJMSprovider,thisservice resumesthepreviouslyestablishedsubscription. Note: Thisparameteronlyapplieswhenthe destinationTypeissettoTOPIC.IfyouselectTOPIC,but donotspecifyadurableSubscriberName,thisservice createsanondurablesubscriber.IfdestinationTypeisset toQUEUE,thisparameterisignored.
Determine the acknowledgment mode. AcknowledgmentmodeindicateshowIntegration Serveracknowledgesmessagesreceivedbyamessageconsumer.
41
Usethefollowingparametertospecifytheacknowledgmentmode. Name acknowledgmentMode Description

AUTO_ACKNOWLEDGE Automaticallyacknowledge
themessagewhenitisreceivedbythemessage consumer.Themessageconsumerwill acknowledgethemessagebeforethemessage processingcompletes.TheJMSprovidercannot redeliverthemessageifIntegrationServer becomesunavailablebeforemessageprocessing completes.

CLIENT_ACKNOWLEDGE Acknowledgethereceiptof amessagewhentheJMSclient(IntegrationServer) invokespub.jms:acknowledgeservice. DUPS_OK_ACKNOWLEDGE Automatically,lazily
acknowledgethereceiptofmessages,which reducessystemoverheadbutmayresultin duplicatemessagesbeingsent. ThedefaultisAUTO_ACKNOWLEDGE. d Indicate whether locally published messages are ignored.IfyouspecifiedTOPICasthe destinationType,youcanconfigureaconsumertoignoremessagespublishedusing thesameJMSconnectionaliasusedbytheconsumer. IntegrationServerconsidersamessagetobelocalifitis: SentbythesameIntegrationServer,and SentusingthesameJMSconnectionalias. Name noLocal Description Indicateswhethertheconsumerignoreslocally publishedmessages:
True indicatestheconsumerwillnotreceive
locallypublishedmessages.
False indicatestheconsumercanreceivelocally publishedmessages
ThedefaultisFalse. 3 Invoke pub.jms:receive. Thisserviceusestheconsumercreatedbythe pub.jms:createConsumerservicetoreceivemessagesfromthespecifieddestination.
42
InthePipelinetab,makesuretheconsumercreatedbythepub.jms:createConsumer serviceislinkedtothe pub.jms:receiveserviceinputparameterconsumer.Developer shouldlinktheseautomatically. SpecifyhowlongtheconsumershouldwaittoreceiveamessagefromtheJMS provider. Name timeout Description Specifiesthetimetowait,inmilliseconds,foramessagetobe receivedfromtheJMSprovider. Ifyouspecify0(zero),theconsumerwillnotwait. Thedefaultis0(zero). 4 Process the received JMS message.Invokeaserviceorasequenceofservicestoprocess themessagereceivedfromtheJMSprovider.InthePipelinetab,linktheJMSMessage returnedbypub.jms:receivetotheinputfortheservicethatprocessesthemessage. Ifthetimeoutperiodelapsesbeforeamessageisreceived,thevalueofJMSMessageis null.Makesuretocodeyourservicetohandlethissituation. 5 Invoke pub.jms:acknowledge. Iftheacknowledgmentmodeoftheconsumerthatreceived themessageissettoCLIENT_ACKNOWLEDGEusethepub.jms:acknowledgeserviceto acknowledgethemessagetotheJMSprovider.Amessageisnotconsideredtobe successfullyconsumeduntilitisacknowledged. Providethefollowinginputparameter. Name message Description Ajavax.jms.Messageobjectthatidentifiesthemessagefor whichyouwantIntegrationServertosendan acknowledgementtotheJMSprovider. YoucanmapthevalueoftheJMSMessage/body/messagefieldin theJMSmessageretrievedbythe pub.jms:receive servicetothis field. Ifyouusetheconsumercreatedbythepub.jms:createConsumerservicetoreceivemultiple messages,keepinmindthatacknowledgingamessageautomaticallyacknowledges thereceiptofallmessagesreceivedinthesamesession.Thatis,allmessagesreceived bythesameconsumerwillbeacknowledgedwhenjustoneofthereceivedmessagesis acknowledged.Therefore,iftheconsumerreceivesmultiplemessages,invokethe pub.jms:acknowledgeserviceafterprocessingallofthereceivedmessages. Anymessageconsumerscreatedduringtheexecutionofaservicewillbeclosed automaticallywhentheservicecompletes.Iftheconsumercloseswithout
43
acknowledgingmessages,messagesareimplicitlyrecoveredbacktotheJMS provider.
Sending a JMS Message as Part of a Transaction

Atransactionisalogicalunitofwork,composedofmanydifferentprocessesand involvingoneormoreresources,thateitherentirelysucceedsorhasnoeffectatall. Transactionscaneitherbeimplicitorexplicit. Inanimplicittransaction,thetransactionmanagerinIntegrationServerautomatically managesthetransactionswithoutrequiringanyadditionalservicesorinput.Inanexplicit transaction,youcontrolthetransactionalunitsofworkbydefiningthestartand completionboundariesofthetransaction.TheWmARTpackageonIntegrationServer providesbuiltinservicesthatyoucanusetostartandcompletetransactions. Insomesituations,youmightusethebuiltinservicepub.art.transaction:startTransactiontostart atransactionexplicitly,butthenallowIntegrationServertocommitorrollbackthe transactionimplicitlybasedonthesuccessorfailureoftheservice. Formoreinformationabouttransactions,seeAppendix C,TransactionManagement. YoucancreateaservicethatsendsorreceivesJMSmessageswithinanexplicit transaction.Theservicemustdothefollowing: Usepub.art.transaction:startTransactiontostartthetransaction. CreateaconnectiontotheJMSproviderusingaJMSconnectionaliaswitha transactiontypeofLOCAL_TRANSACTIONorXA_TRANSACTION,dependingon thekindoftransaction. Usepub.art.transaction:commitTransactiontocommitthetransaction. Usepub.art.transaction:rollbackTransactiontorollbackthetransaction. KeepthefollowingpointsinmindwhenbuildingservicesthatsendorreceiveJMS messageswithinatransaction: TosendorreceiveJMSmessageswithinatransaction,youmustinstallandenablethe WmARTpackage.(ThisistrueevenifyouintendtouseIntegrationServertomanage alltransactionsimplicitly.) Tousepub.jms:send orpub.jms:sendAndWaitwithinatransaction,clientsidequeuing cannotbeused(theuseCSQparametermustbesettofalse). Tousepub.jms:sendAndWaitwithinatransaction,therequest/replymustbe asynchronous(theasyncparametermustbesettotrue).Ifasyncissettofalse, IntegrationServerthrowsaJMSSubsystemExceptionwhentheserviceexecutes. Ifyoudonotspecificallyinvokepub.art.transaction:commitTransactionor pub.art.transaction:rollbakTransaction,IntegrationServerimplicitlycommitsthetransaction whentheserviceswithinthetransactionaresuccessful.IntegrationServerimplicitly
44
rollsbackthetransactionwhenoneoftheserviceswithinthetransactionfailswith anytypeofexception.
How to Send a JMS Message within a Transaction

ThefollowingdescribesthegeneralstepsyoutaketosendaJMSmessagetoaJMS provideraspartofatransaction(XAorLocal). 1 2 3 Create an empty flow service. Create the message body.Formoreinformationaboutcreatingcontentforthebodyofa JMSmessage,seestep 2inthesectionHowtoSendaJMSMessageonpage 30. Invoke pub.art.transaction:startTransaction. Thisservicestartsanexplicittransaction.This serviceislocatedintheWmARTpackage. InthestartTransactionInputdocumentlist,youcanprovidethefollowingoptional parameter: Name transactionName Description AStringthatspecifiesthenameofthetransactiontobe started.IfthisfieldisblankIntegrationServerwillgeneratea nameforyou.
Ifyoudonotusepub.art.transaction:startTransactiontostartanexplicittransaction, IntegrationServerstartsanimplicittransactionwhenitexecutesapub.jms:sendservice thatspeechifiesatransactedJMSconnectionalias. 4 5 Invoke pub.jms:send.ThisservicetakestheJMSmessageyoucreatedandsendsittothe JMSprovider. Specify the JMS connection alias.TheJMSconnectionaliasindicateshowIntegration ServerconnectstotheJMSprovider. Name connectionAliasName Description NameoftheJMSconnectionaliasthatyouwanttouseto sendthemessage. ThespecifiedJMSconnectionaliasmusthaveatransaction typeofLOCAL_TRANSACTIONor XA_TRANSACTION,dependingonthekindof transaction. 6 Finish supplying inputs to the pub.jms:send service.Followsteps59underHowtoSenda JMSMessageonpage 30.
45
7 8
Add any additional services to the transaction. Forexample,youmightwanttoinvoke anotherbuiltinJMSserviceoranadapterservice. Insert logic to commit and/or rollback the transaction explicitly. Youmaybuildyourservice tocommitthetransactionifallservicesexecutesuccessfullyandtorollbackthe transactionifallservicesdonotexecutesuccessfully. Invokepub.art.transaction:commitTransactiontocommitthetransactionandsendthe JMSmessage.OnthePipelinetab,mapthecontentsof startTransactionOutput/transactionNametocommitTransactionInput/transactionName. Invokepub.art.transaction:rollbakTransactiontorollbackthetransaction.Themessage willnotbesenttotheJMSprovider.OnthePipelinetab,mapthecontentsof startTransactionOutput/transactionNametorollbackTransactionInput/transactionName. Ifyoudonotspecificallyinvokepub.art.transaction:commitTransactionor pub.art.transaction:rollbakTransaction,IntegrationServerimplicitlycommitsthetransaction whentheserviceswithinthetransactionaresuccessful.IntegrationServerimplicitly rollsbackthetransactionwhenoneoftheserviceswithinthetransactionfailswith anytypeofexception.
Setting Properties in a JMS Message

PropertiesareanoptionalpartofaJMSmessagethatenableyoutoaddfieldstothe messageheader.Propertiesusuallyholdmessageselectorvaluesandareapplication specific,standard,orproviderspecific. WhenbuildingaservicethatsendsaJMSmessage,youcan: AddyourowncustompropertiestotheJMSMessage/propertiesdocumentusingthe pipelineinDeveloper. Assignvaluestotheapplicationspecificpropertiesactivationanduuidincludedby IntegrationServer. Thefollowingsectionsprovideinformationaboutsettingtheactivationanduuid.For informationaboutaddingfieldstothepipelineinDeveloper,seethewebMethodsDeveloper UsersGuide.
Assigning an Activation to a JMS Message

AnactivationisauniqueidentifierassignedtoamessagethatwillbeprocessedbyaJMS triggerthatcontainsajoin.AjoinspecifiesthataJMStriggerhandlesmessagesreceived fromtwoormoredestinationsasasingleunitandwithasingleroutingrule.TheJMS triggerneedstoreceivemessagesfromall,onlyone,oranyofthedestinationsbeforeit executestheassociatedroutingrule.
46
BecauseaJMStriggercanreceivemultiplemessagesfromthedestinations,Integration Serverusestheactivationvaluetoidentifythesetofmessagesprocessedbyaninstanceof ajoin. ForanAll(AND)join,IntegrationServerwaitsuntilitreceivesmessageswiththe sameactivationfromeachdestinationbeforeexecutingtheroutingrule. ForanOnlyone(XOR)join,IntegrationServerexecutestheroutingruleafterit receivesamessagefromanydestinationinthejoin;however,theJMStriggerdiscards messageswiththesameactivationreceivedfromtheotherdestinationsforthe durationofthejointimeout. ForanAny(OR)join,IntegrationServerexecutestheroutingrulewhenitreceives messagesfromanydestinationinthejoin.IntegrationServerdoesnotusethe activationvaluewhenprocessingJMStriggerswithanAny(OR)join. WhentheJMStriggerreceivesmessageswithadifferentactivationfromonethe destinations,IntegrationServertreatsitasanotherinstanceofthejoin. IntegrationServerstorestheactivationintheactivationfieldofaJMSmessage,specifically, JMSMessage/properties/activation.TheactivationfieldisoftypeString.Youassignan activationtoamessagemanually.IntegrationServerdoesnotassignanactivation automatically.
Setting the UUID

TheUUIDisauniversallyuniqueidentifierforamessage.IntegrationServerusesthe UUIDtoprovideduplicatedetectionforexactlyonceprocessing.IntegrationServerstores theUUIDintheJMSMessage/properties/uuidfield. YoumightwanttoassignaUUIDinthefollowingsituations: TheJMSmessageoriginatedinabackendsystemthatassignedauniqueidentifierto themessagedata.Youcanmapthevalueassignedbythesystemtothe JMSMessage/properties/uuidfield.AJMStriggerthatreceivesthemessagecanusethe assignedUUIDtofilteroutduplicatemessagesfromabackendsystem. AJMSmessageispartofarequest/reply.Ifyouspecifytheuuidwhensendingthe request,thereplyingIntegrationServerwillusetheuuidastheJMSCorrelationIDof thereplymessage.Ifyoudonotspecifyauuid,thereplyingIntegrationServeruses theJMSMessageIDoftherequestmessageastheJMSCorrelationIDofthereply message. ThemaximumlengthofaUUIDis96characters.IntegrationServerdoesnotassigna UUIDautomatically.
47
48
Chapter 4. Working with JMS Triggers
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Overview of Building a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 JMS Trigger Service Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Creating a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Enabling or Disabling a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Setting an Acknowledgment Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Setting a Join Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Specifying the Execution User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Specifying Message Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Handling Fatal Errors for Non-Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Handling Transient Errors for Non-Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Generating Events for JMS Retrieval Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Debugging a JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Building JMS Triggers with Multiple Routing Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
49
4. Working with JMS Triggers
Introduction
AJMStriggerspecifiesthedestinations(queuesortopics)onaJMSproviderfromwhich theJMStriggerwouldliketoreceivemessages.TheJMStriggeralsocontainsrouting rules,whichspecifytheservicethatIntegrationServerinvokestoprocessamessage receivedbytheJMStrigger.
Overview of Building a JMS Trigger

BuildingaJMStriggerisaprocessthatinvolvesthefollowingbasicstages. Stage
1
Description Create a new JMS trigger on Integration Server. Duringthisstage,youuse DevelopertocreatethenewJMStriggerontheIntegrationServerwhere youwilldoyourdevelopmentandtesting.Formoreinformation,see CreatingaJMSTriggeronpage 51. Specify a JMS connection alias.Duringthisstage,youspecifytheJMS connectionaliasthatIntegrationServerusestocreateconnectionstothe JMSprovider.ThetransactiontypeoftheJMSconnectionaliasdetermines whetherornottheJMStriggerreceivesandprocessesmessagesaspartof transaction. Specify JMS destinations and message selectors. Duringthisstage,youspecify thedestinations(queuesortopics)ontheJMSprovidertowhichtheJMS triggersubscribes.Thatis,thedestinationisthesourceofthemessages thattheJMStriggerconsumes.Youalsospecifyanymessageselectorsthat youwanttheJMSprovidertousetofilterthemessagesitenqueuesforthe JMStrigger. Create routing rules. Duringthisstage,youspecifytheservicethat IntegrationServerinvokeswhentheJMStriggerreceivesmessages.You canalsospecifyalocalfilterthatIntegrationServerappliestomessages. Set JMS trigger properties. Duringthisstage,youdeterminethetypeof messageprocessing,theacknowledgementmode,fatalandtransienterror handling,andexactlyonceprocessing. Test and debug the JMS trigger. Duringthisstage,youtestanddebugthe triggerusingthetoolsprovidedbyIntegrationServer.Formore information,seeDebuggingaJMSTriggeronpage 73.
JMS Trigger Service Requirements

TheservicethatprocessesamessagereceivedbyaJMStriggeriscalledatriggerservice. EachroutingruleinaJMStriggerspecifiesasingletriggerservice.
50
BeforeaJMStriggercanbeenabled,thetriggerservicemustalreadyexistonthesame IntegrationServer.Additionally,thesignatureforthetriggerservicemustreferenceoneof thefollowingspecifications: Usepub.jms:triggerSpecasthespecificationreferenceifthetriggerservicewillprocess onemessageatatime. Usepub.jms:batchTriggerSpecasthespecificationreferenceifthetriggerservicewill processmultiplemessagesatonetime.Thatis,thetriggerservicewillreceiveabatch ofmessagesasinputandprocessallofthosemessagesinasingleexecution.Atrigger thatreceivesandprocessesabatchofmessagesissometimesreferredtoasabatch trigger. Formoreinformationaboutbatchtriggers,seeProcessingMessagesinBatcheson page 63.
Creating a JMS Trigger

WhenyoucreateaJMStrigger,keepthefollowingpointsinmind: TheJMSconnectionaliasyouwantIntegrationServertousetoobtainconnectionsto andreceivemessagesfromtheJMSprovidermustalreadyexist.AlthoughaJMS connectionaliasdoesnotneedtobeenabledatthetimeyoucreatetheJMStrigger,the JMSconnectionaliasmustbeenabledfortheJMStriggertoexecuteatruntime. IfyouuseaJNDIprovidertostoreJMSadministeredobjects,theConnection FactoriesandDestinations(queuesandtopics)thatyouwantthisJMStriggertouseto consumemessagesmustalreadyexist. IfyouusethenativewebMethodsAPItoconnectdirectlytothewebMethodsJMS Provider,theDestinationsfromwhichyouwanttheJMStriggertoreceivemessages mustexistontheBroker.FormoreinformationaboutcreatingDestinationsonthe Broker,seethewebMethodsBrokerAdministratorsGuide. ThetransactiontypeoftheJMSconnectionaliasdetermineswhetherornottheJMS triggeristransacted(thatis,itreceivesandprocessesmessagesaspartofa transaction).TransactedJMStriggershaveslightlydifferentpropertiesandoperate differentlythannontransactedJMStriggers.Formoreinformationaboutbuildinga transactedJMStrigger,seeChapter 5,BuildingaTransactedJMSTrigger. Thetriggerservicethatyouwanttospecifyintheroutingrulemustalreadyexiston thesameIntegrationServeronwhichyoucreatetheJMStrigger.Formore informationabouttriggerservicerequirements,seeJMSTriggerService Requirementsonpage 50. AJMStriggercancontainmultipleroutingrules.Eachroutingrulemusthavea uniquename.Formoreinformationaboutusingmultipleroutingrules,seeBuilding JMSTriggerswithMultipleRoutingRulesonpage 74.
51
AJMStriggerthatcontainsanAll(AND)orOnlyone(XOR)joincanonlyhaveone routingruleandcannothaveabatchprocessingsize(Max batch messagesproperty) greaterthan1.AJMStriggerwithanAny(Or)joincanhavemultipleroutingrules. Formoreinformationaboutbatchprocessing,seeProcessingMessagesinBatches onpage 63. TouseAll(AND)orOnlyone(XOR)joins,theISInternalaliasneedstopointtoan externaldatabase.Formoreinformationaboutsettingupanexternaldatabase,seethe webMethodsInstallationGuide. To create a JMS trigger 1 2 3 OntheFilemenu,clickNew. IntheNewdialogbox,selectTrigger,andclickNext. IntheNewTriggerdialogbox,dothefollowing: a b InthelistnexttoFolder,selectthefolderinwhichyouwanttosavethetrigger. IntheNamefield,typeanameforthetriggerusinganycombinationofletters, and/ortheunderscorecharacter.Foralistofreservedwordsandsymbolsor elementnames,seethewebMethodsDeveloperUsersGuide. ClickNext. InthenewTriggerNamedialogbox,selectJMS TriggerandclickFinish. DevelopergeneratesthenewtriggeranddisplaysitintheDeveloperwindow. 4 5 IntheJMStriggereditor,intheJMS Connection Alias Namefield,click .
c d
IntheSelectaJMSconnectionaliasfortriggerNamedialogbox,selecttheJMS connectionaliasthatyouwantthisJMStriggertousetoreceivemessagesfromthe JMSprovider.ClickOK.DevelopersetstheTransaction typepropertytomatchthe transactiontypespecifiedfortheJMSconnectionalias. IfaJMSconnectionaliashasnotyetbeenconfiguredonIntegrationServer,Developer displaysamessagestatingtheJMSsubsystemhasnotbeenconfigured.For informationabutcreatingaJMSconnectionalias,seeWorkingwithJMSConnection Aliasesonpage 13.
6 7
UnderJMSdestinationsandmessageselectors,click
UsethefollowingstepstospecifythedestinationsfromwhichtheJMStriggerwill receivemessages: a IntheDestination Namecolumn,typethenameorlookupnameoftheDestination fromwhichyouwanttheJMStriggertoreceivemessages. SpecifythelookupnameoftheDestinationobjectwhentheJMSconnectionalias usesJNDItoretrieveadministeredobjects.Specifytheproviderspecificnameof
52
theDestinationwhentheJMSconnectionaliasusesthenativewebMethodsAPI toconnectdirectlytothewebMethodsJMSProvider. b IntheDestination Typecolumn,selectthetypeofdestination: Select... Queue If... Thedestinationisaqueue. Thisisthedefault. Topic c Thedestinationisatopic.
IntheJMS Message Selector column,click .IntheJMSMessageSelectordialog box,entertheexpressionthatyouwanttousetoreceiveasubsetofmessages fromthisdestinationandclickOK. AmessageselectorisafilterevaluatedbytheJMSprovider.Ifamessagedoesnot meetthecriteriaspecifiedinthemessageselector,theJMStriggerdoesnotreceive themessage.FormoreinformationaboutcreatingaJMSmessageselector,see CreatingaMessageSelectoronpage 56.
Ifyouspecifiedadestinationtypeoftopicandyouwanttocreateadurable subscriber,intheDurable Subscriber Namecolumn,enteranameforthesubscriber. Thenamemustbeuniqueforthattopic. AdurablesubscribercreatesadurablesubscriptionontheJMSprovider.A durablesubscriptionallowssubscriberstoreceiveallthemessagespublishedona topic,includingthosepublishedwhilethesubscriberisinactive.
IfyouspecifiedadestinationtypeoftopicandyouwanttheJMStriggertoignore messagessentusingthesameJMSconnectionaliasastheJMStrigger,selectthe checkboxinthe Ignore Locally Publishedcolumn.
8 9
Repeatstep7foreachdestinationfromwhichyouwanttheJMStriggertoreceive messages. Ifyouselectedmultipledestinations,selectthejointype.Thejointypedetermines whetherIntegrationServerneedstoreceivemessagesfromall,any,oronlyoneof destinationstoexecutethetriggerservice.
53
Select... All (AND)
If you want... IntegrationServertoinvokethetriggerservicewhenthe triggerreceivesamessagefromeverydestinationwithinthe jointimeoutperiod.Themessagesmusthavethesame activationID. FormoreinformationaboutactivationIDs,seeSetting PropertiesinaJMSMessageonpage 46.
Any (OR)
IntegrationServertoinvokethetriggerservicewhenthe triggerreceivesamessagefromanyofthespecified destinations. Thisisthedefaultjointype. Note: UsinganAny(OR)joinissimilartocreatingmultiple JMStriggersthatlistentodifferentdestinations.WhileaJMS triggerwithanAny(OR)joinwillusefewerresources(a singlethreadwillpolleachdestinationformessages),itmay causeadecreaseinperformance(itmaytakelongerforone threadtopollmultipledestinations).
Only one (XOR)
IntegrationServertoinvokethetriggerservicewhenit receivesamessagefromanyofthespecifieddestinations.For thedurationofthejointimeoutperiod,theIntegrationServer discardsanymessageswiththesameactivationIDthatthe triggerreceivesfromthespecifieddestinations. FormoreinformationaboutactivationIDs,seeSetting PropertiesinaJMSMessageonpage 46.
10 UnderMessagerouting,click
toaddanewroutingrule.
11 Createaroutingrulebyprovidingthefollowinginformation: a b IntheNamecolumn,typeanamefortheroutingrule.BydefaultDeveloper assignsthefirstrulethenameRule1. IntheServicecolumn,click tonavigatetoandselecttheservicethatyouwant toinvokewhenIntegrationServerreceivesmessagesfromthespecified destinations. IntheLocal Filtercolumn,click toenterthefilterthatyouwantIntegration ServertoapplytomessagesthisJMStriggerreceives.
54
IntegrationServerevaluatesalocalfilterafteritreceivesthemessagefromthe JMSprovider.Formoreinformationaboutcreatingalocalfilter,seeCreatinga LocalFilteronpage 56. 12 InthePropertiespanel,setpropertiesfortheJMStrigger. Property group or name... Enabled Acknowledgement mode Join expires and Expire after Execution user Message processing Fatal error handling Transient error handling Exactly once Permissions Refer to... EnablingorDisablingaJMSTriggeronpage 57 SettinganAcknowledgmentModeonpage 58 SettingaJoinTimeoutonpage 59 SpecifyingtheExecutionUseronpage 61 SpecifyingMessageProcessingonpage 62 HandlingFatalErrorsforNonTransactedJMS Triggersonpage 65 HandlingTransientErrorsforNonTransactedJMS Triggersonpage 66 Chapter 6,ExactlyOnceProcessingforJMSTriggers webMethodsDeveloperUsersGuide
13 OntheFilemenu,clickSave. Notes: WhenyouselectTopicasthedestinationtypeandspecifyadurablesubscriber name,IntegrationServercreatesaadurablesubscriberfortheJMStriggerontheJMS provider.Adurablesubscriberestablishesadurablesubscriptionwithauniqueidentity ontheJMSprovider.Adurablesubscriptionallowssubscriberstoreceiveallthe messagespublishedonatopic,includingthosepublishedwhilethesubscriberis inactive(forexample,iftheJMStriggerisdisabled).WhentheassociatedJMStrigger isdisabled,theJMSproviderholdsthemessagesinnonvolatilestorage.Ifadurable subscriptionalreadyexistsforthespecifieddurablesubscriberontheJMSprovider, thisserviceresumesthesubscription. WhenyouselectTopicasthedestinationtype,butdonotspecifyadurable subscribername,IntegrationServercreatesanondurablesubscriberfortheJMS trigger. Anondurablesubscriptionallowssubscriberstoreceivemessagesontheirchosen topiconlyifthemessagesarepublishedwhilethesubscriberisinactive.Anon durablesubscriptionlaststhelifetimeofitsmessageconsumer. IntegrationServerusesaconsumertoreceivemessagesforaJMStrigger.This consumerencapsulatestheactualjavax.jms.MessageConsumerandjavax.jms.Session.
55
Creating a Message Selector

IfyouwanttheJMStriggertoreceiveasubsetofmessagesfromaspecifieddestination, createamessageselector.Amessageselectorisanexpressionthatspecifiesthecriteriafor themessagesinwhichtheJMStriggerisinterested. TheJMSproviderappliesthemessageselectortomessagesitreceives.Iftheselector evaluatestotrue,themessageissenttotheJMStrigger.Iftheselectorevaluatestofalse, themessageisnotsenttotheJMStrigger. Bycreatingmessageselectors,youcandelegatesomefilteringworktotheJMSprovider. ThiscanpreserveIntegrationServerresourcesthatotherwisewouldhavebeenspent receivingandprocessingunwantedmessages. ThemessageselectormustusethemessageselectorsyntaxspecifiedintheJavaMessage Service,Version1.1.Themessageselectorcanreferenceheaderandpropertyfieldsinthe JMSmessageonly. Note: IfyouwanttofilteronthecontentsoftheJMSmessagebody,writealocalfilter. IntegrationServerevaluatesalocalfilteraftertheJMStriggerreceivesthemessagefrom theJMSprovider.Formoreinformationaboutcreatingalocalfilter,seeCreatingaLocal Filterbelow.
Creating a Local Filter

YoucanfurtherrefineaJMStriggerbycreatinglocalfilters.Alocalfilterspecifiescriteria forthecontentsofthemessagebody.IntegrationServerappliesalocalfiltertoamessage aftertheJMStriggerreceivesthemessagefromtheJMSprovider.Ifthemessagemeetsthe filtercriteria,IntegrationServerexecutesthetriggerservicespecifiedintheroutingrule.If themessagedoesnotmeetthefiltercriteria,IntegrationServerdiscardsthemessageand acknowledgesthemessagetotheJMSprovider. IfaJMStriggercontainsmultipleroutingrulestosupportorderedserviceexecution,you canuselocalfilterstoprocessaseriesofmessagesinaparticularorder.Formore informationaboutorderedserviceexecution,seeBuildingJMSTriggerswithMultiple RoutingRulesonpage 74. Tocreatealocalfilter,usethesyntaxspecifiedintheConditionalExpressionsappendix inthewebMethodsDeveloperUsersGuide. Whencreatingalocalfilter,youcanexcludetheJMSMessagedocumentfromthefilter eventhoughitispartofthepipelineprovidedtotheJMStriggerservice.Forexample,a filterthatmatchesthosemessageswherethevalueofthemyFieldfieldisXYZwould looklikethefollowing:
%properties/myField% == XYZ
NotethateventhoughthepropertiesfieldisachildoftheJMSMessagedocument,the JMSMessagedocumentdoesnotneedtoappearinthefilterexpression.
56
Thefollowingfiltermatchesthosemessageswherethedatadocumentwithinthe JMSMessagebodydocumentcontainsafieldnamedmyFieldwhosevalueisA:
%body/data/myField% == A
Note: Whenreceivingabatchofmessages,IntegrationServerevaluatesthelocalfilter againstthefirstmessageinthebatchonly.Formoreinformationaboutbatchprocessing, seeProcessingMessagesinBatchesonpage 63.
Enabling or Disabling a JMS Trigger

InDeveloper,youcanenableordisableaJMStrigger.AJMStriggercanhaveoneofthe followingstates: Trigger State Enabled Description TheJMStriggerisrunningandconnectedtotheJMSprovider. IntegrationServerretrievesandprocessesmessagesfortheJMS trigger. TheJMStriggerisstopped.IntegrationServerneitherretrievesnor processesmessagesfortheJMStrigger. TheJMStriggerisrunningandconnectedtotheJMSprovider. IntegrationServerhasstoppedmessageretrieval,butcontinues processinganymessagesithasalreadyretrieved. Note: YoucansuspendaJMStriggerusingIntegrationServer Administratororthepub.triggers:suspendJMSTriggers service.
Disabled Suspended
To enable or disable a JMS trigger 1 2 IntheNavigationpanel,opentheJMStriggerthatyouwanttoenableordisable. InthePropertiespanel,underGeneral,settheEnabledpropertytooneofthefollowing: Select... True False 3 To... EnableaJMStriggerthatiscurrentlydisabled. DisableaJMStriggerthatiscurrentlyenabled.
OntheFilemenu,clickSave.
57
Notes: WhenyoudisableaJMStrigger,IntegrationServerinterruptsanyserverthreadsthat areprocessingmessages.IftheJMStriggeriscurrentlyprocessingmessages, IntegrationServerwaits3secondsbeforeforcingtheJMStriggertostopprocessing messages.Ifitdoesnotcompletewithin3seconds,IntegrationServerstopsthe messageconsumerusedtoreceivemessagesfortheJMStriggerandclosestheJMS consumer.AtthispointtheserverthreadfortheJMStriggermaycontinuetorunto completion.However,theJMStriggerwillnotbeabletoacknowledgethemessage whenprocessingcompletes.Ifthemessageispersistent,thiscanleadtoduplicate messages. YoucandisableoneormoreJMStriggersusingthepub.triggers:disableJMSTriggers service. YoucanenableoneormoreJMStriggersusingthepub.triggers:enableJMSTriggersservice. Youcanenable,disable,andsuspendoneormoreJMStriggersusingIntegration ServerAdministrator.Formoreinformation,seeEnabling,Disabling,and SuspendingJMSTriggersonpage 106.
Setting an Acknowledgment Mode

AcknowledgmentmodeindicateshowIntegrationServeracknowledgesmessagesreceived onbehalfofaJMStrigger.Amessageisnotconsideredtobesuccessfullyconsumeduntil itisacknowledged. Note: TheAcknowledgement modepropertyisnotavailablefortransactedJMStriggers.That is,iftheJMSconnectionaliasisoftypeXA_TRANSACTIONor LOCAL_TRANSACATION,DeveloperdoesnotdisplaytheAcknowledgement mode property.
To set an acknowledgment mode 1 IntheNavigationpanel,opentheJMStriggerforwhichyouwanttosetthe acknowledgmentmode.
58
InthePropertiespanel,underGeneral,selectoneofthefollowingforAcknowledgment mode: Select... AUTO_ACKNOWLEDGE To... Automaticallyacknowledgethemessagewhen itisreceivedbytheJMStrigger.Integration Serverwillacknowledgethemessagebeforethe triggercompletesprocessing.TheJMSprovider cannotredeliverthemessageifIntegration Serverbecomesunavailablebeforemessage processingcompletes. Acknowledgeorrecoverthemessageonlyafter theJMStriggerprocessesthemessage completely. Thisisthedefault. DUPS_OK_ACKNOWLEDGE Lazilyacknowledgethedeliveryofmessages. Thismayresultinthedeliveryofduplicate messages.
CLIENT_ACKNOWLEDGE
Setting a Join Timeout

Whenyoucreateajoin(aJMStriggerthatreceivesmessagesfromtwoormore destinations),youneedtospecifyajointimeout.Ajointimeoutspecifieshowlong IntegrationServerwaitsforadditionalmessagestofulfillthejoin.IntegrationServerstarts thejointimeoutperiodwhenitreceivesthefirstmessagethatsatisfiesthejoin. Note: YouneedtospecifyajointimeoutonlywhenthejointypeisAll (AND)orOnly one (XOR).YoudonotneedtospecifyajointimeoutforanAny (OR) join. Theimplicationsofajointimeoutaredifferentdependingonthejointype.
Join Time-outs for All (AND) Joins

AjointimeoutforanAll (AND)joinspecifieshowlongIntegrationServerwaitsfor messagesfromallofthedestinationsspecifiedinthejoin. WhenaJMStriggerreceivesamessagethatsatisfiespartofanAll(AND)join,Integration ServerplacesthemessageintheISInternaldatabase.IntegrationServerwaitsfortheJMS triggertoreceivemessagesfromtheremainingdestinationsspecifiedinthejoin.Only messageswiththesameactivationIDasthefirstreceivedmessagewillsatisfythejoin.
59
IfIntegrationServerreceivesmessagesfromallofthedestinationsspecifiedinthejoin beforethetimeoutperiodelapses,IntegrationServerexecutestheservicespecifiedinthe routingrule.IfIntegrationServerdoenotreceivemessagesfromallofthedestinations beforethetimeoutperiodelapses,IntegrationServerdiscardsthemessagesandwritesa logentry. Whenthetimeoutperiodelapses,thenextmessagethatsatisfiestheAll (AND)joincauses thetimeoutperiodtostartagain.
Join Time-outs for Only One (XOR) Joins

AjointimeoutforanOnly one (XOR)joinspecifieshowlongIntegrationServerdiscards instancesoftheothermessagesreceivedfromthespecifieddestinations. WhenaJMStriggerreceivesamessagethatsatisfiespartofanOnly one (XOR)join, IntegrationServerexecutestheservicespecifiedintheroutingrule.IntegrationServer startsthejointimeoutwhentheJMStriggerreceivesthemessage.Forthedurationofthe timeoutperiod,IntegrationServerdiscardsanymessagestheJMStriggerreceivesfroma destinationspecifiedintheJMStrigger.IntegrationServeronlydiscardsthosemessages withthesameactivationIDasthefirstmessage. Whenthetimeoutperiodelapses,thenextmessagethattheJMStriggerreceivesthat satisfiestheOnly one (XOR)joincausesthetriggerservicetoexecuteandthetimeout periodtostartagain.
Setting a Join Time-out

WhenconfiguringJMStriggerproperties,youcanspecifywhetherajointimesoutandif itdoes,whatthetimeoutperiodshouldbe.Thetimeoutperiodindicateshowlong IntegrationServerwaitsformessagesfromtheotherdestinationsspecifiedinthejoinafter IntegrationServerreceivesthefirstmessage. Note: YouneedtospecifyajointimeoutonlywhenthejointypeisAll (AND)orOnly one (XOR).YoudonotneedtospecifyajointimeoutforanAny (OR) join.
To set a join time-out 1 2 IntheNavigationpanel,opentheJMStriggerforwhichyouwanttosetthejointime out. InthePropertiespanel,underGeneral,nexttoJoin expires,selectoneofthefollowing:
60
Select... True
To... SpecifythatIntegrationServershouldstopwaitingformessages fromotherdestinationsinthejoinafterthetimeoutperiod elapses. IntheExpire afterproperty,specifythelengthofthejointimeout period.Thedefaultjointimeoutperiodis1day.
False
Specifythatthejoindoesnotexpire.IntegrationServershould waitindefinitelyformessagesfromtheadditionaldestinations specifiedinthejoincondition.SettheJoin expirespropertytoFalse onlyifyouareconfidentthatallofthemessageswillbereceived eventually. Important! Ajoinispersistedacrossserverrestarts.
Specifying the Execution User

ForaJMStrigger,theexecutionuserindicateswhichcredentialsIntegrationServershould usewheninvokingservicesassociatedwiththeJMStrigger.Whenaclientinvokesa serviceviaanHTTPrequest,IntegrationServerchecksthecredentialsandusergroup membershipoftheclientagainsttheExecuteACLassignedtotheservice.Integration Serverperformsthischecktomakesurethattheclientisallowedtoinvokethatservice. WhenaJMStriggerexecutes,however,IntegrationServerinvokestheservicewhenit receivesamessageratherthanasaresultofaclientrequest.IntegrationServerdoesnot associateusercredentialswithamessage.YoucanspecifywhichcredentialsIntegration ServershouldsupplywheninvokingaJMStriggerservicebysettinganexecutionuserfor aJMStrigger. YoucaninstructIntegrationServertoinvokeaserviceusingthecredentialsofoneofthe predefineduseraccounts(Administrator,Default,Developer,Replicator).Youcanalso specifyauseraccountthatyouoranotherserveradministratordefined.WhenIntegration ServerreceivesamessagefortheJMStrigger,IntegrationServerusesthecredentialsfor thespecifieduseraccounttoinvoketheservicespecifiedintheroutingrule. Makesurethattheuseraccountyouselectincludesthecredentialsrequiredbythe executeActsassignedtotheservicesassociatedwiththeJMStriggers.
61
To assign an execution user 1 2 IntheNavigationpanel,opentheJMStriggerthatyouwanttoenableordisable. InthePropertiespanel,underGeneral,intheExecution userproperty,typethenameof theuseraccountwhosecredentialsIntegrationServerusestoexecuteaservice associatedwiththeJMStrigger.Youcanspecifyalocallydefineduseraccountora useraccountdefinedinacentralorexternaldirectory. OntheFilemenu,clickSave.
Specifying Message Processing

MessageprocessingdetermineshowIntegrationServerprocessesthemessagesreceived bytheJMStrigger.Youcanspecifyserialprocessingorconcurrentprocessing.
Serial Processing
Inserialprocessing,IntegrationServerprocessesmessagesreceivedbyaJMStriggerone aftertheotherintheorderinwhichthemessageswerereceivedfromtheJMSprovider. IntegrationServerusesasinglethreadforreceivingandprocessingamessageforaserial JMStrigger.IntegrationServerevaluatesthefirstmessageitreceives,determineswhich routingrulethemessagesatisfies,andexecutestheservicespecifiedintheroutingrule. IntegrationServerwaitsfortheservicetofinishexecutingbeforeprocessingthenext messagereceivedfromtheJMSprovider. IfyouwanttoprocessmessagesinthesameorderinwhichJMSclientssentthemessages totheJMSprovider,youwillneedtoconfiguretheJMSprovidertoensurethatmessages arereceivedbytheJMStriggerinthesameorderinwhichthemessagesarepublished. Tip! Ifyourtriggercontainsmultipleroutingrulestohandleagroupofmessagesthat mustbeprocessedinaspecificorder,useserialprocessing.
Concurrent Processing
Inconcurrentprocessing,IntegrationServerprocessesmessagesreceivedfromtheJMS providerinparallel.Thatis,IntegrationServerprocessesasmanymessagesfortheJMS triggersasitcanatthesametime,usingaseparateserverthreadtoprocesseachmessage. IntegrationServerdoesnotwaitfortheservicespecifiedintheroutingruletofinish executingbeforeitbeginsprocessingthenextmessage.Youcanspecifythemaximum numberofmessagesIntegrationServercanprocessconcurrently.Thisequatesto specifyingthemaximumnumberofserverthreadsthatcanprocessmessagesfortheJMS triggeratonetime.
62
Concurrentprocessingprovidesfasterperformancethanserialprocessing.Integration Serverprocessesthereceivedmessagesmorequicklybecauseitcanprocessmorethan onemessageforthetriggeratatime.However,themoremessagesIntegrationServer processesconcurrently,themoreserverthreadsitdispatches,andthemorememorythe messageprocessingconsumes. Additionally,forJMStriggerswithconcurrentprocessing,IntegrationServerdoesnot guaranteethatmessagesareprocessedintheorderinwhichtheyarereceived.
Message Processing and Message Consumers

IntegrationServerusesaconsumertoreceivemessagesforaJMStrigger.Thisconsumer encapsulatestheactualjavax.jms.MessageConsumerandjavax.jms.Session.Thetypeof messageprocessingaffectshowIntegrationServerusesconsumerstoreceivemessages. SerialJMStriggershaveoneconsumerandwilluseonethreadfromtheserverthread pooltoreceiveandprocessamessage. ConcurrentJMStriggersuseapoolofconsumerstoreceiveandprocessmessages.Each consumerusesonethreadfromtheserverthreadpooltoreceiveandprocessamessage. ForaconcurrentJMStrigger,theMax execution threadspropertyspecifieshowmany threadscanbeusedtoprocessmessagesforthetriggeratonetime.ForconcurrentJMS triggers,IntegrationServeralsodedicatesathreadtomanagingthepoolofconsumers. Consequently,themaximumnumberofthreadsthatcanbeusedbyaJMStriggerisequal totheMax execution threadsvalueplus1.Forexample,aconcurrentJMStriggerconfigured toprocessupto10messagesatatimecanuseamaximumof11serverthreads.
Processing Messages in Batches

YoucanconfigureaJMStriggeranditsassociatedtriggerservicetoprocessagroupor batchofmessagesatonetime.Batchprocessingcanbeaneffectivewayofhandlinga highvolumeofsmallmessagesforthepurposesofpersistingthemordeliveringthemto anotherbackendresource.Forexample,youmightwanttotakeabatchofmessages, createapacketofSAPIDocs,andsendthepackettoSAPwithasinglecall.Alternatively, youmightwanttoinsertmultiplemessagesintoadatabaseatonetimeusingonlyone insert.Thetriggerserviceprocessesthemessagesasaunitasopposedtoinaseries. TheMax batch messagespropertyindicatesthemaximumnumberofmessagesthatthe triggerservicecanreceiveatonetime.Forexample,iftheMax batch messagespropertyis setto5,IntegrationServerpassesthetriggerserviceupto5messagesreceivedbytheJMS triggertoprocessduringasingleexecution. IntegrationServerusesoneconsumertoreceiveandprocessabatchofmessages.During preprocessing,IntegrationServerchecksthemaximumdeliverycountforeachmessage and,ifexactlyonceprocessingisconfigured,determineswhetherornotthemessageisa duplicate.IntegrationServerthenbundlesthemessageintoasingleIDataandpassesitto thetriggerservice.Ifthemessagehasexceededthemaximumdeliverycountorisa
63
duplicatemessage,IntegrationServerdoesnotincludeitinthemessagebatchsenttothe triggerservice. Note: Thewatt.server.jms.trigger.maxDeliveryCountpropertydeterminesthe maximumnumberoftimestheJMSprovidercandeliveramessagetoaJMStrigger. IntegrationServeracknowledgesallthemessagesreceivedinabatchfromtheJMS provideratonetime.Thisincludesmessagesthatfailedpreprocessing.Accordingtothe JavaMessageService,Version1.1,whenaclientacknowledgesonemessage,theclient acknowledgesallofthemessagesreceivedbythesession.BecauseIntegrationServeruses aconsumerthatincludesajavax.jms.MessageConsumerandajavax.jms.Session,when IntegrationServeracknowledgesonemessageinthebatch,iteffectivelyacknowledgesall themessagesreceivedinthebatch. IfabatchofmessagesisnotacknowledgedortheyarerecoveredbacktotheJMS provider,theJMSprovidercanredeliverallofthemessagesinthebatchtotheJMS trigger.However,whenusingthewebMethodsJMSProvider,IntegrationServercan acknowledgeindividualmessagesthatfailpreprocessing. WhenconfiguringJMStriggerforbatchprocessing,keepthefollowinginmind: Thetriggerservicemustbecodedtohandlemultiplemessagesasinput.Thatis,the triggerservicemustusethepub.jms.batchTriggerSpecastheservicesignature. Whenreceivingabatchofmessages,IntegrationServerevaluatesthelocalfilterinthe routingruleagainstthefirstmessageinthebatchonly. TheJMStriggermustnotbepartofatransaction.TheJMSconnectionaliasspecified bythetriggermusthaveatransactiontypeofNOTRANSACTION. AJMStriggerthatcontainsanAll(AND)orOnlyone(XOR)joincannotusebatch processing.
Configuring Message Processing

UsethefollowingproceduretoconfiguremessageprocessingforaJMStrigger. To configure message processing for a JMS trigger 1 2 IntheNavigationpanel,opentheJMStriggerforwhichyouwanttospecifymessage processing. InthePropertiespanel,nexttoProcessing mode,selectoneofthefollowing:
64
Select... Serial Concurrent
To... SpecifythatIntegrationServershouldprocessmessagesreceived bythetriggeroneaftertheother. SpecifythatIntegrationServershouldprocessmultiplemessages forthistriggeratonetime. IntheMax execution threadsproperty,specifythemaximumnumber ofmessagesthatIntegrationServercanprocessconcurrently.
Ifyouwantthistriggertoperformbatchprocessing,nexttoMax batch messages, specifythemaximumnumberofmessagesthatthetriggerservicecanreceiveatone time.Ifyoudonotwantthetriggertoperformbatchprocessing,leavethisproperty setto1.Thedefaultis1. Important! ForatransactedJMStrigger,Max batch messagesmustbesetto1.Formore informationabouttransactedJMStriggers,seeChapter 5,BuildingaTransactedJMS Trigger.
Handling Fatal Errors for Non-Transacted JMS Triggers

YoucanspecifythatIntegrationServersuspendaJMStriggerautomaticallyifafatalerror occursduringtriggerserviceexecution.Afatalerroroccurswhenthetriggerserviceends becauseofanexception. Ifatriggerserviceendsbecauseofanexception,andyouconfiguredtheJMStriggerto suspendonfatalerrors,IntegrationServersuspendsthetriggerandacknowledgesthe messagetotheJMSprovider.TheJMStriggerremainssuspendeduntiloneofthe followingoccurs: Youenablethetriggerusingthepub.trigger:enableJMSTriggersservice. YouenablethetriggerusingIntegrationServerAdministrator. IntegrationServerrestartsorthepackagecontainingthetriggerreloads.(When IntegrationServersuspendsatriggerbecauseofafatalerror,IntegrationServer considersthechangetobetemporary.Formoreinformationabouttemporaryvs. permanentstatechangesfortriggers,seethewebMethodsIntegrationServer AdministratorsGuide.) Automaticsuspensionofatriggercanbeespeciallyusefulforserialtriggersthatare designedtoprocessagroupofmessagesinaparticularorder.Ifthetriggerserviceendsin errorwhileprocessingthefirstmessage,youmightnotwantthetriggertoproceedwith processingthesubsequentmessagesinthegroup.IfIntegrationServerautomatically
65
suspendsthetrigger,youhaveanopportunitytodeterminewhythetriggerservicedid notexecutesuccessfully. YoucanhandletheexceptionthatcausesthefatalerrorbyconfiguringIntegrationServer togenerateJMSretrievalfailureeventsforfatalerrorsandbycreatinganeventhandler thatsubscribestoJMSretrievalfailureevents.IntegrationServerpassestheeventhandler thecontentsoftheJMSmessageaswellasinformationabouttheexception.Formore informationaboutJMSretrievalfailureevents,seeGeneratingEventsforJMSRetrieval Failureonpage 72. IntegrationServerhandlesfatalerrorsfortransactedJMSdifferentlythanfornon transactedJMStriggers.ForinformationaboutfatalerrorhandlingfortransactedJMS triggers,seeHandlingFatalErrorsforTransactedJMSTriggersonpage 80. To configure fatal error handling 1 2 IntheNavigationpanel,opentheJMStriggerforwhichyouwanttospecify documentprocessing. InthePropertiespanel,underFatal error handling,settheSuspend on errorpropertyto TrueifyouwantIntegrationServertosuspendthetriggerwhenatriggerserviceends withanerror.Otherwise,selectFalse.ThedefaultisFalse. OntheFilemenu,clickSave.
Handling Transient Errors for Non-Transacted JMS Triggers

WhenbuildingaJMStrigger,youcanspecifywhatactionIntegrationServertakeswhen thetriggerservicefailsbecauseofatransienterrorcausedbyaruntimeexception.A transienterrorisanerrorthatarisesfromatemporaryconditionthatmightberesolvedor correctedquickly,suchastheunavailabilityofaresourceduetonetworkissuesorfailure toconnecttoadatabase.Becausetheconditionthatcausedthetriggerservicetofailis temporary,thetriggerservicemightexecutesuccessfullyifIntegrationServerwaitsand thenreexecutestheservice. Aruntimeexception(specifically,anISRuntimeException)occursinthefollowing situations: Thetriggerservicecatchesandwrapsatransienterrorandthenrethrowsitasan ISRuntimeException. Apub.jms:send,pub.jms:sendAndWait,orpub.jms:reply servicefailsbecausearesource(such astheJNDIproviderorJMSprovider)isnotavailable. IftheJMSproviderisnotavailable,andthesettingsforthepub.jms*serviceindicate thatIntegrationServershouldwritemessagestotheclientsidequeue,Integration ServerdoesnotthrowanISRuntimeException.
66
Atransienterroroccursonthebackendresourceforanadapterservice.Adapter servicesbuiltonIntegrationServer6.0orlater,andbasedontheARTframework, detectandpropagateexceptionsthatsignalaretryautomaticallyifatransienterroris detectedontheirbackendresource. YoucanconfiguretransienterrorhandlingforatriggertoinstructIntegrationServerhow andwhentoretrythetriggerservice.Thefollowingsectionsprovidemoreinformation aboutconfiguringretrybehaviorfortransienterrors. ForinformationaboutconfiguringtransienterrorhandlingforJMStriggersthatarepart ofatransaction,seeChapter 5,BuildingaTransactedJMSTrigger.
Configuring Retry Behavior for Trigger Services

WhenyouconfiguretransienterrorhandlingforanontransactedJMStrigger,youspecify thefollowingretrybehavior: WhetherIntegrationServershouldretrytriggerservicesforthetrigger.Keepinmind thatatriggerservicecanretryonlyifitiscodedtothrowISRuntimeExceptions.For moreinformation,seeServiceRequirementsforRetryingaTriggerServiceon page 67. ThemaximumnumberofretryattemptsIntegrationServershouldmakeforeach triggerservice. Ifyoudonotwanttoretryatriggerservice,makesurethattheMax retry attemptsterm issetto0.Thismayimproveperformance. Thetimeintervalbetweenretryattempts. Howtohandlearetryfailure.Thatis,youcanspecifywhatactionIntegrationServer takesifalltheretryattemptsaremadeandthetriggerservicestillfailsbecauseofan ISRuntimeException.Formoreinformationabouthandlingretryfailures,see HandlingRetryFailureonpage 68. Thefollowingsectionsprovidemoreinformationaboutconfiguringthetriggerserviceto throwISRuntimeExceptions,determiningthebestoptionforhandlingretryfailure,and configuringtheretrypropertiesforatrigger.
Service Requirements for Retrying a Trigger Service

Tobeeligibleforretry,thetriggerservicemustdooneofthefollowingtocatchatransient errorandrethrowitasanISRuntimeException: Ifthetriggerserviceisaflowservice,thetriggerservicemustinvoke pub.flow:throwExceptionForRetry.Formoreinformationaboutthe pub.flow:throwExceptionForRetry,seethewebMethodsIntegrationServerBuiltInServices Reference.Formoreinformationaboutbuildingaservicethatthrowsanexceptionfor retry,seethewebMethodsDeveloperUsersGuide.
67
IfthetriggerserviceiswritteninJava,theservicecanuse com.wm.app.b2b.server.ISRuntimeException().Formoreinformationabout constructingISRuntimeExceptionsinJavaservices,seethewebMethodsIntegration ServerJavaAPIReferenceforthecom.wm.app.b2b.server.ISRuntimeExceptionclass. Whenaserviceinvokesapub.jms*servicethatsendsaJMSmessageandtheservicefails becausearesourceneededbythepub.jms*serviceisnotavailable,IntegrationServer automaticallydetectsandpropagatesanISRuntimeException. AdapterservicesbuiltonIntegrationServer6.0orlater,andbasedontheART framework,detectandpropagateexceptionsthatsignalaretryifatransienterroris detectedontheirbackendresource.Thisbehaviorallowsfortheautomaticretrywhen theservicefunctionsasatriggerservice. Note: IntegrationServerdoesnotretryatriggerservicethatfailsbecauseaservice exceptionoccurred.Aserviceexceptionindicatesthatthereissomethingfunctionally wrongwiththeservice.AservicecanthrowaserviceexceptionusingtheEXITstep.For moreinformationabouttheEXITstep,seethewebMethodsDeveloperUsersGuide.
Handling Retry Failure

RetryfailureoccurswhenIntegrationServermakesthemaximumnumberofretry attemptsandthetriggerservicestillfailsbecauseofanISRuntimeException.Whenyou configureretryproperties,youcanspecifyoneofthefollowingactionstodeterminehow IntegrationServerhandlesretryfailureforatrigger. Throw exception.WhenIntegrationServerexhauststhemaximumnumberofretry attempts,IntegrationServertreatsthelasttriggerservicefailureasaserviceerror. Thisisthedefaultbehavior. Suspend and retry later.WhenIntegrationServerreachesthemaximumnumberofretry attempts,IntegrationServersuspendsthetriggerandthenretriesthetriggerservice atalatertime. Thefollowingsectionsprovidemoreinformationabouteachoptionforhandlingretry failures.
Overview of Throw Exception

ThefollowingtableprovidesanoverviewofhowIntegrationServerhandlesretryfailure whentheThrow exceptionoptionisselected.
68
Step
1 2 3
Description IntegrationServermakesthefinalretryattemptandthetriggerservicefails becauseofanISRuntimeException. IntegrationServertreatsthelasttriggerservicefailureasaservice exception. IntegrationServerrejectsthemessage. Ifthemessageispersistent,IntegrationServerreturnsanacknowledgement totheJMSprovider.
IntegrationServergeneratesaJMSretrievalfailureeventifthe watt.server.jms.trigger.raiseEventOnRetryFailurepropertyisset totrue(thedefault). IftheJMStriggerisconfiguredtosuspendonerrorwhenafatalerror occurs,IntegrationServersuspendstheJMStrigger.Otherwise,Integration ServerprocessesthenextmessagefortheJMStrigger.
Insummary,thedefaultretryfailurebehavior(Throw exception)rejectsthemessageand allowsthetriggertocontinuewithmessageprocessingwhenretryfailureoccursfora triggerservice.
Overview of Suspend and Retry Later

ThefollowingtableprovidesmoreinformationabouthowtheSuspend and retry later optionworks. Step
1 2
Description IntegrationServermakesthefinalretryattemptandthetriggerservicefails becauseofanISRuntimeException. IntegrationServersuspendstheJMStriggertemporarily. Note: Thechangetothetriggerstateistemporary.Messageprocessingwill resumeforthetriggerifIntegrationServerrestarts,thetriggerisenabledor disabled,orthepackagecontainingthetriggerreloads.Youcanalsoenable triggersmanuallyusingIntegrationServerAdministratororbyinvokingthe pub.trigger:enableJMSTriggersservice.
IntegrationServerrecoversthemessagebacktotheJMSprovider.This indicatesthattherequiredresourcesarenotreadytoprocessthemessage andmakesthemessageavailableforprocessingatalatertime.Forserial triggers,italsoensuresthatthemessagemaintainsitspositionatthetopof triggerqueue.
69
Step
4
Description Optionally,IntegrationServerschedulesandexecutesaresourcemonitoring service.Aresourcemonitoringserviceisaservicethatyoucreatetodetermine whethertheresourcesassociatedwithatriggerserviceareavailable.A resourcemonitoringservicereturnsasingleoutputparameternamed isAvailable. Iftheresourcemonitoringserviceindicatesthattheresourcesareavailable (thatis,thevalueofisAvailableistrue),IntegrationServerenablesthetrigger. MessageprocessingandmessageretrievalresumefortheJMStrigger. Iftheresourcemonitoringserviceindicatesthattheresourcesarenot available(thatis,thevalueofisAvailableisfalse),IntegrationServerwaitsa shorttimeinterval(bydefault,60seconds)andthenreexecutestheresource monitoringservice.IntegrationServercontinuesexecutingtheresource monitoringserviceperiodicallyuntiltheserviceindicatestheresourcesare available. Tip! Youcanchangethefrequencywithwhichtheresourcemonitoring serviceexecutesbymodifyingthevalueofthe watt.server.jms.trigger.monitoringIntervalproperty.
AfterIntegrationServerresumestheJMStrigger,IntegrationServerpasses themessagetothetrigger.Thetriggerandtriggerserviceprocessthe messagejustastheywouldanymessagereceivedbytheJMStrigger. Note: Atthispoint,theretrycountissetto0(zero).
Insummary,theSuspend and retry lateroptionprovidesawaytoresubmitthemessage programmatically.Italsopreventsthetriggerfromretrievingandprocessingother messagesuntilthecauseofthetransienterrorconditionhasbeenremedied.
Configuring Transient Error Handling

Usethefollowingproceduretoconfiguretransienterrorhandlingandretrybehaviorfora JMStrigger. To configure transient error handling for a JMS trigger 1 2 IntheNavigationpanel,opentheJMStriggerforwhichyouwanttoconfigureretry behavior. InthePropertiespanel,underTransient error handling,intheMax retry attemptsfield, specifythemaximumnumberoftimesIntegrationServershouldattemptto
70
reexecutethetriggerservice.Thedefaultis0retries(thetriggerservicedoesnot retry). 3 4 IntheRetry interval property,specifythetimeperiodtheIntegrationServerwaits betweenretryattempts.Thedefaultis10seconds. SettheOn retry failurepropertytooneofthefollowing: Select... Throw exception To... SpecifythatIntegrationServershouldthrowa serviceexceptionwhenthelastallowedretryattempt endsbecauseofanISRuntimeException. Thisisthedefault. FormoreinformationabouttheThrow exception option,seeOverviewofThrowExceptionon page 68. Suspend and retry later SpecifythatIntegrationServershouldrecoverthe messagebacktotheJMSproviderandsuspendthe triggerwhenthelastallowedretryattemptends becauseofanISRuntimeException.Formore informationabouttheSuspend and retry lateroption, seeOverviewofSuspendandRetryLateron page 69. Note: IfyouwantIntegrationServertoautomatically enablethetriggerwhenthetriggersresources becomeavailable,youmustprovidearesource monitoringservicethatIntegrationServercan executetodeterminewhentoresumethetrigger.For moreinformationaboutbuildingaresource monitoringservice,seeAppendix B,Buildinga ResourceMonitoringService. 5 IfyouselectedSuspend and retry later,thenintheResource monitoring serviceproperty specifytheservicethatIntegrationServershouldexecutetodeterminetheavailability ofresourcesassociatedwiththetriggerservice.Multipletriggerscanusethesame resourcemonitoringservice.Forinformationaboutbuildingaresourcemonitoring service,seeBuildingaResourceMonitoringServiceonpage 115. OntheFilemenu,clickSave.
71
Notes: Triggersandservicescanbothbeconfiguredtoretry.Whenatriggerinvokesaservice (thatis,theservicefunctionsasatriggerservice),IntegrationServerusesthetrigger retrypropertiesinsteadoftheserviceretryproperties. WhenIntegrationServerretriesatriggerserviceandthetriggerserviceisconfigured togenerateauditdataonerror,IntegrationServeraddsanentrytotheauditlogfor eachfailedretryattempt.EachoftheseentrieswillhaveastatusofRetriedandan errormessageofNull.However,ifIntegrationServermakesthemaximumretry attemptsandthetriggerservicestillfails,thefinalauditlogentryfortheservicewill haveastatusofFailedandwilldisplaytheactualerrormessage.IntegrationServer makestheauditlogentryregardlessofwhichretryfailureoptionthetriggeruses. IntegrationServergeneratesthefollowingjournallogmessagebetweenretry attempts: [ISS.0014.0031D]ServiceserviceNamefailedwithISRuntimeException.Retryxofywill begininretryIntervalmilliseconds. Ifyoudonotconfigureserviceretryforatrigger,setthe Max retry attemptspropertyto 0.Becausemanagingserviceretriescreatesextraoverhead,settingthispropertyto0 canimprovetheperformanceofservicesinvokedbythetrigger. Youcaninvokethepub.flow:getRetryCountservicewithinatriggerservicetodetermine thecurrentnumberofretryattemptsmadebyIntegrationServerandthemaximum numberofretryattemptsallowedforthetriggerservice.Formoreinformationabout thepub.flow:getRetryCountservice,seethewebMethodsIntegrationServerBuiltInServices Reference.
Generating Events for JMS Retrieval Failure

Bydefault,IntegrationServergeneratesJMSretrievalfailureeventswhenerrorsoccur duringmessageretrievalandJMStriggerprocessing.Youcanbuildeventhandlersthat subscribetoandhandletheJMSretrievalfailureevents. AJMSretrievalfailureeventoccursinthefollowingsituations: AtriggerserviceexecutedbyaJMStriggerthrowsanontransienterrorandthe watt.server.jms.trigger.raiseEventOnExceptionpropertyissettotrue(the default). AtriggerserviceassociatedwithaJMStriggerendsbecauseofatransienterror,all retryattemptshavebeenmade,andtheJMStriggerisconfiguredtothrowan exceptiononretryfailure.Inaddition,the watt.server.jms.trigger.raiseEventOnRetryFailurepropertyissettotrue(the default).
72
ThemaximumdeliverycountfromtheJMSproviderhasbeenmetforthemessage andthewatt.server.jms.trigger.raiseEventOnRetryFailurepropertyissetto true(thedefault). The watt.server.jms.trigger.maxDeliveryCountpropertyspecifiesthe maximumnumberoftimestheJMSprovidercandeliveramessagetoIntegration Server.Thedefaultis100.InaJMSmessage,thepropertyJMSXDeliveryCount specifiesthenumberoftimestheJMSproviderdeliveredthemessage.MostJMS providerssetthisvalue. Whileperformingexactlyonceprocessing,theconnectiontothedocumenthistory databaseisunavailable,andtransienterrorhandlingfortheJMStriggerisconfigured to Throw exception(nontransactedJMStrigger)orRecover only (transactedJMS trigger).Inaddition,thewatt.server.jms.trigger.raiseEventOnRetryFailure propertyissettotrue(thedefault). Whileperformingexactlyonceprocessing,thedocumentresolverserviceendswith anISRuntimeException,andtransienterrorhandlingfortheJMStriggerisconfigured to Throw exception(nontransactedJMStrigger)orRecover only (transactedJMS trigger).Inaddition,thewatt.server.jms.trigger.raiseEventOnRetryFailure propertyissettotrue(thedefault). Whileperformingexactlyonceprocessing,thedocumentresolverserviceendswith anexceptionotherthananISRuntimeException.Inaddition,the watt.server.jms.trigger.raiseEventOnRetryFailurepropertyissettotrue(the default). AservicethatfunctionsasaneventhandlerforaJMSretrievalfailureeventshoulduse thepub.event:jmsReceiveErrorEventspecificationasitsservicesignature.Formoreinformation aboutthepub.event:jmsReceiveErrorEventspecification,seethewebMethodsIntegrationServer BuiltInServicesReference.Formoreinformationaboutbuildingeventhandlers,seethe webMethodsDeveloperUsersGuide.
Debugging a JMS Trigger

IntegrationServerprovidesaserverconfigurationpropertythatyoucanusetoproduce anextralevelofverboselogging.YoucanenabledebugtraceloggingforallJMStriggers orforindividualJMStriggers. To enable debug trace logging for all JMS triggers 1 2 3 OpenIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickExtended. ClickEdit Extended Settings.
73
4 5 6
UnderExtended Settings,typethefollowing:
watt.server.jms.debugTrace=true
ClickSave Changes. SuspendandthenenableallJMStriggers. ForinformationaboutsuspendingandenablingallJMStriggersatonetime,see Enabling,Disabling,andSuspendingJMSTriggersonpage 106.
To enable debug trace logging for a specific JMS trigger 1 2 3 4 OpenIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickExtended. ClickEdit Extended Settings. UnderExtended Settings,typethefollowing:
watt.server.jms.debugTrace.triggerName=true
WheretriggerNameisthefullyqualifiednameofthetriggerintheformat folder.subfolder:triggerName. 5 6 ClickSave Changes. Disableandthenenablethetrigger. FormoreinformationaboutenablinganddisablingJMStriggersusingDeveloper,see EnablingorDisablingaJMSTriggeronpage 57.Forinformationaboutenabling anddisablingJMStriggersusingIntegrationServerAdministrator,seeEnabling, Disabling,andSuspendingJMSTriggersonpage 106.
Building JMS Triggers with Multiple Routing Rules

AJMStriggercancontainmorethanoneroutingrule.Eachroutingrulecanspecifya differentlocalfilterandadifferentservicetoinvoke. YoumightcreatemultipleroutingrulessothataJMStriggerprocessesagroupof messagesinaspecificorder.Eachroutingrulemightexecuteadifferenttriggerservice basedonthecontentsortypeofmessagereceived.WhenaJMStriggerreceivesa message,IntegrationServerdetermineswhichservicetoinvokebyevaluatingthelocal filtersforeachroutingrule. IntegrationServerevaluatestheroutingrulesinthesameorderinwhichtherulesappear intheeditor.Itispossiblethatamessagecouldsatisfymorethanoneroutingrule. However,IntegrationServerexecutesonlytheserviceassociatedwiththefirstsatisfied routingruleandignorestheremainingroutingrules.Therefore,theorderinwhichyou listroutingrulesontheeditorisimportant.
74
Youmightwanttousemultipleroutingrulestocontrolserviceexecutionwhenaservice thatprocessesamessagedependsonsuccessfulexecutionofanotherservice.For example,toprocessapurchaseorder,youmightcreateoneservicethataddsanew customerrecordtoadatabase,anotherthataddsacustomerorder,andathirdthatbills thecustomer.Theservicethataddsacustomerordercanonlyexecutesuccessfullyifthe newcustomerrecordhasbeenaddedtothedatabase.Likewise,theservicethatbillsthe customercanonlyexecutesuccessfullyiftheorderhasbeenadded.Youcanensurethat theservicesexecuteinthenecessaryorderbycreatingatriggerthatcontainsonerouting ruleforeachexpectedmessage. UsethefollowinggeneralguidelinestobuildaJMStriggerthatperformsorderedservice execution. BecausetheJMSprovidercannotguaranteemessageorderacrossdestinations,the JMStriggermustspecifyasingledestination.Thatis,theJMStriggercannotincludea join. Eachroutingrule,exceptthelastone,mustcontainalocalfilter.Forexample,you mightcreateafilterbasedonacustompropertythatthesendingclientaddstothe message.IntegrationServerusesthelocalfilterstodifferentiatebetweenthe messages.Withoutalocalfilter,onlythefirstroutingrulewouldeverexecute. Routingrulesmustappearintheorderinwhichyouwantthemessagestobe processed.Eachroutingrulemusthaveauniquename. SettheProcessing modepropertytoserialtoensurethattheIntegrationServer processesthemessagesinthesameorderinwhichtheJMStriggerreceivesthem. Serialprocessingensuresthattheservicesthatprocessthemessagesdonotexecuteat thesametime. SetMax batch messages to1(thedefault).Whenatriggerserviceprocessesabatchof messages,IntegrationServeronlyappliesthefiltertothefirstmessageinthebatch. Important! MessagesmustbesenttoJMSproviderinthesameorderinwhichyouwantthe messagestobeprocessed.
75
76
Chapter 5. Building a Transacted JMS Trigger
What Is a Transacted JMS Trigger? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Overview of Building a Transacted JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Handling Fatal Errors for Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Handling Transient Errors for Transacted JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
77
5. Building a Transacted JMS Trigger
What Is a Transacted JMS Trigger?

AtransactedJMStriggerisaJMStriggerthatexecuteswithinatransaction.Atransactionis alogicalunitofworkcomposedofoneormoreinteractionswithoneormoreresources. Theinteractionswithinatransactionareeitherallcommittedorallrolledback.A transactioneitherentirelysucceedsorhasnoeffectatall. ForatransactedJMStrigger,IntegrationServerusesatransactedJMSconnectionaliasto receivemessagesfromtheJMSproviderandtoprocessthemessages.AJMSconnection aliasisconsideredtobetransactedwhenithasatransactiontypeofXATRANSACTION orLOCALTRANSACTION. TheexecutionofatransactedJMStriggerisanimplicittransaction.Inanimplicit transaction,IntegrationServerstartsandcompletesthetransactionautomatically,without theneedforexecutinganyofthetransactionmanagementservices. IntegrationServerstartstheimplicittransactionwhenitusesthespecifiedtransactedJMS connectionaliastoconnecttotheJMSproviderandreceivemessagesforthetransacted JMStrigger.IntegrationServerimplicitlycommitsorrollsbackthetransactionbasedon thesuccessorfailureofthetriggerservice. IntegrationServercommitsthetransactionifthetriggerserviceexecutessuccessfully. IntegrationServerrollsbackthetransactionifthetriggerservicefailswithan ISRuntimeException(atransienterror).Fordetailedinformationabouthow IntegrationServerhandlesatransienterrorwithinatransaction,seeHandling TransientErrorsforTransactedJMSTriggersonpage 82. IntegrationServerrollsbackthetransactionifthetriggerservicefailswithaService Exception(afatalerror).FordetailedinformationabouthowIntegrationServer handlesafatalerrorwithinatransaction,seeHandlingFatalErrorsforTransacted JMSTriggersonpage 80. BecauseIntegrationServerhandlesthetransactionimplicitly,youdonotneedtouseany ofthetransactionmanagementservices,suchaspub.art.transaction:startTransaction,inthe triggerservice.However,ifthetriggerserviceincludesanestedtransaction,youcanuse thetransactionmanagementservicestoexplicitlymanagethenestedtransaction.
Overview of Building a Transacted JMS Trigger

LikeanontransactedJMStrigger,atransactedJMStriggerspecifiesadestinationfrom whichitwouldliketoreceivedocumentsandspecifiesroutingrulestoprocessmessages itreceives.However,atransactedJMStriggerhassomeprerequisitesaswellassome propertiesthataredifferentfromanontransactedJMStrigger.
78
Prerequisites for a Transacted JMS Trigger

BeforeyoubuildatransactedJMStrigger,makesurethefollowingpointsaretrue: AtransactedJMSconnectionaliasexists.AJMSconnectionaliasisconsideredtobe transactedwhenithasatransactiontypeofXATRANSACTIONorLOCAL TRANSACTION. TheWmARTpackageisinstalledandenabled.
Properties for Transacted JMS Triggers

IntegrationServerandDeveloperprovidedifferentpropertiesforatransactedJMStrigger thanforanontransactedJMStrigger.Thefollowinglistidentifiespropertiesthatare specifictotransactedJMStriggers,specifictonontransactedJMStriggers,orapplyto bothbutmustbesettoaparticularvaluefortransactedJMStriggers. FortransactedJMStriggers,messageacknowledgementishandledbythetransaction; theacknowledgementmodedoesnotapply.Consequently,Developerdoesnot displaytheAcknowledgement modepropertyforatransactedJMStrigger. AtransactedJMStriggercanonlyuseAny(OR)joins,forwhichyoudonotneedto specifyajointimeout.BecauseAll(AND)andOnlyone(XOR)joinscannotbeused, DeveloperdoesnotdisplaytheJoin expiresandExpire afterpropertiesforatransacted JMStrigger. AtransactedJMStriggercanprocessonemessageatatime.Itcannotprocessbatches ofmessages.MakesurethattheMax batch processing propertyissetto1. Becauseatransactionisanallornothingsituation,atriggerservicecannotretrya messageifatriggerserviceendsbecauseofatransienterror.Developerdoesnot displaytheretryproperties(Max retry attempts,Retry interval,andOn retry failure)fora transactedJMStrigger. YoucanspecifyhowIntegrationServerhandlesatransienterrorthatcausesthe transactiontoberolledback.DeveloperdisplaysanOn transaction rollback property thatyoucanusetospecifywhetherIntegrationServersimplyrecoversthemessage fromtheJMSproviderorwhetheritsuspendstheJMStriggerinadditionto recoveringthemessage.Formoreinformationabouttransienterrorhandlingfor transactedJMStriggers,seeHandlingTransientErrorsforTransactedJMSTriggers onpage 82.
79
Steps for Building a Transacted JMS Trigger

BuildingatransactedJMStriggerisaprocessthatinvolvesthefollowingbasicstages. Stage
1 2 3
Description CreateanewJMStriggeronIntegrationServer. SpecifyaJMSconnectionaliaswithatransactiontypeofXA TRANSACTIONorLOCALTRANSACTION. Specifythedestination(queuesortopics)ontheJMSproviderfromwhich youwanttoreceivemessages.Youalsospecifyanymessageselectorsthat youwanttheJMSprovidertousetofiltermessagesfortheJMStrigger. CreateroutingrulesandspecifytheservicesthatIntegrationServer invokeswhentheJMStriggerreceivesmessages. SetthefollowingJMStriggerproperties: Property name... Enabled Execution user Message processing Fatal error handling Transient error handling Exactly once Permissions For additional information, see... EnablingorDisablingaJMSTriggeron page 57 SpecifyingtheExecutionUseronpage 61 SpecifyingMessageProcessingonpage 62 HandlingFatalErrorsforTransactedJMS Triggersonpage 80 HandlingTransientErrorsforTransactedJMS Triggersonpage 82 Chapter 6,ExactlyOnceProcessingforJMS Triggers webMethodsDeveloperUsersGuide
4 5
TestanddebugtheJMStrigger. Formoreinformation,seeDebugginga JMSTriggeronpage 73.
Handling Fatal Errors for Transacted JMS Triggers

YoucanspecifythatIntegrationServersuspendatransactedJMStriggerautomaticallyifa fatalerroroccursduringtriggerserviceexecution.Afatalerroroccurswhenthetrigger serviceendsbecauseofaServiceException. Whenatransactedtriggerisconfiguredtosuspendwhenafatalerroroccurs,Integration ServerdoesthefollowingwhenthetriggerserviceendswithaServiceException:
80
Step
1 2
Description ThetriggerserviceforatransactedJMStriggerfailsbecauseofaService Exception. IntegrationServerrollsbacktheentiretransactionandIntegrationServer recoversthemessagebacktotheJMSprovider.TheJMSprovidermarksthe messageasredeliveredandincrementsthevalueoftheJMSXDeliveryCount propertyintheJMSmessage. IftheJMStriggerisconfiguredtouseadocumenthistorydatabasefor exactlyonceprocessing,IntegrationServeraddsanentrywithastatusof completedforthemessagetothedocumenthistorydatabase. BecauseIntegrationServerdoesnotacknowledgethemessagewhenitis rolledback,theJMSprovidermakesthemessageavailableforredeliveryto theJMStrigger.However,amessagethatcausesatriggerservicetoend becauseofaServiceExceptiontypicallydoesnotprocesssuccessfullyupon redelivery.IntegrationServeraddsthecompletedentrysothatthe messageistreatedasaduplicatewhenitisreceivedfromtheJMSprovider. Themessageisrejectedafteritisresent. IftheJMStriggerdoesnotuseadocumenthistorydatabase,Integration Servercontinuestoreceiveandattemptmessageprocessinguntilthe messageprocessessuccessfullyorthemaximumdeliverycounthasbeen met.Themaximumdeliverycountdeterminesthemaximumnumberof timetheJMSprovidercandeliverthemessagetotheJMStrigger.Itis controlledbythewatt.server.jms.trigger.maxDeliveryCount property.
4 5
IntegrationServersuspendstheJMStrigger. TheJMStriggerremainssuspendeduntiloneofthefollowingoccurs: Youenablethetriggerusingthepub.trigger:enableJMSTriggersservice. YouenablethetriggerusingIntegrationServerAdministrator. IntegrationServerrestartsorthepackagecontainingthetrigger reloads.(WhenIntegrationServersuspendsatriggerbecauseofafatal error,IntegrationServerconsidersthechangetobetemporary.For moreinformationabouttemporaryvs.permanentstatechangesfor triggers,seethewebMethodsIntegrationServerAdministratorsGuide.)
YoucanhandletheexceptionthatcausesthefatalerrorbyconfiguringIntegrationServer togenerateJMSretrievalfailureeventsforfatalerrorsandbycreatinganeventhandler thatsubscribestoJMSretrievalfailureevents.IntegrationServerpassesthecontentsofthe JMSmessageandexceptioninformationtotheeventhandler.Formoreinformationabout JMSretrievalfailureevents,seeGeneratingEventsforJMSRetrievalFailureonpage 72.
81
To configure fatal error handling for a transacted JMS trigger 1 2 IntheNavigationpanel,opentheJMStriggerforwhichyouwanttospecify documentprocessing. InthePropertiespanel,underFatal error handling,settheSuspend on errorpropertyto TrueifyouwantIntegrationServertosuspendthetriggerwhenatriggerserviceends withanerror.Otherwise,selectFalse.ThedefaultisFalse. ConfigureexactlyonceprocessingfortheJMStrigger.Formoreinformationabout configuringexactlyonceprocessing,seeConfiguringExactlyOnceProcessingon page 99. OntheFilemenu,clickSave.
Handling Transient Errors for Transacted JMS Triggers

WhenbuildingatransactedJMStrigger,youcanspecifywhatactionIntegrationServer takeswhenatransienterrorcausesatriggerservicetofailandtheentiretransactionis rolledback. Atransienterrorisanerrorthatarisesfromatemporaryconditionthatmightberesolved orcorrectedquickly,suchastheunavailabilityofaresourceduetonetworkissuesor failuretoconnecttoadatabase.Atransienterroriscausedbyaruntimeexception.Arun timeexception(specifically,anISRuntimeException)occursinthefollowingsituations. Thetriggerservicecatchesandwrapsatransienterrorandthenrethrowsitasan ISRuntimeException. Thepub.jms:send,pub.jms:sendAndWait,orpub.jms:replyservicefailsbecausearesource (suchastheJNDIproviderorJMSprovider)isnotavailable. IftheJMSproviderisnotavailable,andthesettingsforthepub.jms*serviceindicate thatIntegrationServershouldwritemessagestotheclientsidequeue,Integration ServerdoesnotthrowanISRuntimeException. Atransienterroroccursonthebackendresourceforanadapterservice.Adapter servicesbuiltonIntegrationServer6.0orlater,andbasedontheARTframework, detectandpropagateexceptionsthatsignalaretryautomaticallyifatransienterroris detectedontheirbackendresource. YoucanspecifyoneofthefollowingtransienterrorhandlingoptionsforatransactedJMS trigger: Recover only.Afteratransactionisrolledback,IntegrationServerreceivesthemessage fromtheJMSprovideralmostimmediately.Thisisthedefault. Suspend and recover. Afteratransactionisrolledback,IntegrationServersuspendsthe JMStriggerandreceivesthemessagefromtheJMSprovideratalatertime.
82
ThefollowingsectionsprovideanoverviewofhowIntegrationServeractsineach situation.
Overview of Recover Only

ThefollowingtableprovidesanoverviewofhowIntegrationServerhandlestransaction rollbackwhentheRecover OnlyoptionisselectedforatransactedJMStrigger. Step
1 2
Description ThetriggerservicefailsbecauseofanISRuntimeException. IntegrationServerrollsbacktheentiretransaction. Whenthetransactionisrolledback,IntegrationServerrecoversthe messagebacktotheJMSproviderautomatically.TheJMSprovidermarks themessageasredeliveredandincrementsthedeliverycount (JMSXDeliveryCountfieldintheJMSmessage). Atthispoint,aJMSprovidertypicallymakesthemessageavailablefor immediateredelivery.
IntegrationServerreceivesthesamemessagefromtheJMSproviderand processesthemessage. BecauseIntegrationServerreceivesthemessagealmostimmediatelyafter transactionrollback,itislikelythatthetemporaryconditionthatcaused theISRuntimeExceptionhasnotresolvedandthetriggerservicewillend withatransienterroragain.Consequently,settingOn transaction rollbackto Recover onlycouldresultinwastedprocessing. Note: IntegrationServerenforcesamaximumdeliverycount,which determinesthemaximumnumberoftimetheJMSprovidercandeliverthe messagetotheJMStrigger.Ifthemaximumdeliverycounthasbeenmet, theJMSproviderwillnotdeliverthemessagetotheJMStrigger.Instead, theJMSproviderwillacknowledgeandremovethemessage.The maximumdeliverycountiscontrolledbythe watt.server.jms.trigger.maxDeliveryCountproperty.
83
Overview of Suspend and Recover

ThefollowingtableprovidesanoverviewofhowIntegrationServerhandlestransaction rollbackwhentheSuspend and recoveroptionisselectedforatransactedJMStrigger. Step
1 2
Description ThetriggerservicefailsbecauseofanISRuntimeException. IntegrationServerrollsbacktheentiretransaction. Whenthetransactionisrolledback,IntegrationServerrecoversthemessage backtotheJMSproviderautomatically.TheJMSprovidermarksthemessage asredeliveredandincrementsthedeliverycount(JMSXDeliveryCountfieldin theJMSmessage).
IntegrationServersuspendstheJMStriggertemporarily. TheJMStriggerissuspendedonthisIntegrationServeronly.Ifthe IntegrationServerispartofacluster,otherserversintheclustercanretrieve andprocessmessagesforthetrigger. Note: Thechangetothetriggerstateistemporary.Messageprocessingwill resumeforthetriggerifIntegrationServerrestarts,thetriggerisenabledor disabled,orthepackagecontainingthetriggerreloads.Youcanalsoenable triggersmanuallyusingIntegrationServerAdministratororbyinvokingthe pub.trigger:enableJMSTriggersservice.
Optionally,IntegrationServerschedulesandexecutesaresourcemonitoring service.Aresourcemonitoringserviceisaservicethatyoucreatetodetermine whethertheresourcesassociatedwithatriggerserviceareavailable.A resourcemonitoringservicereturnsasingleoutputparameternamed isAvailable.
84
Step
5
Description Iftheresourcemonitoringserviceindicatesthattheresourcesareavailable (thatis,thevalueofisAvailableistrue),IntegrationServerenablesthetrigger. MessageprocessingandmessageretrievalresumefortheJMStrigger. Iftheresourcemonitoringserviceindicatesthattheresourcesarenot available(thatis,thevalueofisAvailableisfalse),IntegrationServerwaitsa shorttimeinterval(bydefault,60seconds)andthenreexecutestheresource monitoringservice.IntegrationServercontinuesexecutingtheresource monitoringserviceperiodicallyuntiltheserviceindicatestheresourcesare available. Tip! Youcanchangethefrequencyatwhichtheresourcemonitoringservice executesbymodifyingthevalueofthe watt.server.jms.trigger.monitoringIntervalproperty.
AfterIntegrationServerresumestheJMStrigger,IntegrationServerreceives themessagefromtheJMSproviderandprocessesthemessage. Note: Ifthemaximumdeliverycounthasbeenmet,theJMSproviderwillnot deliverthemessagetotheJMStrigger.Themaximumdeliverycount determinesthemaximumnumberoftimetheJMSprovidercandeliverthe messagetotheJMStrigger.Itiscontrolledbythe watt.server.jms.trigger.maxDeliveryCountproperty.
Configuring Transient Error Handling for a Transacted JMS Trigger

UsethefollowingproceduretoconfigurehowIntegrationServerrespondswhena transactionisrolledbackduetoatransienterrorthatoccursduringprocessingofa transactedJMStrigger. To configure transient error handling for a transacted JMS trigger 1 2 IntheNavigationpanel,openthetriggerforwhichyouwanttoconfiguretransient errorhandling. InthePropertiespanel,underTransient error handling,intheOn transaction rollback property,selectoneofthefollowing:
85
Select... Recover only
To... SpecifythatIntegrationServerrecoversthemessageaftera transactionisrolledbackduetoatransienterror. Thisisthedefault. FormoreinformationabouttheRecover onlyoption,see OverviewofRecoverOnlyonpage 83.
Suspend and recover
SpecifythatIntegrationServerdoesthefollowingaftera transactionisrolledbackduetoatransienterror: SuspendstheJMStrigger Recoversthemessageafteraresourcemonitoring serviceindicatesthattheresourcesneededbythe triggerserviceareavailable FormoreinformationabouttheSuspend and recoveroption, seeOverviewofSuspendandRecoveronpage 84.
IfyouselectedSuspend and recover,intheResource monitoring serviceproperty,specify theservicethatIntegrationServershouldexecutetodeterminetheavailabilityof resourcesassociatedwiththetriggerservice.Multipletriggerscanusethesame resourcemonitoringservice.Forinformationaboutbuildingaresourcemonitoring service,seeAppendix B,BuildingaResourceMonitoringService. OntheFilemenu,clickSave.
86
Chapter 6. Exactly-Once Processing for JMS Triggers
Overview of Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Duplicate Detection Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Extenuating Circumstances for Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Exactly-Once Processing and Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Configuring Exactly-Once Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Building a Document Resolver Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Viewing Exactly-Once Processing Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
87
6. Exactly-Once Processing for JMS Triggers
Overview of Exactly-Once Processing

WithinIntegrationServer,exactlyonceprocessingisafacilitythatensuresonetime processingofapersistentmessagebyaJMStrigger.Thetriggerdoesnotprocess duplicatesofthemessage.IntegrationServerprovidesexactlyonceprocessingwhenall ofthefollowingaretrue: Themessageispersistent. TheJMStriggerhasanacknowledgementmodesettoCLIENT_ACKNOWLEDGE. ExactlyoncepropertiesareconfiguredfortheJMStrigger.
Duplicate Detection Methods

IntegrationServerensuresexactlyonceprocessingbyperformingduplicatedetectionand byprovidingtheabilitytoretrytriggerservices.Duplicatedetectiondetermineswhether thecurrentmessageisacopyofonepreviouslyprocessedbythetrigger. DuplicatemessagescanbeintroducedintothewebMethodssysteminthefollowing situations: Thesendingclientsendsthesamemessagemorethanonce. WhenreceivingpersistentmessagesfromtheJMSprovider,IntegrationServerand theJMSproviderloseconnectivitybeforetheJMStriggerprocessesand acknowledgesthemessage.TheJMStriggerwillreceivethemessageagainwhenthe connectionisrestored. IntegrationServerusesduplicatedetectiontodeterminethemessagesstatus.The messagestatuscanbeoneofthefollowing: New.Themessageisnewandhasnotbeenprocessedbythetrigger. Duplicate.Themessageisacopyofonealreadyprocessedthetrigger. In Doubt.IntegrationServercannotdeterminethestatusofthemessage.Thetrigger mayormaynothaveprocessedthemessagebefore. Toresolvethemessagestatus,IntegrationServerevaluates,inorder,oneormoreofthe following: Delivery countindicateshowmanytimestheJMSproviderhasdeliveredthemessage totheJMStrigger. Document history databasemaintainsarecordofallpersistentmessageIDsprocessedby JMStriggersthathaveanacknowledgmentmodeofCLIENT_ACKNOWLEDGEandfor whichexactlyonceprocessingisconfigured.
88
Document resolver serviceisaservicecreatedbyausertodeterminethemessagestatus. Thedocumentresolverservicecanbeusedinsteadoforinadditiontothedocument historydatabase. ThestepsthatIntegrationServertakestodetermineamessagesstatusdependonthe exactlyoncepropertiesconfiguredfortheJMStrigger.Formoreinformationabout configuringexactlyonceproperties,seeConfiguringExactlyOnceProcessingon page 99. ThetablebelowsummarizestheprocessIntegrationServerfollowstodeterminea messagesstatusandtheactiontheservertakesforeachduplicatedetectionmethod.
1
Check Delivery Count Whenthetriggerisconfiguredtodetectduplicates,IntegrationServerwill checkthemessagesdeliverycounttodetermineiftheJMStriggerprocessedthe messagepreviously.Specifically,IntegrationServerchecksthevalueofthe JMSXDeliveryCountpropertyinthemessage. Delivery Count 1 Action Ifusingdocumenthistory,IntegrationServerproceeds to 2 tocheckthedocumenthistorydatabase. Ifdocumenthistoryisnotused,IntegrationServer considersthemessagetobeNew.IntegrationServer executesthetriggerservice. >1 Ifusingdocumenthistory,IntegrationServerproceeds to 2 tocheckthedocumenthistorydatabase. Ifdocumenthistoryisnotused,IntegrationServer proceedsto 3 toexecutethedocumentresolver service. Ifneitherdocumenthistorynoradocumentresolver serviceareused,IntegrationServerconsidersthe messagetobeInDoubt. 1(Undefined) Ifusingdocumenthistory,IntegrationServerproceeds to 2 tocheckthedocumenthistorydatabase. Ifdocumenthistoryisnotused,IntegrationServer proceedsto 3 toexecutethedocumentresolver service. Otherwise,IntegrationServerconsidersthemessageto beNew.IntegrationServerexecutesthetriggerservice.
89
Check Document History Ifadocumenthistorydatabaseisconfiguredandthetriggerusesittomaintain arecordofprocessedmessages,IntegrationServerchecksforthemessages UUIDinthedocumenthistorydatabase.IfthemessagedoesnothaveaUUID, IntegrationServerusesthevalueoftheJMSMessageIDfieldfromthemessage header. UUID or JMSMessageID Exists? No. Yes. Action MessageisNew.IntegrationServerexecutesthetrigger service. IntegrationServercheckstheprocessingstatusofthe entry. Iftheprocessingstatusindicatesthatmessage processingcompleted,thenIntegrationServer considersthemessagetobeaDuplicate.Integration Serveracknowledgesthemessage,butdoesnot executetriggerservice. Iftheprocessingstatusindicatesthatprocessing startedbutdidnotcomplete,IntegrationServer considersthemessagetobeInDoubt. Ifprovided,IntegrationServerproceedsto 3 to invokethedocumentresolverservice.Otherwise, IntegrationServerconsidersthemessagetobeIn Doubt.IntegrationServeracknowledgesthe message,butdoesnotexecutethetriggerservice.
Execute Document Resolver Service Ifadocumentresolverserviceisspecified,IntegrationServerexecutesthe documentresolverserviceassignedtothetrigger. Returned Status NEW DUPLICATE INDOUBT Action IntegrationServerexecutesthetriggerserviceand acknowledgesthemessage. IntegrationServeracknowledgesthemessage,butdoes notexecutethetriggerservice. IntegrationServeracknowledgesthemessage,butdoes notexecutethetriggerservice.
Thefollowingsectionsprovidemoreinformationabouteachmethodofduplicate detection.
90
Delivery Count
ThedeliverycountindicatesthenumberoftimestheJMSproviderhasdeliveredor attemptedtodeliveramessagetotheJMStrigger.MostJMSproviderstrackthemessage deliverycountintheJMSdefinedpropertyJMSXDeliveryCount.Theinitialdeliveryis1, theseconddeliveryis2,andsoforth.Adeliverycountotherthan1indicatesthatthe triggermighthavereceivedandprocessed(orpartiallyprocessed)themessagebefore. Forexample,whenIntegrationServerfirstretrievesamessageforaJMStrigger,the JMSXDeliveryCountcountis1(one).Ifaresource(JMSproviderorIntegrationServer) shutsdownbeforethetriggerprocessesandacknowledgesthemessage,Integration Serverwillretrievethemessageagainwhentheconnectionisreestablished.Thesecond timeIntegrationServerretrievesthemessage,theJMSXDeliveryCountwillbe2.Adelivery countgreaterthan1indicatesthattheJMSprovidermayhavedeliveredthemessageto thetriggerbefore. Thefollowingtableidentifiesthepossibledeliverycountvaluesandthemessagestatus associatedwitheachvalue. A delivery count of... 1 Indicates... TheJMSproviderthatdeliveredthemessagedoesnot maintainaJMSXDeliveryCountortherewasanerrorwhen retrievingtheJMSXDeliveryCount.Asaresult,thedelivery countisundefined.IntegrationServerusesavalueof1to indicatethatthedeliverycountisabsent. Ifothermethodsofduplicatedetectionareconfiguredforthis trigger(documenthistorydatabaseordocumentresolver service),IntegrationServerusesthesemethodstodetermine themessagestatus.Ifnoothermethodsofduplicatedetection areconfigured,IntegrationServerassignsthemessageastatus ofNewandexecutesthetriggerservice. 1 ThisisthefirsttimetheJMStriggerreceivedthemessage. IftheJMStriggerusesadocumenthistorytoperform duplicatedetection,IntegrationServerchecksthedocument historydatabasetodeterminethemessagestatus.Ifnoother methodsofduplicatedetectionareconfigured,Integration ServerassignsthemessageastatusofNewandexecutesthe triggerservice.
91
A delivery count of... >1
Indicates... TheJMSproviderhasdeliveredthemessagemorethanonce. Thetriggermightormightnothaveprocessedthemessage before.Thedeliverycountdoesnotprovideenough informationtodeterminewhetherthetriggerprocessedthe messagebefore. Ifothermethodsofduplicatedetectionareconfiguredforthis trigger(documenthistorydatabaseordocumentresolver service),IntegrationServerusesthesemethodstodetermine themessagestatus.Ifnoothermethodsofduplicatedetection areconfigured,IntegrationServerassignsthemessageastatus ofInDoubtandacknowledgesthemessage.
IntegrationServerusesdeliverycounttodeterminemessagestatuswheneveryouenable exactlyonceprocessingforaJMStrigger.Thatis,settingtheDetect duplicatespropertyto trueindicatesdeliverycountwillbeusedaspartofduplicatedetection.
Document History Database

Thedocumenthistorydatabasemaintainsahistoryofthepersistentmessagesprocessed byJMStriggers.IntegrationServeraddsanentrytothedocumenthistorydatabasewhen atriggerservicebeginsexecutingandwhenitexecutestocompletion(whetheritendsin successorfailure).Thedocumenthistorydatabasecontainsmessageprocessing informationonlyfortriggersforwhichtheUse historypropertyissettotrue. Thedatabasesavesthefollowinginformationabouteachmessage: Trigger ID. UniversallyuniqueidentifierfortheJMStriggerprocessingthemessage. UUID or JMSMessageID. Universallyuniqueidentifierforthemessage.Ifthesending clientassignedavaluetotheuuidfieldinthemessage,IntegrationServerusesthe uuidvaluetoidentifythemessage.Iftheuuidfieldisempty,IntegrationServeruses thevalueoftheJMSMessageIDfieldinthemessageheadertoidentifythemessage. Processing Status. Indicateswhetherthetriggerserviceexecutedtocompletionoris stillprocessingthemessage.Anentryinthedocumenthistorydatabasehaseithera statusofprocessingorastatusofcompleted.IntegrationServeraddsanentry withaprocessingstatusimmediatelybeforeexecutingthetriggerservice.Whenthe triggerserviceexecutestocompletion,IntegrationServeraddsanentrywithastatus ofcompletedtothedocumenthistorydatabase. Time. Thetimethetriggerservicebeganexecuting.Thedocumenthistorydatabase usesthesametimestampforbothentriesitmakesforamessage.Thisallowsthe IntegrationServertoremovebothentriesforaspecificmessageatthesametime. TodeterminewhetheramessageisaduplicateofonealreadyprocessedbytheJMS trigger,IntegrationServerchecksforthemessagesUUID(orJMSMessageID)inthe
92
documenthistorydatabase.TheexistenceorabsenceofthemessagesUUID (JMSMessageID)canindicatewhetherthemessageisneworaduplicate. If the UUID or JMSMessageID... Doesnotexist. Then Integration Server... AssignsthemessageastatusofNewandexecutesthe triggerservice.TheabsenceoftheUUID(JMSMessageID) indicatesthatthetriggerhasnotprocessedthemessage before. AssignsthemessageastatusofDuplicate.Theexistence oftheprocessingandcompletedentriesforthe messagesUUID(JMSMessageID)indicatethetrigger processedthemessagesuccessfullyalready.Integration Serveracknowledgesthemessage,discardsit,andwrites ajournallogentryindicatingthataduplicatemessage wasreceived. Cannotdeterminethestatusofthemessageconclusively. Theabsenceofanentrywithacompletedstatusfor theUUID(JMSMessageID)indicatesthatthetrigger servicestartedtoprocessthemessage,butdidnotfinish. Thetriggerservicemightstillbeexecutingortheserver mighthaveunexpectedlyshutdownduringservice execution. IfadocumentresolverserviceisspecifiedfortheJMS trigger,IntegrationServerinvokesit.Ifadocument resolverserviceisnotspecified,IntegrationServer assignsthemessageastatusofInDoubt,acknowledges themessage,andwritesajournallogentrystatingthat anInDoubtmessagewasreceived. Existsinacompleted entryonly. DeterminesthemessageisaDuplicate.Theexistenceof thecompletedentryindicatestheJMStrigger processedthemessagesuccessfullyalready.Integration Serveracknowledgesthemessage,discardsit,andwrites ajournallogentryindicatingthataDuplicatemessage wasreceived.
Existsinaprocessing entryandacompleted entry.
Existsinaprocessing entryonly.
Note: IntegrationServeralsoconsidersamessagetobeInDoubtwhenthevalueofthe messagesUUID(orJMSMessageID)exceeds96characters.Ifspecified,IntegrationServer executesthedocumentresolverservicetodeterminethemessagesstatus.Otherwise,the IntegrationServerlogsthemessageasInDoubt. Forinformationaboutconfiguringthedocumenthistorydatabase,refertothewebMethods InstallationGuide.
93
What Happens When the Document History Database Is Not Available?

IftheconnectiontothedocumenthistorydatabaseisunavailablewhenIntegrationServer attemptstoquerythedatabase,IntegrationServertakesoneofthefollowingactions dependingonthetransactionalityoftheJMStriggerandtheconfiguredtransienterror handling. For a non-transacted JMS trigger... If On retry failure is set to... Suspend and retry later Integration Server does the following... Ifthedocumenthistorydatabaseisproperlyconfigured, IntegrationServersuspendstheJMStriggerand schedulesasystemtaskthatexecutesaservicethatchecks fortheavailabilityofthedocumenthistorydatabase. IntegrationServerenablesthetriggerandreexecutesit whentheserviceindicatesthatthedocumenthistory databaseisavailable. Ifthedocumenthistorydatabaseisnotproperly configured,IntegrationServersuspendsthetrigger,butit doesnotscheduleasystemtasktocheckforthedatabases availabilityanditdoesnotresumethetrigger automatically.YoumustmanuallyenabletheJMStrigger afterconfiguringthedocumenthistorydatabaseproperly. Throw exception GeneratesaJMSretrievalfailureeventandacknowledges themessage.
94
For a transacted JMS trigger... If On transaction rollback is set to... Suspend and recover Integration Server does the following... Ifthedocumenthistorydatabaseisproperly configured,IntegrationServersuspendstheJMS triggerandschedulesasystemtaskthatexecutesa servicethatchecksfortheavailabilityofthe documenthistorydatabase.IntegrationServer enablesthetriggerandreexecutesitwhenthe serviceindicatesthatthedocumenthistorydatabase isavailable. Ifthedocumenthistorydatabaseisnotproperly configured,IntegrationServersuspendsthetrigger, butitdoesnotscheduleasystemtasktocheckfor thedatabasesavailabilityanditdoesnotresume thetriggerautomatically.Youmustmanuallyenable theJMStriggerafterconfiguringthedocument historydatabaseproperly. Recover only GeneratesaJMSretrievalfailureeventand acknowledgesthemessage.
FormoreinformationaboutgeneratingJMSretrievalevents,seeGeneratingEventsfor JMSRetrievalFailureonpage 72.
Managing the Size of the Document History Database

Tokeepthesizeofthedocumenthistorydatabasemanageable,IntegrationServer periodicallyremovesexpiredrowsfromthedatabase.Thelengthoftimethedocument historydatabasemaintainsinformationaboutaUUIDvariesforeachtriggeranddepends onthevalueofthetriggersHistory time to liveproperty. IntegrationServerprovidesascheduledservicethatremovesexpiredentriesfromthe database.Bydefault,thewm.server.dispatcher:deleteExpiredUUID serviceexecutesevery10 minutes.Youcanchangethefrequencywithwhichtheserviceexecutes.Forinformation abouteditingscheduledservices,seethewebMethodsIntegrationServerAdministratorsGuide. Note: Thewatt.server.idr.reaperIntervalpropertydeterminestheinitialexecution frequencyforthewm.server.dispatcher:deleteExpiredUUIDservice.AfteryoudefineaJDBC connectionpoolforIntegrationServertousetocommunicatewiththedocumenthistory database,changetheexecutionintervalbyeditingthescheduledservice. YoucanalsouseIntegrationServerAdministratortoclearexpireddocumenthistory entriesfromthedatabaseimmediately.
95
To clear expired entries from the document history database 1 2 3 4 OpenIntegrationServerAdministrator. FromtheSettingsmenuintheNavigationpanel,clickResources. ClickExactly Once Statistics. ClickRemove Expired Document History Entries.
Document Resolver Service

Thedocumentresolverserviceisaservicethatyoubuildtodeterminewhethera messagesstatusisNew,Duplicate,orInDoubt.IntegrationServerpassesthedocument resolverservicesomebasicinformationthattheservicewillusetodeterminemessage status,suchasthetriggernameandtheJMSmessage.Thedocumentresolverservice mustreturnoneofthefollowingforthemessagestatus:New,InDoubt,orDuplicate. Byusingthedeliverycountandthedocumenthistorydatabase,IntegrationServercan assignmostmessagesastatusofNeworDuplicate.However,asmallwindowoftime existswherecheckingthedeliverycountandthemessagehistorydatabasemightnot conclusivelydeterminewhetheratriggerprocessedamessagebefore.Forexample: Ifaduplicatemessagearrivesbeforethetriggerfinishesprocessingtheoriginal message,thedocumenthistorydatabasedoesnotyetcontainanentrythatindicates processingcompleted.IntegrationServerassignsthesecondmessageastatusofIn Doubt.Typically,thisisonlyanissueforlongrunningtriggerservices. IfIntegrationServerfailsbeforecompletingmessageprocessing,theJMSprovider redeliversthemessage.However,thedocumenthistorydatabasecontainsonlyan entrythatindicatesmessageprocessingstarted.IntegrationServerassignsthe redeliveredmessageastatusofInDoubt. Youcanwriteadocumentresolverservicetodeterminethestatusofmessagesreceived duringthesewindows.Howthedocumentresolverservicedeterminesthemessagestatus isuptothedeveloperoftheservice.Ideally,thewriterofthedocumentresolverservice understandsthesemanticsofalltheapplicationsinvolvedandcanusethemessageto determinethemessagestatusconclusively.Ifprocessinganearliercopyofthemessage leftsomeapplicationresourcesinanindeterminatestate,thedocumentresolverservice canalsoissuecompensatingtransactions. Ifprovided,thedocumentresolverserviceisthefinalmethodofduplicatedetection. Formoreinformationaboutbuildingadocumentresolverservice,seeBuildinga DocumentResolverServiceonpage 101.
96
Document Resolver Service and Exceptions

Atruntime,adocumentresolverservicemightendbecauseofanexception.How IntegrationServerproceedsdependsonthetypeofexceptionandhowtheJMStriggeris configuredtohandletransienterrors. IfthedocumentresolverserviceendswithanISRuntimeException,andtransient errorhandlingfortheJMStriggerisconfiguredto Suspend and retry later(non transactedJMStrigger)orSuspend and recover(transactedJMStrigger),Integration Serversuspendsthetriggerandschedulesasystemtasktoexecutethetriggers resourcemonitoringservice(ifoneisspecified).IntegrationServerenablesthetrigger andretriestriggerexecutionwhentheresourcemonitoringserviceindicatesthatthe resourcesusedbythetriggerareavailable. Ifaresourcemonitoringserviceisnotspecified,youwillneedtoresumethetrigger manually(viatheIntegrationServerAdministratororthepub.trigger:enableJMSTriggers service).Formoreinformationaboutconfiguringaresourcemonitoringservice,see Appendix B,BuildingaResourceMonitoringService. IfthedocumentresolverserviceendswithanISRuntimeException,andtransient errorhandlingfortheJMStriggerisconfiguredto Throw exception(nontransactedJMS trigger)orRecover only (transactedJMStrigger),IntegrationServerassignsthe documentastatusofInDoubt,acknowledgesthedocument,andgeneratesaJMS retrievalfailureevent. Ifthedocumentresolverserviceendswithanexceptionotherthanan ISRuntimeException,IntegrationServerassignsthemessageastatusofInDoubt, acknowledgesthemessage,andgeneratesaJMSretrievalfailureevent. Thewatt.server.jms.trigger.raiseEventOnRetryFailurepropertyissettotrue(the default)forIntegrationServertogenerateJMSretrievalfailureevents.Formore informationaboutJMSretrievalfailureevents,seeGeneratingEventsforJMSRetrieval Failureonpage 72.
Extenuating Circumstances for Exactly-Once Processing

AlthoughIntegrationServerprovidesrobustduplicatedetectioncapabilities,activity outsideofthescopeorcontroloftheIntegrationServerretrievingthemessagemight causeaJMStriggertoprocessamessagemorethanonce.Alternatively,situationscan occurwhereIntegrationServermightdetermineamessageisaduplicatewhenitis actuallyanewmessage. Forexample,inthefollowingsituationsatriggerwithexactlyonceprocessingconfigured mightprocessaduplicatemessage. IftheclientsendsamessagetwiceandassignsadifferentUUIDeachtime,Integration Serverdoesnotdetectthesecondmessageasaduplicate.Becausethemessageshave differentUUIDs,IntegrationServerprocessesbothmessages.
97
Ifthedocumentresolverserviceincorrectlydeterminesthestatusofamessagetobe new(whenitis,infact,aduplicate),theserverprocessesthemessageasecondtime. Ifaclientsendsamessagetwice,andthesecondmessageissentafterIntegration ServerremovestheexpiredmessageUUIDentriesfromthedocumenthistorytable, IntegrationServerdeterminesthesecondmessageisnewandprocessesit.Because thesecondmessagearrivesafterthefirstmessagesentrieshavebeenremovedfrom thedocumenthistorydatabase,IntegrationServerdoesnotdetectthesecondmessage asaduplicate. IfthetimedriftbetweenthecomputershostingaclusterofIntegrationServersis greaterthantheduplicatedetectionwindowforthetrigger,oneoftheIntegration Serversintheclustermightprocessaduplicatemessage.(Thesizeoftheduplicate detectionwindowisdeterminedbytheHistory time to livepropertyunderExactly Once.) Forexample,supposetheduplicatedetectionwindowis15minutesandthattheclock onthecomputerhostingoneIntegrationServerintheclusteris20minutesaheadof theclocksonthecomputershostingtheotherIntegrationServers.Atriggerononeof theIntegrationServerswithaslowerclockprocessesamessagesuccessfullyat10:00 GMT.TheIntegrationServeraddstwoentriestothedocumenthistorydatabase.Both entriesusethesametimestampandbothentriesexpireat10:15GMT.However,the IntegrationServerwiththefasterclockis20minutesaheadoftheothersandmight reaptheentriesfromthedocumenthistorydatabasebeforeoneoftheother IntegrationServersintheclusterdoes.IftheIntegrationServerwiththefasterclock removestheentriesbefore15minuteshaveelapsedandaduplicateofthemessage arrives,theIntegrationServersintheclusterwilltreatthemessageasanewmessage. Note: Timedriftoccurswhenthecomputersthathosttheclusteredserversgradually developdifferentdate/timevalues.Eveniftheadministratorsynchronizesthe computerdate/timewhenconfiguringthecluster,thetimemaintainedbyeach computercangraduallydifferastimepasses.Toalleviatetimedrift,synchronizethe clusternodetimesregularly. InsomecircumstancesIntegrationServermightnotprocessanew,uniquemessage becauseduplicatedetectiondeterminesthemessageisduplicate.Forexample: IfthesendingclientassignstwodifferentmessagesthesameUUID,theIntegration Serverdetectsthesecondmessageasaduplicateanddoesnotprocessit. Ifthedocumentresolverserviceincorrectlydeterminesthestatusofamessagetobe duplicate(whenitis,infact,new),IntegrationServerdiscardsthemessagewithout processingit.
98
Important! Intheaboveexamples,IntegrationServerfunctionscorrectlywhendetermining themessagestatus.However,factorsoutsideofthecontroloftheIntegrationServercreate situationsinwhichduplicatemessagesareprocessedornewmessagesaremarkedas duplicates.Thedesignersanddevelopersofthesolutionneedtomakesurethatclients properlysendmessages,exactlyoncepropertiesareoptimallyconfigured,andthat documentresolverservicescorrectlydetermineamessagesstatus.
Exactly-Once Processing and Performance

ExactlyonceprocessingforaJMStriggerconsumesserverresourcesandcanintroduce latencyintomessageprocessingbytriggers.Forexample,whenIntegrationServer maintainsahistoryofpersistentmessagesprocessedbyaJMStrigger,eachtriggerservice executioncausestwoinsertsintothedocumenthistorydatabase.ThisrequiresIntegration ServertoobtainaconnectionfromtheJDBCpool,traversethenetworktoaccessthe database,andtheninsertentriesintothedatabase. Additionally,whenthedeliverycountcannotconclusivelydetermineamessagesstatus, theservermustobtainadatabaseconnectionfromtheJDBCpool,traversethenetwork, andquerythedatabasetodeterminewhetherthetriggerprocessedthemessage. Ifqueryingthedocumenthistorydatabaseisinconclusiveoriftheserverdoesnot maintainadocumenthistoryforthetrigger,invocationofthedocumentresolverservice willalsoconsumeresources,includingaserverthreadandmemory. Themoreduplicatedetectionmethodsthatareconfiguredforatrigger,thehigherthe qualityofservice.However,eachduplicatedetectionmethodcanleadtoadecreasein performance. Ifatriggerdoesnotneedexactlyonceprocessing(forexample,thetriggerservicesimply requestsorretrievesdata),considerleavingexactlyonceprocessingdisabledforthe trigger.However,ifyouwanttoensureexactlyonceprocessing,youmustusea documenthistorydatabaseorimplementacustomsolutionusingthedocumentresolver service.
Configuring Exactly-Once Processing

ConfigureexactlyonceprocessingforaJMStriggerwhenyouwantthetriggertoprocess persistentmessagesonceandonlyonce.Ifitisacceptableforatriggerservicetoprocess duplicatesofamessage,youshouldnotconfigureexactlyonceprocessingforthetrigger.
99
Considerations for Configuring Exactly-Once Processing

Keepthefollowingpointsinmindwhenconfiguringexactlyonceprocessing: IntegrationServercanperformexactlyonceprocessingforpersistentmessagesonly. ThesendingclientmustsettheJMSDeliveryModetopersistent. TheJMStriggermustspecifyCLIENT_ACKNOWLEDGEfortheacknowledgementmode. Youdonotneedtoconfigureallthreemethodsofduplicatedetection.However,if youwanttoensureexactlyonceprocessing,youmustuseadocumenthistory databaseorimplementacustomsolutionusingthedocumentresolverservice. Adocumenthistorydatabaseoffersasimplerapproachthanbuildingacustom solutionandwilltypicallycatchallduplicatemessages.Theremaybeexceptions dependingonyourimplementation.Formoreinformationabouttheseexceptions,see ExtenuatingCircumstancesforExactlyOnceProcessingonpage 97.Tominimize theseexceptions,itisrecommendedthatyouuseahistorydatabaseandadocument resolverservice. StandaloneIntegrationServerscannotshareadocumenthistorydatabase.Onlya clusterofIntegrationServerscan(andmust)shareadocumenthistorydatabase. MakesuretheduplicatedetectionwindowsetbytheHistory time to livepropertyis longenoughtocatchduplicatemessagesbutdoesnotcausethedocumenthistory databasetoconsumetoomanyserverresources.IfsendingJMSclientsreliablysend messagesonce,youmightuseasmallerduplicatedetectionwindow.IftheJMSclients arepronetosendingduplicatemessages,considersettingalongerduplicatedetection window. Ifyouintendtouseadocumenthistorydatabaseaspartofduplicatedetection,you mustfirstinstallthedocumenthistorydatabasecomponentandassociateitwitha JDBCconnectionpool.Forinstructions,seethewebMethodsInstallationGuide.
Configuring Exactly-Once Processing for a JMS Trigger

TosetupexactlyonceprocessingforaJMStrigger,youcanconfigureuptothreemethods ofduplicatedetection:deliverycount,documenthistorydatabase,andadocument resolverservice. To configure exactly-once processing for a JMS trigger 1 2 3 IntheNavigationpanel,opentheJMStriggerforwhichyouwanttoconfigure exactlyonceprocessing. InthePropertiespanel,underExactly Once,settheDetect duplicatespropertytoTrue. Touseadocumenthistorydatabaseaspartofduplicatedetection,dothefollowing:
100
a b
SettheUse historypropertytoTrue. IntheHistory time to liveproperty,specifyhowlongthedocumenthistorydatabase maintainsanentryforamessageprocessedbythistrigger.Thisvaluedetermines thelengthoftheduplicatedetectionwindow.
4 5
TouseaservicethatyoucreatetoresolvethestatusofInDoubtmessages,specifythat serviceintheDocument resolver serviceproperty. OntheFilemenu,clickSave.
Disabling Exactly-Once Processing

IfyoulaterdeterminethatexactlyonceprocessingisnotnecessaryforaJMStrigger,you candisableit. To disable exactly-once processing for a trigger 1 2 IntheNavigationpanel,openthetriggerforwhichyouwanttoconfigureexactly onceprocessing. InthePropertiespanel,underExactly Once,settheDetect duplicatespropertytoFalse. Developerdisablestheremainingexactlyonceproperties. 3 OntheFilemenu,clickSave.
Building a Document Resolver Service

Adocumentresolverserviceisaservicethatyoucreatetoperformduplicatedetection. IntegrationServerusesthedocumentresolverserviceasthefinalmethodofduplicate detection. Thedocumentresolverservicemustdothefollowing: Usethepub.jms:documentResolverSpecastheservicesignature.IntegrationServerpasses thedocumentresolverservicevaluesforeachofthevariablesdeclaredintheinput signature. ReturnastatusofNew,InDoubt,orDuplicate.IntegrationServerusesthestatusto determinewhetherornottoprocessthemessage. Catchandhandleanyexceptionsthatmightoccur,includinganISRuntimeException. ForinformationabouthowIntegrationServerproceedswithduplicatedetection whenanexceptionoccurs,seeDocumentResolverServiceandExceptionson page 97.Forinformationaboutbuildingservicesthatthrowaretryexception,seethe webMethodsDeveloperUsersGuide.
101
Determinehowfarmessageprocessingprogressed.Ifnecessary,thedocument resolverservicecanissuecompensatingtransactionstoreversetheeffectsofa partiallycompletedtransaction.
Viewing Exactly-Once Processing Statistics

YoucanuseIntegrationServerAdministratortoviewahistoryoftheInDoubtor DuplicatemessagesreceivedbyJMStriggers.IntegrationServerAdministratordisplays thename,UUID(universallyuniqueidentifier),andstatusfortheDuplicateorInDoubt messagesreceivedbytriggersforwhichexactlyonceprocessingisconfigured. IntegrationServersavesexactlyoncestatisticsinmemory.WhenIntegrationServer restarts,thestatisticswillberemovedfrommemory. To view exactly-once processing statistics 1 2 3 StartwebMethodsIntegrationServerandopentheIntegrationServerAdministrator. UndertheSettingsmenuinthenavigationarea,clickResources. ClickExactly-Once Statistics.
To clear exactly-once processing statistics 1 2 3 4 StartwebMethodsIntegrationServerandopentheIntegrationServerAdministrator. UndertheSettingsmenuinthenavigationarea,clickResources. ClickExactly-Once Statistics. ClickClear All Duplicate or In Doubt Document Statistics.
102
Chapter 7. Managing JMS Triggers
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Controlling Thread Usage for JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Enabling, Disabling, and Suspending JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
103
7. Managing JMS Triggers
Introduction
IntegrationServerAdministratorprovidescontrolsformanagingJMStriggersandthe resourcesusedbyJMStriggers.Specifically,youcanusethecontrolsprovidedby IntegrationServerAdministratorto: IncreaseordecreasethemaximumnumberofserverthreadsusedforJMStriggers. ChangethemaximumexecutionthreadsforconcurrentJMStriggers. Enable,disable,orsuspendoneoremoreJMStriggers. ThefollowingsectionsprovidemoreinformationaboutmanagingJMStriggers.
Controlling Thread Usage for JMS Triggers

YoucanuseIntegrationServerAdministratortolimitthenumberofserverthreadsthat JMStriggerscanuse.Bydefault,IntegrationServercanconsumeupto100%oftheserver threadpoolforJMStriggers.However,serverresourcesalsoneedtobeavailableto performotherfunctions.
Viewing Thread Usage for JMS Triggers

IntegrationServerAdministratordisplaysthenumberofserverthreadscurrentlyusedby eachJMStriggeronIntegrationServer. To view thread usage for JMS triggers 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. ClickJMS Trigger Management. UnderIndividual JMS Trigger Controls,intheCurrent Threadscolumn,IntegrationServer Administratordisplaysthenumberofserverthreadscurrentlyusedtoreceiveand processmessagesforeachJMStrigger.TheCurrent ThreadscolumndisplaysNot ConnectedifIntegrationServerisnotconnectedtoaJMSprovider.
Increasing or Decreasing Thread Usage for JMS Triggers

IntegrationServerprovidescontrolsthatyoucanusetomanageserverthreadusageby JMStriggers.Youcanusethecontrolsto: SetthepercentageoftheserverthreadpoolthatIntegrationServercanusefor receivingandprocessingallJMStriggers.
104
Reducemaximumexecutionthreadsbythesamepercentageacrossallconcurrent JMStriggers.ThisalsodecreasestherateatwhichconcurrentJMStriggersprocess messages. To increase or decrease thread usage for JMS triggers 1 2 3 4 5 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. ClickJMS Trigger Management. ClickEdit JMS Global Trigger Controls. IntheThread Pool Throttlefield,typethemaximumpercentageoftheserverthread poolthatcanbeusedforJMStriggers.Thisincludesthreadsusedtoretrievemessages fromtheJMSproviderandthreadsusedtoprocessmessages.Youmustenteravalue greaterthanzero. IntheIndividual Trigger Processing Throttlefield,selectthevalue,asapercentageofthe configuredmaximumexecutionthreadsvalue,atwhichyouwanttotheserverto function.IntegrationServerappliesthispercentagetothemaximumexecution threadsvalueforallconcurrentJMStriggers. ThisvalueappliestoconcurrentJMStriggersonly. 7 ClickSave Changes.
Notes: IftheThread Pool Throttlepercentagedoesnotevaluatetoawholenumberwhen appliedtothesizeoftheserverthreadpool,IntegrationServerroundsupordownto thenearestwholenumber. SerialJMStriggersalwaysprocessonemessageatatime.Foraserialtrigger, IntegrationServerusesthesamethreadforreceivingandprocessingamessage.The Individual Trigger Processing ThrottledoesnotaffectserialJMStriggers. ConcurrentJMStriggersuseapoolofconsumerstoreceiveandprocessmessages. Eachconsumerwilluseathreadfromtheserverthreadpooltoreceiveandprocessa message.AconcurrentJMStriggerdedicatesanadditionalthreadtomanagingthe poolofconsumers.Forexample,aconcurrentJMStriggerconfiguredtoprocessupto 10messagesatatimecanuseamaximumof11serverthreads. IfthepercentagebywhichyoureduceconcurrentJMStriggerexecutionthreadsdoes notresolvetoawholenumberforaJMStrigger,IntegrationServerroundsupor roundsdowntothenearestwholenumber.However,ifroundingdownwouldsetthe valueto0,theIntegrationServerroundsupto1.Forexample,ifyoureduceIndividual Trigger Processing Throttleto10%ofmaximum,aconcurrentJMStriggerwitha maximumexecutionthreadsvalueof12wouldhaveanadjustedvalueof1 (IntegrationServerrounds1.2downto1).AconcurrentJMStriggerwithamaximum
105
executionthreadsvalueof4wouldhaveanadjustedvalueof1(IntegrationServer rounds0.4upto1). WhenyoureducetheIndividual Trigger Processing Throttleandsaveyourchanges, IntegrationServerdoesnotmeettheadjustedmaximumbyterminatinganythreads currentlyexecutingconcurrentJMStriggers.IntegrationServerallowsserverthreads processingmessagesforconcurrentJMStriggerstoexecutetocompletion.Integration ServerwaitsuntilthenumberofthreadsexecutingforaconcurrentJMStriggerisless thantheadjustedmaximumbeforedispatchinganotherserverthreadforthatJMS trigger.
Enabling, Disabling, and Suspending JMS Triggers

YoucanmanageJMStriggersandtheamountofresourcestheyconsumebychangingthe stateofaJMStrigger.AJMStriggercanhaveoneofthefollowingstates: Trigger State Enabled Description TheJMStriggerisrunningandconnectedtotheJMSprovider. IntegrationServerretrievesandprocessesmessagesfortheJMS trigger. TheJMStriggerisstopped.IntegrationServerneitherretrievesnor processesmessagesfortheJMStrigger. TheJMStriggerisrunningandconnectedtotheJMSprovider. IntegrationServerhasstoppedmessageretrieval,butcontinues processinganymessagesithasalreadyretrieved.
Disabled Suspended
UsingtheIntegrationServerAdministrator,youcan: Enable,disable,orsuspendallJMStriggers. Enable,disable,orsuspendspecificJMStriggers. YoumightwanttochangethestateofallJMStriggersatonceasaquickwayoffreeingup serverresources.ThiscanbeespeciallyhelpfulinasituationinwhichIntegrationServer isfunctioningunderheavyloadandadditionalresourcesareneededimmediately. YoumightwanttochangethestateforaspecificJMStriggerinthefollowingsituations: Whenabackendsystemneedsmaintenanceorisbecomingunresponsive,youmight wanttosuspendJMStriggersthatinteractwiththebackendsystem.Whentheback endsystembecomesavailable,youcanenabletheJMStriggers. AftersuspendingordisablingallJMStriggers,youmightenablespecificJMStriggers. Forexample,iftheserverisfunctioningunderanunusuallyheavyload,youmight firstsuspendallJMStriggersandthengraduallyenableJMStriggers,startingwith theJMStriggersinvolvedinkeyprocesses.
106
AfterIntegrationServersuspendsaserialJMStriggerautomaticallybecauseafatal erroroccurredduringmessageprocessing.ForinformationaboutconfiguringaJMS triggerforfatalerrorhandling,seeHandlingFatalErrorsforNonTransactedJMS Triggersonpage 65. ThefollowingprocedureexplainshowtouseIntegrationServerAdministratortochange thestateofallorindividualJMStriggers. To enable, disable, or suspend JMS triggers 1 2 3 4 OpentheIntegrationServerAdministratorifitisnotalreadyopen. IntheSettingsmenuoftheNavigationpanel,clickMessaging. ClickJMS Trigger Management. IfyouwanttochangethestateofallJMStriggers,dothefollowing: a b 5 UnderIndividualJMSTriggerControls,intheEnabledcolumn,clickedit all. OntheSettings > Messaging > JMS Trigger Management > Edit Statescreen,intheNew Statelist,selectthestatethatyouwanttoapplytoallJMStriggers.
IfyouwanttochangethestateofaspecificJMStrigger,dothefollowing: a b UnderIndividualJMSTriggerControls,intherowfortheJMStriggerthatyou wanttoenable,disable,orsuspend,clickthetextintheEnabledcolumn OntheSettings > Messaging > JMS Trigger Management > Edit State: triggerNamescreen, intheNew Statelist,selectthestatethatyouwanttoapplytothisJMStrigger.
ClickSave Changes.
Notes: IfyouwanttodisableaJMStrigger,firstsuspendtheJMStriggerandwaitforallthe processingthreadscomplete.Then,disabletheJMStrigger.Youcanviewthenumber ofthreadscurrentlyusedbyaJMStriggerontheSettings > Messaging > JMS Trigger Managementscreen. WhenyoudisableaJMStrigger,IntegrationServerdoesthefollowing: IftheJMStriggeriswaitingbeforemakingaretryattempt,IntegrationServer interruptsprocessingfortheJMStrigger. IftheJMStriggeriscurrentlyprocessingmessages,IntegrationServerwaitsa specifiedamountoftimebeforeforcingtheJMStriggertostopprocessing messages.Ifitdoesnotcompleteintheallottedtime,IntegrationServerstopsthe messageconsumerusedtoreceivemessagesfortheJMStriggerandclosesthe JMSsession.AtthispointtheserverthreadfortheJMStriggercontinuestorunto completion.However,theJMStriggerwillnotbeabletoacknowledgethe
107
messagewhenprocessingcompletes.Ifthedeliverymodeofthemessageissetto persistent,thiscanleadtoduplicatemessages. ThetimeIntegrationServerwaitsbetweentherequesttodisabletheJMStrigger andforcingthetriggertostopisspecifiedbythe watt.server.jms.trigger.stopRequestTimeoutproperty. Becauseadministeredobjects,likedestinations,areconfiguredoutsideofIntegration Server,disablingaJMStriggerhasnoimpactonthesubscription. IfaJMStriggerisprocessingmessagesatthetimeitissuspended,theJMStriggerwill completeprocessingofthosemessages.TheJMStriggeralsoacknowledgesthe messagestotheJMSprovider. Youcanusebuiltinservicestoenable,disable,andsuspendoneormoretriggers.For informationaboutthepub.trigger:disableJMSTriggers,pub.trigger:enableJMSTriggers,and pub.trigger:suspendJMSTriggersservices,seethewebMethodsIntegrationServerBuiltIn ServicesReference.
108
Appendix A. JMS Server Configuration Parameters
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 watt.server.jms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
109
A. JMS Server Configuration Parameters
Introduction
ThisappendixcontainsadescriptionoftheJMSrelatedparametersyoucanspecifyinthe serverconfigurationfile(server.cnf),whichislocatedinthe IntegrationServer_directory\configdirectory.TypicallyyouwillusetheSettings > Extended screenfromtheIntegrationServerAdministratortoupdatethisfile,buttheremightbe timeswhenyouneedtoeditthefiledirectlyusingatexteditor.Ifyoueditthefiledirectly, youshouldfirstshutdowntheIntegrationServerbeforeupdatingthefile.Afteryoumake thechanges,restarttheserver. Theserverusesdefaultvaluesformanyoftheparameters.Ifaparameterhasadefault,it islistedwiththedescriptionoftheparameter.Manyoftheseparametersaresetasyou administerthewebMethodsIntegrationServerusingtheIntegrationServer Administrator.
watt.server.jms
watt.server.jms.connection.pingPeriod Specifieshowoften,measuredinseconds,IntegrationServershouldpingtheJMS provider.ThepingservesasakeepaliverequestsenttotheJMSprovider.Thedefaultis 300seconds(5minutes). Important! YoumustrestartIntegrationServerforthenewvaluetotakeeffect. watt.server.jms.connection.retryPeriod Specifiesthelengthoftime,inseconds,thatIntegrationServerwaitsbetweenconnection attemptswhenaconnectiontotheJMSproviderorJNDIproviderfails.Thedefaultis20 seconds. Important! YoumustrestartIntegrationServerforthenewvaluetotakeeffect. watt.server.jms.csq.batchProcessingSize SpecifiesthemaximumnumberofmessagesIntegrationServerretrievesfromtheclient sidequeueandthensendstotheJMSprovider.IntegrationServerplacessentmessagesin theclientsidequeuewhentheconnectiontotheJMSproviderfails.IntegrationServer beginstodraintheclientsidequeueaftertheconnectiontotheJMSproviderbecomes available.Thedefaultis25. Important! YoumustrestartIntegrationServerforthenewvaluetotakeeffect. watt.server.jms.debugTrace EnablesanextralevelofverboseloggingforJMStriggersthatcanbecontrolledglobally orattheindividualJMStriggerlevel.
110
ToenabledebugTraceloggingforallJMStriggers,setthewatt.server.jms.debugTrace propertytotrue.Forthissettingtotakeeffect,youneedtodisableandthenenableall JMStriggers.ForinformationaboutusingIntegrationServerAdministratortoenable anddisableallJMStriggers,seeEnabling,Disabling,andSuspendingJMSTriggers onpage 106. ToenabledebugTraceloggingforanspecificJMStrigger,appendthefullyqualified JMStriggernametothewatt.server.jms.debugTracepropertyandsetthatpropertyto true.Forexample,toenabledebugTraceloggingfortheJMStriggernamed myFolder:myJMSTrigger,enterthefollowingontheEditExtendedSettingspage: watt.server.jms.debugTrace.myFolder:myJMSTrigger=true Forthissettingtotakeeffect,youneedtodisableandthenenabletheJMStrigger specifiedintheproperty.ForinformationaboutusingIntegrationServer Administratortodisableandenableanindividualtrigger,seeEnabling,Disabling, andSuspendingJMSTriggersonpage 106. watt.server.jms.trigger.maxDeliveryCount SpecifiesthemaximumnumberoftimestheJMSprovidercandeliveramessageto IntegrationServer.Thedefaultis100. Important! YoumustrestartIntegrationServerforthenewvaluetotakeeffect. watt.server.jms.trigger.maxPrefetchSize SpecifiesthemaximumnumberofmessagesthatthewebMethodsJMSAPIwillretrieve andcacheperrequestforaJMStrigger.Usingprefetchcachecanspeeduptheretrievalof messagesfromthewebMethodsJMSProvider.Becausemessageswillbeplacedin IntegrationServermemory,youmaywanttodecreasethissettingifyouhaveJMStriggers receivingverylargemessages.Otherwise,memoryissuescanoccur.Thispropertyonly appliestoJMStriggersreceivingmessagesfromthewebMethodsJMSProvider.The defaultis10messages. IntegrationServerchecksthisvaluewhenaJMStriggerstarts.Toapplyanewvaluetoall JMStriggers,useIntegrationServerAdministratortodisableandthenenableJMS triggers.FormoreinformationaboutenablinganddisablingJMStriggers,seeEnabling, Disabling,andSuspendingJMSTriggersonpage 106. WhenworkinginaclusterofIntegrationServers,thebehaviorcontrolledbythisproperty mightappearatfirsttobemisleading.Forexample,supposethatyouhaveaclusterof twoIntegrationServerss.EachIntegrationServercontainsthesameJMStrigger.Twenty messagesaresenttoadestinationfromwhichJMStriggerreceivesmessages.Itmightbe expectedtheJMStriggeronIntegrationServer1willreceivethefirstmessage,theJMS triggeronIntegrationServer1willreceivethesecondmessage,andsoforth.However, whatmayhappenisthattheJMStriggeronIntegrationServer1willreceivethefirst10 messagesandtheJMStriggeronIntegrationServer2willreceivethesecond10messages.
111
watt.server.jms.trigger.monitoringInterval Specifiestheinterval,measuredinseconds,atwhichIntegrationServerexecutesresource monitoringservicesforJMStriggers.Aresourcemonitoringserviceisaservicethatyou createtochecktheavailabilityofresourcesusedbyaJMStriggerservice.AfterIntegration ServersuspendsaJMStriggerbecauseallretryattemptshavefailed,itschedulesasystem tasktoexecutetheresourcemonitoringserviceassignedtotheJMStrigger.Thedefaultis 60seconds.ChangestothispropertytakeeffectthenexttimeIntegrationServerschedules asystemtasktoexecutearesourcemonitoringserviceforaJMStrigger. FormoreinformationaboutbuildingresourcemonitoringservicesforJMStriggers,see Appendix B,BuildingaResourceMonitoringService. watt.server.jms.trigger.pooledConsumer.timeout Specifiesthelengthoftime,inmilliseconds,thatapooledconsumershouldremainactive. IntegrationServerusesapoolofconsumerstoretrieveandprocessmessagesfor concurrentJMStriggers.Eachconsumerinthepoolencapsulatesanactual javax.jms.MessageConsumerandjavax.jms.Session.Thedefaultis60,000milliseconds(60 seconds). Important! YoumustrestartIntegrationServerforthenewvaluetotakeeffect. watt.server.jms.trigger.raiseEventOnException IndicateswhetherIntegrationServergeneratesaJMSretrievalfailureeventwhenaJMS triggerexperiencesafatalexception,suchasanontransienterrororamessagethat cannotbereprocessed,duringmessageprocessing.SpecifytrueifyouwantIntegration ServertogenerateaJMSretrievalfailureevent.Thedefaultistrue. Important! YoumustrestartIntegrationServerforthenewvaluetotakeeffect. watt.server.jms.trigger.raiseEventOnRetryFailure IndicatesthatIntegrationServergeneratesaJMSretrievalfailureeventwhenaJMS triggerexperiencesaretryfailure.AretryfailurecanoccurwhentheJMSproviderhas reachedthemaxdeliverycountforamessageorwhenanISRuntimeExceptionisthrown andtheJMStriggerisnotconfiguredtorecoverthemessage(forexample,ifretryfailure handlingforanontransactedJMStriggerissettoThrowexceptioninsteadofSuspend andRetryLater.)Whensettotrue,IntegrationServergeneratesaJMSretrievalfailure eventforaJMStriggerwhenretryfailureoccurs.Thedefaultistrue. Important! YoumustrestartIntegrationServerforthenewvaluetotakeeffect. watt.server.jms.trigger.reuseSession IndicateswhetherinstancesofaJMStriggerusethesamesessiononIntegrationServer Whenthispropertyissettotrue,theJMStriggerusesasharedsession.Eachofthetrigger servicesexecutedbytheJMStriggerwillusethesamesessionID.Whenthispropertyis settofalse,IntegrationServerusesanewsessionforeachinstanceofaJMStrigger. ReusingsessionsforaJMStriggermightimproveperformance.However,thisproperty
112
doesnotworkwithalladapters.Ifyouareworkingwithanadapter,suchastheSAP adapter,thatrequiresthesessionIDtobeunique,setthispropertytofalse.Thedefaultis false. Important! YoumustrestartIntegrationServerforthenewvaluetotakeeffect. watt.server.jms.trigger.stopRequestTimeout Specifiesthemaximumamountoftime,measuredinsecondsthatIntegrationServer waitsafteraJMStriggerisdisabledbeforeforcingtheJMStriggertostopprocessing messages.Thedefaultis3seconds. YoucandisableaJMStriggerbyinvokingthepub.trigger:disableJMSTriggerserviceorbyusing orviatheSettings > Messaging > JMS Trigger ManagementscreensinIntegrationServer Administrator.FormoreinformationaboutdisablingJMStriggers,seeEnabling, Disabling,andSuspendingJMSTriggersonpage 106. WhenyousaveaJMStriggerinDeveloper,IntegrationServerstopsandthenrestartsthe trigger.Inthissituation,IntegrationServerwaits3secondsbeforeforcingtheJMStrigger tostopprocessingmessages.Thisvaluecannotbeconfigured. Important! YoumustrestartIntegrationServerforthenewvaluetotakeeffect. watt.server.jms.wmjms.lms.readTimeout Specifiestheamountoftime(measuredinmilliseconds)thatIntegrationServerwaitsfor thenextportionofaninputstreambeforethrowingWmReadTimeoutException.Theread timeoutonlyappliesafterIntegrationServerretrievestheinitialpieceoftheinputstream. Thedefaultis30000milliseconds.
113
114
Appendix B. Building a Resource Monitoring Service
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Service Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
115
B. Building a Resource Monitoring Service
Overview
Aresourcemonitoringserviceisaservicethatyoucreatetochecktheavailabilityof resourcesusedbyatrigger.IntegrationServerschedulesasystemtasktoexecutea resourcemonitoringserviceafteritsuspendsatrigger.Specifically,IntegrationServer suspendsatriggerandinvokestheassociatedresourcemonitoringservicewhenoneof thefollowingoccurs: Duringexactlyonceprocessing,thedocumentresolverserviceendsbecauseofan ISRuntimeExceptionandthe watt.server.trigger.preprocess.suspendAndRetryOnErrorpropertyissetto true(thedefault). Aretryfailureoccursforanontransactedtriggerandtheconfiguredretrybehavioris suspendandretrylater. AtransienterroroccursforatransactedJMStriggerandtheconfiguredbehavior whentransactionrollbackoccursistosuspendtheJMStriggerandrecoverthe message Thesameresourcemonitoringservicecanbeusedformultipletriggers.Whentheservice indicatesthatresourcesareavailable,IntegrationServerresumesallthetriggersthatuse theresourcemonitoringservice.
Service Requirements
Aresourcemonitoringservicemustdothefollowing: Usethepub.trigger:resourceMonitoringSpecastheservicesignature. Checktheavailabilityoftheresourcesusedbythedocumentresolverserviceandall thetriggerservicesassociatedwithatrigger.Keepinmindthateachconditionina triggercanbeassociatedwithadifferenttriggerservice.However,youcanonly specifyoneresourcemonitoringservicepertrigger. ReturnavalueoftrueorfalsefortheisAvailableoutputparameter.Theauthorof theresourcemonitoringservicedetermineswhatcriteriamakesaresourceavailable. Catchandhandleanyexceptionsthatmightoccur.Iftheresourcemonitoringservice endsbecauseofanexception,IntegrationServerlogstheexceptionandcontinuesasif theresourcemonitoringservicereturnedavalueoffalsefortheisAvailableoutput parameter.
116
Appendix C. Transaction Management
Transaction Management Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Built-In Transaction Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
117
C. Transaction Management
Transaction Management Overview

Thisappendixprovidesanoverviewoftransactionmanagement,includingtransaction typesandimplicitvs.explicittransactions.ItalsodescribeshowIntegrationServer supportsthebuiltinservicesusedtomanageexplicittransactions.Fordescriptionsof eachofthespecificbuiltintransactionmanagementservices,seeBuiltInTransaction ManagementServicesonpage 121.
Transactions
IntegrationServerconsidersatransactiontobeoneormoreinteractionswithoneormore resourcesthataretreatedasasinglelogicalunitofwork.Theinteractionswithina transactionareeitherallcommittedorallrolledback.Forexample,ifatransaction includesmultipledatabaseinserts,andoneormoreinsertsfail,allinsertsarerolledback.
Transaction Types
IntegrationServersupportsthefollowingkindsoftransactions: Alocaltransaction(LOCAL_TRANSACTION)whichisatransactiontoaresources localtransactionmechanism AnXAResourcetransaction(XA_TRANSACTION)whichisatransactiontoa resourcesXAResourcetransactionmechanism IntegrationServercanautomaticallymanagebothkindsoftransactions,without requiringtheusertodoanything.Formoreinformationaboutimplicittransactions,see ImplicitandExplicitTransactionsonpage 119. However,therearecaseswhereusersneedtoexplicitlycontrolthetransactionalunitsof work.ExamplesofthesecasesareprovidedinImplicitandExplicitTransactionson page 119. Tosupporttransactions,theIntegrationServerreliesonabuiltinJ2EEbasedtransaction manager.Thetransactionmanagerisresponsibleforbeginningandendingtransactions, maintainingatransactioncontext,enlistingnewlyconnectedresourcesintoexisting transactions,andensuringthatlocalandXAResourcetransactionsarenotcombinedin illegalways. Thetransactionmanageronlymanagesoperationsperformedbyadapterservices,a transactedJMStrigger,orabuiltinJMSservicethatusesatransactedJMSconnection alias. Important! Youcannotsteportraceaflowthatcontainsatransactedadapterserviceora transactedJMSservice.
118
XA Transactions
IfanXAtransactionalconnectionthrowsanexceptionduringaservicetransactionand theexceptionresultsinaninconsistentstate,youmayneedtoresolvethetransaction usingthetoolsprovidedwiththedatabase. ForinformationaboutusingtheIntegrationServertomanageXAtransactions,seethe webMethodsIntegrationServerAdministratorsGuide.
Implicit and Explicit Transactions

ImplicittransactionsareautomaticallyhandledbyIntegrationServertransaction manager.Whenyoudefineanexplicittransaction,youdefinethestartoncompletion boundariesofthetransaction.Assuch,implicitandexplicittransactionsneedtobe createdandmanageddifferently. Thefollowingsectionsdescribeimplicitandexplicittransactionsandhowtomanage them.
Implicit Transactions
Withimplicittransactions,IntegrationServerautomaticallymanagesbothlocaland XAResourcetransactionswithoutrequiringyoutoexplicitlydoanything.Thatis,the IntegrationServerstartsandcompletesanimplicittransactionwithnoadditionalservice callsrequiredbytheuser. Atransactioncontext,whichthetransactionmanagerusestodefineaunitofwork,starts whenoneofthefollowingoccurs: Anadapterserviceisencounteredduringflowserviceexecution.Theconnection requiredbytheadapterserviceisregisteredwiththenewlycreatedcontextandused bytheadapterservice.Ifanotheradapterserviceisencountered,thetransaction contextissearchedtoseeiftheconnectionisalreadyregistered.Iftheconnectionis alreadyregistered,theadapterserviceusesthisconnection.Iftheconnectionisnot registered,anewconnectioninstanceisretrievedandregisteredwiththetransaction. IntegrationServerusesatransactedJMSconnectionaliastoreceivemessagesfrom theJMSproviderforaJMStrigger.AJMSconnectionaliasisconsideredtobe transactedwhenithasatransactiontypeofXATRANSACTIONorLOCAL TRANSACTION. AbuiltinJMSservicethatusesatransactedJMSconnectionaliastoconnecttothe JMSproviderisencounteredduringflowserviceexecution. Notethatifthetoplevelflowserviceinvokesanotherflow,servicesinthechildflowuse thesametransactioncontext. Whenthetoplevelflowservicecompletes,thetransactioniscompletedandiseither committedorrolledback,dependingonthestatus(successorfailure)ofthetoplevelflow serviceortheJMStriggerservice.
119
AsingletransactioncontextcancontainanynumberofXA_TRANSACTIONconnections butnomorethanoneLOCAL_TRANSACTIONconnection. Formoreinformationaboutdesigningandusingflows,seethewebMethodsDeveloper UsersGuide.
Explicit Transactions
Youuseexplicittransactionswhenyouneedtoexplicitlycontrolthetransactionalunitsof work.Todothis,youuseadditionalservices,knownasbuiltinservices,inyourflow. Atransactioncontextstartswhenthepub.art.transaction:startTransactionserviceisexecuted. Thetransactioncontextiscompletedwheneitherthepub.art.transaction:commitTransactionor pub.art.transaction:rollbackTransactionserviceisexecuted.Aswithimplicittransactions,asingle transactioncontextcancontainanynumberofXA_TRANSACTIONconnectionsbutno morethanoneLOCAL_TRANSACTIONconnection. Note: Withexplicittransactions,youmustbesuretocalleithera pub.art.transaction:commitTransactionorpub.art.transaction:rollbackTransactionforeach pub.art.transaction:startTransaction;otherwiseyouwillhavedanglingtransactionsthatwill requireyoutoreboottheIntegrationServer.Youmustalsoensurethatthe startTransactionisoutsidetheSEQUENCE. Anewexplicittransactioncontextcanbestartedwithinatransactioncontext,provided thatyouensurethatthetransactionswithinthetransactioncontextarecompletedinthe reverseordertheywerestartedthatis,thelasttransactiontostartshouldbethefirst transactiontocomplete,andsoforth. Forexample,considerthefollowingisavalidconstruct:
pub.art.transaction:startTransaction pub.art.transaction:startTransaction pub.art.transaction:startTransaction pub.art.transaction:commitTransaction pub.art.transaction:commitTransaction pub.art.transaction:commitTransaction
Thefollowingexampleshowsaninvalidconstruct:
pub.art.transaction:startTransaction pub.art.transaction:startTransaction pub.art.transaction:commitTransaction pub.art.transaction:commitTransaction
Note: Youcanusethepub.flow:getLastErrorserviceintheSEQUENCE,toretrievetheerror informationwhenasequencefails.Formoreinformationonusingthepub.flow:getLastError service,seethewebMethodsDeveloperUsersGuide. Formoreinformationaboutdesigningandusingflows,seethewebMethodsDeveloper UsersGuide.
120
Built-In Transaction Management Services

Thefollowingtableidentifieseachofthebuiltinservicesyoucanusefortransaction management. Service pub.art.transaction:commitTransaction Description Commitsanexplicittransaction.Itmustbeused inconjunctionwiththe pub.art.transaction:startTransactionservice.Ifitdoes nothaveacorresponding pub.art.transaction:startTransactionservice,yourflow servicewillreceivearuntimeerror Rollsbackanexplicittransaction.Itmustbeused inconjunctionwiththe pub.art.transaction:startTransactionservice.Ifitdoes nothaveacorresponding pub.art.transaction:startTransactionservice,yourflow servicewillreceivearuntimeerror. Manuallysetsatransactiontimeoutintervalfor implicitandexplicittransactions.Whenyouuse thisservice,youaretemporarilyoverridingthe IntegrationServertransactiontimeoutinterval. Startsanexplicittransaction.Itmustbeusedin conjunctionwitheithera pub.art.transaction:commitTransactionserviceor pub.art.transaction:rollbackTransactionservice.Ifitdoes nothaveacorresponding pub.art.transaction:commitTransactionserviceor pub.art.transaction:rollbackTransactionservice,your flowservicewillreceivearuntimeerror.
pub.art.transaction:rollbackTransaction
pub.art.transaction:setTransactionTimeout
pub.art.transaction:startTransaction
Formoreinformationaboutthetransactionmanagementservices,includingdetailed descriptionsoftheservicesignatures,seethewebMethodsIntegrationServerBuiltIn ServicesReference.
121
122

Web Methods Integration Server JMS Client Developer&#39;s Guide 7.1

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Web Methods Integration Server JMS Client Developer&#39;s Guide 7.1

Hochgeladen von

Copyright:

Verfügbare Formate

TitlePage

webMethods Integration Server JMS Client Developers Guide

Copyright & Docu mentID

Document ID: DEV-JMS-DG-71-20070928

Chapter 1. Configuring Integration Server for JMS Messaging . . . . . . . . . . . . . . . . . . . . .

Chapter 2. JMS Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Integration Server JMS Client Developers Guide Version 7.1

Chapter 3. Sending and Receiving JMS Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 4. Working with JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Integration Server JMS Client Developers Guide Version 7.1

Chapter 5. Building a Transacted JMS Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 6. Exactly-Once Processing for JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Integration Server JMS Client Developers Guide Version 7.1

Chapter 7. Managing JMS Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Appendix A. JMS Server Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Appendix B. Building a Resource Monitoring Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Appendix C. Transaction Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

webMethods Integration Server JMS Client Developers Guide Version 7.1

About This Guide

About This Guide

webMethods Integration Server JMS Client Developers Guide Version 7.1

About This Guide

webMethods Integration Server JMS Client Developers Guide Version 7.1

Chapter 1. Configuring Integration Server for JMS Messaging

webMethods Integration Server JMS Client Developers Guide Version 7.1

1. Configuring Integration Server for JMS Messaging

Working with JNDI Providers

Creating a JNDI Provider Alias

webMethods Integration Server JMS Client Developers Guide Version 7.1

1. Configuring Integration Server for JMS Messaging

In this field... JNDI Alias Name Description Predefined JNDI Templates

Initial Context Factory

TheclassnameoftheJNDIprovider.TheJNDIprovideruses theinitialcontextasthestartingpointforresolvingnamesfor naminganddirectoryoperations. IfyouselectedapredefinedJNDItemplate,IntegrationServer displaystheinitialcontextfactoryfortheprovider.

TheURLoftheinitialcontextforsessionswiththeJNDI provider.TheURLspecifiestheJNDIdirectoryinwhichthe JNDIproviderstoresJMSadministeredobjects. IfyouselectedapredefinedJNDItemplate,replacethe placeholderinformationinbrackets<<>>withinformation specifictoyourconfiguration.

Theprincipalname,orusernamesuppliedbyIntegration ServertotheJNDIprovider,iftheproviderrequiresonefor accessingtheJNDIdirectory ForinformationaboutwhetherornottheJNDIprovider requiressecurityprincipalinformation,consulttheproduct documentationfortheJNDIprovider.

webMethods Integration Server JMS Client Developers Guide Version 7.1

1. Configuring Integration Server for JMS Messaging

In this field... Security Credentials

Specify... Thecredentials,orpassword,thatIntegrationServerprovides totheJNDIprovider,iftheproviderrequiressecurity credentialstoaccesstheJNDIdirectory. ForinformationaboutwhetherornottheJNDIprovider requiressecuritycredentials,consulttheproduct documentationfortheJNDIprovider.

Editing a JNDI Provider Alias

webMethods Integration Server JMS Client Developers Guide Version 7.1

1. Configuring Integration Server for JMS Messaging

Deleting a JNDI Provider Alias

Performing a Test Lookup for a JNDI Provider

Working with JMS Connection Aliases

webMethods Integration Server JMS Client Developers Guide Version 7.1

1. Configuring Integration Server for JMS Messaging

Creating a JMS Connection Alias

webMethods Integration Server JMS Client Developers Guide Version 7.1

1. Configuring Integration Server for JMS Messaging

For this field...

Specify... LOCAL_TRANSACTION Indicatethatsessionsthatusethis JMSconnectionaliasarepartofalocal transaction. Indicatethatsessionsthatusethis JMSconnectionaliasarepartofanXA transaction.

Connection Client ID User (optional)

TheJMSclientidentifierassociatedwiththeconnections establishedbythisJMSconnectionalias. Usernameneededtoacquireaconnectionfromthe connectionfactory. FormoreinformationaboutwhetherornottheJMSprovider requiresausernameandpasswordtoobtainaconnection, refertotheproductdocumentationfortheJMSprovider.

Passwordneededtoacquireaconnectionfromtheconnection factory. FormoreinformationaboutwhetherornottheJMSprovider requiresausernameandpasswordtoobtainaconnection, refertotheproductdocumentationfortheJMSprovider.

Ifyouselected Native webMethods APIinstep6,dothefollowingintheremainingfields underConnection Protocol Settings:

webMethods Integration Server JMS Client Developers Guide Version 7.1

1. Configuring Integration Server for JMS Messaging

webMethods Integration Server JMS Client Developers Guide Version 7.1

1. Configuring Integration Server for JMS Messaging

For this field... Maximum CSQ Size (number of documents)

Drain CSQ in Order

Specifying a Retry Interval for Failed Connections

webMethods Integration Server JMS Client Developers Guide Version 7.1

Web Methods Integration Server JMS Client Developer's Guide 7.1

Web Methods Integration Server JMS Client Developer's Guide 7.1