svn.apache.org · 1. introduction 2. legal notice 3. preface 4. project info 5. messaging concepts...

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


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.


...

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.


...

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:


connectionFactory.invmConnectionFactory0=vm://0



HereisalistofallthesupportedURLschemes:

vm

tcp

udp

jgroups

Mostclientswon'tbeconnectingtoanembeddedbroker.Clientswillmostcommonlyconnectacrossanetworkaremote

broker.Here'sasimpleexampleofaclientconfiguringaconnectionfactorytoconnecttoaremotebrokerrunningon

myhost:5445:


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.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.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");


//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...


//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]

[INFO]generate-sources@queue>>>

[INFO]


[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


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


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

svn.apache.org · 1. introduction 2. legal notice 3. preface 4. project info 5. messaging concepts...

Documents