Upload
others
View
10
Download
0
Embed Size (px)
Citation preview
1.1
1.2
1.3
1.4
1.5
1.6
1.7
1.8
1.9
1.10
1.11
1.12
1.13
1.14
1.15
1.16
1.17
1.18
1.19
1.20
1.21
1.22
1.23
1.24
1.25
1.26
1.27
TableofContentsIntroduction
LegalNotice
Preface
ProjectInfo
MessagingConcepts
Architecture
UsingtheServer
UsingJMS
UsingCore
MappingJMSConceptstotheCoreAPI
TheClientClasspath
Examples
RoutingMessagesWithWildCards
UnderstandingtheApacheActiveMQArtemisWildcardSyntax
FilterExpressions
Persistence
ConfiguringTransports
ConfigurationReload
DetectingDeadConnections
DetectingSlowConsumers
ResourceManagerConfiguration
FlowControl
Guaranteesofsendsandcommits
MessageRedeliveryandUndeliveredMessages
MessageExpiry
LargeMessages
Paging
1
1.28
1.29
1.30
1.31
1.32
1.33
1.34
1.35
1.36
1.37
1.38
1.39
1.40
1.41
1.42
1.43
1.44
1.45
1.46
1.47
1.48
1.49
1.50
1.51
1.52
1.53
1.54
1.55
1.56
1.57
QueueAttributes
ScheduledMessages
Last-ValueQueues
MessageGrouping
ExtraAcknowledgeModes
Management
Security
ResourceLimits
TheJMSBridge
ClientReconnectionandSessionReattachment
DivertingandSplittingMessageFlows
CoreBridges
DuplicateMessageDetection
Clusters
HighAvailabilityandFailover
GracefulServerShutdown
LibaioNativeLibraries
Threadmanagement
Logging
RESTInterface
EmbeddingApacheActiveMQArtemis
ApacheKaraf
SpringIntegration
AeroGearIntegration
VertXIntegration
InterceptingOperations
ProtocolsandInteroperability
Tools
MavenPlugin
TroubleshootingandPerformanceTuning
2
1.58ConfigurationReference
3
ApacheActiveMQArtemisUserManualTheUsermanualisanindepthmanualonallaspectsofApacheActiveMQArtemis
Introduction
4
LegalNoticeLicensedtotheApacheSoftwareFoundation(ASF)underoneormorecontributorlicenseagreements.SeetheNOTICEfiledistributedwiththisworkforadditionalinformationregardingcopyrightownership.TheASFlicensesthisfiletoYouundertheApacheLicense,Version2.0(the"License");youmaynotusethisfileexceptincompliancewiththeLicense.YoumayobtainacopyoftheLicenseat
http://www.apache.org/licenses/LICENSE-2.0
Unlessrequiredbyapplicablelaworagreedtoinwriting,softwaredistributedundertheLicenseisdistributedonan"ASIS"BASIS,WITHOUTWARRANTIESORCONDITIONSOFANYKIND,eitherexpressorimplied.SeetheLicenseforthespecificlanguagegoverningpermissionsandlimitationsundertheLicense.
LegalNotice
5
http://www.apache.org/licenses/LICENSE-2.0
PrefaceWhatisApacheActiveMQArtemis?
ApacheActiveMQArtemisisanopensourceprojecttobuildamulti-protocol,embeddable,veryhighperformance,clustered,asynchronousmessagingsystem.
ApacheActiveMQArtemisisanexampleofMessageOrientedMiddleware(MoM).ForadescriptionofMoMsandothermessagingconceptspleaseseetheMessagingConcepts.
ForanswerstomorequestionsaboutwhatApacheActiveMQArtemisisandwhatitisn'tpleasevisittheFAQswikipage.
WhyuseApacheActiveMQArtemis?Herearejustafewofthereasons:
100%opensourcesoftware.ApacheActiveMQArtemisislicensedusingtheApacheSoftwareLicensev2.0tominimisebarrierstoadoption.
ApacheActiveMQArtemisisdesignedwithusabilityinmind.
WritteninJava.RunsonanyplatformwithaJava8+runtime,that'severythingfromWindowsdesktopstoIBMmainframes.
Amazingperformance.Ourground-breakinghighperformancejournalprovidespersistentmessagingperformanceatratesnormallyseenfornon-persistentmessaging,ournon-persistentmessagingperformancerockstheboattoo.
Fullfeatureset.Allthefeaturesyou'dexpectinanyseriousmessagingsystem,andothersyouwon'tfindanywhereelse.
Elegant,clean-cutdesignwithminimalthirdpartydependencies.RunActiveMQArtemisstand-alone,runitinintegratedinyourfavouriteJEEapplicationserver,orrunitembeddedinsideyourownproduct.It'suptoyou.
Seamlesshighavailability.WeprovideaHAsolutionwithautomaticclientfailoversoyoucanguaranteezeromessagelossorduplicationineventofserverfailure.
Hugelyflexibleclustering.Createclustersofserversthatknowhowtoloadbalancemessages.Linkgeographicallydistributedclustersoverunreliableconnectionstoformaglobalnetwork.Configureroutingofmessagesinahighlyflexibleway.
Preface
6
Preface
7
ProjectInformationTheofficialApacheActiveMQArtemisprojectpageishttp://activemq.apache.org/artemis/.
SoftwareDownloadThesoftwarecanbedownloadfromtheDownloadpage:http://activemq.apache.org/download.html
ProjectInformationIfyouhaveanyuserquestionspleaseuseouruserforum
Ifyouhavedevelopmentrelatedquestions,pleaseuseourdeveloperforum
PopinandchattousinourIRCchannel
ApacheActiveMQArtemisGitrepositoryishttps://github.com/apache/activemq-artemis
Allreleasetagsareavailablefromhttps://github.com/apache/activemq-artemis/releases
Andmanythankstoallourcontributors,botholdandnewwhohelpedcreateApacheActiveMQArtemis.
ProjectInfo
8
http://activemq.apache.org/artemis/http://activemq.apache.org/download.htmlhttp://activemq.2283324.n4.nabble.com/ActiveMQ-User-f2341805.htmlhttp://activemq.2283324.n4.nabble.com/ActiveMQ-Dev-f2368404.htmlirc://irc.freenode.net:6667/apache-activemqhttps://github.com/apache/activemq-artemishttps://github.com/apache/activemq-artemis/releases
MessagingConceptsApacheActiveMQArtemisisanasynchronousmessagingsystem,anexampleofMessageOrientedMiddleware,we'lljustcallthemmessagingsystemsintheremainderofthisbook.
We'llfirstpresentabriefoverviewofwhatkindofthingsmessagingsystemsdo,wherethey'reusefulandthekindofconceptsyou'llhearaboutinthemessagingworld.
Ifyou'realreadyfamiliarwithwhatamessagingsystemisandwhatit'scapableof,thenyoucanskipthischapter.
MessagingConceptsMessagingsystemsallowyoutolooselycoupleheterogeneoussystemstogether,whilsttypicallyprovidingreliability,transactionsandmanyotherfeatures.
UnlikesystemsbasedonaRemoteProcedureCall(RPC)pattern,messagingsystemsprimarilyuseanasynchronousmessagepassingpatternwithnotightrelationshipbetweenrequestsandresponses.Mostmessagingsystemsalsosupportarequest-responsemodebutthisisnotaprimaryfeatureofmessagingsystems.
Designingsystemstobeasynchronousfromend-to-endallowsyoutoreallytakeadvantageofyourhardwareresources,minimizingtheamountofthreadsblockingonIOoperations,andtouseyournetworkbandwidthtoitsfullcapacity.WithanRPCapproachyouhavetowaitforaresponseforeachrequestyoumakesoarelimitedbythenetworkroundtriptime,orlatencyofyournetwork.Withanasynchronoussystemyoucanpipelineflowsofmessagesindifferentdirections,soarelimitedbythenetworkbandwidthnotthelatency.Thistypicallyallowsyoutocreatemuchhigherperformanceapplications.
Messagingsystemsdecouplethesendersofmessagesfromtheconsumersofmessages.Thesendersandconsumersofmessagesarecompletelyindependentandknownothingofeachother.Thisallowsyoutocreateflexible,looselycoupledsystems.
Often,largeenterprisesuseamessagingsystemtoimplementamessagebuswhichlooselycouplesheterogeneoussystemstogether.MessagebusesoftenformthecoreofanEnterpriseServiceBus.(ESB).Usingamessagebustode-coupledisparatesystems
MessagingConcepts
9
http://en.wikipedia.org/wiki/Message_oriented_middlewarehttp://en.wikipedia.org/wiki/Remote_procedure_callhttp://en.wikipedia.org/wiki/Enterprise_service_bus
canallowthesystemtogrowandadaptmoreeasily.Italsoallowsmoreflexibilitytoaddnewsystemsorretireoldonessincetheydon'thavebrittledependenciesoneachother.
MessagingstylesMessagingsystemsnormallysupporttwomainstylesofasynchronousmessaging:messagequeuemessaging(alsoknownaspoint-to-pointmessaging)andpublishsubscribemessaging.We'llsummarisethembrieflyhere:
TheMessageQueuePattern
Withthistypeofmessagingyousendamessagetoaqueue.Themessageisthentypicallypersistedtoprovideaguaranteeofdelivery,thensometimelaterthemessagingsystemdeliversthemessagetoaconsumer.Theconsumerthenprocessesthemessageandwhenitisdone,itacknowledgesthemessage.Oncethemessageisacknowledgeditdisappearsfromthequeueandisnotavailabletobedeliveredagain.Ifthesystemcrashesbeforethemessagingserverreceivesanacknowledgementfromtheconsumer,thenonrecovery,themessagewillbeavailabletobedeliveredtoaconsumeragain.
Withpoint-to-pointmessaging,therecanbemanyconsumersonthequeuebutaparticularmessagewillonlyeverbeconsumedbyamaximumofoneofthem.Senders(alsoknownasproducers)tothequeuearecompletelydecoupledfromreceivers(alsoknownasconsumers)ofthequeue-theydonotknowofeachother'sexistence.
Aclassicexampleofpointtopointmessagingwouldbeanorderqueueinacompany'sbookorderingsystem.Eachorderisrepresentedasamessagewhichissenttotheorderqueue.Let'simaginetherearemanyfrontendorderingsystemswhichsendorderstotheorderqueue.Whenamessagearrivesonthequeueitispersisted-thisensuresthatiftheservercrashestheorderisnotlost.Let'salsoimaginetherearemanyconsumersontheorderqueue-eachrepresentinganinstanceofanorderprocessingcomponent-thesecanbeondifferentphysicalmachinesbutconsumingfromthesamequeue.Themessagingsystemdeliverseachmessagetooneandonlyoneoftheorderingprocessingcomponents.Differentmessagescanbeprocessedbydifferentorderprocessors,butasingleorderisonlyprocessedbyoneorderprocessor-thisensuresordersaren'tprocessedtwice.
MessagingConcepts
10
http://en.wikipedia.org/wiki/Message_queuehttp://en.wikipedia.org/wiki/Publish_subscribe
Asanorderprocessorreceivesamessage,itfulfillstheorder,sendsorderinformationtothewarehousesystemandthenupdatestheorderdatabasewiththeorderdetails.Onceit'sdonethatitacknowledgesthemessagetotelltheserverthattheorderhasbeenprocessedandcanbeforgottenabout.Oftenthesendtothewarehousesystem,updateindatabaseandacknowledgementwillbecompletedinasingletransactiontoensureACIDproperties.
ThePublish-SubscribePattern
Withpublish-subscribemessagingmanysenderscansendmessagestoanentityontheserver,oftencalledatopic(e.g.intheJMSworld).
Therecanbemanysubscriptionsonatopic,asubscriptionisjustanotherwordforaconsumerofatopic.Eachsubscriptionreceivesacopyofeachmessagesenttothetopic.Thisdiffersfromthemessagequeuepatternwhereeachmessageisonlyconsumedbyasingleconsumer.
Subscriptionscanoptionallybedurablewhichmeanstheyretainacopyofeachmessagesenttothetopicuntilthesubscriberconsumesthem-eveniftheservercrashesorisrestartedinbetween.Non-durablesubscriptionsonlylastamaximumofthelifetimeoftheconnectionthatcreatedthem.
Anexampleofpublish-subscribemessagingwouldbeanewsfeed.Asnewsarticlesarecreatedbydifferenteditorsaroundtheworldtheyaresenttoanewsfeedtopic.Therearemanysubscribersaroundtheworldwhoareinterestedinreceivingnewsitems-eachonecreatesasubscriptionandthemessagingsystemensuresthatacopyofeachnewsmessageisdeliveredtoeachsubscription.
DeliveryguaranteesAkeyfeatureofmostmessagingsystemsisreliablemessaging.Withreliablemessagingtheservergivesaguaranteethatthemessagewillbedeliveredonceandonlyoncetoeachconsumerofaqueueoreachdurablesubscriptionofatopic,evenintheeventofsystemfailure.Thisiscrucialformanybusinesses;e.g.youdon'twantyourordersfulfilledmorethanonceoranyofyourorderstobelost.
Inothercasesyoumaynotcareaboutaonceandonlyoncedeliveryguaranteeandarehappytocopewithduplicatedeliveriesorlostmessages-anexampleofthismightbetransientstockpriceupdates-whicharequicklysupersededbythenextupdateonthe
MessagingConcepts
11
http://en.wikipedia.org/wiki/ACID
samestock.Themessagingsystemallowsyoutoconfigurewhichdeliveryguaranteesyourequire.
TransactionsMessagingsystemstypicallysupportthesendingandacknowledgementofmultiplemessagesinasinglelocaltransaction.ApacheActiveMQArtemisalsosupportsthesendingandacknowledgementofmessageaspartofalargeglobaltransaction-usingtheJavamappingofXA:JTA.
DurabilityMessagesareeitherdurableornondurable.Durablemessageswillbepersistedinpermanentstorageandwillsurviveserverfailureorrestart.Nondurablemessageswillnotsurviveserverfailureorrestart.Examplesofdurablemessagesmightbeordersortrades,wheretheycannotbelost.Anexampleofanondurablemessagemightbeastockpriceupdatewhichistransitoryanddoesn'tneedtosurvivearestart.
MessagingAPIsandprotocolsHowdoclientapplicationsinteractwithmessagingsystemsinordertosendandconsumemessages?
SeveralmessagingsystemsprovidetheirownproprietaryAPIswithwhichtheclientcommunicateswiththemessagingsystem.
Therearealsosomestandardwaysofoperatingwithmessagingsystemsandsomeemergingstandardsinthisspace.
Let'stakeabrieflookatthese:
JavaMessageService(JMS)
JMSispartofOracle'sJEEspecification.It'saJavaAPIthatencapsulatesbothmessagequeueandpublish-subscribemessagingpatterns.JMSisalowestcommondenominatorspecification-i.e.itwascreatedtoencapsulatecommonfunctionalityofthealreadyexistingmessagingsystemsthatwereavailableatthetimeofitscreation.
MessagingConcepts
12
http://en.wikipedia.org/wiki/Java_Message_Service
JMSisaverypopularAPIandisimplementedbymostmessagingsystems.JMSisonlyavailabletoclientsrunningJava.
JMSdoesnotdefineastandardwireformat-itonlydefinesaprogrammaticAPIsoJMSclientsandserversfromdifferentvendorscannotdirectlyinteroperatesinceeachwillusethevendor'sowninternalwireprotocol.
ApacheActiveMQArtemisprovidesafullycompliantJMS1.1andJMS2.0API.
SystemspecificAPIs
ManysystemsprovidetheirownprogrammaticAPIforwhichtointeractwiththemessagingsystem.Theadvantageofthisitallowsthefullsetofsystemfunctionalitytobeexposedtotheclientapplication.API'slikeJMSarenotnormallyrichenoughtoexposealltheextrafeaturesthatmostmessagingsystemsprovide.
ApacheActiveMQArtemisprovidesitsowncoreclientAPIforclientstouseiftheywishtohaveaccesstofunctionalityoverandabovethataccessibleviatheJMSAPI.
RESTfulAPI
RESTapproachestomessagingareshowingalotinterestrecently.
ItseemsplausiblethatAPIstandardsforcloudcomputingmayconvergeonaRESTstylesetofinterfacesandconsequentlyaRESTmessagingapproachisaverystrongcontenderforbecomingthede-factomethodformessaginginteroperability.
WithaRESTapproachmessagingresourcesaremanipulatedasresourcesdefinedbyaURIandtypicallyusingasimplesetofoperationsonthoseresources,e.g.PUT,POST,GETetc.RESTapproachestomessagingoftenuseHTTPastheirunderlyingprotocol.
TheadvantageofaRESTapproachwithHTTPisinitssimplicityandthefacttheinternetisalreadytunedtodealwithHTTPoptimally.
PleaseseeRestInterfaceforusingApacheActiveMQArtemis'sRESTfulinterface.
STOMP
Stompisaverysimpletextprotocolforinteroperatingwithmessagingsystems.Itdefinesawireformat,sotheoreticallyanyStompclientcanworkwithanymessagingsystemthatsupportsStomp.Stompclientsareavailableinmanydifferentprogramminglanguages.
MessagingConcepts
13
http://en.wikipedia.org/wiki/Representational_State_Transferhttp://stomp.github.io/
PleaseseeStompforusingSTOMPwithApacheActiveMQArtemis.
AMQP
AMQPisaspecificationforinteroperablemessaging.Italsodefinesawireformat,soanyAMQPclientcanworkwithanymessagingsystemthatsupportsAMQP.AMQPclientsareavailableinmanydifferentprogramminglanguages.
ApacheActiveMQArtemisimplementstheAMQP1.0specification.Anyclientthatsupportsthe1.0specificationwillbeabletointeractwithApacheActiveMQArtemis.
HighAvailabilityHighAvailability(HA)meansthatthesystemshouldremainoperationalafterfailureofoneormoreoftheservers.ThedegreeofsupportforHAvariesbetweenvariousmessagingsystems.
ApacheActiveMQArtemisprovidesautomaticfailoverwhereyoursessionsareautomaticallyreconnectedtothebackupserveroneventofliveserverfailure.
FormoreinformationonHA,pleaseseeHighAvailabilityandFailover.
ClustersManymessagingsystemsallowyoutocreategroupsofmessagingserverscalledclusters.Clustersallowtheloadofsendingandconsumingmessagestobespreadovermanyservers.Thisallowsyoursystemtoscalehorizontallybyaddingnewserverstothecluster.
Degreesofsupportforclustersvariesbetweenmessagingsystems,withsomesystemshavingfairlybasicclusterswiththeclustermembersbeinghardlyawareofeachother.
ApacheActiveMQArtemisprovidesveryconfigurablestate-of-the-artclusteringmodelwheremessagescanbeintelligentlyloadbalancedbetweentheserversinthecluster,accordingtothenumberofconsumersoneachnode,andwhethertheyarereadyformessages.
ApacheActiveMQArtemisalsohastheabilitytoautomaticallyredistributemessagesbetweennodesofaclustertopreventstarvationonanyparticularnode.
MessagingConcepts
14
http://en.wikipedia.org/wiki/AMQPhttps://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp
Forfulldetailsonclustering,pleaseseeClusters.
BridgesandroutingSomemessagingsystemsallowisolatedclustersorsinglenodestobebridgedtogether,typicallyoverunreliableconnectionslikeawideareanetwork(WAN),ortheinternet.
Abridgenormallyconsumesfromaqueueononeserverandforwardsmessagestoanotherqueueonadifferentserver.Bridgescopewithunreliableconnections,automaticallyreconnectingwhentheconnectionsbecomesavailableagain.
ApacheActiveMQArtemisbridgescanbeconfiguredwithfilterexpressionstoonlyforwardcertainmessages,andtransformationcanalsobehookedin.
ApacheActiveMQArtemisalsoallowsroutingbetweenqueuestobeconfiguredinserversideconfiguration.Thisallowscomplexroutingnetworkstobesetupforwardingorcopyingmessagesfromonedestinationtoanother,formingaglobalnetworkofinterconnectedbrokers.
FormoreinformationpleaseseeCoreBridgesandDivertingandSplittingMessageFlows.
MessagingConcepts
15
ArchitectureInthissectionwewillgiveanoverviewoftheApacheActiveMQArtemishighlevelarchitecture.
CoreArchitectureApacheActiveMQArtemiscoreisdesignedsimplyassetofPlainOldJavaObjects(POJOs)-wehopeyoulikeitsclean-cutdesign.
We'vealsodesignedittohaveasfewdependenciesonexternaljarsaspossible.Infact,ApacheActiveMQArtemiscorehasonlyonejardependency,netty.jar,otherthanthestandardJDKclasses!Thisisbecauseweusesomeofthenettybufferclassesinternally.
ThisallowsApacheActiveMQArtemistobeeasilyembeddedinyourownproject,orinstantiatedinanydependencyinjectionframeworksuchasSpringorGoogleGuice.
EachApacheActiveMQArtemisserverhasitsownultrahighperformancepersistentjournal,whichitusesformessageandotherpersistence.
Usingahighperformancejournalallowsoutrageouspersistencemessageperformance,somethingnotachievablewhenusingarelationaldatabaseforpersistence.
ApacheActiveMQArtemisclients,potentiallyondifferentphysicalmachinesinteractwiththeApacheActiveMQArtemisserver.ApacheActiveMQArtemiscurrentlyprovidestwoAPIsformessagingattheclientside:
1. CoreclientAPI.ThisisasimpleintuitiveJavaAPIthatallowsthefullsetofmessagingfunctionalitywithoutsomeofthecomplexitiesofJMS.
2. JMSclientAPI.ThestandardJMSAPIisavailableattheclientside.
ApacheActiveMQArtemisalsoprovidesdifferentprotocolimplementationsontheserversoyoucanuserespectiveclientsfortheseprotocols:
1. Stomp2. OpenWire3. AMQP
Architecture
16
JMSsemanticsareimplementedbyaJMSfacadelayerontheclientside.
TheApacheActiveMQArtemisserverdoesnotspeakJMSandinfactdoesnotknowanythingaboutJMS,itisaprotocolagnosticmessagingserverdesignedtobeusedwithmultipledifferentprotocols.
WhenauserusestheJMSAPIontheclientside,allJMSinteractionsaretranslatedintooperationsontheApacheActiveMQArtemiscoreclientAPIbeforebeingtransferredoverthewireusingtheApacheActiveMQArtemiswireformat.
TheserveralwaysjustdealswithcoreAPIinteractions.
Aschematicillustratingthisrelationshipisshowninfigure3.1below:
Architecture
17
Architecture
18
Figure3.1showstwouserapplicationsinteractingwithanApacheActiveMQArtemisserver.UserApplication1isusingtheJMSAPI,whileUserApplication2isusingthecoreclientAPIdirectly.
YoucanseefromthediagramthattheJMSAPIisimplementedbyathinfacadelayerontheclientside.
ApacheActiveMQArtemisembeddedinyourownapplicationApacheActiveMQArtemiscoreisdesignedasasetofsimplePOJOssoifyouhaveanapplicationthatrequiresmessagingfunctionalityinternallybutyoudon'twanttoexposethatasanApacheActiveMQArtemisserveryoucandirectlyinstantiateandembedApacheActiveMQArtemisserversinyourownapplication.
FormoreinformationonembeddingApacheActiveMQArtemis,seeEmbeddingApacheActiveMQArtemis.
ApacheActiveMQArtemisintegratedwithaJavaEEapplicationserverApacheActiveMQArtemisprovidesitsownfullyfunctionalJavaConnectorArchitecture(JCA)adaptorwhichenablesittobeintegratedeasilyintoanyJavaEEcompliantapplicationserverorservletengine.
JavaEEapplicationserversprovideMessageDrivenBeans(MDBs),whichareaspecialtypeofEnterpriseJavaBeans(EJBs)thatcanprocessmessagesfromsourcessuchasJMSsystemsormailsystems.
ProbablythemostcommonuseofanMDBistoconsumemessagesfromaJMSmessagingsystem.
AccordingtotheJavaEEspecification,aJavaEEapplicationserverusesaJCAadaptertointegratewithaJMSmessagingsystemsoitcanconsumemessagesforMDBs.
However,theJCAadapterisnotonlyusedbytheJavaEEapplicationserverforconsumingmessagesviaMDBs,itisalsousedwhensendingmessagetotheJMSmessagingsysteme.g.frominsideanEJBorservlet.
Architecture
19
WhenintegratingwithaJMSmessagingsystemfrominsideaJavaEEapplicationserveritisalwaysrecommendedthatthisisdoneviaaJCAadaptor.Infact,communicatingwithaJMSmessagingsystemdirectly,withoutusingJCAwouldbeillegalaccordingtotheJavaEEspecification.
Theapplicationserver'sJCAserviceprovidesextrafunctionalitysuchasconnectionpoolingandautomatictransactionenlistment,whicharedesirablewhenusingmessaging,say,frominsideanEJB.ItispossibletotalktoaJMSmessagingsystemdirectlyfromanEJB,MDBorservletwithoutgoingthroughaJCAadapter,butthisisnotrecommendedsinceyouwillnotbeabletotakeadvantageoftheJCAfeatures,suchascachingofJMSsessions,whichcanresultinpoorperformance.
Figure3.2belowshowsaJavaEEapplicationserverintegratingwithaApacheActiveMQArtemisserverviatheApacheActiveMQArtemisJCAadaptor.NotethatallcommunicationbetweenEJBsessionsorentitybeansandMessageDrivenbeansgothroughtheadaptorandnotdirectlytoApacheActiveMQArtemis.
ThelargearrowwiththeprohibitedsignshowsanEJBsessionbeantalkingdirectlytotheApacheActiveMQArtemisserver.Thisisnotrecommendedasyou'llmostlikelyendupcreatinganewconnectionandsessioneverytimeyouwanttointeractfromtheEJB,whichisananti-pattern.
Architecture
20
FormoreinformationonusingtheJCAadaptor,pleaseseeApplicationServerIntegrationandJavaEE.
Architecture
21
ApacheActiveMQArtemisstand-aloneserverApacheActiveMQArtemiscanalsobedeployedasastand-aloneserver.ThismeansafullyindependentmessagingservernotdependentonaJavaEEapplicationserver.
Thestandardstand-alonemessagingserverconfigurationcomprisesacoremessagingserverandaJMSservice.
TheroleoftheJMSServiceistodeployanyJMSQueue,TopicandConnectionFactoryinstancesfromanyserversideJMSconfiguration.ItalsoprovidesasimplemanagementAPIforcreatinganddestroyingQueuesandTopicswhichcanbeaccessedviaJMXortheconnection.ItisaseparateservicetotheActiveMQArtemiscoreserver,sincethecoreserverisJMSagnostic.Ifyoudon'twanttodeployanyJMSQueueorTopicviaserversideXMLconfigurationanddon'trequireaJMSmanagementAPIontheserversidethenyoucandisablethisservice.
Thestand-aloneserverconfigurationusesAirlineforbootstrappingtheBroker.
Thestand-aloneserverarchitectureisshowninfigure3.3below:
Architecture
22
https://github.com/airlift/airline
FormoreinformationonserverconfigurationfilesseeServerConfiguration
Architecture
23
Architecture
24
UsingtheServerThischapterwillfamiliariseyouwithhowtousetheApacheActiveMQArtemisserver.
We'llshowwhereitis,howtostartandstopit,andwe'lldescribethedirectorylayoutandwhatallthefilesareandwhattheydo.
FortheremainderofthischapterwhenwetalkabouttheApacheActiveMQArtemisserverwemeantheApacheActiveMQArtemisstandaloneserver,initsdefaultconfigurationwithaJMSServiceenabled.
ThisdocumentwillrefertothefullpathofthedirectorywheretheActiveMQdistributionhasbeenextractedtoas${ARTEMIS_HOME}directory.
InstallationAfterdownloadingthedistribution,thefollowinghighlightssomeimportantfoldersonthedistribution:
|___bin||___web||___user-manual||___api||___examples||___core||___javaee||___jms||___lib||___schema
bin--binariesandscriptsneededtorunActiveMQArtemis.
web--ThefolderwherethewebcontextisloadedwhenActiveMQArtemisruns.
user-manual--Theusermanualisplacedunderthewebfolder.
api--Theapidocumentationisplacedunderthewebfolder
UsingtheServer
25
examples--JMSandJavaEEexamples.Pleaserefertothe'runningexamples'chapterfordetailsonhowtorunthem.
lib--jarsandlibrariesneededtorunActiveMQArtemis
licenses--licensesforActiveMQArtemis
schemas--XMLSchemasusedtovalidateActiveMQArtemisconfigurationfiles
CreatingaBrokerInstanceAbrokerinstanceisthedirectorycontainingalltheconfigurationandruntimedata,suchaslogsanddatafiles,associatedwithabrokerprocess.Itisrecommendedthatyoudonotcreatetheinstancedirectoryunder${ARTEMIS_HOME}.ThisseparationisencouragedsothatyoucanmoreeasilyupgradewhenthenextversionofActiveMQArtemisisreleased.
OnUnixsystems,itisacommonconventiontostorethiskindofruntimedataunderthe/var/libdirectory.Forexample,tocreateaninstanceat'/var/lib/mybroker',runthefollowingcommandsinyourcommandlineshell:
cd/var/lib${ARTEMIS_HOME}/bin/artemiscreatemybroker
Abrokerinstancedirectorywillcontainthefollowingsubdirectories:
bin:holdsexecutionscriptsassociatedwiththisinstance.etc:holdtheinstanceconfigurationfilesdata:holdsthedatafilesusedforstoringpersistentmessageslog:holdsrotatinglogfilestmp:holdstemporaryfilesthataresafetodeletebetweenbrokerruns
Atthispointyoumaywanttoadjustthedefaultconfigurationlocatedintheetcdirectory.
Options
Thereareseveraloptionsyoucanusewhencreatinganinstance.
Forafulllistofupdatedpropertiesalwaysuse:
UsingtheServer
26
$./artemishelpcreateNAMEartemiscreate-createsanewbrokerinstance
SYNOPSISartemiscreate[--allow-anonymous][--cluster-password][--cluster-user][--clustered][--data][--encoding][--force][--home][--host][--java-options][--password][--port-offset][--replicated][--role][--shared-store][--silent][--user][--]
OPTIONS--allow-anonymousEnablesanonymousconfigurationonsecurity(Default:input)
--cluster-passwordTheclusterpasswordtouseforclustering.(Default:input)
--cluster-userTheclusterusertouseforclustering.(Default:input)
--clusteredEnableclustering
--dataDirectorywhereActiveMQDataisused.Patharerelativetoartemis.instance/bin
--encodingTheencodingthattextfilesshoulduse
--forceOverwriteconfigurationatdestinationdirectory
--homeDirectorywhereActiveMQArtemisisinstalled
--hostThehostnameofthebroker(Default:0.0.0.0orinputifclustered)
--java-optionsExtrajavaoptionstobepassedtotheprofile
--passwordTheuser'spassword(Default:input)
--port-offset
UsingtheServer
27
Offsetsthedefaultports
--replicatedEnablebrokerreplication
--roleThenamefortherolecreated(Default:amq)
--shared-storeEnablebrokersharedstore
--silentItwilldisablealltheinputs,anditwouldmakeabestguessforanyrequiredinput
--userTheusername(Default:input)
--Thisoptioncanbeusedtoseparatecommand-lineoptionsfromthelistofargument,(usefulwhenargumentsmightbemistakenforcommand-lineoptions
Theinstancedirectorytoholdthebroker'sconfigurationanddata
Someofthesepropertiesmaybemandatoryincertainconfigurationsandthesystemmayaskyouforadditionalinput.
UsingtheServer
28
./artemiscreate/usr/serverCreatingActiveMQArtemisinstanceat:/user/server
--user:ismandatorywiththisconfiguration:Pleaseprovidethedefaultusername:admin
--password:ismandatorywiththisconfiguration:Pleaseprovidethedefaultpassword:
--allow-anonymous:ismandatorywiththisconfiguration:Allowanonymousaccess?(Y/N):y
Youcannowstartthebrokerbyexecuting:
"/user/server/bin/artemis"run
Oryoucanrunthebrokerinthebackgroundusing:
"/user/server/bin/artemis-service"start
StartingandStoppingaBrokerInstance
Assumingyoucreatedthebrokerinstanceunder/var/lib/mybrokerallyouneedtodostartrunningthebrokerinstanceisexecute:
/var/lib/mybroker/bin/artemisrun
Nowthatthebrokerisrunning,youcanoptionallyrunsomeoftheincludedexamplestoverifythethebrokerisrunningproperly.
TostoptheApacheActiveMQArtemisinstanceyouwillusethesameartemisscript,butwiththestopargument.Example:
/var/lib/mybroker/bin/artemisstop
PleasenotethatApacheActiveMQArtemisrequiresaJava7orlaterruntimetorun.
Bydefaulttheetc/bootstrap.xmlconfigurationisused.Theconfigurationcanbechangede.g.byrunning./artemisrun--xml:path/to/bootstrap.xmloranotherconfigofyourchoosing.
UsingtheServer
29
Environmentvariablesareusedtoprovideeaseofchangingports,hostsanddatadirectoriesusedandcanbefoundinetc/artemis.profileonlinuxandetc\artemis.profile.cmdonWindows.
ServerJVMsettingsTherunscriptssetsomeJVMsettingsfortuningthegarbagecollectionpolicyandheapsize.WerecommendusingaparallelgarbagecollectionalgorithmtosmoothoutlatencyandminimiselargeGCpauses.
BydefaultApacheActiveMQArtemisrunsinamaximumof1GiBofRAM.Toincreasethememorysettingschangethe-Xmsand-XmxmemorysettingsasyouwouldforanyJavaprogram.
IfyouwishtoaddanymoreJVMargumentsortunetheexistingones,therunscriptsaretheplacetodoit.
Pre-configuredOptionsThedistributioncontainsseveralstandardconfigurationsetsforrunning:
Nonclusteredstand-alone.
Clusteredstand-alone
Replicatedstand-alone
Shared-storestand-alone
Youcanofcoursecreateyourownconfigurationandspecifyanyconfigurationwhenrunningtherunscript.
LibraryPathIfyou'reusingtheAsynchronousIOJournalonLinux,youneedtospecifyjava.library.pathasapropertyonyourJavaoptions.Thisisdoneautomaticallyinthescripts.
Ifyoudon'tspecifyjava.library.pathatyourJavaoptionsthentheJVMwillusetheenvironmentvariableLD_LIBRARY_PATH.
UsingtheServer
30
YouwillneedtomakesurelibaioisinstalledonLinux.FormoreinformationrefertothelibaiochapteratRuntimeDependencies
SystempropertiesApacheActiveMQArtemiscantakeasystempropertyonthecommandlineforconfiguringlogging.
Formoreinformationonconfiguringlogging,pleaseseethesectiononLogging.
ConfigurationfilesTheconfigurationfileusedtobootstraptheserver(e.g.bootstrap.xmlbydefault)referencesthespecificbrokerconfigurationfiles.
broker.xml.ThisisthemainActiveMQconfigurationfile.Alltheparametersinthisfilearedescribedhere
Itisalsopossibletousesystempropertysubstitutioninalltheconfigurationfiles.byreplacingavaluewiththenameofasystemproperty.Hereisanexampleofthiswithaconnectorconfiguration:
tcp://${activemq.remoting.netty.host:localhost}:${activemq.remoting.netty.port:61616}
Hereyoucanseewehavereplaced2valueswithsystempropertiesactivemq.remoting.netty.hostandactivemq.remoting.netty.port.Thesevalueswillbereplacedbythevaluefoundinthesystempropertyifthereisone,ifnottheydefaultbacktolocalhostor61616respectively.Itisalsopossibletonotsupplyadefault.i.e.${activemq.remoting.netty.host},howeverthesystempropertymustbesuppliedinthatcase.
BootstrapFileThestand-aloneserverisbasicallyasetofPOJOswhichareinstantiatedbyAirlinecommands.
Thebootstrapfileisverysimple.Let'stakealookatanexample:
UsingtheServer
31
core-Instantiatesacoreserverusingtheconfigurationfilefromtheconfigurationattribute.ThisisthemainbrokerPOJOnecessarytodoalltherealmessagingwork.InadditionallJMSobjectssuchas:Queues,TopicsandConnectionFactoryinstancesareconfiguredhere.
Themainconfigurationfile.TheconfigurationfortheApacheActiveMQArtemiscoreserveriscontainedinbroker.xml.ThisiswhattheFileConfigurationbeanusestoconfigurethemessagingserver.
TherearemanyattributeswhichyoucanconfigureApacheActiveMQArtemis.Inmostcasesthedefaultswilldofine,infacteveryattributecanbedefaultedwhichmeansafilewithasingleemptyconfigurationelementisavalidconfigurationfile.Thedifferentconfigurationwillbeexplainedthroughoutthemanualoryoucanrefertotheconfigurationreferencehere.
WindowsServerOnwindowsyouwillhavetheoptiontorunActiveMQArtemisasaservice.Justusethefollowingcommandtoinstallit:
$./artemis-service.exeinstall
Thecreateprocessshouldgiveyouahintoftheavailablecommandsavailablefortheartemis-service.exe
UsingtheServer
32
UsingtheServer
33
UsingJMSAlthoughApacheActiveMQArtemisprovidesaJMSagnosticmessagingAPI,manyuserswillbemorecomfortableusingJMS.
JMSisaverypopularAPIstandardformessaging,andmostmessagingsystemsprovideaJMSAPI.IfyouarecompletelynewtoJMSwesuggestyoufollowtheOracleJMStutorial-afullJMStutorialisoutofscopeforthisguide.
ApacheActiveMQArtemisalsoshipswithawiderangeofexamples,manyofwhichdemonstrateJMSAPIusage.AgoodplacetostartwouldbetoplayaroundwiththesimpleJMSQueueandTopicexample,butwealsoprovideexamplesformanyotherpartsoftheJMSAPI.AfulldescriptionoftheexamplesisavailableinExamples.
Inthissectionwe'llgothroughthemainstepsinconfiguringtheserverforJMSandcreatingasimpleJMSprogram.We'llalsoshowhowtoconfigureanduseJNDI,andalsohowtouseJMSwithApacheActiveMQArtemiswithoutusinganyJNDI.
AsimpleorderingsystemForthischapterwe'regoingtouseaverysimpleorderingsystemasourexample.Itisasomewhatcontrivedexamplebecauseofitsextremesimplicity,butitservestodemonstratetheverybasicsofsettingupandusingJMS.
WewillhaveasingleJMSQueuecalledOrderQueue,andwewillhaveasingleMessageProducersendinganordermessagetothequeueandasingleMessageConsumerconsumingtheordermessagefromthequeue.
Thequeuewillbeadurablequeue,i.e.itwillsurviveaserverrestartorcrash.Wealsowanttopre-deploythequeue,i.e.specifythequeueintheserverconfigurationsoitiscreatedautomaticallywithoutushavingtoexplicitlycreateitfromtheclient.
JNDIConfiguration
UsingJMS
34
http://docs.oracle.com/javaee/7/tutorial/partmessaging.htm
TheJMSspecificationestablishestheconventionthatadministeredobjects(i.e.JMSqueue,topicandconnectionfactoryinstances)aremadeavailableviatheJNDIAPI.BrokersarefreetoimplementJNDIastheyseefitassumingtheimplementationfitstheAPI.ApacheActiveMQArtemisdoesnothaveaJNDIserver.Rather,itusesaclient-sideJNDIimplementationthatreliesonspecialpropertiessetintheenvironmenttoconstructtheappropriateJMSobjects.Inotherwords,noobjectsarestoredinJNDIontheApacheActiveMQArtemisserver,insteadtheyaresimplyinstantiatedontheclientbasedontheprovidedconfiguration.Let'slookatthedifferentkindsofadministeredobjectsandhowtoconfigurethem.
Note
ThefollowingconfigurationpropertiesarestrictlyrequiredwhenApacheActiveMQArtemisisrunninginstand-alonemode.WhenApacheActiveMQArtemisisintegratedtoanapplicationserver(e.g.Wildfly)theapplicationserveritselfwillalmostcertainlyprovideaJNDIclientwithitsownproperties.
ConnectionFactoryJNDIAJMSconnectionfactoryisusedbytheclienttomakeconnectionstotheserver.Itknowsthelocationoftheserveritisconnectingto,aswellasmanyotherconfigurationparameters.
Here'sasimpleexampleoftheJNDIcontextenvironmentforaclientlookingupaconnectionfactorytoaccessanembeddedinstanceofApacheActiveMQArtemis:
java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactoryconnectionFactory.invmConnectionFactory=vm://0
InthisinstancewehavecreatedaconnectionfactorythatisboundtoinvmConnectionFactory,anyentrywithprefixconnectionFactory.willcreateaconnectionfactory.
IncertainsituationstherecouldbemultipleserverinstancesrunningwithinaparticularJVM.InthatsituationeachserverwouldtypicallyhaveanInVMacceptorwithauniqueserver-ID.AclientusingJMSandJNDIcanaccountforthisbyspecifyingaconnctionfactoryforeachserver,likeso:
UsingJMS
35
java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactoryconnectionFactory.invmConnectionFactory0=vm://0connectionFactory.invmConnectionFactory1=vm://1connectionFactory.invmConnectionFactory2=vm://2
HereisalistofallthesupportedURLschemes:
vm
tcp
udp
jgroups
Mostclientswon'tbeconnectingtoanembeddedbroker.Clientswillmostcommonlyconnectacrossanetworkaremotebroker.Here'sasimpleexampleofaclientconfiguringaconnectionfactorytoconnecttoaremotebrokerrunningonmyhost:5445:
java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactoryconnectionFactory.ConnectionFactory=tcp://myhost:5445
IntheexampleabovetheclientisusingthetcpschemefortheproviderURL.Aclientmayalsospecifymultiplecomma-delimitedhost:portcombinationsintheURL(e.g.(tcp://remote-host1:5445,remote-host2:5445)).Whetherthereisoneormanyhost:portcombinationsintheURLtheyaretreatedastheinitialconnector(s)fortheunderlyingconnection.
Theudpschemeisalsosupportedwhichshoulduseahost:portcombinationthatmatchesthegroup-addressandgroup-portfromthecorrespondingbroadcast-groupconfiguredontheActiveMQArtemisserver(s).
EachschemehasaspecificsetofpropertieswhichcanbesetusingthetraditionalURLquerystringformat(e.g.scheme://host:port?key1=value1&key2=value2)tocustomizetheunderlyingtransportmechanism.Forexample,ifaclientwantedtoconnecttoaremoteserverusingTCPandSSLitwouldcreateaconnectionfactorylikeso,tcp://remote-host:5445?ssl-enabled=true.
AllthepropertiesavailableforthetcpschemearedescribedinthedocumentationregardingtheNettytransport.
UsingJMS
36
Noteifyouareusingthetcpschemeandmultipleaddressesthenaquerycanbeappliedtoalltheurl'sorjusttoanindividualconnector,sowhereyouhave
(tcp://remote-host1:5445?httpEnabled=true,remote-host2:5445?httpEnabled=true)?
clientID=1234
thenthehttpEnabledpropertyisonlysetontheindividualconnectorswhereastheclientIdissetontheactualconnectionfactory.AnyconnectorspecificpropertiessetonthewholeURIwillbeappliedtoalltheconnectors.
Theudpschemesupports4properties:
localAddress-Ifyouarerunningwithmultiplenetworkinterfacesonthesamemachine,youmaywanttospecifythatthediscoverygrouplistensonlyonlyaspecificinterface.Todothisyoucanspecifytheinterfaceaddresswiththisparameter.
localPort-Ifyouwanttospecifyalocalporttowhichthedatagramsocketisboundyoucanspecifyithere.Normallyyouwouldjustusethedefaultvalueof-1whichsignifiesthatananonymousportshouldbeused.ThisparameterisalwaysspecifiedinconjunctionwithlocalAddress.
refreshTimeout-Thisistheperiodthediscoverygroupwaitsafterreceivingthelastbroadcastfromaparticularserverbeforeremovingthatserversconnectorpairentryfromitslist.Youwouldnormallysetthistoavaluesignificantlyhigherthanthebroadcast-periodonthebroadcastgroupotherwiseserversmightintermittentlydisappearfromthelisteventhoughtheyarestillbroadcastingduetoslightdifferencesintiming.Thisparameterisoptional,thedefaultvalueis10000milliseconds(10seconds).
discoveryInitialWaitTimeout-Iftheconnectionfactoryisusedimmediatelyaftercreationthenitmaynothavehadenoughtimetoreceivedbroadcastsfromallthenodesinthecluster.Onfirstusage,theconnectionfactorywillmakesureitwaitsthislongsincecreationbeforecreatingthefirstconnection.Thedefaultvalueforthisparameteris10000milliseconds.
Lastly,thejgroupsschemeissupportedwhichprovidesanalternativetotheudpschemeforserverdiscovery.TheURLpatterniseitherjgroups://channelName?file=jgroups-xml-conf-filenamewherejgroups-xml-conf-filenamereferstoanXMLfileontheclasspaththatcontainstheJGroupsconfigurationoritcanbejgroups://channelName?properties=some-jgroups-properties.InbothinstancethechannelNameisthenamegiventothejgroupschannelcreated.
UsingJMS
37
TherefreshTimeoutanddiscoveryInitialWaitTimeoutpropertiesaresupportedjustlikewithudp.
Thedefaulttypeforthedefaultconnectionfactoryisoftypejavax.jms.ConnectionFactory.Thiscanbechangedbysettingthetypelikeso
java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactoryjava.naming.provider.url=tcp://localhost:5445?type=CF
Inthisexampleitisstillsettothedefault,belowshowsalistoftypesthatcanbeset.
ConfigurationforConnectionFactoryTypes
type interface
CF(default) javax.jms.ConnectionFactory
XA_CF javax.jms.XAConnectionFactory
QUEUE_CF javax.jms.QueueConnectionFactory
QUEUE_XA_CF javax.jms.XAQueueConnectionFactory
TOPIC_CF javax.jms.TopicConnectionFactory
TOPIC_XA_CF javax.jms.XATopicConnectionFactory
DestinationJNDI
JMSdestinationsarealsotypicallylookedupviaJNDI.Aswithconnectionfactories,destinationscanbeconfiguredusingspecialpropertiesintheJNDIcontextenvironment.Thepropertynameshouldfollowthepattern:queue.ortopic..ThepropertyvalueshouldbethenameofthequeuehostedbytheApacheActiveMQArtemisserver.Forexample,iftheserverhadaJMSqueueconfiguredlikeso:
Andiftheclientwantedtobindthisqueueto"queues/OrderQueue"thentheJNDIpropertieswouldbeconfiguredlikeso:
UsingJMS
38
java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactoryjava.naming.provider.url=tcp://myhost:5445queue.queues/OrderQueue=OrderQueue
Itisalsopossibletolook-upJMSdestinationswhichhaven'tbeenconfiguredexplicitlyintheJNDIcontextenvironment.ThisispossibleusingdynamicQueues/ordynamicTopics/inthelook-upstring.Forexample,iftheclientwantedtolook-uptheaforementioned"OrderQueue"itcoulddososimplybyusingthestring"dynamicQueues/OrderQueue".Note,thetextthatfollowsdynamicQueues/ordynamicTopics/mustcorrespondexactlytothenameofthedestinationontheserver.
Thecode
Here'sthecodefortheexample:
Firstwe'llcreateaJNDIinitialcontextfromwhichtolookupourJMSobjects.Iftheabovepropertiesaresetinjndi.propertiesanditisontheclasspaththenanynew,emptyInitialContextwillbeinitializedusingthoseproperties:
UsingJMS
39
InitialContextic=newInitialContext();
//Nowwe'lllookuptheconnectionfactoryfromwhichwecancreate//connectionstomyhost:5445:
ConnectionFactorycf=(ConnectionFactory)ic.lookup("ConnectionFactory");
//AndlookuptheQueue:
QueueorderQueue=(Queue)ic.lookup("queues/OrderQueue");
//NextwecreateaJMSconnectionusingtheconnectionfactory:
Connectionconnection=cf.createConnection();
//AndwecreateanontransactedJMSSession,withAUTO\_ACKNOWLEDGE//acknowledgemode:
Sessionsession=connection.createSession(false,Session.AUTO_ACKNOWLEDGE);
//WecreateaMessageProducerthatwillsendorderstothequeue:
MessageProducerproducer=session.createProducer(orderQueue);
//AndwecreateaMessageConsumerwhichwillconsumeordersfromthe//queue:
MessageConsumerconsumer=session.createConsumer(orderQueue);
//Wemakesurewestarttheconnection,ordeliverywon'toccuronit:
connection.start();
//WecreateasimpleTextMessageandsendit:
TextMessagemessage=session.createTextMessage("Thisisanorder");producer.send(message);
//Andweconsumethemessage:
TextMessagereceivedMessage=(TextMessage)consumer.receive();System.out.println("Gotorder:"+receivedMessage.getText());
Itisassimpleasthat.ForawiderangeofworkingJMSexamplespleaseseetheexamplesdirectoryinthedistribution.
UsingJMS
40
Warning
PleasenotethatJMSconnections,sessions,producersandconsumersaredesignedtobere-used.
Itisananti-patterntocreatenewconnections,sessions,producersandconsumersforeachmessageyouproduceorconsume.Ifyoudothis,yourapplicationwillperformverypoorly.ThisisdiscussedfurtherinthesectiononperformancetuningPerformanceTuning.
DirectlyinstantiatingJMSResourceswithoutusingJNDI
AlthoughitisaverycommonJMSusagepatterntolookupJMSAdministeredObjects(that'sJMSQueue,TopicandConnectionFactoryinstances)fromJNDI,insomecasesyoujustthink"WhydoIneedJNDI?Whycan'tIjustinstantiatetheseobjectsdirectly?"
WithApacheActiveMQArtemisyoucandoexactlythat.ApacheActiveMQArtemissupportsthedirectinstantiationofJMSQueue,TopicandConnectionFactoryinstances,soyoudon'thavetouseJNDIatall.
Forafullworkingexampleofdirectinstantiationpleaselookatthe"InstantiateJMSObjectsDirectly"exampleundertheJMSsectionoftheexamples.SeetheExamplessectionformoreinfo.
Here'soursimpleexample,rewrittentonotuseJNDIatall:
WecreatetheJMSConnectionFactoryobjectviatheActiveMQJMSClientUtilityclass,noteweneedtoprovideconnectionparametersandspecifywhichtransportweareusing,formoreinformationonconnectorspleaseseeConfiguringtheTransport.
UsingJMS
41
TransportConfigurationtransportConfiguration=newTransportConfiguration(NettyConnectorFactory.class.getName());
ConnectionFactorycf=ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF,transportConfiguration);
//WealsocreatetheJMSQueueobjectviatheActiveMQJMSClientUtility//class:
QueueorderQueue=ActiveMQJMSClient.createQueue("OrderQueue");
//NextwecreateaJMSconnectionusingtheconnectionfactory:
Connectionconnection=cf.createConnection();
//AndwecreateanontransactedJMSSession,withAUTO\_ACKNOWLEDGE//acknowledgemode:
Sessionsession=connection.createSession(false,Session.AUTO_ACKNOWLEDGE);
//WecreateaMessageProducerthatwillsendorderstothequeue:
MessageProducerproducer=session.createProducer(orderQueue);
//AndwecreateaMessageConsumerwhichwillconsumeordersfromthe//queue:
MessageConsumerconsumer=session.createConsumer(orderQueue);
//Wemakesurewestarttheconnection,ordeliverywon'toccuronit:
connection.start();
//WecreateasimpleTextMessageandsendit:
TextMessagemessage=session.createTextMessage("Thisisanorder");producer.send(message);
//Andweconsumethemessage:
TextMessagereceivedMessage=(TextMessage)consumer.receive();System.out.println("Gotorder:"+receivedMessage.getText());
SettingTheClientID
ThisrepresentstheclientidforaJMSclientandisneededforcreatingdurablesubscriptions.ItispossibletoconfigurethisontheconnectionfactoryandcanbesetviatheclientIdelement.Anyconnectioncreatedbythisconnectionfactorywillhavethis
UsingJMS
42
setasitsclientid.
SettingTheBatchSizeforDUPS_OK
WhentheJMSacknowledgemodeissettoDUPS_OKitispossibletoconfiguretheconsumersothatitsendsacknowledgementsinbatchesratherthatoneatatime,savingvaluablebandwidth.ThiscanbeconfiguredviatheconnectionfactoryviathedupsOkBatchSizeelementandissetinbytes.Thedefaultis1024*1024bytes=1MiB.
SettingTheTransactionBatchSize
Whenreceivingmessagesinatransactionitispossibletoconfiguretheconsumertosendacknowledgementsinbatchesratherthanindividuallysavingvaluablebandwidth.ThiscanbeconfiguredontheconnectionfactoryviathetransactionBatchSizeelementandissetinbytes.Thedefaultis1024*1024.
UsingJMS
43
UsingCoreApacheActiveMQArtemiscoreisacompletelyJMS-agnosticmessagingsystemwithitsownnon-JMSAPI.WecallthisthecoreAPI.
Ifyoudon'twanttouseJMSyoucanusethecoreAPIdirectly.ThecoreAPIprovidesallthefunctionalityofJMSbutwithoutmuchofthecomplexity.ItalsoprovidesfeaturesthatarenotavailableusingJMS.
CoreMessagingConceptsSomeofthecoremessagingconceptsaresimilartoJMSconcepts,butcoremessagingconceptsdifferinsomeways.IngeneralthecoremessagingAPIissimplerthantheJMSAPI,sinceweremovedistinctionsbetweenqueues,topicsandsubscriptions.We'lldiscusseachofthemajorcoremessagingconceptsinturn,buttoseetheAPIindetail,pleaseconsulttheJavadoc.
Message
Amessageistheunitofdatawhichissentbetweenclientsandservers.
Amessagehasabodywhichisabuffercontainingconvenientmethodsforreadingandwritingdataintoit.
Amessagehasasetofpropertieswhicharekey-valuepairs.Eachpropertykeyisastringandpropertyvaluescanbeoftypeinteger,long,short,byte,byte[],String,double,floatorboolean.
Amessagehasanaddressitisbeingsentto.Whenthemessagearrivesontheserveritisroutedtoanyqueuesthatareboundtotheaddress-ifthequeuesareboundwithanyfilter,themessagewillonlyberoutedtothatqueueifthefiltermatches.Anaddressmayhavemanyqueuesboundtoitorevennone.Theremayalsobeentitiesotherthanqueues,likedivertsboundtoaddresses.
Messagescanbeeitherdurableornondurable.Durablemessagesinadurablequeuewillsurviveaservercrashorrestart.Nondurablemessageswillneversurviveaservercrashorrestart.
UsingCore
44
Messagescanbespecifiedwithapriorityvaluebetween0and9.0representsthelowestpriorityand9representsthehighest.ApacheActiveMQArtemiswillattempttodeliverhigherprioritymessagesbeforelowerpriorityones.
Messagescanbespecifiedwithanoptionalexpirytime.ApacheActiveMQArtemiswillnotdelivermessagesafteritsexpirytimehasbeenexceeded.
Messagesalsohaveanoptionaltimestampwhichrepresentsthetimethemessagewassent.
ApacheActiveMQArtemisalsosupportsthesending/consumingofverylargemessagesmuchlargerthancanfitinavailableRAMatanyonetime.
Address
Aservermaintainsamappingbetweenanaddressandasetofqueues.Zeroormorequeuescanbeboundtoasingleaddress.Eachqueuecanbeboundwithanoptionalmessagefilter.Whenamessageisrouted,itisroutedtothesetofqueuesboundtothemessage'saddress.Ifanyofthequeuesareboundwithafilterexpression,thenthemessagewillonlyberoutedtothesubsetofboundqueueswhichmatchthatfilterexpression.
Otherentities,suchasdivertscanalsobeboundtoanaddressandmessageswillalsoberoutedthere.
Note
Incore,thereisnoconceptofaTopic,TopicisaJMSonlyterm.Instead,incore,wejustdealwithaddressesandqueues.
Forexample,aJMStopicwouldbeimplementedbyasingleaddresstowhichmanyqueuesarebound.Eachqueuerepresentsasubscriptionofthetopic.AJMSQueuewouldbeimplementedasasingleaddresstowhichonequeueisbound-thatqueuerepresentstheJMSqueue.
Queue
Queuescanbedurable,meaningthemessagestheycontainsurviveaservercrashorrestart,aslongasthemessagesinthemaredurable.Nondurablequeuesdonotsurviveaserverrestartorcrashevenifthemessagestheycontainaredurable.
UsingCore
45
Queuescanalsobetemporary,meaningtheyareautomaticallydeletedwhentheclientconnectionisclosed,iftheyarenotexplicitlydeletedbeforethat.
Queuescanbeboundwithanoptionalfilterexpression.Ifafilterexpressionissuppliedthentheserverwillonlyroutemessagesthatmatchthatfilterexpressiontoanyqueuesboundtotheaddress.
Manyqueuescanbeboundtoasingleaddress.Aparticularqueueisonlyboundtoamaximumofoneaddress.
ServerLocator
ClientsuseServerLocatorinstancestocreateClientSessionFactoryinstances.ServerLocatorinstancesareusedtolocateserversandcreateconnectionstothem.
InJMStermsthinkofaServerLocatorinthesamewayyouwouldaJMSConnectionFactory.
ServerLocatorinstancesarecreatedusingtheActiveMQClientfactoryclass.
ClientSessionFactory
ClientsuseClientSessionFactoryinstancestocreateClientSessioninstances.ClientSessionFactoryinstancesarebasicallytheconnectiontoaserver
InJMStermsthinkofthemasJMSConnections.
ClientSessionFactoryinstancesarecreatedusingtheServerLocatorclass.
ClientSession
AclientusesaClientSessionforconsumingandproducingmessagesandforgroupingthemintransactions.ClientSessioninstancescansupportbothtransactionalandnontransactionalsemanticsandalsoprovideanXAResourceinterfacesomessagingoperationscanbeperformedaspartofaJTAtransaction.
ClientSessioninstancesgroupClientConsumersandClientProducers.
ClientSessioninstancescanberegisteredwithanoptionalSendAcknowledgementHandler.Thisallowsyourclientcodetobenotifiedasynchronouslywhensentmessageshavesuccessfullyreachedtheserver.ThisuniqueApacheActiveMQArtemisfeature,allowsyoutohavefullguaranteesthatsentmessageshavereachedtheserverwithouthaving
UsingCore
46
http://www.oracle.com/technetwork/java/javaee/tech/jta-138684.html
toblockoneachmessagesentuntilaresponseisreceived.Blockingoneachmessagessentiscostlysinceitrequiresanetworkroundtripforeachmessagesent.BynotblockingandreceivingsendacknowledgementsasynchronouslyyoucancreatetrueendtoendasynchronoussystemswhichisnotpossibleusingthestandardJMSAPI.FormoreinformationonthisadvancedfeaturepleaseseethesectionGuaranteesofsendsandcommits.
ClientConsumer
ClientsuseClientConsumerinstancestoconsumemessagesfromaqueue.CoreMessagingsupportsbothsynchronousandasynchronousmessageconsumptionsemantics.ClientConsumerinstancescanbeconfiguredwithanoptionalfilterexpressionandwillonlyconsumemessageswhichmatchthatexpression.
ClientProducer
ClientscreateClientProducerinstancesonClientSessioninstancessotheycansendmessages.ClientProducerinstancescanspecifyanaddresstowhichallsentmessagesarerouted,ortheycanhavenospecifiedaddress,andtheaddressisspecifiedatsendtimeforthemessage.
Warning
PleasenotethatClientSession,ClientProducerandClientConsumerinstancesaredesignedtobere-used.
It'sananti-patterntocreatenewClientSession,ClientProducerandClientConsumerinstancesforeachmessageyouproduceorconsume.Ifyoudothis,yourapplicationwillperformverypoorly.ThisisdiscussedfurtherinthesectiononperformancetuningPerformanceTuning.
AsimpleexampleofusingCoreHere'saverysimpleprogramusingthecoremessagingAPItosendandreceiveamessage.Logicallyit'scomprisedoftwosections:firstlysettinguptheproducertowriteamessagetoanaddresss,andsecondly,creatingaqueuefortheconsumer,creatingtheconsumerandstartingit.
UsingCore
47
ServerLocatorlocator=ActiveMQClient.createServerLocatorWithoutHA(newTransportConfiguration(InVMConnectorFactory.class.getName()));
//Inthissimpleexample,wejustuseonesessionforbothproducingandreceiving
ClientSessionFactoryfactory=locator.createClientSessionFactory();ClientSessionsession=factory.createSession();
//Aproducerisassociatedwithanaddress...
ClientProducerproducer=session.createProducer("example");ClientMessagemessage=session.createMessage(true);message.getBodyBuffer().writeString("Hello");
//Weneedaqueueattachedtotheaddress...
session.createQueue("example","example",true);
//Andaconsumerattachedtothequeue...
ClientConsumerconsumer=session.createConsumer("example");
//Oncewehaveaqueue,wecansendthemessage...
producer.send(message);
//Weneedtostartthesessionbeforewecan-receive-messages...
session.start();ClientMessagemsgReceived=consumer.receive();
System.out.println("message="+msgReceived.getBodyBuffer().readString());
session.close();
UsingCore
48
MappingJMSConceptstotheCoreAPIThischapterdescribeshowJMSdestinationsaremappedtoApacheActiveMQArtemisaddresses.
ApacheActiveMQArtemiscoreisJMS-agnostic.ItdoesnothaveanyconceptofaJMStopic.AJMStopicisimplementedincoreasanaddress(thetopicname)withzeroormorequeuesboundtoit.Eachqueueboundtothataddressrepresentsatopicsubscription.Likewise,aJMSqueueisimplementedasanaddress(theJMSqueuename)withonesinglequeueboundtoitwhichrepresentstheJMSqueue.
Byconvention,allJMSqueuesmaptocorequeueswherethecorequeuenamehasthestringjms.queue.prependedtoit.E.g.theJMSqueuewiththename"orders.europe"wouldmaptothecorequeuewiththename"jms.queue.orders.europe".Theaddressatwhichthecorequeueisboundisalsogivenbythecorequeuename.
ForJMStopicstheaddressatwhichthequeuesthatrepresentthesubscriptionsareboundisgivenbyprependingthestring"jms.topic."tothenameoftheJMStopic.E.g.theJMStopicwithname"news.europe"wouldmaptothecoreaddress"jms.topic.news.europe"
InotherwordsifyousendaJMSmessagetoaJMSqueuewithname"orders.europe"itwillgetroutedontheservertoanycorequeuesboundtotheaddress"jms.queue.orders.europe".IfyousendaJMSmessagetoaJMStopicwithname"news.europe"itwillgetroutedontheservertoanycorequeuesboundtotheaddress"jms.topic.news.europe".
IfyouwanttoconfiguresettingsforaJMSQueuewiththename"orders.europe",youneedtoconfigurethecorrespondingcorequeue"jms.queue.orders.europe":
jms.queue.expiry.europe...
MappingJMSConceptstotheCoreAPI
49
TheClientClasspathApacheActiveMQArtemisrequiresseveraljarsontheClientClasspathdependingonwhethertheclientusesApacheActiveMQArtemisCoreAPI,JMS,andJNDI.
Warning
AllthejarsmentionedherecanbefoundinthelibdirectoryoftheApacheActiveMQArtemisdistribution.Besureyouonlyusethejarsfromthecorrectversionoftherelease,youmustnotmixandmatchversionsofjarsfromdifferentApacheActiveMQArtemisversions.Mixingandmatchingdifferentjarversionsmaycausesubtleerrorsandfailurestooccur.
ApacheActiveMQArtemisCoreClientIfyouareusingjustapureApacheActiveMQArtemisCoreclient(i.e.noJMS)thenyouneedactivemq-core-client.jar,activemq-commons.jar,andnetty.jaronyourclientclasspath.
JMSClientIfyouareusingJMSontheclientside,thenyouwillalsoneedtoincludeactivemq-jms-client.jarandgeronimo-jms_2.0_spec.jar.
Note
geronimo-jms_2.0_spec.jarjustcontainsJavaEEAPIinterfaceclassesneededforthejavax.jms.*classes.Ifyoualreadyhaveajarwiththeseinterfaceclassesonyourclasspath,youwillnotneedit.
TheClientClasspath
50
ExamplesTheApacheActiveMQArtemisdistributioncomeswithover90runout-of-the-boxexamplesdemonstratingmanyofthefeatures.
Theexamplesareavailableinboththebinaryandsourcedistributionundertheexamplesdirectory.Examplesaresplitbythefollowingsourcetree:
features-Examplescontainingbrokerspecificfeatures.ha-examplesshowingfailoverandreconnectioncapabilities.clustered-examplesshowingloadbalancinganddistributioncapabilities.perf-examplesallowingyoutorunafewperformancetestsontheserversub-modules-examplesofintegratedexternalmodules.
protocols-Protocolspecificexamplesopenwiremqttstompamqp
AsetofJavaEEexamplesarealsoprovidedwhichneedWildFlyinstalledtobeabletorun.
RunnningtheExamplesTorunanyexample,simplycdintotheappropriateexampledirectoryandtypemvnverifyormvninstall(Fordetailspleasereadthereadme.htmlineachexampledirectory).
Youcanusetheprofile-Pexamplestorunmultipleexamplesunderanyexampletree.
Foreachserver,youwillhaveacreatedserverunder./target/server0(someexamplesusemorethanoneserver).
Youhavetheoptiontopreventtheexamplefromstartingtheserver(e.g.ifyouwanttostarttheservermanually)bysimplyspecifyingthe-PnoServerprofile,e.g.:
#runninganexamplewithoutrunningtheservermvnverify-PnoServer
Examples
51
Alsounder./targettherewillbeascriptrepeatingthecommandstocreateeachserver.Hereisthecreate-server0.shgeneratedbytheQueueexample.Thisisusefultoseeexactlywhatcommand(s)arerequiredtoconfiguretheserver(s).
#Thesearethecommandsusedtocreateserver0/myInstallDirectory/apache-artemis-1.1.0/bin/artemiscreate--allow-anonymous--silent--force--no-web--userguest--passwordguest--roleguest--port-offset0--data./data--allow-anonymous--no-autotune--verbose/myInstallDirectory/apache-artemis-1.1.0/examples/features/standard/queue/target/server0
SeveralexamplesuseUDPclusteringwhichmaynotworkinyourenvironmentbydefault.Onlinuxthecommandwouldbe:
routeadd-net224.0.0.0netmask240.0.0.0devlo
Thiscommandshouldberunasroot.Thiswillredirectanytrafficdirectedto224.0.0.0totheloopbackinterface.OnMacOSX,thecommandisslightlydifferent:
sudorouteadd224.0.0.0127.0.0.1-netmask240.0.0.0
AlltheexamplesusetheMavenplugin,whichcanbeusefulforrunningyourtestserversaswell.
Thisisthecommonoutputwhenrunninganexample.OnthiscasetakenfromtheQueueexample:
[INFO]Scanningforprojects...[INFO][INFO]------------------------------------------------------------------------[INFO]BuildingActiveMQArtemisJMSQueueExample1.1.0[INFO]------------------------------------------------------------------------[INFO][INFO]---maven-enforcer-plugin:1.4:enforce(enforce-java)@queue---[INFO][INFO]---maven-remote-resources-plugin:1.5:process(default)@queue---[INFO][INFO]---maven-resources-plugin:2.6:resources(default-resources)@queue---[INFO]Using'UTF-8'encodingtocopyfilteredresources.[INFO]Copying1resource[INFO]Copying3resources[INFO][INFO]---maven-compiler-plugin:3.1:compile(default-compile)@queue---[INFO]Changesdetected-recompilingthemodule![INFO]Compiling1sourcefileto/work/apache-artemis-1.1.0/examples/features/sta
Examples
52
ndard/queue/target/classes[INFO][INFO]---maven-checkstyle-plugin:2.16:check(default)@queue---[INFO][INFO]---apache-rat-plugin:0.11:check(default)@queue---[INFO]RATwillnotexecutesinceitisconfiguredtobeskippedviasystemproperty'rat.skip'.[INFO][INFO]---maven-resources-plugin:2.6:testResources(default-testResources)@queue---[INFO]Using'UTF-8'encodingtocopyfilteredresources.[INFO]skipnonexistingresourceDirectory/work/apache-artemis-1.1.0/examples/features/standard/queue/src/test/resources[INFO]Copying3resources[INFO][INFO]---maven-compiler-plugin:3.1:testCompile(default-testCompile)@queue---[INFO]Nosourcestocompile[INFO][INFO]---maven-surefire-plugin:2.18.1:test(default-test)@queue---[INFO][INFO]---maven-jar-plugin:2.4:jar(default-jar)@queue---[INFO]Buildingjar:/work/apache-artemis-1.1.0/examples/features/standard/queue/target/queue-1.1.0.jar[INFO][INFO]---maven-site-plugin:3.3:attach-descriptor(attach-descriptor)@queue---[INFO][INFO]>>>maven-source-plugin:2.2.1:jar(attach-sources)>generate-sources@queue>>>[INFO][INFO]---maven-enforcer-plugin:1.4:enforce(enforce-java)@queue---[INFO][INFO]generate-sources@queue>>>[INFO][INFO]---maven-enforcer-plugin:1.4:enforce(enforce-java)@queue---[INFO][INFO]always]
Examples
53
[INFO]Entries.size2[INFO]...key=project=MavenProject:org.apache.activemq.examples.broker:queue:1.1.0@/work/apache-artemis-1.1.0/examples/features/standard/queue/pom.xml[INFO]...key=pluginDescriptor=ComponentDescriptor:role:'org.apache.maven.plugin.Mojo',implementation:'org.apache.activemq.artemis.maven.ArtemisCLIPlugin',rolehint:'org.apache.activemq:artemis-maven-plugin:1.1.0:cli'role:'org.apache.maven.plugin.Mojo',implementation:'org.apache.activemq.artemis.maven.ArtemisCreatePlugin',rolehint:'org.apache.activemq:artemis-maven-plugin:1.1.0:create'role:'org.apache.maven.plugin.Mojo',implementation:'org.apache.activemq.artemis.maven.ArtemisClientPlugin',rolehint:'org.apache.activemq:artemis-maven-plugin:1.1.0:runClient'---Executingorg.apache.activemq.artemis.cli.commands.Createcreate--allow-anonymous--silent--force--no-web--userguest--passwordguest--roleguest--port-offset0--data./data--allow-anonymous--no-autotune--verbose/work/apache-artemis-1.1.0/examples/features/standard/queue/target/server0Home::/work/apache-artemis-1.1.0/examples/features/standard/queue/../../../..,Instance::.CreatingActiveMQArtemisinstanceat:/work/apache-artemis-1.1.0/examples/features/standard/queue/target/server0
Youcannowstartthebrokerbyexecuting:
"/work/apache-artemis-1.1.0/examples/features/standard/queue/target/server0/bin/artemis"run
Oryoucanrunthebrokerinthebackgroundusing:
"/work/apache-artemis-1.1.0/examples/features/standard/queue/target/server0/bin/artemis-service"start
[INFO]###################################################################################################[INFO]create-server0.shcreatedwithcommandstoreproduceserver0[INFO]under/work/apache-artemis-1.1.0/examples/features/standard/queue/target[INFO]###################################################################################################[INFO][INFO]---artemis-maven-plugin:1.1.0:cli(start)@queue---[INFO]awaitingservertostart[INFO]awaitingservertostartserver-out:___server-out:/\____||________(_)_____server-out:/_\|_\__|/_\\/||/__/server-out:/___\|\/|_/__/|\/|||\___\server-out:/_/\_\|\__\____|_||_|_|/___/server-out:ApacheActiveMQArtemis1.1.0server-out:server-out:server-out:17:30:25,091INFO[org.apache.activemq.artemis.integration.bootstrap]
Examples
54
AMQ101000:StartingActiveMQArtemisServerserver-out:17:30:25,120INFO[org.apache.activemq.artemis.core.server]AMQ221000:liveMessageBrokerisstartingwithconfigurationBrokerConfiguration(clustered=false,journalDirectory=./data/journal,bindingsDirectory=./data/bindings,largeMessagesDirectory=./data/large-messages,pagingDirectory=./data/paging)server-out:17:30:25,152INFO[org.apache.activemq.artemis.core.server]AMQ221013:UsingNIOJournalserver-out:17:30:25,195INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-server].Addingprotocolsupportfor:COREserver-out:17:30:25,199INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-amqp-protocol].Addingprotocolsupportfor:AMQPserver-out:17:30:25,209INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-hornetq-protocol].Addingprotocolsupportfor:HORNETQserver-out:17:30:25,211INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-mqtt-protocol].Addingprotocolsupportfor:MQTTserver-out:17:30:25,214INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-openwire-protocol].Addingprotocolsupportfor:OPENWIREserver-out:17:30:25,335INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-stomp-protocol].Addingprotocolsupportfor:STOMP[INFO]awaitingservertostartserver-out:17:30:25,781INFO[org.apache.activemq.artemis.core.server]AMQ221003:tryingtodeployqueuejms.queue.DLQserver-out:17:30:25,835INFO[org.apache.activemq.artemis.core.server]AMQ221003:tryingtodeployqueuejms.queue.ExpiryQueueserver-out:17:30:25,933INFO[org.apache.activemq.artemis.core.server]AMQ221020:StartedAcceptorat0.0.0.0:61616forprotocols[CORE,MQTT,AMQP,HORNETQ,STOMP,OPENWIRE]server-out:17:30:25,936INFO[org.apache.activemq.artemis.core.server]AMQ221020:StartedAcceptorat0.0.0.0:5445forprotocols[HORNETQ,STOMP]server-out:17:30:25,939INFO[org.apache.activemq.artemis.core.server]AMQ221020:StartedAcceptorat0.0.0.0:5672forprotocols[AMQP]server-out:17:30:25,944INFO[org.apache.activemq.artemis.core.server]AMQ221020:StartedAcceptorat0.0.0.0:1883forprotocols[MQTT]server-out:17:30:25,948INFO[org.apache.activemq.artemis.core.server]AMQ221020:StartedAcceptorat0.0.0.0:61613forprotocols[STOMP]server-out:17:30:25,949INFO[org.apache.activemq.artemis.core.server]AMQ221007:Serverisnowliveserver-out:17:30:25,949INFO[org.apache.activemq.artemis.core.server]AMQ221001:ApacheActiveMQArtemisMessageBrokerversion1.1.0[nodeID=a855176b-50f0-11e5-937e-2fe9bb000966][INFO]Serverstarted[INFO][INFO]---artemis-maven-plugin:1.1.0:runClient(runClient)@queue---Sentmessage:ThisisatextmessageReceivedmessage:Thisisatextmessage[INFO][INFO]---artemis-maven-plugin:1.1.0:cli(stop)@queue---server-out:17:30:27,476INFO[org.apache.activemq.artemis.core.server]AMQ221002:ApacheActiveMQArtemisMessageBrokerversion1.0.1-SNA
Examples
55
[INFO]------------------------------------------------------------------------[INFO]BUILDSUCCESS[INFO]------------------------------------------------------------------------[INFO]Totaltime:7.840s[INFO]Finishedat:2015-09-01T17:30:27-04:00[INFO]FinalMemory:42M/508M[INFO]------------------------------------------------------------------------
ListThisincludesapreviewlistofafewexamplesthatwedistributewithArtemis.Pleaserefertothedistributionforamoreaccuratelist.
AppletThisexampleshowsyouhowtosendandreceiveJMSmessagesfromanApplet.
Application-LayerFailoverApacheActiveMQArtemisalsosupportsApplication-Layerfailover,usefulinthecasethatreplicationisnotenabledontheserverside.
WithApplication-Layerfailover,it'suptotheapplicationtoregisteraJMSExceptionListenerwithApacheActiveMQArtemiswhichwillbecalledbyApacheActiveMQArtemisintheeventthatconnectionfailureisdetected.
ThecodeintheExceptionListenerthenrecreatestheJMSconnection,session,etconanothernodeandtheapplicationcancontinue.
Application-layerfailoverisanalternativeapproachtoHighAvailability(HA).Application-layerfailoverdiffersfromautomaticfailoverinthatsomeclientsidecodingisrequiredinordertoimplementthis.Also,withApplication-layerfailover,sincetheoldsessionobjectdiesandanewoneiscreated,anyuncommittedworkintheoldsessionwillbelost,andanyunacknowledgedmessagesmightberedelivered.
CoreBridgeExample
Examples
56
Thebridgeexampledemonstratesacorebridgedeployedononeserver,whichconsumesmessagesfromalocalqueueandforwardsthemtoanaddressonasecondserver.
CorebridgesareusedtocreatemessageflowsbetweenanytwoApacheActiveMQArtemisserverswhichareremotelyseparated.Corebridgesareresilientandwillcopewithtemporaryconnectionfailureallowingthemtobeanidealchoiceforforwardingoverunreliableconnections,e.g.aWAN.
BrowserThebrowserexampleshowsyouhowtouseaJMSQueueBrowserwithApacheActiveMQArtemis.
QueuesareastandardpartofJMS,pleaseconsulttheJMS1.1specificationforfulldetails.
AQueueBrowserisusedtolookatmessagesonthequeuewithoutremovingthem.Itcanscantheentirecontentofaqueueoronlymessagesmatchingamessageselector.
ClientKickoffTheclient-kickoffexampleshowshowtoterminateclientconnectionsgivenanIPaddressusingtheJMXmanagementAPI.
ClientsidefailoverlistenerTheclient-side-failoverlistenerexampleshowshowtoregisteralistenertomonitorfailoverevents
Client-SideLoad-BalancingTheclient-side-load-balancingexampledemonstrateshowsessionscreatedfromasingleJMSConnectioncanbecreatedtodifferentnodesofthecluster.InotherwordsitdemonstrateshowApacheActiveMQArtemisdoesclient-sideload-balancingofsessionsacrossthecluster.
Examples
57
ClusteredDurableSubscriptionThisexampledemonstratesaclusteredJMSdurablesubscription
ClusteredGroupingThisissimilartothemessagegroupingexampleexceptthatitdemonstratesitworkingoveracluster.Messagessenttodifferentnodeswiththesamegroupidwillbesenttothesamenodeandthesameconsumer.
ClusteredQueueTheclustered-queueexampledemonstratesaJMSqueuedeployedontwodifferentnodes.Thetwonodesareconfiguredtoformacluster.Wethencreateaconsumerforthequeueoneachnode,andwecreateaproducerononlyoneofthenodes.Wethensendsomemessagesviatheproducer,andweverifythatbothconsumersreceivethesentmessagesinaround-robinfashion.
ClusteringwithJGroupsTheclustered-jgroupsexampledemonstrateshowtoformatwonodeclusterusingJGroupsasitsunderlyingtopologydiscoverytechnique,ratherthanthedefaultUDPbroadcasting.Wethencreateaconsumerforthequeueoneachnode,andwecreateaproducerononlyoneofthenodes.Wethensendsomemessagesviatheproducer,andweverifythatbothconsumersreceivethesentmessagesinaround-robinfashion.
ClusteredStandaloneTheclustered-standaloneexampledemonstrateshowtoconfigureandstarts3clusternodesonthesamemachinetoformacluster.AsubscriberforaJMStopiciscreatedoneachnode,andwecreateaproducerononlyoneofthenodes.Wethensendsomemessagesviatheproducer,andweverifythatthe3subscribersreceiveallthesentmessages.
Examples
58
ClusteredStaticDiscoveryThisexampledemonstrateshowtoconfigureaclusterusingalistofconnectorsratherthanUDPfordiscovery
ClusteredStaticClusterOneWayThisexampledemonstrateshowtosetupaclusterwhereclusterconnectionsareoneway,i.e.serverA->ServerB->ServerC
ClusteredTopicTheclustered-topicexampledemonstratesaJMStopicdeployedontwodifferentnodes.Thetwonodesareconfiguredtoformacluster.Wethencreateasubscriberonthetopiconeachnode,andwecreateaproducerononlyoneofthenodes.Wethensendsomemessagesviatheproducer,andweverifythatbothsubscribersreceiveallthesentmessages.
MessageConsumerRateLimitingWithApacheActiveMQArtemisyoucanspecifyamaximumconsumerateatwhichaJMSMessageConsumerwillconsumemessages.Thiscanbespecifiedwhencreatingordeployingtheconnectionfactory.
IfthisvalueisspecifiedthenApacheActiveMQArtemiswillensurethatmessagesareneverconsumedataratehigherthanthespecifiedrate.Thisisaformofconsumerthrottling.
DeadLetterThedead-letterexampleshowsyouhowtodefineanddealwithdeadlettermessages.Messagescanbedeliveredunsuccessfully(e.g.ifthetransactedsessionusedtoconsumethemisrolledback).
Examples
59
SuchamessagegoesbacktotheJMSdestinationreadytoberedelivered.However,thismeansitispossibleforamessagetobedeliveredagainandagainwithoutanysuccessandremaininthedestination,cloggingthesystem.
Topreventthis,messagingsystemsdefinedeadlettermessages:afteraspecifiedunsuccessfuldeliveryattempts,themessageisremovedfromthedestinationandputinsteadinadeadletterdestinationwheretheycanbeconsumedforfurtherinvestigation.
DelayedRedeliveryThedelayed-redeliveryexampledemonstrateshowApacheActiveMQArtemiscanbeconfiguredtoprovideadelayedredeliveryinthecaseamessageneedstoberedelivered.
Delayingredeliverycanoftenbeusefulinthecasethatclientsregularlyfailorroll-back.Withoutadelayedredelivery,thesystemcangetintoa"thrashing"state,withdeliverybeingattempted,theclientrollingback,anddeliverybeingre-attemptedinquicksuccession,usingupvaluableCPUandnetworkresources.
DivertApacheActiveMQArtemisdivertsallowmessagestobetransparently"diverted"orcopiedfromoneaddresstoanotherwithjustsomesimpleconfigurationdefinedontheserverside.
DurableSubscriptionThedurable-subscriptionexampleshowsyouhowtouseadurablesubscriptionwithApacheActiveMQArtemis.DurablesubscriptionsareastandardpartofJMS,pleaseconsulttheJMS1.1specificationforfulldetails.
Unlikenon-durablesubscriptions,thekeyfunctionofdurablesubscriptionsisthatthemessagescontainedinthempersistlongerthanthelifetimeofthesubscriber-i.e.theywillaccumulatemessagessenttothetopicevenifthereisnoactivesubscriberonthem.Theywillalsosurviveserverrestartsorcrashes.Notethatforthemessagestobepersisted,themessagessenttothemmustbemarkedasdurablemessages.
Examples
60
EmbeddedTheembeddedexampleshowshowtoembedJMSwithinyourowncodeusingPOJOinstantiationandnoconfigfiles.
EmbeddedSimpleTheembeddedexampleshowshowtoembedJMSwithinyourowncodeusingregularApacheActiveMQArtemisXMLfiles.
MessageExpirationTheexpiryexampleshowsyouhowtodefineanddealwithmessageexpiration.Messagescanberetainedinthemessagingsystemforalimitedperiodoftimebeforebeingremoved.JMSspecificationstatesthatclientsshouldnotreceivemessagesthathavebeenexpired(butitdoesnotguaranteethiswillnothappen).
ApacheActiveMQArtemiscanassignanexpiryaddresstoagivenqueuesothatwhenmessagesareexpired,theyareremovedfromthequeueandsenttotheexpiryaddress.These"expired"messagescanlaterbeconsumedfromtheexpiryaddressforfurtherinspection.
ApacheActiveMQArtemisResourceAdapterexampleThisexamplesshowshowtobuildtheactivemqresourceadaptersararfordeploymentinotherApplicationServer's
HTTPTransportThehttp-transportexampleshowsyouhowtoconfigureApacheActiveMQArtemistousetheHTTPprotocolasitstransportlayer.
InstantiateJMSObjectsDirectly
Examples
61
Usually,JMSObjectssuchasConnectionFactory,QueueandTopicinstancesarelookedupfromJNDIbeforebeingusedbytheclientcode.Thisobjectsarecalled"administeredobjects"inJMSterminology.
However,insomecasesaJNDIservermaynotbeavailableordesired.TocometotherescueApacheActiveMQArtemisalsosupportsthedirectinstantiationoftheseadministeredobjectsontheclientsidesoyoudon'thavetouseJNDIforJMS.
InterceptorApacheActiveMQArtemisallowsanapplicationtouseaninterceptortohookintothemessagingsystem.InterceptorsallowyoutohandlevariousmessageeventsinApacheActiveMQArtemis.
JAASThejaasexampleshowsyouhowtoconfigureApacheActiveMQArtemistouseJAASforsecurity.ApacheActiveMQArtemiscanleverageJAAStodelegateuserauthenticationandauthorizationtoexistingsecurityinfrastructure.
JMSAutoClosableThejms-auto-closeableexampleshowshowJMSresources,suchasconnections,sessionsandconsumers,inJMS2canbeautomaticallyclosedonerror.
JMSCompletionListenerThejms-completion-listenerexampleshowshowtosendamessageasynchronouslytoApacheActiveMQArtemisanduseaCompletionListenertobenotifiedoftheBrokerreceivingit.
JMSBridgeThejms-brigdeexampleshowshowtosetupabridgebetweentwostandaloneApacheActiveMQArtemisservers.
Examples
62
JMSContextThejms-contextexampleshowshowtosendandreceiveamessagetoaJMSQueueusingApacheActiveMQArtemisbyusingaJMSContext.
AJMSContextispartofJMS2.0andcombinestheJMSConnectionandSessionObjectsintoasimpleInterface.
JMSSharedConsumerThejms-shared-consumerexampleshowsyouhowcanusesharedconsumerstoshareasubscriptiononatopic.InJMS1.1thiswasnotallowedandsocausedascalabilityissue.InJMS2thisrestrictionhasbeenliftedsoyoucansharetheloadacrossdifferentthreadsandconnections.
JMXManagementThejmxexampleshowshowtomanageApacheActiveMQArtemisusingJMX.
LargeMessageThelarge-messageexampleshowsyouhowtosendandreceiveverylargemessageswithApacheActiveMQArtemis.ApacheActiveMQArtemissupportsthesendingandreceivingofhugemessages,muchlargerthancanfitinavailableRAMontheclientorserver.Effectivelytheonlylimittomessagesizeistheamountofdiskspaceyouhaveontheserver.
Largemessagesarepersistedontheserversotheycansurviveaserverrestart.InotherwordsApacheActiveMQArtemisdoesn'tjustdoasimplesocketstreamfromthesendertotheconsumer.
Last-ValueQueueThelast-value-queueexampleshowsyouhowtodefineanddealwithlast-valuequeues.Last-valuequeuesarespecialqueueswhichdiscardanymessageswhenanewermessagewiththesamevalueforawell-definedlast-valuepropertyisputinthe
Examples
63
queue.Inotherwords,alast-valuequeueonlyretainsthelastvalue.
Atypicalexampleforlast-valuequeueisforstockprices,whereyouareonlyinterestedbythelatestpriceforaparticularstock.
ManagementThemanagementexampleshowshowtomanageApacheActiveMQArtemisusingJMSMessagestoinvokemanagementoperationsontheserver.
ManagementNotificationThemanagement-notificationexampleshowshowtoreceivemanagementnotificationsfromApacheActiveMQArtemisusingJMSmessages.ApacheActiveMQArtemisserversemitmanagementnotificationswheneventsofinterestoccur(consumersarecreatedorclosed,addressesarecreatedordeleted,securityauthenticationfails,etc.).
MessageCounterThemessage-countersexampleshowsyouhowtousemessagecounterstoobtainmessageinformationforaJMSqueue.
MessageGroupThemessage-groupexampleshowsyouhowtoconfigureandusemessagegroupswithApacheActiveMQArtemis.Messagegroupsallowyoutopinmessagessotheyareonlyconsumedbyasingleconsumer.Messagegroupsaresetsofmessagesthathasthefollowingcharacteristics:
Messagesinamessagegroupsharethesamegroupid,i.e.theyhavesameJMSXGroupIDstringpropertyvalues
Theconsumerthatreceivesthefirstmessageofagroupwillreceiveallthemessagesthatbelongstothegroup
MessageGroup
Examples
64
Themessage-group2exampleshowsyouhowtoconfigureandusemessagegroupswithApacheActiveMQArtemisviaaconnectionfactory.
MessagePriorityMessagePrioritycanbeusedtoinfluencethedeliveryorderformessages.
Itcanberetrievedbythemessage'sstandardheaderfield'JMSPriority'asdefinedinJMSspecificationversion1.1.
Thevalueisoftypeinteger,rangingfrom0(thelowest)to9(thehighest).Whenmessagesarebeingdelivered,theirprioritieswilleffecttheirorderofdelivery.Messagesofhigherprioritieswilllikelybedeliveredbeforethoseoflowerpriorities.
Messagesofequalprioritiesaredeliveredinthenaturalorderoftheirarrivalattheirdestinations.PleaseconsulttheJMS1.1specificationforfulldetails.
MultipleFailoverThisexampledemonstrateshowtosetupaliveserverwithmultiplebackups
MultipleFailoverFailbackThisexampledemonstrateshowtosetupaliveserverwithmultiplebackupsbutforcingfailoverbacktotheoriginalliveserver
NoConsumerBufferingBydefault,ApacheActiveMQArtemisconsumersbuffermessagesfromtheserverinaclientsidebufferbeforeyouactuallyreceivethemontheclientside.Thisimprovesperformancesinceotherwiseeverytimeyoucalledreceive()orhadprocessedthelastmessageinaMessageListeneronMessage()method,theApacheActiveMQArtemisclientwouldhavetogotheservertorequestthenextmessage,whichwouldthengetsenttotheclientside,ifonewasavailable.
Examples
65
Thiswouldinvolveanetworkroundtripforeverymessageandreduceperformance.Therefore,bydefault,ApacheActiveMQArtemispre-fetchesmessagesintoabufferoneachconsumer.
Insomecasebufferingisnotdesirable,andApacheActiveMQArtemisallowsittobeswitchedoff.Thisexampledemonstratesthat.
Non-TransactionFailoverWithServerDataReplicationThenon-transaction-failoverexampledemonstratestwoserverscoupledasalive-backuppairforhighavailability(HA),andaclientusinganon-transactedJMSsessionfailingoverfromlivetobackupwhentheliveserveriscrashed.
ApacheActiveMQArtemisimplementsfailoverofclientconnectionsbetweenliveandbackupservers.Thisisimplementedbythereplicationofstatebetweenliveandbackupnodes.Whenreplicationisconfiguredandalivenodecrashes,theclientconnectionscancarryandcontinuetosendandconsumemessages.Whennon-transactedsessionsareused,onceandonlyoncemessagedeliveryisnotguaranteedanditispossiblethatsomemessageswillbelostordeliveredtwice.
OpenWireTheOpenwireexampleshowshowtoconfigureanApacheActiveMQArtemisservertocommunicatewithanApacheActiveMQArtemisJMSclientthatusesopen-wireprotocol.
Youwillfindthequeueexampleforopenwire,andthechatexample.
PagingThepagingexampleshowshowApacheActiveMQArtemiscansupporthugequeuesevenwhentheserverisrunninginlimitedRAM.Itdoesthisbytransparentlypagingmessagestodisk,anddepagingthemwhentheyarerequired.
Pre-Acknowledge
Examples
66
StandardJMSsupportsthreeacknowledgementmodes:AUTO_ACKNOWLEDGE,CLIENT_ACKNOWLEDGE,andDUPS_OK_ACKNOWLEDGE.ForafulldescriptiononthesemodespleaseconsulttheJMSspecification,oranyJMStutorial.
Allofthesestandardmodesinvolvesendingacknowledgementsfromtheclienttotheserver.Howeverinsomecases,youreallydon'tmindlosingmessagesineventoffailure,soitwouldmakesensetoacknowledgethemessageontheserverbeforedeliveringittotheclient.ThisexampledemonstrateshowApacheActiveMQArtemisallowsthiswithanextraacknowledgementmode.
MessageProducerRateLimitingTheproducer-rte-limitexampledemonstrateshow,withApacheActiveMQArtemis,youcanspecifyamaximumsendrateatwhichaJMSmessageproducerwillsendmessages.
QueueAsimpleexampledemonstratingaJMSqueue.
MessageRedistributionThequeue-message-redistributionexampledemonstratesmessageredistributionbetweenqueueswiththesamenamedeployedindifferentnodesofacluster.
QueueRequestorAsimpleexampledemonstratingaJMSqueuerequestor.
QueuewithMessageSelectorThequeue-selectorexampleshowsyouhowtoselectivelyconsumemessagesusingmessageselectorswithqueueconsumers.
Examples
67
ReattachNodeexampleTheReattachNodeexampleshowshowaclientcantrytoreconnecttothesameserverinsteadoffailingtheconnectionimmediatelyandnotifyinganyuserExceptionListenerobjects.ApacheActiveMQArtemiscanbeconfiguredtoautomaticallyretrytheconnection,andreattachtotheserverwhenitbecomesavailableagainacrossthenetwork.
ReplicatedFailbackexampleAnexampleshowinghowfailbackworkswhenusingreplication,InthisexamplealiveserverwillreplicateallitsJournaltoabackupserverasitupdatesit.Whentheliveservercrashesthebackuptakesoverfromtheliveserverandtheclientreconnectsandcarriesonfromwhereitleftoff.
ReplicatedFailbackstaticexampleAnexampleshowinghowfailbackworkswhenusingreplication,butthistimewithstaticconnectors
ReplicatedmultiplefailoverexampleAnexampleshowinghowtoconfiguremultiplebackupswhenusingreplication
ReplicatedFailovertransactionexampleAnexampleshowinghowfailoverworkswithatransactionwhenusingreplication
Request-ReplyexampleAsimpleexampleshowingtheJMSrequest-responsepattern.
ScheduledMessage
Examples
68
Thescheduled-messageexampleshowsyouhowtosendascheduledmessagetoaJMSQueuewithApacheActiveMQArtemis.Scheduledmessageswon'tgetdelivereduntilaspecifiedtimeinthefuture.
SecurityThesecurityexampleshowsyouhowconfigureanduserolebasedqueuesecuritywithApacheActiveMQArtemis.
SendAcknowledgementsThesend-acknowledgementsexampleshowsyouhowtouseApacheActiveMQArtemis'sadvancedasynchronoussendacknowledgementsfeaturetoobtainacknowledgementfromtheserverthatsendshavebeenreceivedandprocessedinaseparatestreamtothesentmessages.
SpringIntegrationThisexampleshowshowtouseembeddedJMSusingApacheActiveMQArtemis'sSpringintegration.
SSLTransportThessl-enabledshowsyouhowtoconfigureSSLwithApacheActiveMQArtemistosendandreceivemessage.
StaticMessageSelectorThestatic-selectorexampleshowsyouhowtoconfigureanApacheActiveMQArtemiscorequeuewithstaticmessageselectors(filters).
StaticMessageSelectorUsingJMS
Examples
69
Thestatic-selector-jmsexampleshowsyouhowtoconfigureanApacheActiveMQArtemisqueuewithstaticmessageselectors(filters)usingJMS.
StompThestompexampleshowsyouhowtoconfigureanApacheActiveMQArtemisservertosendandreceiveStompmessages.
Stomp1.1ThestompexampleshowsyouhowtoconfigureanApacheActiveMQArtemisservertosendandreceiveStompmessagesviaaStomp1.1connection.
Stomp1.2ThestompexampleshowsyouhowtoconfigureanApacheActiveMQArtemisservertosendandreceiveStompmessagesviaaStomp1.2connection.
StompOverWebSocketsThestomp-websocketsexampleshowsyouhowtoconfigureanApacheActiveMQArtemisservertosendandreceiveStompmessagesdirectlyfromWebbrowsers(providedtheysupportWebSockets).
SymmetricClusterThesymmetric-clusterexampledemonstratesasymmetricclusterset-upwithApacheActiveMQArtemis.
ApacheActiveMQArtemishasextremelyflexibleclusteringwhichallowsyoutoset-upserversinmanydifferenttopologies.Themostcommontopologythatyou'llperhapsbefamiliarwithifyouareusedtoapplicationserverclusteringisasymmetriccluster.
Examples
70
Withasymmetriccluster,theclusterishomogeneous,i.e.eachnodeisconfiguredthesameaseveryothernode,andeverynodeisconnectedtoeveryothernodeinthecluster.
TemporaryQueueAsimpleexampledemonstratinghowtouseaJMStemporaryqueue.
TopicAsimpleexampledemonstratingaJMStopic.
TopicHierarchyApacheActiveMQArtemissupportstopichierarchies.Withatopichierarchyyoucanregisterasubscriberwithawild-cardandthatsubscriberwillreceiveanymessagessenttoanaddressthatmatchesthewildcard.
TopicSelector1Thetopic-selector-example1exampleshowsyouhowtosendmessagetoaJMSTopic,andsubscribethemusingselectorswithApacheActiveMQArtemis.
TopicSelector2Thetopic-selector-example2exampleshowsyouhowtoselectivelyconsumemessagesusingmessageselectorswithtopicconsumers.
TransactionFailoverThetransaction-failoverexampledemonstratestwoserverscoupledasalive-backuppairforhighavailability(HA),andaclientusingatransactedJMSsessionfailingoverfromlivetobackupwhentheliveserveriscrashed.
Examples
71
ApacheActiveMQArtemisimplementsfailoverofclientconnectionsbetweenliveandbackupservers.Thisisimplementedbythesharingofajournalbetweentheservers.Whenalivenodecrashes,theclientconnectionscancarryandcontinuetosendandconsumemessages.Whentransactedsessionsareused,onceandonlyoncemessagedeliveryisguaranteed.
FailoverWithoutTransactionsThestop-server-failoverexampledemonstratesfailoveroftheJMSconnectionfromonenodetoanotherwhentheliveservercrashesusingaJMSnon-transactedsession.
TransactionalSessionThetransactionalexampleshowsyouhowtouseatransactionalSessionwithApacheActiveMQArtemis.
XAHeuristicThexa-heuristicexampleshowsyouhowtomakeanXAheuristicdecisionthroughApacheActiveMQArtemisManagementInterface.AheuristicdecisionisaunilateraldecisiontocommitorrollbackanXAtransactionbranchafterithasbeenprepared.
XAReceiveThexa-receiveexampleshowsyouhowmessagereceivingbehavesinanXAtransactioninApacheActiveMQArtemis.
XASendThexa-sendexampleshowsyouhowmessagesendingbehavesinanXAtransactioninApacheActiveMQArtemis.
CoreAPIExamples
Examples
72
Torunacoreexample,simplycdintotheappropriateexampledirectoryandtypeant
EmbeddedTheembeddedexampleshowshowtoembedtheApacheActiveMQArtemisserverwithinyourowncode.
Examples
73
RoutingMessagesWithWildCardsApacheActiveMQArtemisallowstheroutingofmessagesviawildcardaddresses.
Ifaqueueiscreatedwithanaddressofsayqueue.news.#thenitwillreceiveanymessagessenttoaddressesthatmatchthis,forinstancequeue.news.europeorqueue.news.usaorqueue.news.usa.sport.Ifyoucreateaconsumeronthisqueue,thisallowsaconsumertoconsumemessageswhicharesenttoahierarchyofaddresses.
Note
InJMSterminologythisallows"topichierarchies"tobecreated.
Toenablethisfunctionalitysetthepropertywild-card-routing-enabledinthebroker.xmlfiletotrue.Thisistruebydefault.
Formoreinformationonthewildcardsyntaxtakealookatwildcardsyntaxchapter,alsoseethetopichierarchyexampleintheexamples.
RoutingMessagesWithWildCards
74
UnderstandingtheApacheActiveMQArtemisWildcardSyntaxApacheActiveMQArtemisusesaspecificsyntaxforrepresentingwildcardsinsecuritysettings,addresssettingsandwhencreatingconsumers.
ThesyntaxissimilartothatusedbyAMQP.
AnApacheActiveMQArtemiswildcardexpressioncontainswordsdelimitedbythecharacter'.'(fullstop).
Thespecialcharacters'#'and'*'alsohavespecialmeaningandcantaketheplaceofaword.
Thecharacter'#'means'matchanysequenceofzeroormorewords'.
Thecharacter'*'means'matchasingleword'.
Sothewildcard'news.europe.#'wouldmatch'news.europe','news.europe.sport','news.europe.politics',and'news.europe.politics.regional'butwouldnotmatch'news.usa','news.usa.sport'nor'entertainment'.
Thewildcard'news.*'wouldmatch'news.europe',butnot'news.europe.sport'.
Thewildcard'news.*.sport'wouldmatch'news.europe.sport'andalso'news.usa.sport',butnot'news.europe.politics'.
UnderstandingtheApacheActive