-
1. Introduction
2. LegalNotice
3. Preface
4. ProjectInfo
5. MessagingConcepts
6. Architecture
7. UsingtheServer
8. AddressModel
9. UsingJMS
10. UsingCore
11. UsingAMQP
12. MappingJMSConceptstotheCoreAPI
13. TheClientClasspath
14. Examples
15. RoutingMessagesWithWildCards
16. UnderstandingtheApacheActiveMQArtemisWildcardSyntax
17. FilterExpressions
18. Persistence
19. ConfiguringTransports
20. ConfigurationReload
21. DetectingDeadConnections
22. DetectingSlowConsumers
23. AvoidingNetworkIsolation
24. ResourceManagerConfiguration
25. FlowControl
26. Guaranteesofsendsandcommits
27. MessageRedeliveryandUndeliveredMessages
28. MessageExpiry
29. LargeMessages
30. Paging
31. QueueAttributes
32. ScheduledMessages
33. Last-ValueQueues
34. MessageGrouping
35. ExtraAcknowledgeModes
36. Management
37. Security
38. ResourceLimits
39. TheJMSBridge
40. ClientReconnectionandSessionReattachment
41. DivertingandSplittingMessageFlows
42. CoreBridges
43. DuplicateMessageDetection
44. Clusters
45. HighAvailabilityandFailover
46. GracefulServerShutdown
47. LibaioNativeLibraries
48. Threadmanagement
49. Logging
50. RESTInterface
51. EmbeddingApacheActiveMQArtemis
52. ApacheKaraf
TableofContents
-
53. SpringIntegration
54. CDIIntegration
55. InterceptingOperations
56. ProtocolsandInteroperability
57. Tools
58. MavenPlugin
59. UnitTesting
60. TroubleshootingandPerformanceTuning
61. ConfigurationReference
62. UpdatingArtemis
-
TheUsermanualisanindepthmanualonallaspectsofApacheActiveMQArtemis
ApacheActiveMQArtemisUserManual
-
LicensedtotheApacheSoftwareFoundation(ASF)underoneormorecontributorlicenseagreements.SeetheNOTICE
filedistributedwiththisworkforadditionalinformationregardingcopyrightownership.TheASFlicensesthisfiletoYou
undertheApacheLicense,Version2.0(the"License");youmaynotusethisfileexceptincompliancewiththeLicense.You
mayobtainacopyoftheLicenseat
http://www.apache.org/licenses/LICENSE-2.0
Unlessrequiredbyapplicablelaworagreedtoinwriting,softwaredistributedundertheLicenseisdistributedonan"ASIS"
BASIS,WITHOUTWARRANTIESORCONDITIONSOFANYKIND,eitherexpressorimplied.SeetheLicenseforthe
specificlanguagegoverningpermissionsandlimitationsundertheLicense.
LegalNotice
http://www.apache.org/licenses/LICENSE-2.0
-
WhatisApacheActiveMQArtemis?
ApacheActiveMQArtemisisanopensourceprojecttobuildamulti-protocol,embeddable,veryhighperformance,
clustered,asynchronousmessagingsystem.
ApacheActiveMQArtemisisanexampleofMessageOrientedMiddleware(MoM).ForadescriptionofMoMsand
othermessagingconceptspleaseseetheMessagingConcepts.
ForanswerstomorequestionsaboutwhatApacheActiveMQArtemisisandwhatitisn'tpleasevisittheFAQswiki
page.
WhyuseApacheActiveMQArtemis?Herearejustafewofthereasons:
100%opensourcesoftware.ApacheActiveMQArtemisislicensedusingtheApacheSoftwareLicensev2.0to
minimisebarrierstoadoption.
ApacheActiveMQArtemisisdesignedwithusabilityinmind.
WritteninJava.RunsonanyplatformwithaJava8+runtime,that'severythingfromWindowsdesktopstoIBM
mainframes.
Amazingperformance.Ourground-breakinghighperformancejournalprovidespersistentmessagingperformanceat
ratesnormallyseenfornon-persistentmessaging,ournon-persistentmessagingperformancerockstheboattoo.
Fullfeatureset.Allthefeaturesyou'dexpectinanyseriousmessagingsystem,andothersyouwon'tfindanywhere
else.
Elegant,clean-cutdesignwithminimalthirdpartydependencies.RunActiveMQArtemisstand-alone,runitin
integratedinyourfavouriteJEEapplicationserver,orrunitembeddedinsideyourownproduct.It'suptoyou.
Seamlesshighavailability.WeprovideaHAsolutionwithautomaticclientfailoversoyoucanguaranteezeromessage
lossorduplicationineventofserverfailure.
Hugelyflexibleclustering.Createclustersofserversthatknowhowtoloadbalancemessages.Linkgeographically
distributedclustersoverunreliableconnectionstoformaglobalnetwork.Configureroutingofmessagesinahighly
flexibleway.
Preface
-
TheofficialApacheActiveMQArtemisprojectpageishttp://activemq.apache.org/artemis/.
ThesoftwarecanbedownloadfromtheDownloadpage:http://activemq.apache.org/download.html
Ifyouhaveanyuserquestionspleaseuseouruserforum
Ifyouhavedevelopmentrelatedquestions,pleaseuseourdeveloperforum
PopinandchattousinourIRCchannel
ApacheActiveMQArtemisGitrepositoryishttps://github.com/apache/activemq-artemis
Allreleasetagsareavailablefromhttps://github.com/apache/activemq-artemis/releases
Andmanythankstoallourcontributors,botholdandnewwhohelpedcreateApacheActiveMQArtemis.
ProjectInformation
SoftwareDownload
ProjectInformation
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
-
ApacheActiveMQArtemisisanasynchronousmessagingsystem,anexampleofMessageOrientedMiddleware,we'lljust
callthemmessagingsystemsintheremainderofthisbook.
We'llfirstpresentabriefoverviewofwhatkindofthingsmessagingsystemsdo,wherethey'reusefulandthekindof
conceptsyou'llhearaboutinthemessagingworld.
Ifyou'realreadyfamiliarwithwhatamessagingsystemisandwhatit'scapableof,thenyoucanskipthischapter.
Messagingsystemsallowyoutolooselycoupleheterogeneoussystemstogether,whilsttypicallyprovidingreliability,
transactionsandmanyotherfeatures.
UnlikesystemsbasedonaRemoteProcedureCall(RPC)pattern,messagingsystemsprimarilyuseanasynchronous
messagepassingpatternwithnotightrelationshipbetweenrequestsandresponses.Mostmessagingsystemsalso
supportarequest-responsemodebutthisisnotaprimaryfeatureofmessagingsystems.
Designingsystemstobeasynchronousfromend-to-endallowsyoutoreallytakeadvantageofyourhardwareresources,
minimizingtheamountofthreadsblockingonIOoperations,andtouseyournetworkbandwidthtoitsfullcapacity.Withan
RPCapproachyouhavetowaitforaresponseforeachrequestyoumakesoarelimitedbythenetworkroundtriptime,or
latencyofyournetwork.Withanasynchronoussystemyoucanpipelineflowsofmessagesindifferentdirections,soarelimitedbythenetworkbandwidthnotthelatency.Thistypicallyallowsyoutocreatemuchhigherperformanceapplications.
Messagingsystemsdecouplethesendersofmessagesfromtheconsumersofmessages.Thesendersandconsumersof
messagesarecompletelyindependentandknownothingofeachother.Thisallowsyoutocreateflexible,looselycoupled
systems.
Often,largeenterprisesuseamessagingsystemtoimplementamessagebuswhichlooselycouplesheterogeneous
systemstogether.MessagebusesoftenformthecoreofanEnterpriseServiceBus.(ESB).Usingamessagebustode-
coupledisparatesystemscanallowthesystemtogrowandadaptmoreeasily.Italsoallowsmoreflexibilitytoaddnew
systemsorretireoldonessincetheydon'thavebrittledependenciesoneachother.
Messagingsystemsnormallysupporttwomainstylesofasynchronousmessaging:messagequeuemessaging(also
knownaspoint-to-pointmessaging)andpublishsubscribemessaging.We'llsummarisethembrieflyhere:
Withthistypeofmessagingyousendamessagetoaqueue.Themessageisthentypicallypersistedtoprovidea
guaranteeofdelivery,thensometimelaterthemessagingsystemdeliversthemessagetoaconsumer.Theconsumerthen
processesthemessageandwhenitisdone,itacknowledgesthemessage.Oncethemessageisacknowledgedit
disappearsfromthequeueandisnotavailabletobedeliveredagain.Ifthesystemcrashesbeforethemessagingserver
receivesanacknowledgementfromtheconsumer,thenonrecovery,themessagewillbeavailabletobedeliveredtoa
consumeragain.
Withpoint-to-pointmessaging,therecanbemanyconsumersonthequeuebutaparticularmessagewillonlyeverbe
consumedbyamaximumofoneofthem.Senders(alsoknownasproducers)tothequeuearecompletelydecoupledfromreceivers(alsoknownasconsumers)ofthequeue-theydonotknowofeachother'sexistence.
Aclassicexampleofpointtopointmessagingwouldbeanorderqueueinacompany'sbookorderingsystem.Eachorder
isrepresentedasamessagewhichissenttotheorderqueue.Let'simaginetherearemanyfrontendorderingsystems
MessagingConcepts
MessagingConcepts
Messagingstyles
TheMessageQueuePattern
http://en.wikipedia.org/wiki/Message_oriented_middlewarehttp://en.wikipedia.org/wiki/Remote_procedure_callhttp://en.wikipedia.org/wiki/Enterprise_service_bushttp://en.wikipedia.org/wiki/Message_queuehttp://en.wikipedia.org/wiki/Publish_subscribe
-
whichsendorderstotheorderqueue.Whenamessagearrivesonthequeueitispersisted-thisensuresthatiftheserver
crashestheorderisnotlost.Let'salsoimaginetherearemanyconsumersontheorderqueue-eachrepresentingan
instanceofanorderprocessingcomponent-thesecanbeondifferentphysicalmachinesbutconsumingfromthesame
queue.Themessagingsystemdeliverseachmessagetooneandonlyoneoftheorderingprocessingcomponents.
Differentmessagescanbeprocessedbydifferentorderprocessors,butasingleorderisonlyprocessedbyoneorder
processor-thisensuresordersaren'tprocessedtwice.
Asanorderprocessorreceivesamessage,itfulfillstheorder,sendsorderinformationtothewarehousesystemandthen
updatestheorderdatabasewiththeorderdetails.Onceit'sdonethatitacknowledgesthemessagetotelltheserverthat
theorderhasbeenprocessedandcanbeforgottenabout.Oftenthesendtothewarehousesystem,updateindatabase
andacknowledgementwillbecompletedinasingletransactiontoensureACIDproperties.
Withpublish-subscribemessagingmanysenderscansendmessagestoanentityontheserver,oftencalledatopic(e.g.intheJMSworld).
Therecanbemanysubscriptionsonatopic,asubscriptionisjustanotherwordforaconsumerofatopic.Eachsubscriptionreceivesacopyofeachmessagesenttothetopic.Thisdiffersfromthemessagequeuepatternwhereeachmessageisonlyconsumedbyasingleconsumer.
Subscriptionscanoptionallybedurablewhichmeanstheyretainacopyofeachmessagesenttothetopicuntilthesubscriberconsumesthem-eveniftheservercrashesorisrestartedinbetween.Non-durablesubscriptionsonlylasta
maximumofthelifetimeoftheconnectionthatcreatedthem.
Anexampleofpublish-subscribemessagingwouldbeanewsfeed.Asnewsarticlesarecreatedbydifferenteditorsaround
theworldtheyaresenttoanewsfeedtopic.Therearemanysubscribersaroundtheworldwhoareinterestedinreceiving
newsitems-eachonecreatesasubscriptionandthemessagingsystemensuresthatacopyofeachnewsmessageis
deliveredtoeachsubscription.
Akeyfeatureofmostmessagingsystemsisreliablemessaging.Withreliablemessagingtheservergivesaguaranteethatthemessagewillbedeliveredonceandonlyoncetoeachconsumerofaqueueoreachdurablesubscriptionofatopic,
evenintheeventofsystemfailure.Thisiscrucialformanybusinesses;e.g.youdon'twantyourordersfulfilledmorethan
onceoranyofyourorderstobelost.
Inothercasesyoumaynotcareaboutaonceandonlyoncedeliveryguaranteeandarehappytocopewithduplicate
deliveriesorlostmessages-anexampleofthismightbetransientstockpriceupdates-whicharequicklysupersededby
thenextupdateonthesamestock.Themessagingsystemallowsyoutoconfigurewhichdeliveryguaranteesyourequire.
Messagingsystemstypicallysupportthesendingandacknowledgementofmultiplemessagesinasinglelocaltransaction.
ApacheActiveMQArtemisalsosupportsthesendingandacknowledgementofmessageaspartofalargeglobal
transaction-usingtheJavamappingofXA:JTA.
Messagesareeitherdurableornondurable.Durablemessageswillbepersistedinpermanentstorageandwillsurvive
serverfailureorrestart.Nondurablemessageswillnotsurviveserverfailureorrestart.Examplesofdurablemessages
mightbeordersortrades,wheretheycannotbelost.Anexampleofanondurablemessagemightbeastockpriceupdate
whichistransitoryanddoesn'tneedtosurvivearestart.
ThePublish-SubscribePattern
Deliveryguarantees
Transactions
Durability
http://en.wikipedia.org/wiki/ACID
-
Howdoclientapplicationsinteractwithmessagingsystemsinordertosendandconsumemessages?
SeveralmessagingsystemsprovidetheirownproprietaryAPIswithwhichtheclientcommunicateswiththemessaging
system.
Therearealsosomestandardwaysofoperatingwithmessagingsystemsandsomeemergingstandardsinthisspace.
Let'stakeabrieflookatthese:
JMSispartofOracle'sJEEspecification.It'saJavaAPIthatencapsulatesbothmessagequeueandpublish-subscribe
messagingpatterns.JMSisalowestcommondenominatorspecification-i.e.itwascreatedtoencapsulatecommon
functionalityofthealreadyexistingmessagingsystemsthatwereavailableatthetimeofitscreation.
JMSisaverypopularAPIandisimplementedbymostmessagingsystems.JMSisonlyavailabletoclientsrunningJava.
JMSdoesnotdefineastandardwireformat-itonlydefinesaprogrammaticAPIsoJMSclientsandserversfromdifferent
vendorscannotdirectlyinteroperatesinceeachwillusethevendor'sowninternalwireprotocol.
ApacheActiveMQArtemisprovidesafullycompliantJMS1.1andJMS2.0API.
ManysystemsprovidetheirownprogrammaticAPIforwhichtointeractwiththemessagingsystem.Theadvantageofthis
itallowsthefullsetofsystemfunctionalitytobeexposedtotheclientapplication.API'slikeJMSarenotnormallyrich
enoughtoexposealltheextrafeaturesthatmostmessagingsystemsprovide.
ApacheActiveMQArtemisprovidesitsowncoreclientAPIforclientstouseiftheywishtohaveaccesstofunctionalityover
andabovethataccessibleviatheJMSAPI.
RESTapproachestomessagingareshowingalotinterestrecently.
ItseemsplausiblethatAPIstandardsforcloudcomputingmayconvergeonaRESTstylesetofinterfacesand
consequentlyaRESTmessagingapproachisaverystrongcontenderforbecomingthede-factomethodformessaging
interoperability.
WithaRESTapproachmessagingresourcesaremanipulatedasresourcesdefinedbyaURIandtypicallyusingasimple
setofoperationsonthoseresources,e.g.PUT,POST,GETetc.RESTapproachestomessagingoftenuseHTTPastheir
underlyingprotocol.
TheadvantageofaRESTapproachwithHTTPisinitssimplicityandthefacttheinternetisalreadytunedtodealwith
HTTPoptimally.
PleaseseeRestInterfaceforusingApacheActiveMQArtemis'sRESTfulinterface.
AMQPisaspecificationforinteroperablemessaging.Italsodefinesawireformat,soanyAMQPclientcanworkwithany
messagingsystemthatsupportsAMQP.AMQPclientsareavailableinmanydifferentprogramminglanguages.
ApacheActiveMQArtemisimplementstheAMQP1.0specification.Anyclientthatsupportsthe1.0specificationwillbe
abletointeractwithApacheActiveMQArtemis.
MessagingAPIsandprotocols
JavaMessageService(JMS)
SystemspecificAPIs
RESTfulAPI
AMQP
http://en.wikipedia.org/wiki/Java_Message_Servicehttp://en.wikipedia.org/wiki/Representational_State_Transferhttp://en.wikipedia.org/wiki/AMQPhttps://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp
-
MQTTisalightweightconnectivityprotocol.Itisdesignedtoruninenvironmentswheredeviceandnetworksare
constrained.OutoftheboxApacheActiveMQArtemissupportsversionMQTT3.1.1.Anyclientsupportingthisversionof
theprotocolwillworkagainstApacheActiveMQArtemis.
Stompisaverysimpletextprotocolforinteroperatingwithmessagingsystems.Itdefinesawireformat,sotheoreticallyany
StompclientcanworkwithanymessagingsystemthatsupportsStomp.Stompclientsareavailableinmanydifferent
programminglanguages.
PleaseseeStompforusingSTOMPwithApacheActiveMQArtemis.
ActiveMQ5.xdefinesit'sownwireProtocol"OPENWIRE".InordertosupportActiveMQ5.xclients,ApacheActiveMQ
ArtemissupportsOPENWIRE.AnyActiveMQ5.12.xorhighercanbeusedwithApacheActiveMQArtemis.
HighAvailability(HA)meansthatthesystemshouldremainoperationalafterfailureofoneormoreoftheservers.The
degreeofsupportforHAvariesbetweenvariousmessagingsystems.
ApacheActiveMQArtemisprovidesautomaticfailoverwhereyoursessionsareautomaticallyreconnectedtothebackup
serveroneventofliveserverfailure.
FormoreinformationonHA,pleaseseeHighAvailabilityandFailover.
Manymessagingsystemsallowyoutocreategroupsofmessagingserverscalledclusters.Clustersallowtheloadofsendingandconsumingmessagestobespreadovermanyservers.Thisallowsyoursystemtoscalehorizontallybyadding
newserverstothecluster.
Degreesofsupportforclustersvariesbetweenmessagingsystems,withsomesystemshavingfairlybasicclusterswiththe
clustermembersbeinghardlyawareofeachother.
ApacheActiveMQArtemisprovidesveryconfigurablestate-of-the-artclusteringmodelwheremessagescanbeintelligently
loadbalancedbetweentheserversinthecluster,accordingtothenumberofconsumersoneachnode,andwhetherthey
arereadyformessages.
ApacheActiveMQArtemisalsohastheabilitytoautomaticallyredistributemessagesbetweennodesofaclustertoprevent
starvationonanyparticularnode.
Forfulldetailsonclustering,pleaseseeClusters.
Somemessagingsystemsallowisolatedclustersorsinglenodestobebridgedtogether,typicallyoverunreliable
connectionslikeawideareanetwork(WAN),ortheinternet.
Abridgenormallyconsumesfromaqueueononeserverandforwardsmessagestoanotherqueueonadifferentserver.
Bridgescopewithunreliableconnections,automaticallyreconnectingwhentheconnectionsbecomesavailableagain.
MQTT
STOMP
OPENWIRE
HighAvailability
Clusters
Bridgesandrouting
http://mqtt.org/http://stomp.github.io/
-
ApacheActiveMQArtemisbridgescanbeconfiguredwithfilterexpressionstoonlyforwardcertainmessages,and
transformationcanalsobehookedin.
ApacheActiveMQArtemisalsoallowsroutingbetweenqueuestobeconfiguredinserversideconfiguration.Thisallows
complexroutingnetworkstobesetupforwardingorcopyingmessagesfromonedestinationtoanother,formingaglobal
networkofinterconnectedbrokers.
FormoreinformationpleaseseeCoreBridgesandDivertingandSplittingMessageFlows.
-
InthissectionwewillgiveanoverviewoftheApacheActiveMQArtemishighlevelarchitecture.
ApacheActiveMQArtemiscoreisdesignedsimplyassetofPlainOldJavaObjects(POJOs)-wehopeyoulikeitsclean-
cutdesign.
EachApacheActiveMQArtemisserverhasitsownultrahighperformancepersistentjournal,whichitusesformessage
andotherpersistence.
Usingahighperformancejournalallowsoutrageouspersistencemessageperformance,somethingnotachievablewhen
usingarelationaldatabaseforpersistence.
ApacheActiveMQArtemisclients,potentiallyondifferentphysicalmachinesinteractwiththeApacheActiveMQArtemis
server.ApacheActiveMQArtemiscurrentlyprovidestwoAPIsformessagingattheclientside:
1. CoreclientAPI.ThisisasimpleintuitiveJavaAPIthatisalignedwiththeArtemisinternalCore.Allowingmorecontrol
ofbrokerobjects,likeforexample,directcreationofaddressesandqueues.TheCoreAPIalsooffersafullsetof
messagingfunctionalitywithoutsomeofthecomplexitiesofJMS.
2. JMSclientAPI.ThestandardJMSAPIisavailableattheclientside.
ApacheActiveMQArtemisalsoprovidesdifferentprotocolimplementationsontheserversoyoucanuserespectiveclients
fortheseprotocols:
1. AMQP
2. OpenWire
3. MQTT
4. STOMP
5. HornetQ(forusewithHornetQclients).
6. CORE(ArtemisCOREprotocol)
JMSsemanticsareimplementedbyaJMSfacadelayerontheclientside.
TheApacheActiveMQArtemisserverdoesnotspeakJMSandinfactdoesnotknowanythingaboutJMS,itisaprotocol
agnosticmessagingserverdesignedtobeusedwithmultipledifferentprotocols.
WhenauserusestheJMSAPIontheclientside,allJMSinteractionsaretranslatedintooperationsontheApache
ActiveMQArtemiscoreclientAPIbeforebeingtransferredoverthewireusingtheApacheActiveMQArtemiswireformat.
TheserveralwaysjustdealswithcoreAPIinteractions.
Aschematicillustratingthisrelationshipisshowninfigure3.1below:
Architecture
CoreArchitecture
-
Figure3.1showstwouserapplicationsinteractingwithanApacheActiveMQArtemisserver.UserApplication1isusingthe
JMSAPI,whileUserApplication2isusingthecoreclientAPIdirectly.
YoucanseefromthediagramthattheJMSAPIisimplementedbyathinfacadelayerontheclientside.
ApacheActiveMQArtemisstand-aloneserver
-
Thestandardstand-alonemessagingserverconfigurationcomprisesacoremessagingserverandanumberofprotocol
managersthatprovidesupportforthevariousprotocolmentionedearlier.Protocolmanagersareplugableifyou
TheroleoftheJMSServiceistodeployanyJMSQueue,TopicandConnectionFactoryinstancesfromanyserverside
JMSconfiguration.ItalsoprovidesasimplemanagementAPIforcreatinganddestroyingQueuesandTopicswhichcanbe
accessedviaJMXortheconnection.ItisaseparateservicetotheActiveMQArtemiscoreserver,sincethecoreserveris
JMSagnostic.Ifyoudon'twanttodeployanyJMSQueueorTopicviaserversideXMLconfigurationanddon'trequirea
JMSmanagementAPIontheserversidethenyoucandisablethisservice.
Thestand-aloneserverconfigurationusesAirlineforbootstrappingtheBroker.
Thestand-aloneserverarchitectureisshowninfigure3.3below:
https://github.com/airlift/airline
-
FormoreinformationonserverconfigurationfilesseeServerConfiguration
ApacheActiveMQArtemiscoreisdesignedasasetofsimplePOJOssoifyouhaveanapplicationthatrequires
messagingfunctionalityinternallybutyoudon'twanttoexposethatasanApacheActiveMQArtemisserveryoucandirectly
ApacheActiveMQArtemisembeddedinyourownapplication
-
instantiateandembedApacheActiveMQArtemisserversinyourownapplication.
FormoreinformationonembeddingApacheActiveMQArtemis,seeEmbeddingApacheActiveMQArtemis.
ApacheActiveMQArtemisprovidesitsownfullyfunctionalJavaConnectorArchitecture(JCA)adaptorwhichenablesitto
beintegratedeasilyintoanyJavaEEcompliantapplicationserverorservletengine.
JavaEEapplicationserversprovideMessageDrivenBeans(MDBs),whichareaspecialtypeofEnterpriseJavaBeans
(EJBs)thatcanprocessmessagesfromsourcessuchasJMSsystemsormailsystems.
ProbablythemostcommonuseofanMDBistoconsumemessagesfromaJMSmessagingsystem.
AccordingtotheJavaEEspecification,aJavaEEapplicationserverusesaJCAadaptertointegratewithaJMS
messagingsystemsoitcanconsumemessagesforMDBs.
However,theJCAadapterisnotonlyusedbytheJavaEEapplicationserverforconsumingmessagesviaMDBs,itisalsousedwhensendingmessagetotheJMSmessagingsysteme.g.frominsideanEJBorservlet.
WhenintegratingwithaJMSmessagingsystemfrominsideaJavaEEapplicationserveritisalwaysrecommendedthat
thisisdoneviaaJCAadaptor.Infact,communicatingwithaJMSmessagingsystemdirectly,withoutusingJCAwouldbe
illegalaccordingtotheJavaEEspecification.
Theapplicationserver'sJCAserviceprovidesextrafunctionalitysuchasconnectionpoolingandautomatictransaction
enlistment,whicharedesirablewhenusingmessaging,say,frominsideanEJB.ItispossibletotalktoaJMSmessaging
systemdirectlyfromanEJB,MDBorservletwithoutgoingthroughaJCAadapter,butthisisnotrecommendedsinceyou
willnotbeabletotakeadvantageoftheJCAfeatures,suchascachingofJMSsessions,whichcanresultinpoor
performance.
Figure3.2belowshowsaJavaEEapplicationserverintegratingwithaApacheActiveMQArtemisserverviatheApache
ActiveMQArtemisJCAadaptor.NotethatallcommunicationbetweenEJBsessionsorentitybeansandMessageDriven
beansgothroughtheadaptorandnotdirectlytoApacheActiveMQArtemis.
ThelargearrowwiththeprohibitedsignshowsanEJBsessionbeantalkingdirectlytotheApacheActiveMQArtemis
server.Thisisnotrecommendedasyou'llmostlikelyendupcreatinganewconnectionandsessioneverytimeyouwantto
interactfromtheEJB,whichisananti-pattern.
ApacheActiveMQArtemisintegratedwithaJavaEEapplicationserver
-
FormoreinformationonusingtheJCAadaptor,pleaseseeApplicationServerIntegrationandJavaEE.
-
ThischapterwillfamiliariseyouwithhowtousetheApacheActiveMQArtemisserver.
We'llshowwhereitis,howtostartandstopit,andwe'lldescribethedirectorylayoutandwhatallthefilesareandwhat
theydo.
FortheremainderofthischapterwhenwetalkabouttheApacheActiveMQArtemisserverwemeantheApacheActiveMQ
Artemisstandaloneserver,initsdefaultconfigurationwithaJMSServiceenabled.
ThisdocumentwillrefertothefullpathofthedirectorywheretheActiveMQdistributionhasbeenextractedtoas
${ARTEMIS_HOME}directory.
Afterdownloadingthedistribution,thefollowinghighlightssomeimportantfoldersonthedistribution:
|___bin
|
|___web
||___user-manual
||___api
|
|___examples
||___core
||___javaee
||___jms
|
|___lib
|
|___schema
bin--binariesandscriptsneededtorunActiveMQArtemis.
web--ThefolderwherethewebcontextisloadedwhenActiveMQArtemisruns.
user-manual--Theusermanualisplacedunderthewebfolder.
api--Theapidocumentationisplacedunderthewebfolder
examples--JMSandJavaEEexamples.Pleaserefertothe'runningexamples'chapterfordetailsonhowtorunthem.
lib--jarsandlibrariesneededtorunActiveMQArtemis
licenses--licensesforActiveMQArtemis
schemas--XMLSchemasusedtovalidateActiveMQArtemisconfigurationfiles
Abrokerinstanceisthedirectorycontainingalltheconfigurationandruntimedata,suchaslogsanddatafiles,associated
withabrokerprocess.Itisrecommendedthatyoudonotcreatetheinstancedirectoryunder${ARTEMIS_HOME}.ThisseparationisencouragedsothatyoucanmoreeasilyupgradewhenthenextversionofActiveMQArtemisisreleased.
OnUnixsystems,itisacommonconventiontostorethiskindofruntimedataunderthe/var/libdirectory.Forexample,
tocreateaninstanceat'/var/lib/mybroker',runthefollowingcommandsinyourcommandlineshell:
UsingtheServer
Installation
CreatingaBrokerInstance
-
cd/var/lib
${ARTEMIS_HOME}/bin/artemiscreatemybroker
Abrokerinstancedirectorywillcontainthefollowingsubdirectories:
bin:holdsexecutionscriptsassociatedwiththisinstance.
etc:holdtheinstanceconfigurationfiles
data:holdsthedatafilesusedforstoringpersistentmessages
log:holdsrotatinglogfiles
tmp:holdstemporaryfilesthataresafetodeletebetweenbrokerruns
Atthispointyoumaywanttoadjustthedefaultconfigurationlocatedintheetcdirectory.
Thereareseveraloptionsyoucanusewhencreatinganinstance.
Forafulllistofupdatedpropertiesalwaysuse:
$./artemishelpcreate
NAME
artemiscreate-createsanewbrokerinstance
SYNOPSIS
artemiscreate[--addresses][--aio][--allow-anonymous]
[--autocreate][--cluster-password]
[--cluster-user][--clustered][--data]
[--default-port][--disable-persistence]
[--encoding][--failover-on-shutdown][--force]
[--home][--host][--http-port]
[--java-options][--mapped][--max-hops]
[--message-load-balancing][--name]
[--nio][--no-amqp-acceptor][--no-autocreate][--no-autotune]
[--no-fsync][--no-hornetq-acceptor][--no-mqtt-acceptor]
[--no-stomp-acceptor][--no-web][--password][--ping]
[--port-offset][--queues][--replicated]
[--require-login][--role][--shared-store][--silent][--slave]
[--ssl-key][--ssl-key-password]
[--ssl-trust][--ssl-trust-password]
[--use-client-auth][--user][--verbose][--]
OPTIONS
--addresses
commaseparatedlistofaddresses
--aio
setsthejournalasasyncio.
--allow-anonymous
Enablesanonymousconfigurationonsecurity,oppositeof
--require-login(Default:input)
--autocreate
Autocreateaddresses.(default:true)
--cluster-password
Theclusterpasswordtouseforclustering.(Default:input)
--cluster-user
Theclusterusertouseforclustering.(Default:input)
--clustered
Enableclustering
--data
DirectorywhereActiveMQDataisused.Pathsarerelativeto
artemis.instance
--default-port
Theportnumbertouseforthemain'artemis'acceptor(Default:
61616)
Options
-
--disable-persistence
Disablemessagepersistencetothejournal
--encoding
Theencodingthattextfilesshoulduse
--failover-on-shutdown
Validforsharedstore:willshutdowntriggerafailover?(Default:
false)
--force
Overwriteconfigurationatdestinationdirectory
--home
DirectorywhereActiveMQArtemisisinstalled
--host
Thehostnameofthebroker(Default:0.0.0.0orinputifclustered)
--http-port
Theportnumbertouseforembeddedwebserver(Default:8161)
--java-options
Extrajavaoptionstobepassedtotheprofile
--mapped
Setsthejournalasmapped.
--max-hops
Numberofhopsontheclusterconfiguration
--message-load-balancing
Loadbalancingpolicyoncluster.[ON_DEMAND(default)|STRICT|
OFF]
--name
Thenameofthebroker(Default:sameashost)
--nio
setsthejournalasnio.
--no-amqp-acceptor
DisabletheAMQPspecificacceptor.
--no-autocreate
DisableAutocreateaddresses.
--no-autotune
Disableautotuningonthejournal.
--no-fsync
Disableusageoffdatasync(channel.force(false)fromjavanio)on
thejournal
--no-hornetq-acceptor
DisabletheHornetQspecificacceptor.
--no-mqtt-acceptor
DisabletheMQTTspecificacceptor.
--no-stomp-acceptor
DisabletheSTOMPspecificacceptor.
--no-web
Thiswillremovethewebserverdefinitionfrombootstrap.xml
--password
Theuser'spassword(Default:input)
--ping
Acommaseparatedstringtobepassedontothebrokerconfigas
network-check-list.Thebrokerwillshutdownwhenallthese
addressesareunreachable.
--port-offset
Offsetstheportsofeveryacceptor
--queues
commaseparatedlistofqueues.
--replicated
Enablebrokerreplication
-
--require-login
Thiswillconfiguresecuritytorequireuser/password,oppositeof
--allow-anonymous
--role
Thenamefortherolecreated(Default:input)
--shared-store
Enablebrokersharedstore
--silent
Itwilldisablealltheinputs,anditwouldmakeabestguessfor
anyrequiredinput
--slave
Validforsharedstoreorreplication:thisisaslaveserver?
--ssl-key
Thekeystorepathforembeddedwebserver
--ssl-key-password
Thekeystorepassword
--ssl-trust
Thetruststorepathincaseofclientauthentication
--ssl-trust-password
Thetruststorepassword
--use-client-auth
Iftheembeddedserverrequiresclientauthentication
--user
Theusername(Default:input)
--verbose
Addsmoreinformationontheexecution
--
Thisoptioncanbeusedtoseparatecommand-lineoptionsfromthe
listofargument,(usefulwhenargumentsmightbemistakenfor
command-lineoptions
Theinstancedirectorytoholdthebroker'sconfigurationanddata.
Pathmustbewritable.
Someofthesepropertiesmaybemandatoryincertainconfigurationsandthesystemmayaskyouforadditionalinput.
./artemiscreate/usr/server
CreatingActiveMQArtemisinstanceat:/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/mybrokerallyouneedtodostartrunningthebrokerinstanceis
execute:
/var/lib/mybroker/bin/artemisrun
Nowthatthebrokerisrunning,youcanoptionallyrunsomeoftheincludedexamplestoverifythethebrokerisrunning
properly.
TostoptheApacheActiveMQArtemisinstanceyouwillusethesameartemisscript,butwiththestopargument.Example:
/var/lib/mybroker/bin/artemisstop
PleasenotethatApacheActiveMQArtemisrequiresaJava7orlaterruntimetorun.
Bydefaulttheetc/bootstrap.xmlconfigurationisused.Theconfigurationcanbechangede.g.byrunning./artemisrun--
xml:path/to/bootstrap.xmloranotherconfigofyourchoosing.
Environmentvariablesareusedtoprovideeaseofchangingports,hostsanddatadirectoriesusedandcanbefoundin
etc/artemis.profileonlinuxandetc\artemis.profile.cmdonWindows.
TherunscriptssetsomeJVMsettingsfortuningthegarbagecollectionpolicyandheapsize.Werecommendusinga
parallelgarbagecollectionalgorithmtosmoothoutlatencyandminimiselargeGCpauses.
BydefaultApacheActiveMQArtemisrunsinamaximumof1GiBofRAM.Toincreasethememorysettingschangethe-
Xmsand-XmxmemorysettingsasyouwouldforanyJavaprogram.
IfyouwishtoaddanymoreJVMargumentsortunetheexistingones,therunscriptsaretheplacetodoit.
Thedistributioncontainsseveralstandardconfigurationsetsforrunning:
Nonclusteredstand-alone.
Clusteredstand-alone
Replicatedstand-alone
Shared-storestand-alone
Youcanofcoursecreateyourownconfigurationandspecifyanyconfigurationwhenrunningtherunscript.
Ifyou'reusingtheAsynchronousIOJournalonLinux,youneedtospecifyjava.library.pathasapropertyonyourJava
options.Thisisdoneautomaticallyinthescripts.
Ifyoudon'tspecifyjava.library.pathatyourJavaoptionsthentheJVMwillusetheenvironmentvariable
LD_LIBRARY_PATH.
YouwillneedtomakesurelibaioisinstalledonLinux.FormoreinformationrefertothelibaiochapteratRuntime
ServerJVMsettings
Pre-configuredOptions
LibraryPath
-
Dependencies
ApacheActiveMQArtemiscantakeasystempropertyonthecommandlineforconfiguringlogging.
Formoreinformationonconfiguringlogging,pleaseseethesectiononLogging.
Theconfigurationfileusedtobootstraptheserver(e.g.bootstrap.xmlbydefault)referencesthespecificbroker
configurationfiles.
broker.xml.ThisisthemainActiveMQconfigurationfile.Alltheparametersinthisfilearedescribedhere
Itisalsopossibletousesystempropertysubstitutioninalltheconfigurationfiles.byreplacingavaluewiththenameofa
systemproperty.Hereisanexampleofthiswithaconnectorconfiguration:
tcp://${activemq.remoting.netty.host:localhost}:${activemq.remoting.netty.port:61616}
Hereyoucanseewehavereplaced2valueswithsystempropertiesactivemq.remoting.netty.hostand
activemq.remoting.netty.port.Thesevalueswillbereplacedbythevaluefoundinthesystempropertyifthereisone,ifnot
theydefaultbacktolocalhostor61616respectively.Itisalsopossibletonotsupplyadefault.i.e.
${activemq.remoting.netty.host},howeverthesystempropertymustbesuppliedinthatcase.
Thestand-aloneserverisbasicallyasetofPOJOswhichareinstantiatedbyAirlinecommands.
Thebootstrapfileisverysimple.Let'stakealookatanexample:
core-Instantiatesacoreserverusingtheconfigurationfilefromtheconfigurationattribute.Thisisthemainbroker
POJOnecessarytodoalltherealmessagingwork.InadditionallJMSobjectssuchas:Queues,Topicsand
ConnectionFactoryinstancesareconfiguredhere.
TheconfigurationfortheApacheActiveMQArtemiscoreserveriscontainedinbroker.xml.Thisiswhatthe
FileConfigurationbeanusestoconfigurethemessagingserver.
TherearemanyattributeswhichyoucanconfigureApacheActiveMQArtemis.Inmostcasesthedefaultswilldofine,in
facteveryattributecanbedefaultedwhichmeansafilewithasingleemptyconfigurationelementisavalidconfiguration
file.Thedifferentconfigurationwillbeexplainedthroughoutthemanualoryoucanrefertotheconfigurationreferencehere.
Systemproperties
Configurationfiles
BootstrapFile
Themainconfigurationfile.
-
OnwindowsyouwillhavetheoptiontorunActiveMQArtemisasaservice.Justusethefollowingcommandtoinstallit:
$./artemis-service.exeinstall
Thecreateprocessshouldgiveyouahintoftheavailablecommandsavailablefortheartemis-service.exe
WindowsServer
-
ApacheActiveMQArtemishasauniqueaddressingmodelthatisbothpowerfulandflexibleandthatoffersgreat
performance.Theaddressingmodelcomprisesthreemainconcepts:addresses,queuesandroutingtypes.
Anaddressrepresentsamessagingendpoint.Withintheconfiguration,atypicaladdressisgivenauniquename,0ormore
queues,andaroutingtype.
Aqueueisassociatedwithanaddress.Therecanbemultiplequeuesperaddress.Onceanincomingmessageismatched
toanaddress,themessagewillbesentontooneormoreofitsqueues,dependingontheroutingtypeconfigured.Queues
canbeconfiguredtobeautomaticallycreatedanddeleted.
Aroutingtypedetermineshowmessagesaresenttothequeuesassociatedwithanaddress.AApacheActiveMQArtemis
addresscanbeconfiguredwithtwodifferentroutingtypes.
Table1.RoutingTypes
Ifyouwantyourmessagesroutedto… Usethisroutingtype…
Asinglequeuewithinthematchingaddress,inapoint-to-pointmanner. Anycast
Everyqueuewithinthematchingaddress,inapublish-subscribemanner. Multicast
Note:Itispossibletodefinemorethanoneroutingtypeperaddress,butthistypicallyresultsinananti-patternandisthereforenotrecommended.Ifanaddressdoesusebothroutingtypes,however,andtheclientdoesnotshowa
preferenceforeitherone,thebrokertypicallydefaultstotheanycastroutingtype.Theoneexceptioniswhentheclient
usestheMQTTprotocol.Inthatcase,thedefaultroutingtypeismulticast.|
Thefollowingexamplesshowhowtoconfigurebasicpointtopointandpublishsubscribeaddresses.
Point-to-pointmessagingisacommonscenarioinwhichamessagesentbyaproducerhasonlyoneconsumer.AMQP
andJMSmessageproducersandconsumerscanmakeuseofpoint-to-pointmessagingqueues,forexample.Definean
anycastroutingtypeforanaddresssothatitsqueuesreceivemessagesinapoint-to-pointmanner.
Whenamessageisreceivedonanaddressusinganycast,ApacheActiveMQArtemislocatesthequeueassociatedwith
theaddressandroutesthemessagetoit.Whenconsumersrequesttoconsumefromtheaddress,thebrokerlocatesthe
relevantqueueandassociatesthisqueuewiththeappropriateconsumers.Ifmultipleconsumersareconnectedtothe
samequeue,messagesaredistributedamongsteachconsumerequally,providingtheconsumersareequallyableto
handlethem.
ApacheActiveMQArtemisAddressingandQueues
BasicAddressConfiguration
Point-to-PointMessaging
-
Figure1.PointtoPointMessaging
Openthefile/etc/broker.xmlforediting.
Addanaddressconfigurationelementanditsassociatedqueueiftheydonotexistalready.
NoteFornormalPointtoPointsemantics,thequeuenameMUSTmatchtheaddressname.
...
Inapublish-subscribescenario,messagesaresenttoeveryconsumersubscribedtoanaddress.JMStopicsandMQTT
subscriptionsaretwoexamplesofpublish-subscribemessaging.
Toconfigureanaddresswithpublish-subscribesemantics,createanaddresswiththemulticastroutingtyoe.
Figure2.Publish-Subscribe
ConfiguringanAddresstoUsetheAnycastRoutingType
Publish-SubscribeMessaging
ConfiguringanAddresstoUsetheMulticastRoutingType
-
Openthefile/etc/broker.xmlforediting.
Addanaddressconfigurationelementwithmulticastroutingtype.
...
Whenclientsconnecttoanaddresswiththemulticastelement,asubscriptionqueuefortheclientwillbeautomatically
createdfortheclient.Itisalsopossibletopre-configuresubscriptionqueuesandconnecttothemdirectlyusingthequeue's
FullyQualifiedQueuenames.
Addonemorequeueelementstotheaddressandwrapthemulticastelementaroundthem.Thisstepistypicallynot
neededsincethebrokerwillautomaticallycreateaqueueforeachsubscriptionrequestedbyaclient.
...
Figure3.Point-to-PointwithTwoQueues
Itisactuallypossibletodefinemorethanonequeueonanaddresswithananycastroutingtype.Whenmessagesare
receivedonsuchanaddress,theyarefirstlydistributedevenlyacrossallthedefinedqueues.UsingFullyQualifiedQueue
names.,clientsareabletoselectthequeuethatthey’dliketosubscribeto.Shouldmorethanoneconsumerconnectdirect
toasinglequeue,ApacheActiveMQArtemiswilltakecareofdistributingmessagesbetweenthem,asintheexample
above.
Figure3.Point-to-PointwithTwoQueues
Note:ThisishowApacheActiveMQArtemishandlesloadbalancingofqueuesacrossmultiplenodesinacluster.ConfiguringaPoint-to-PointAddresswithTwoQueuesOpenthefile/etc/broker.xmlforediting.
Point-to-PointAddressmultipleQueues
-
AddanaddressconfigurationwithAnycastroutingtypeelementanditsassociatedqueues.
...
Itispossibletodefineanaddresswithbothpoint-to-pointandpublish-subscribesemanticsenabled.Whilenottypically
recommend,thiscanbeusefulwhenyouwant,forexample,aJMSQueuesayordersandaJMSTopicnamedorders.The
differentroutingtypesmaketheaddressesappeartobedistinct.
UsinganexampleofJMSClients,themessagessentbyaJMSqueueproducerwillberoutedusingtheanycastrouting
type.MessagessentbyaJMStopicproducerwillusethemulticastroutingtype.InadditionwhenaJMStopicconsumer
attachesitwillbeattachedtoit’sownsubscriptionqueue.JMSqueueconsumerwillbeattachedtotheanycastqueue.
Figure4.[Point-to-PointandPublish-Subscribe
Note:Thebehaviorinthisscenarioisdependentontheprotocolbeingused.ForJMSthereisacleardistinctionbetweentopicandqueueproducersandconsumers,whichmakethelogicstraightforward.OtherprotocolslikeAMQPdonotmake
thisdistinction.AmessagebeingsentviaAMQPwillberoutedbybothanycastandmulticastandconsumerswilldefaultto
anycast.Formoreinformation,pleasecheckthebehaviorofeachprotocolinthesectionsonprotocols.
TheXMLsnippetbelowisanexampleofwhattheconfigurationforanaddressusingbothanycastandmulticastwouldlook
likein/etc/broker.xml.routingtypes.Notethatsubscriptionqueuesaretypicallycreatedondemand,sothereisnoneedto
listspecificqueueelementsinsidethemulticastroutingtype.
...
Point-to-PointandPublish-SubscribeAddresses
-
ApacheActiveMQArtemissupportstheabilitytofiltermessagesusingApacheArtemisFilterExpressions.
Filterscanbeappliedintwoplaces,onaqueueandonaconsumer.
Whenafilterisappliedtoaqueue,messagesarefilterbeforetheysenttothequeue.Toaddaqueuefilterusethefilter
elementwhenconfiguringaqueue.Openupthebroker.xmlandaddanaddresswithaqueue,usingthefilterelementto
configureafilteronthisqueue.
Thefilterdefinedaboveensuresthatonlymessageswithanattribute"color='red'"issenttothisqueue.
ConsumerfiltersareappliedaftermessageshavereachedaqueueandaredefinedusingtheappropriateclientAPIs.The
followJMSexampleshowshowtoconsumerfilterswork.
1. Defineanaddresswithasinglequeue,withnofilterapplied.
...
//Sendsomemessages
for(inti=0;i<3;i++){
TextMessageredMessage=senderSession.createTextMessage("Red");
redMessage.setStringProperty("color","red");
producer.send(redMessage)
TextMessagegreenMessage=senderSession.createTextMessage("Green");
greenMessage.setStringProperty("color","green");
producer.send(greenMessage)
}
Atthispointthequeuewouldhave6messages:red,green,red,green,red,green
MessageConsumerredConsumer=redSession.createConsumer(queue,"color='red'");
TheredConsumerhasafilterthatonlymatches"red"messages.TheredConsumerwillreceive3messages.
red,red,red
Theresultingqueuewouldnowbe
green,green,green
Howtofiltermessages
QueueFilter
ConsumerFilters
-
YoucanconfigureApacheActiveMQArtemistoautomaticallycreateaddressesandqueues,andthendeletethemwhen
theyarenolongerinuse.Thissavesyoufromhavingtopreconfigureeachaddressandqueuebeforeaclientcanconnect
toit.Automaticcreationanddeletionisconfiguredonaperaddressbasisandiscontrolledbyfollowing:
Parameter Description
auto-create-addresses
Whensettotrue,thebrokerwillcreatetheaddressrequestedbytheclientifitdoesnotexistalready.Thedefaultistrue.
auto-delete-addresses
Whensettotrue,thebrokerwillbedeleteanyauto-createdadddressonceallofit’squeueshavebeendeleted.Thedefaultistrue
default-address-routing-type
Theroutingtypetouseiftheclientdoesnotspecifyone.PossiblevaluesareMULTICASTandANYCAST.Seeearlierinthischapterformoreinformationaboutroutingtypes.ThedefaultvalueisMULTICAST.
Editthefile/etc/broker.xmlandaddtheauto-create-addresseselementtotheaddress-settingyouwantthebrokerto
automaticallycreate.
(Optional)Addtheaddress-settingifitdoesnotexits.UsethematchparameterandtheTheApacheActiveMQArtemis
WildcardSyntaxtomatchmorethanonespecificaddress.
Setauto-create-addressestotrue
(Optional)AssignMULTICASTorANYCASTasthedefaultroutingtypefortheaddress.
Theexamplebelowconfiguresanaddress-settingtobeautomaticallycreatedbythebroker.Thedefaultroutingtypetobe
usedifnotspecifiedbytheclientisMULTICAST.Notethatwildcardsyntaxisused.Anyaddressstartingwith/news/politics/
willbeautomaticallycreatedbythebroker.
...
true
MULTICAST
...
Editthefile/etc/broker.xmlandaddtheauto-delete-addresseselementtotheaddress-settingyouwantthebrokerto
automaticallycreate.
(Optional)Addtheaddress-settingifitdoesnotexits.UsethematchparameterandtheTheApacheActiveMQArtemis
WildcardSyntaxtomatchmorethanonespecificaddress.
Setauto-delete-addressestotrue
Theexamplebelowconfiguresanaddress-settingtobeautomaticallydeletedbythebroker.Notethatwildcardsyntaxis
CreatingandDeletingAddressesandQueuesAutomatically
ConfiguringanAddresstobeAutomaticallyCreated
ConfiguringanAddresstobeAutomaticallyDeleted
-
used.Anyaddressrequestbytheclientthatstartswith/news/politics/isconfiguredtobeautomaticallydeletedbythe
broker.
...
true
MULTICAST
...
Internallythebrokermapsaclient’srequestforanaddresstospecificqueues.Thebrokerdecidesonbehalfoftheclient
whichqueuestosendmessagestoorfromwhichqueuetoreceivemessages.However,moreadvancedusecasesmight
requirethattheclientspecifyaqueuedirectly.Inthesesituationstheclientanduseafullyqualifiedqueuename,by
specifyingboththeaddressnameandthequeuename,separatedbya::.
Inthisexample,theaddressfooisconfiguredwithtwoqueuesq1,q2asshownintheconfigurationbelow.
...
Intheclientcode,useboththeaddressnameandthequeuenamewhenrequestingaconnectionfromthebroker.
Remembertousetwocolons,::,toseparatethenames,asintheexampleJavacodebelow.
StringFQQN="foo::q1";
Queueq1session.createQueue(FQQN);
MessageConsumerconsumer=session.createConsumer(q1);
Normally,ifaApacheActiveMQArtemisreceivsamessagesenttoaparticularaddress,thathasbothanycastand
multicastroutingtypesenable,ApacheActiveMQArtemiswillrouteacopyofthemessagetooneoftheanycastqueuesandtoallofthemulticastqueues.
However,clientscanspecifyaspecialprefixwhenconnectingtoanaddresstospecifywhethertoconnectusinganycastor
multicast.TheprefixesarecustomvaluesthataredesignatedusingtheanycastPrefixandmulticastPrefixparameters
withintheURLofanacceptor.
FullyQualifiedQueueNames
SpecifyingaFullyQualifiedQueueName
ConfiguringaPrefixtoConnecttoaSpecificRoutingType
ConfiguringanAnycastPrefix
-
In/etc/broker.xml,addtheanycastPrefixtotheURLofthedesiredacceptor.Intheexamplebelow,theacceptoris
configuredtouseanycast://fortheanycastPrefix.Clientcodecanspecifyanycast://foo/iftheclientneedstosenda
messagetoonlyoneoftheanycastqueues.
...
tcp://0.0.0.0:61616?protocols=AMQP;anycastPrefix=anycast://
...
In/etc/broker.xml,addtheanycastPrefixtotheURLofthedesiredacceptor.Intheexamplebelow,theacceptoris
configuredtousemulticast://forthemulticastPrefix.Clientcodecanspecifymulticast://foo/iftheclientneedsthemessage
senttoonlythemulticastqueuesoftheaddress.
...
tcp://0.0.0.0:61616?protocols=AMQP;multicastPrefix=multicast://
...
Inmostcasesit’snotnecessarytopre-createsubscriptionqueues.Therelevantprotocolmanagerstakecareofcreating
subscriptionqueueswhenclientsrequesttosubscribetoanaddress.Thetypeofsubscriptionqueuecreated,dependson
whatpropertiestheclientrequest.E.g.durable,non-shared,sharedetc...Protocolmanagersusesspecialqueuenamesto
identifywhichqueuesbelowtowhichconsumersandusersneednotworryaboutthedetails.
However,therearescenarioswhereausermaywanttousebrokersideconfigurationtopre-configureasubscription.And
laterconnecttothatqueuedirectlyusingaFullyQualifiedQueuename..Theexamplesbelowshowhowtousebrokerside
configurationtopre-configureaqueuewithpublishsubscribebehaviorforshared,non-shared,durableandnon-durable
subscriptionbehavior.
Thedefaultbehaviorforqueuesistonotlimitthenumberconnectedqueueconsumers.Themax-consumersparamterofthequeueelementcanbeusedtolimitthenumberofconnectedconsumersallowedatanyonetime.
Openthefile/etc/broker.xmlforediting.
...
true
ConfiguringaMulticastPrefix
AdvancedAddressConfiguration
Pre-configuringsubscriptionqueuesemantics
Configuringashareddurablesubscriptionqueuewithupto10concurrentconsumers
-
Thebrokercanbeconfiguredtopreventmorethanoneconsumerfromconnectingtoaqueueatanyonetime.The
subscriptionstoqueuesconfiguredthiswayaretherefore"non-shared".Todothissimplysetthemax-consumersparameterto"1"
...
true
Non-durablesubscriptionsareagainusuallymanagedbytherelevantprotocolmanager,bycreatinganddeleting
temporaryqueues.
Ifauserrequirestopre-createaqueuethatbehaveslikeanon-durablesubscriptionqueuethepurge-on-no-consumersflagcanbeenabledonthequeue.Whenpurge-on-no-consumersissettotrue.Thequeuewillnotstartreceivingmessagesuntilaconsumerisattached.Whenthelastconsumerisdetachedfromthequeue.Thequeueispurged(it's
messagesareremoved)andwillnotreceiveanymoremessagesuntilanewconsumerisattached.
Openthefile/etc/broker.xmlforediting.
...
AprotocolmanagermapsprotocolspecificconceptsdowntotheApacheActiveMQArtemiscoremodelofaddresses,
queuesandroutingtypes.Forexample,whenaclientsendsaMQTTsubscriptionpacketwiththeaddresses
/house/room1/lights
/house/room2/lights
TheMQTTprotocolmanagerunderstandsthatthetwoaddressesrequiremulticastsemantics.Theprotocolmanagerwill
thereforefirstlooktoensurethatmulticastisenabledforbothaddresses.Ifnot,itwillattempttodynamicallycreatethem.If
successful,theprotocolmanagerwillthencreatespecialsubscriptionqueueswithspecialnames,foreachsubscription
Configuringanon-shareddurablesubscription
Pre-configuringaqueueasanon-durablesubscriptionqueue
AdditionalInformation:ProtocolManagers,Address
-
requestedbytheclient.
Thespecialnameallowstheprotocolmanagertoquicklyidentifytherequiredclientsubscriptionqueuesshouldtheclient
disconnectandreconnectatalaterdate.Ifthesubscriptionistemporarytheprotocolmanagerwilldeletethequeueonce
theclientdisconnects.
Whenaclientrequeststosubscribetoapointtopointaddress.Theprotocolmanagerwilllookupthequeueassociated
withthepointtopointaddress.Thisqueueshouldhavethesamenameastheaddresss.
Note:Ifthequeueisautocreated,itwillbeautodeletedoncetherearenoconsumersandnomessagesinit.FormoreinformationonautocreateseethenextsectionConfiguringAddressesandQueuesviaAddressSettings
Therearesomeattributesthataredefinedagainstanaddresswildcardratherthanaspecificaddress/queue.Herean
exampleofanaddress-settingentrythatwouldbefoundinthebroker.xmlfile.
DLA
3
5000
ExpiryQueue
true
100000
20000
0
true
PAGE
-1
NOTIFY
5
Theideawithaddresssettings,isyoucanprovideablockofsettingswhichwillbeappliedagainstanyaddressesthat
matchthestringinthematchattribute.Intheaboveexamplethesettingswouldonlybeappliedtotheaddress"order.foo"
addressbutyoucanalsousewildcardstoapplysettings.See:Thechapteronthewildcardsyntax.
Forexample,ifyouusedthematchstringjms.queue.#thesettingswouldbeappliedtoalladdresseswhichstartwith
jms.queue.whichwouldbeallJMSqueues.
Themeaningofthespecificsettingsareexplainedfullythroughouttheusermanual,howeverhereisabriefdescription
withalinktotheappropriatechapterifavailable.
max-delivery-attemptsdefineshowmanytimeacancelledmessagecanberedeliveredbeforesendingtothedead-letter-
address.Afullexplanationcanbefoundhere.
redelivery-delaydefineshowlongtowaitbeforeattemptingredeliveryofacancelledmessage.seehere.
expiry-addressdefineswheretosendamessagethathasexpired.seehere.
expiry-delaydefinestheexpirationtimethatwillbeusedformessageswhichareusingthedefaultexpirationtime(i.e.0).
Forexample,ifexpiry-delayissetto"10"andamessagewhichisusingthedefaultexpirationtime(i.e.0)arrivesthenits
expirationtimeof"0"willbechangedto"10."However,ifamessagewhichisusinganexpirationtimeof"20"arrivesthen
itsexpirationtimewillremainunchanged.Settingexpiry-delayto"-1"willdisablethisfeature.Thedefaultis"-1".
last-value-queuedefineswhetheraqueueonlyuseslastvaluesornot.seehere.
max-size-bytesandpage-size-bytesareusedtosetpagingonanaddress.Thisisexplainedhere.
ConfiguringAddressesandQueuesviaAddressSettings
-
redistribution-delaydefineshowlongtowaitwhenthelastconsumerisclosedonaqueuebeforeredistributingany
messages.seehere.
send-to-dla-on-no-route.Ifamessageissenttoanaddress,buttheserverdoesnotrouteittoanyqueues,forexample,
theremightbenoqueuesboundtothataddress,ornoneofthequeueshavefiltersthatmatch,thennormallythatmessage
wouldbediscarded.Howeverifthisparameterissettotrueforthataddress,ifthemessageisnotroutedtoanyqueuesit
willinsteadbesenttothedeadletteraddress(DLA)forthataddress,ifitexists.
address-full-policy.Thisattributecanhaveoneofthefollowingvalues:PAGE,DROP,FAILorBLOCKanddetermines
whathappenswhenanaddresswheremax-size-bytesisspecifiedbecomesfull.ThedefaultvalueisPAGE.Ifthevalueis
PAGEthenfurthermessageswillbepagedtodisk.IfthevalueisDROPthenfurthermessageswillbesilentlydropped.If
thevalueisFAILthenfurthermessageswillbedroppedandanexceptionwillbethrownontheclient-side.Ifthevalueis
BLOCKthenclientmessageproducerswillblockwhentheytryandsendfurthermessages.Seethefollowingchaptersfor
moreinfoFlowControl,Paging.
slow-consumer-threshold.Theminimumrateofmessageconsumptionallowedbeforeaconsumerisconsidered"slow."
Measuredinmessages-per-second.Defaultis-1(i.e.disabled);anyothervalidvaluemustbegreaterthan0.
slow-consumer-policy.Whatshouldhappenwhenaslowconsumerisdetected.KILLwillkilltheconsumer'sconnection
(whichwillobviouslyimpactanyotherclientthreadsusingthatsameconnection).NOTIFYwillsendaCONSUMER_SLOW
managementnotificationwhichanapplicationcouldreceiveandtakeactionwith.Seeslowconsumersformoredetailson
thisnotification.
slow-consumer-check-period.Howoftentocheckforslowconsumersonaparticularqueue.Measuredinseconds.Default
is5.Seeslowconsumersformoreinformationaboutslowconsumerdetection.
auto-create-jms-queues.WhetherornotthebrokershouldautomaticallycreateaJMSqueuewhenaJMSmessageissent
toaqueuewhosenamefitstheaddressmatch(remember,aJMSqueueisjustacorequeuewhichhasthesameaddress
andqueuename)oraJMSconsumertriestoconnecttoaqueuewhosenamefitstheaddressmatch.Queueswhichare
auto-createdaredurable,non-temporary,andnon-transient.Defaultistrue.ThisisDEPRECATED.Seeauto-create-queues.
auto-delete-jms-queues.Whetherornotthebrokershouldautomaticallydeleteauto-createdJMSqueueswhentheyhave
both0consumersand0messages.Defaultistrue.ThisisDEPRECATED.Seeauto-delete-queues.
auto-create-jms-topics.WhetherornotthebrokershouldautomaticallycreateaJMStopicwhenaJMSmessageissent
toatopicwhosenamefitstheaddressmatch(remember,aJMStopicisjustacoreaddresswhichhasoneormorecore
queuesmappedtoit)oraJMSconsumertriestosubscribetoatopicwhosenamefitstheaddressmatch.Defaultistrue.
ThisisDEPRECATED.Seeauto-create-addresses.
auto-delete-jms-topics.Whetherornotthebrokershouldautomaticallydeleteauto-createdJMStopicsoncethelast
subscriptiononthetopichasbeenclosed.Defaultistrue.ThisisDEPRECATED.Seeauto-delete-addresses.
auto-create-queues.Whetherornotthebrokershouldautomaticallycreateaqueuewhenamessageissentoraconsumer
triestoconnecttoaqueuewhosenamefitstheaddressmatch.Queueswhichareauto-createdaredurable,non-
temporary,andnon-transient.Defaultistrue.
auto-delete-queues.Whetherornotthebrokershouldautomaticallydeleteauto-createdqueueswhentheyhaveboth0
consumersand0messages.Defaultistrue.
auto-create-addresses.Whetherornotthebrokershouldautomaticallycreateanaddresswhenamessageissenttoora
consumertriestoconsumefromaqueuewhichismappedtoanaddresswhosenamefitstheaddressmatch.Defaultis
true.
auto-delete-addresses.Whetherornotthebrokershouldautomaticallydeleteauto-createdaddressesoncetheaddressno
longerhasanyqueues.Defaultistrue.
-
AlthoughApacheActiveMQArtemisprovidesaJMSagnosticmessagingAPI,manyuserswillbemorecomfortableusing
JMS.
JMSisaverypopularAPIstandardformessaging,andmostmessagingsystemsprovideaJMSAPI.Ifyouarecompletely
newtoJMSwesuggestyoufollowtheOracleJMStutorial-afullJMStutorialisoutofscopeforthisguide.
ApacheActiveMQArtemisalsoshipswithawiderangeofexamples,manyofwhichdemonstrateJMSAPIusage.Agood
placetostartwouldbetoplayaroundwiththesimpleJMSQueueandTopicexample,butwealsoprovideexamplesfor
manyotherpartsoftheJMSAPI.AfulldescriptionoftheexamplesisavailableinExamples.
Inthissectionwe'llgothroughthemainstepsinconfiguringtheserverforJMSandcreatingasimpleJMSprogram.We'll
alsoshowhowtoconfigureanduseJNDI,andalsohowtouseJMSwithApacheActiveMQArtemiswithoutusingany
JNDI.
Forthischapterwe'regoingtouseaverysimpleorderingsystemasourexample.Itisasomewhatcontrivedexample
becauseofitsextremesimplicity,butitservestodemonstratetheverybasicsofsettingupandusingJMS.
WewillhaveasingleJMSQueuecalledOrderQueue,andwewillhaveasingleMessageProducersendinganordermessage
tothequeueandasingleMessageConsumerconsumingtheordermessagefromthequeue.
Thequeuewillbeadurablequeue,i.e.itwillsurviveaserverrestartorcrash.Wealsowanttopre-deploythequeue,i.e.
specifythequeueintheserverconfigurationsoitiscreatedautomaticallywithoutushavingtoexplicitlycreateitfromthe
client.
TheJMSspecificationestablishestheconventionthatadministeredobjects(i.e.JMSqueue,topicandconnectionfactoryinstances)aremadeavailableviatheJNDIAPI.BrokersarefreetoimplementJNDIastheyseefitassumingthe
implementationfitstheAPI.ApacheActiveMQArtemisdoesnothaveaJNDIserver.Rather,itusesaclient-sideJNDI
implementationthatreliesonspecialpropertiessetintheenvironmenttoconstructtheappropriateJMSobjects.Inother
words,noobjectsarestoredinJNDIontheApacheActiveMQArtemisserver,insteadtheyaresimplyinstantiatedonthe
clientbasedontheprovidedconfiguration.Let'slookatthedifferentkindsofadministeredobjectsandhowtoconfigure
them.
Note
ThefollowingconfigurationpropertiesarestrictlyrequiredwhenApacheActiveMQArtemisisrunninginstand-alonemode.WhenApacheActiveMQArtemisisintegratedtoanapplicationserver(e.g.Wildfly)theapplicationserveritselfwillalmostcertainlyprovideaJNDIclientwithitsownproperties.
AJMSconnectionfactoryisusedbytheclienttomakeconnectionstotheserver.Itknowsthelocationoftheserveritis
connectingto,aswellasmanyotherconfigurationparameters.
Here'sasimpleexampleoftheJNDIcontextenvironmentforaclientlookingupaconnectionfactorytoaccessan
embeddedinstanceofApacheActiveMQArtemis:
UsingJMS
Asimpleorderingsystem
JNDIConfiguration
ConnectionFactoryJNDI
http://docs.oracle.com/javaee/7/tutorial/partmessaging.htm
-
java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory
connectionFactory.invmConnectionFactory=vm://0
InthisinstancewehavecreatedaconnectionfactorythatisboundtoinvmConnectionFactory,anyentrywithprefix
connectionFactory.willcreateaconnectionfactory.
IncertainsituationstherecouldbemultipleserverinstancesrunningwithinaparticularJVM.Inthatsituationeachserver
wouldtypicallyhaveanInVMacceptorwithauniqueserver-ID.AclientusingJMSandJNDIcanaccountforthisby
specifyingaconnctionfactoryforeachserver,likeso:
java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory
connectionFactory.invmConnectionFactory0=vm://0
connectionFactory.invmConnectionFactory1=vm://1
connectionFactory.invmConnectionFactory2=vm://2
HereisalistofallthesupportedURLschemes:
vm
tcp
udp
jgroups
Mostclientswon'tbeconnectingtoanembeddedbroker.Clientswillmostcommonlyconnectacrossanetworkaremote
broker.Here'sasimpleexampleofaclientconfiguringaconnectionfactorytoconnecttoaremotebrokerrunningon
myhost:5445:
java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory
connectionFactory.ConnectionFactory=tcp://myhost:5445
IntheexampleabovetheclientisusingthetcpschemefortheproviderURL.Aclientmayalsospecifymultiplecomma-
delimitedhost:portcombinationsintheURL(e.g.(tcp://remote-host1:5445,remote-host2:5445)).Whetherthereisoneor
manyhost:portcombinationsintheURLtheyaretreatedastheinitialconnector(s)fortheunderlyingconnection.
Theudpschemeisalsosupportedwhichshoulduseahost:portcombinationthatmatchesthegroup-addressandgroup-
portfromthecorrespondingbroadcast-groupconfiguredontheActiveMQArtemisserver(s).
EachschemehasaspecificsetofpropertieswhichcanbesetusingthetraditionalURLquerystringformat(e.g.
scheme://host:port?key1=value1&key2=value2)tocustomizetheunderlyingtransportmechanism.Forexample,ifaclient
wantedtoconnecttoaremoteserverusingTCPandSSLitwouldcreateaconnectionfactorylikeso,tcp://remote-
host:5445?ssl-enabled=true.
AllthepropertiesavailableforthetcpschemearedescribedinthedocumentationregardingtheNettytransport.
Noteifyouareusingthetcpschemeandmultipleaddressesthenaquerycanbeappliedtoalltheurl'sorjusttoan
individualconnector,sowhereyouhave
(tcp://remote-host1:5445?httpEnabled=true,remote-host2:5445?httpEnabled=true)?clientID=1234
thenthehttpEnabledpropertyisonlysetontheindividualconnectorswhereastheclientIdissetontheactual
connectionfactory.AnyconnectorspecificpropertiessetonthewholeURIwillbeappliedtoalltheconnectors.
Theudpschemesupports4properties:
-
localAddress-Ifyouarerunningwithmultiplenetworkinterfacesonthesamemachine,youmaywanttospecifythat
thediscoverygrouplistensonlyonlyaspecificinterface.Todothisyoucanspecifytheinterfaceaddresswiththis
parameter.
localPort-Ifyouwanttospecifyalocalporttowhichthedatagramsocketisboundyoucanspecifyithere.Normally
youwouldjustusethedefaultvalueof-1whichsignifiesthatananonymousportshouldbeused.Thisparameteris
alwaysspecifiedinconjunctionwithlocalAddress.
refreshTimeout-Thisistheperiodthediscoverygroupwaitsafterreceivingthelastbroadcastfromaparticularserver
beforeremovingthatserversconnectorpairentryfromitslist.Youwouldnormallysetthistoavaluesignificantly
higherthanthebroadcast-periodonthebroadcastgroupotherwiseserversmightintermittentlydisappearfromthelist
eventhoughtheyarestillbroadcastingduetoslightdifferencesintiming.Thisparameterisoptional,thedefaultvalue
is10000milliseconds(10seconds).
discoveryInitialWaitTimeout-Iftheconnectionfactoryisusedimmediatelyaftercreationthenitmaynothavehad
enoughtimetoreceivedbroadcastsfromallthenodesinthecluster.Onfirstusage,theconnectionfactorywillmake
sureitwaitsthislongsincecreationbeforecreatingthefirstconnection.Thedefaultvalueforthisparameteris10000
milliseconds.
Lastly,thejgroupsschemeissupportedwhichprovidesanalternativetotheudpschemeforserverdiscovery.TheURL
patterniseitherjgroups://channelName?file=jgroups-xml-conf-filenamewherejgroups-xml-conf-filenamereferstoanXML
fileontheclasspaththatcontainstheJGroupsconfigurationoritcanbejgroups://channelName?properties=some-jgroups-
properties.InbothinstancethechannelNameisthenamegiventothejgroupschannelcreated.
TherefreshTimeoutanddiscoveryInitialWaitTimeoutpropertiesaresupportedjustlikewithudp.
Thedefaulttypeforthedefaultconnectionfactoryisoftypejavax.jms.ConnectionFactory.Thiscanbechangedbysetting
thetypelikeso
java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory
java.naming.provider.url=tcp://localhost:5445?type=CF
Inthisexampleitisstillsettothedefault,belowshowsalistoftypesthatcanbeset.
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
JMSdestinationsarealsotypicallylookedupviaJNDI.Aswithconnectionfactories,destinationscanbeconfiguredusing
specialpropertiesintheJNDIcontextenvironment.Thepropertynameshouldfollowthepattern:queue.ortopic..ThepropertyvalueshouldbethenameofthequeuehostedbytheApacheActiveMQArtemisserver.Forexample,iftheserverhadaJMSqueueconfiguredlikeso:
ConfigurationforConnectionFactoryTypes
DestinationJNDI
-
Andiftheclientwantedtobindthisqueueto"queues/OrderQueue"thentheJNDIpropertieswouldbeconfiguredlikeso:
java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory
java.naming.provider.url=tcp://myhost:5445
queue.queues/OrderQueue=OrderQueue
Itisalsopossibletolook-upJMSdestinationswhichhaven'tbeenconfiguredexplicitlyintheJNDIcontextenvironment.
ThisispossibleusingdynamicQueues/ordynamicTopics/inthelook-upstring.Forexample,iftheclientwantedtolook-up
theaforementioned"OrderQueue"itcoulddososimplybyusingthestring"dynamicQueues/OrderQueue".Note,thetext
thatfollowsdynamicQueues/ordynamicTopics/mustcorrespondexactlytothenameofthedestinationontheserver.
Here'sthecodefortheexample:
Firstwe'llcreateaJNDIinitialcontextfromwhichtolookupourJMSobjects.Iftheabovepropertiesaresetin
jndi.propertiesanditisontheclasspaththenanynew,emptyInitialContextwillbeinitializedusingthoseproperties:
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.
Warning
PleasenotethatJMSconnections,sessions,producersandconsumersaredesignedtobere-used.
Itisananti-patterntocreatenewconnections,sessions,producersandconsumersforeachmessageyouproduce
Thecode
-
orconsume.Ifyoudothis,yourapplicationwillperformverypoorly.Thisisdiscussedfurtherinthesectionon
performancetuningPerformanceTuning.
AlthoughitisaverycommonJMSusagepatterntolookupJMSAdministeredObjects(that'sJMSQueue,TopicandConnectionFactoryinstances)fromJNDI,insomecasesyoujustthink"WhydoIneedJNDI?Whycan'tIjustinstantiate
theseobjectsdirectly?"
WithApacheActiveMQArtemisyoucandoexactlythat.ApacheActiveMQArtemissupportsthedirectinstantiationofJMS
Queue,TopicandConnectionFactoryinstances,soyoudon'thavetouseJNDIatall.
Forafullworkingexampleofdirectinstantiationpleaselookatthe"InstantiateJMSObjectsDirectly"exampleunder
theJMSsectionoftheexamples.SeetheExamplessectionformoreinfo.
Here'soursimpleexample,rewrittentonotuseJNDIatall:
WecreatetheJMSConnectionFactoryobjectviatheActiveMQJMSClientUtilityclass,noteweneedtoprovideconnection
parametersandspecifywhichtransportweareusing,formoreinformationonconnectorspleaseseeConfiguringthe
Transport.
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());
ThisrepresentstheclientidforaJMSclientandisneededforcreatingdurablesubscriptions.Itispossibletoconfigurethis
ontheconnectionfactoryandcanbesetviatheclientIdelement.Anyconnectioncreatedbythisconnectionfactorywill
havethissetasitsclientid.
DirectlyinstantiatingJMSResourceswithoutusingJNDI
SettingTheClientID
-
WhentheJMSacknowledgemodeissettoDUPS_OKitispossibletoconfiguretheconsumersothatitsends
acknowledgementsinbatchesratherthatoneatatime,savingvaluablebandwidth.Thiscanbeconfiguredviathe
connectionfactoryviathedupsOkBatchSizeelementandissetinbytes.Thedefaultis1024*1024bytes=1MiB.
Whenreceivingmessagesinatransactionitispossibletoconfiguretheconsumertosendacknowledgementsinbatches
ratherthanindividuallysavingvaluablebandwidth.Thiscanbeconfiguredontheconnectionfactoryviathe
transactionBatchSizeelementandissetinbytes.Thedefaultis1024*1024.
SettingTheBatchSizeforDUPS_OK
SettingTheTransactionBatchSize
-
ApacheActiveMQArtemiscoreisacompletelyJMS-agnosticmessagingsystemwithitsownAPI.WecallthisthecoreAPI.
Ifyoudon'twanttouseJMSorotherprotocolsyoucanusethecoreAPIdirectly.ThecoreAPIprovidesallthefunctionality
ofJMSbutwithoutmuchofthecomplexity.ItalsoprovidesfeaturesthatarenotavailableusingJMS.
SomeofthecoremessagingconceptsaresimilartoJMSconcepts,butcoremessagingconceptsdifferinsomeways.In
generalthecoremessagingAPIissimplerthantheJMSAPI,sinceweremovedistinctionsbetweenqueues,topicsand
subscriptions.We'lldiscusseachofthemajorcoremessagingconceptsinturn,buttoseetheAPIindetail,pleaseconsult
theJavadoc.
Amessageistheunitofdatawhichissentbetweenclientsandservers.
Amessagehasabodywhichisabuffercontainingconvenientmethodsforreadingandwritingdataintoit.
Amessagehasasetofpropertieswhicharekey-valuepairs.Eachpropertykeyisastringandpropertyvaluescanbe
oftypeinteger,long,short,byte,byte[],String,double,floatorboolean.
Amessagehasanaddressitisbeingsentto.Whenthemessagearrivesontheserveritisroutedtoanyqueuesthatareboundtotheaddress-ifthequeuesareboundwithanyfilter,themessagewillonlyberoutedtothatqueueifthe
filtermatches.Anaddressmayhavemanyqueuesboundtoitorevennone.Theremayalsobeentitiesotherthan
queues,likedivertsboundtoaddresses.
Messagescanbeeitherdurableornondurable.Durablemessagesinadurablequeuewillsurviveaservercrashor
restart.Nondurablemessageswillneversurviveaservercrashorrestart.
Messagescanbespecifiedwithapriorityvaluebetween0and9.0representsthelowestpriorityand9representsthe
highest.ApacheActiveMQArtemiswillattempttodeliverhigherprioritymessagesbeforelowerpriorityones.
Messagescanbespecifiedwithanoptionalexpirytime.ApacheActiveMQArtemiswillnotdelivermessagesafterits
expirytimehasbeenexceeded.
Messagesalsohaveanoptionaltimestampwhichrepresentsthetimethemessagewassent.
ApacheActiveMQArtemisalsosupportsthesending/consumingofverylargemessagesmuchlargerthancanfitin
availableRAMatanyonetime.
Aservermaintainsamappingbetweenanaddressandasetofqueues.Zeroormorequeuescanbeboundtoasingle
address.Eachqueuecanbeboundwithanoptionalmessagefilter.Whenamessageisrouted,itisroutedtothesetof
queuesboundtothemessage'saddress.Ifanyofthequeuesareboundwithafilterexpression,thenthemessagewillonly
beroutedtothesubsetofboundqueueswhichmatchthatfilterexpression.
Otherentities,suchasdivertscanalsobeboundtoanaddressandmessageswillalsoberoutedthere.
Note
Incore,thereisnoconceptofaTopic,TopicisaJMSonlyterm.Instead,incore,wejustdealwithaddressesand
UsingCore
CoreMessagingConcepts
Message
Address
-
queues.
Forexample,aJMStopicwouldbeimplementedbyasingleaddresstowhichmanyqueuesarebound.Eachqueue
representsasubscriptionofthetopic.AJMSQueuewouldbeimplementedasasingleaddresstowhichonequeue
isbound-thatqueuerepresentstheJMSqueue.
Queuescanbedurable,meaningthemessagestheycontainsurviveaservercrashorrestart,aslongasthemessagesin
themaredurable.Nondurablequeuesdonotsurviveaserverrestartorcrashevenifthemessagestheycontainare
durable.
Queuescanalsobetemporary,meaningtheyareautomaticallydeletedwhentheclientconnectionisclosed,iftheyarenot
explicitlydeletedbeforethat.
Queuescanbeboundwithanoptionalfilterexpression.Ifafilterexpressionissuppliedthentheserverwillonlyroute
messagesthatmatchthatfilterexpressiontoanyqueuesboundtotheaddress.
Manyqueuescanbeboundtoasingleaddress.Aparticularqueueisonlyboundtoamaximumofoneaddress.
ClientsuseServerLocatorinstancestocreateClientSessionFactoryinstances.ServerLocatorinstancesareusedtolocate
serversandcreateconnectionstothem.
InJMStermsthinkofaServerLocatorinthesamewayyouwouldaJMSConnectionFactory.
ServerLocatorinstancesarecreatedusingtheActiveMQClientfactoryclass.
ClientsuseClientSessionFactoryinstancestocreateClientSessioninstances.ClientSessionFactoryinstancesare
basicallytheconnectiontoaserver
InJMStermsthinkofthemasJMSConnections.
ClientSessionFactoryinstancesarecreatedusingtheServerLocatorclass.
AclientusesaClientSessionforconsumingandproducingmessagesandforgroupingthemintransactions.ClientSession
instancescansupportbothtransactionalandnontransactionalsemanticsandalsoprovideanXAResourceinterfaceso
messagingoperationscanbeperformedaspartofaJTAtransaction.
ClientSessioninstancesgroupClientConsumersandClientProducers.
ClientSessioninstancescanberegisteredwithanoptionalSendAcknowledgementHandler.Thisallowsyourclientcodetobe
notifiedasynchronouslywhensentmessageshavesuccessfullyreachedtheserver.ThisuniqueApacheActiveMQArtemis
feature,allowsyoutohavefullguaranteesthatsentmessageshavereachedtheserverwithouthavingtoblockoneach
messagesentuntilaresponseisreceived.Blockingoneachmessagessentiscostlysinceitrequiresanetworkroundtrip
foreachmessagesent.Bynotblockingandreceivingsendacknowledgementsasynchronouslyyoucancreatetrueendto
endasynchronoussystemswhichisnotpossibleusingthestandardJMSAPI.Formoreinformationonthisadvanced
featurepleaseseethesectionGuaranteesofsendsandcommits.
ClientsuseClientConsumerinstancestoconsumemessagesfromaqueue.CoreMessagingsupportsbothsynchronous
Queue
ServerLocator
ClientSessionFactory
ClientSession
ClientConsumer
http://www.oracle.com/technetwork/java/javaee/tech/jta-138684.html
-
andasynchronousmessageconsumptionsemantics.ClientConsumerinstancescanbeconfiguredwithanoptionalfilter
expressionandwillonlyconsumemessageswhichmatchthatexpression.
ClientscreateClientProducerinstancesonClientSessioninstancessotheycansendmessages.ClientProducer
instancescanspecifyanaddresstowhichallsentmessagesarerouted,ortheycanhavenospecifiedaddress,andthe
addressisspecifiedatsendtimeforthemessage.
Warning
PleasenotethatClientSession,ClientProducerandClientConsumerinstancesaredesignedtobere-used.
It'sananti-patterntocreatenewClientSession,ClientProducerandClientConsumerinstancesforeachmessage
youproduceorconsume.Ifyoudothis,yourapplicationwillperformverypoorly.Thisisdiscussedfurtherinthe
sectiononperformancetuningPerformanceTuning.
Here'saverysimpleprogramusingthecoremessagingAPItosendandreceiveamessage.Logicallyit'scomprisedoftwo
sections:firstlysettinguptheproducertowriteamessagetoanaddresss,andsecondly,creatingaqueuefortheconsumer,creatingtheconsumerandstartingit.
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();
ClientProducer
AsimpleexampleofusingCore
-
ThischapterdescribeshowJMSdestinationsaremappedtoApacheActiveMQArtemisaddresses.
ApacheActiveMQArtemiscoreisJMS-agnostic.ItdoesnothaveanyconceptofaJMStopic.AJMStopicisimplemented
incoreasanaddresswithname=(thetopicname)andwithaMULTICASTroutingtypewithzeroormorequeuesboundto
it.Eachqueueboundtothataddressrepresentsatopicsubscription.
Likewise,aJMSqueueisimplementedasanaddresswithname=(theJMSqueuename)withanANYCASTroutingtype
assocatiedwithit.
Note.ThatwhilstitispossibletoconfigureaJMStopicandqueuewiththesamename,itisnotarecommended
configurationforusewithcrossprotocol.
MappingJMSConceptstotheCoreAPI
-
ApacheActiveMQArtemisrequiresseveraljarsontheClientClasspathdependingonwhethertheclientusesApacheActiveMQArtemisCoreAPI,JMS,andJNDI.
Warning
AllthejarsmentionedherecanbefoundinthelibdirectoryoftheApacheActiveMQArtemisdistribution.Besure
youonlyusethejarsfromthecorrectversionoftherelease,youmustnotmixandmatchversionsofjarsfromdifferentApacheActiveMQArtemisversions.Mixingandmatchingdifferentjarversionsmaycausesubtleerrorsand
failurestooccur.
IfyouareusingjustapureApacheActiveMQArtemisCoreclient(i.e.noJMS)thenyouneedactivemq-core-client.jar,
activemq-commons.jar,andnetty.jaronyourclientclasspath.
IfyouareusingJMSontheclientside,thenyouwillalsoneedtoincludeactivemq-jms-client.jarandgeronimo-
jms_2.0_spec.jar.
Note
geronimo-jms_2.0_spec.jarjustcontainsJavaEEAPIinterfaceclassesneededforthejavax.jms.*classes.Ifyou
alreadyhaveajarwiththeseinterfaceclassesonyourclasspath,youwillnotneedit.
TheClientClasspath
ApacheActiveMQArtemisCoreClient
JMSClient
-
TheApacheActiveMQArtemisdistributioncomeswithover90runout-of-the-boxexamplesdemonstratingmanyofthe
features.
Theexamplesareavailableinboththebinaryandsourcedistributionundertheexamplesdirectory.Examplesaresplitby
thefollowingsourcetree:
features-Examplescontainingbrokerspecificfeatures.
ha-examplesshowingfailoverandreconnectioncapabilities.
clustered-examplesshowingloadbalancinganddistributioncapabilities.
perf-examplesallowingyoutorunafewperformancetestsontheserver
sub-modules-examplesofintegratedexternalmodules.
protocols-Protocolspecificexamples
openwire
mqtt
stomp
amqp
AsetofJavaEEexamplesarealsoprovidedwhichneedWildFlyinstalledtobeabletorun.
Torunanyexample,simplycdintotheappropriateexampledirectoryandtypemvnverifyormvninstall(Fordetails
pleasereadthereadme.htmlineachexampledirectory).
Youcanusetheprofile-Pexamplestorunmultipleexamplesunderanyexampletree.
Foreachserver,youwillhaveacreatedserverunder./target/server0(someexamplesusemorethanoneserver).
Youhavetheoptiontopreventtheexamplefromstartingtheserver(e.g.ifyouwanttostarttheservermanually)bysimply
specifyingthe-PnoServerprofile,e.g.:
#runninganexamplewithoutrunningtheserver
mvnverify-PnoServer
Alsounder./targettherewillbeascriptrepeatingthecommandstocreateeachserver.Hereisthecreate-server0.sh
generatedbytheQueueexample.Thisisusefultoseeexactlywhatcommand(s)arerequiredtoconfiguretheserver(s).
#Thesearethecommandsusedtocreateserver0
/myInstallDirectory/apache-artemis-1.1.0/bin/artemiscreate--allow-anonymous--silent--force--no-web--userguest--passwordguest--roleguest--port-offset
SeveralexamplesuseUDPclusteringwhichmaynotworkinyourenvironmentbydefault.Onlinuxthecommandwouldbe:
routeadd-net224.0.0.0netmask240.0.0.0devlo
Thiscommandshouldberunasroot.Thiswillredirectanytrafficdirectedto224.0.0.0totheloopbackinterface.OnMac
OSX,thecommandisslightlydifferent:
sudorouteadd224.0.0.0127.0.0.1-netmask240.0.0.0
Examples
RunnningtheExamples
-
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/standard/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]
[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'
role:'org.apache.maven.plugin.Mojo',implementation:'org.apache.activemq.artemis.maven.ArtemisCreatePlugin',rolehint:
role:'org.apache.maven.plugin.Mojo',implementation:'org.apache.activemq.artemis.maven.ArtemisClientPlugin',rolehint:
---
Executingorg.apache.activemq.artemis.cli.commands.Createcreate--allow-anonymous--silent--force--no-web--userguest--passwordguest--roleguest--port-offset
Home::/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]awaitingservertostart
server-out:___
server-out:/\____||________(_)_____
server-out:/_\|_\__|/_\\/||/__/
server-out:/___\|\/|_/__/|\/|||\___\
server-out:/_/\_\|\__\____|_||_|_|/___/
server-out:ApacheActiveMQArtemis1.1.0
server-out:
server-out:
server-out:17:30:25,091INFO[org.apache.activemq.artemis.integration.bootstrap]AMQ101000:StartingActiveMQArtemisServer
server-out:17:30:25,120INFO[org.apache.activemq.artemis.core.server]AMQ221000:liveMessageBrokerisstartingwithconfigurationBrokerConfiguration(clustered=
server-out:17:30:25,152INFO[org.apache.activemq.artemis.core.server]AMQ221013:UsingNIOJournal
server-out:17:30:25,195INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-server].Addingprotocolsupport
server-out:17:30:25,199INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-amqp-protocol].Addingprotocolsupport
server-out:17:30:25,209INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-hornetq-protocol].Addingprotocolsupport
server-out:17:30:25,211INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-mqtt-protocol].Addingprotocolsupport
server-out:17:30:25,214INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-openwire-protocol].Addingprotocolsupport
server-out:17:30:25,335INFO[org.apache.activemq.artemis.core.server]AMQ221043:Protocolmodulefound:[artemis-stomp-protocol].Addingprotocolsupport
[INFO]awaitingservertostart
server-out:17:30:25,781INFO[org.apache.activemq.artemis.core.server]AMQ221003:tryingtodeployqueuejms.queue.DLQ
server-out:17:30:25,835INFO[org.apache.activemq.artemis.core.server]AMQ221003:tryingtodeployqueuejms.queue.ExpiryQueue
server-out:17:30:25,933INFO[org.apache.activemq.artemis.core.server]AMQ221020:StartedAcceptorat0.0.0.0:61616for
server-out:17:30:25,936INFO[org.apache.activem