1.1

1.2

1.3

1.4

1.5

1.6

1.7

1.8

1.9

1.10

1.11

1.12

1.13

1.14

1.15

1.16

1.17

1.18

1.19

1.20

1.21

1.22

1.23

1.24

1.25

1.26

1.27

1.28

1.29

1.30

1.31

1.32

1.33

1.34

1.35

1.36

1.37

TableofContentsIntroduction

LegalNotice

Preface

ProjectInfo

Versions

MessagingConcepts

Architecture

UsingtheServer

Upgrading

AddressModel

ProtocolsandInteroperability

AMQP

MQTT

STOMP

OpenWire

Core

MappingJMSConceptstotheCoreAPI

UsingJMS

TheClientClasspath

Examples

RoutingMessagesWithWildCards

WildcardSyntax

FilterExpressions

Persistence

ConfiguringTransports

ConfigurationReload

DetectingDeadConnections

DetectingSlowConsumers

AvoidingNetworkIsolation

DetectingBrokerIssues(CriticalAnalysis)

ResourceManagerConfiguration

FlowControl

Guaranteesofsendsandcommits

MessageRedeliveryandUndeliveredMessages

MessageExpiry

LargeMessages

Paging

1

1.39

1.40

1.41

1.42

1.43

1.44

1.45

1.46

1.47

1.48

1.49

1.50

1.51

1.52

1.53

1.54

1.55

1.56

1.57

1.57.1

1.57.2

1.58

1.59

1.60

1.61

1.62

1.63

1.64

1.65

1.66

1.67

1.68

1.69

1.70

1.71

1.72

1.73

1.74

1.75

1.38ScheduledMessages

Last-ValueQueues

ExclusiveQueues

MessageGrouping

ConsumerPriority

ExtraAcknowledgeModes

Management

ManagementConsole

Metrics

Security

MaskingPasswords

BrokerPlugins

ResourceLimits

TheJMSBridge

ClientReconnectionandSessionReattachment

DivertingandSplittingMessageFlows

CoreBridges

DuplicateMessageDetection

Clusters

Federation

AddressFederation

QueueFederation

HighAvailabilityandFailover

GracefulServerShutdown

LibaioNativeLibraries

Threadmanagement

EmbeddedWebServer

Logging

RESTInterface

EmbeddingtheBroker

ApacheKaraf

ApacheTomcat

SpringIntegration

CDIIntegration

InterceptingOperations

DataTools

MavenPlugin

UnitTesting

TroubleshootingandPerformanceTuning

ConfigurationReference

2

ApacheActiveMQArtemisUserManualTheUsermanualisanindepthmanualonallaspectsofApacheActiveMQArtemis

Introduction

3

LegalNoticeLicensedtotheApacheSoftwareFoundation(ASF)underoneormorecontributorlicenseagreements.SeetheNOTICEfiledistributedwiththisworkforadditionalinformationregardingcopyrightownership.TheASFlicensesthisfiletoYouundertheApacheLicense,Version2.0(the"License");youmaynotusethisfileexceptincompliancewiththeLicense.YoumayobtainacopyoftheLicenseat

http://www.apache.org/licenses/LICENSE-2.0

Unlessrequiredbyapplicablelaworagreedtoinwriting,softwaredistributedundertheLicenseisdistributedonan"ASIS"BASIS,WITHOUTWARRANTIESORCONDITIONSOFANYKIND,eitherexpressorimplied.SeetheLicenseforthespecificlanguagegoverningpermissionsandlimitationsundertheLicense.

LegalNotice

4

http://www.apache.org/licenses/LICENSE-2.0

PrefaceWhatisApacheActiveMQArtemis?

ApacheActiveMQArtemisisanopensourceprojecttobuildamulti-protocol,embeddable,veryhighperformance,clustered,asynchronousmessagingsystem.

ApacheActiveMQArtemisisanexampleofMessageOrientedMiddleware(MoM).ForadescriptionofMoMsandothermessagingconceptspleaseseetheMessagingConcepts.

WhyuseApacheActiveMQArtemis?Herearejustafewofthereasons:

100%opensourcesoftware.ApacheActiveMQArtemisislicensedusingtheApacheSoftwareLicensev2.0tominimisebarrierstoadoption.

ApacheActiveMQArtemisisdesignedwithusabilityinmind.

WritteninJava.RunsonanyplatformwithaJava8+runtime,that'severythingfromWindowsdesktopstoIBMmainframes.

Amazingperformance.Ourground-breakinghighperformancejournalprovidespersistentmessagingperformanceatratesnormallyseenfornon-persistentmessaging,ournon-persistentmessagingperformancerockstheboattoo.

Fullfeatureset.Allthefeaturesyou'dexpectinanyseriousmessagingsystem,andothersyouwon'tfindanywhereelse.

Elegant,clean-cutdesignwithminimalthirdpartydependencies.RunActiveMQArtemisstand-alone,runitinintegratedinyourfavouriteJavaEEapplicationserver,orrunitembeddedinsideyourownproduct.It'suptoyou.

Seamlesshighavailability.WeprovideaHAsolutionwithautomaticclientfailoversoyoucanguaranteezeromessagelossorduplicationineventofserverfailure.

Hugelyflexibleclustering.Createclustersofserversthatknowhowtoloadbalancemessages.Linkgeographicallydistributedclustersoverunreliableconnectionstoformaglobalnetwork.Configureroutingofmessagesinahighlyflexibleway.

Preface

5

ProjectInformationTheofficialApacheActiveMQArtemisprojectpageishttp://activemq.apache.org/artemis/.

SoftwareDownload

ThesoftwarecanbedownloadfromtheDownloadpage:http://activemq.apache.org/artemis/download.html

ProjectInformation

Ifyouhaveanyuserquestionspleaseuseouruserforum

Ifyouhavedevelopmentrelatedquestions,pleaseuseourdeveloperforum

PopinandchattousinourIRCchannel

ApacheActiveMQArtemisGitrepositoryishttps://github.com/apache/activemq-artemis

Allreleasetagsareavailablefromhttps://github.com/apache/activemq-artemis/releases

Andmanythankstoallourcontributors,botholdandnewwhohelpedcreateApacheActiveMQArtemis.

ProjectInfo

6

http://activemq.apache.org/artemis/http://activemq.apache.org/artemis/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

VersionsThischapterprovidesthefollowinginformationforeachrelease:

Alinktothefullreleasenoteswhichincludesallissuesresolvedintherelease.Abrieflistof"highlights"whenapplicable.Ifnecessary,specificstepsrequiredwhenupgradingfromthepreviousversion.

Note:Iftheupgradespansmultipleversionsthenthestepsfromeachversionneedtobefollowedinorder.Note:FollowthegeneralupgradeprocedureoutlinedintheUpgradingtheBrokerchapterinadditiontoanyversion-specificupgradeinstructionsoutlinedhere.

2.9.0

Fullreleasenotes.

Thiswasalightrelease.Itincludedahandfulofbugfixes,afewimprovements,andonemajornewfeature.

Highlights:

Supportexportingmetrics.

2.8.1Fullreleasenotes.

Thiswasmainlyabug-fixreleasewithanotabledependencychangeimpactingversionupgrade.

Upgradingfrom2.8.0

DuetothedependencyupgrademadeonARTEMIS-2319thebrokerstartscriptsneedtobeadjustedafterupgrading.

On*nix

Locatethis ifstatementin bin/artemis:

if[-z"$LOG_MANAGER"];then

#thisistheonefoundwhentheserverwascreated

LOG_MANAGER="$ARTEMIS_HOME/lib/jboss-logmanager-2.0.3.Final.jar"

fi

Thisneedstobereplacedwiththisblock:

if[-z"$LOG_MANAGER"];then

#thisistheonefoundwhentheserverwascreated

LOG_MANAGER="$ARTEMIS_HOME/lib/jboss-logmanager-2.1.10.Final.jar"

fi

WILDFLY_COMMON=`ls$ARTEMIS_HOME/lib/wildfly-common*jar2>/dev/null`

if[-z"$WILDFLY_COMMON"];then

#thisistheonefoundwhentheserverwascreated

WILDFLY_COMMON="$ARTEMIS_HOME/lib/wildfly-common-1.5.1.Final.jar"

fi

Noticethatthe jboss-logmanagerversionhaschangedandthereisalsoanew wildfly-commonlibrary.

Versions

7

https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12345527https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12345432https://issues.apache.org/jira/browse/ARTEMIS-2319

Notmuchfurtherdownthereisthisline:

-Xbootclasspath/a:"$LOG_MANAGER"\

Thislineshouldbechangedtobe:

-Xbootclasspath/a:"$LOG_MANAGER:$WILDFLY_COMMON"\

OnWindows

Locatethispartof JAVA_ARGSin etc/artemis.profile.cmd:

-Xbootclasspath/a:%ARTEMIS_HOME%\lib\jboss-logmanager-2.1.10.Final.jar

Thisneedstobereplacedwiththis:

-Xbootclasspath/a:%ARTEMIS_HOME%\lib\jboss-logmanager-2.1.10.Final.jar;%ARTEMIS_HOME%\lib\wildfly-common-1.5.1.

Final.jar}

2.8.0

Fullreleasenotes.

Highlights:

SupportActiveMQ5featureJMSXGroupFirstForConsumer.Clarifyhandshaketimeouterrorwithremoteaddress.SupportduplicatedetectionforAMQPmessagesthesameascore.

2.7.0

Fullreleasenotes.

Highlights:

Supportadvanceddestinationoptionslike consumersBeforeDispatchStartsand timeBeforeDispatchStartsfrom5.x.Addsupportfordelaysbeforedeletingaddressesandqueuesvia auto-delete-queues-delayand auto-delete-addresses-delayAddressSettings.SupportloggingHTTPaccess.AddaCLIcommandtopurgeaqueue.SupportuserandrolemanipulationforPropertiesLoginModuleviamanagementinterfaces.Dockerimages.Auditlogging.Implementingconsumerpriority.SupportFQQNforproducers.Trackroutedandunroutedmessagessenttoanaddress.SupportconnectionpoolinginLDAPLoginModule.Supportconfiguringadefaultconsumerwindowsizevia default-consumer-window-sizeAddressSetting.Supportmasking key-store-passwordand trust-store-passwordinmanagement.xml.Support JMSXGroupSeq-1toclose/resetmessagegroupsfrom5.x.AllowconfigurationofRMIregistryport.

Versions

8

https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12345169https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12342977https://github.com/apache/activemq-artemis/tree/master/artemis-docker

Supportrouting-typeconfigurationoncorebridge.Moveartemis-nativeasitsownproject,asactivemq-artemis-native.Supportfederatedqueuesandaddresses.

2.6.4

Fullreleasenotes.

Thiswasmainlyabug-fixreleasewithafewimprovementsacouplenotablenewfeatures:

Highlights:

Addedtheabilitytosetthetextmessagecontentonthe producerCLIcommand.Supportreloadloggingconfigurationatruntime.

2.6.3

Fullreleasenotes.

Thiswasmainlyabug-fixreleasewithafewimprovementsbutnosubstantialnewfeatures.

2.6.2Fullreleasenotes.

Thiswasabug-fixreleasewithnosubstantialnewfeaturesorimprovements.

2.6.1

Fullreleasenotes.

Thiswasabug-fixreleasewithnosubstantialnewfeaturesorimprovements.

2.6.0Fullreleasenotes.

Highlights:

Supportregularexpressionsformatchingclientcertificates.Support SASL_EXTERNALforAMQPclients.Newexamplesshowingvirtualtopicmappingandexclusivequeuefeatures.

2.5.0

Fullreleasenotes.

Highlights:

Exclusiveconsumers.EquivalentActiveMQ5.xVirtualTopicnamingabilities.

Versions

9

https://github.com/apache/activemq-artemis-nativehttps://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12344010https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12343472https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12343404https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12343356https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12342903https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12342127

SSLCertificaterevocationlist.Last-valuequeuesupportforOpenWire.Supportmaskedpasswordsinbootstrap.xmandlogin.configConfigurablebrokerpluginimplementationforloggingvariousbrokerevents(i.e. LoggingActiveMQServerPlugin).OptiontouseOpenSSLproviderforNettyviathe sslProviderURLparameter.Enablesplittingofbroker.xmlintomultiplefiles.Enhancedmessagecountandsizemetricsforqueues.

Upgradingfrom2.4.0

1. DuetochangesfromARTEMIS-1644any acceptorthatneedstobecompatiblewithHornetQand/orArtemis1.xclientsneedstohave anycastPrefix=jms.queue.;multicastPrefix=jms.topic.inthe acceptorurl.Thisprefixusedtobeconfiguredautomaticallybehindthesceneswhenthebrokerdetectedtheseoldtypesofclients,butthatbrokecertainuse-caseswithnopossiblework-around.SeeARTEMIS-1644formoredetails.

2.4.0

Fullreleasenotes.

Highlights:

JMXconfigurationviaXMLratherthanhavingtousesystempropertiesviacommandlineorstartscript.ConfigurationofmaxframepayloadlengthforSTOMPweb-socket.AbilitytoconfigureHAusingJDBCpersistence.Implementrole-basedaccesscontrolformanagementobjects.

Upgradingfrom2.3.0

1. Create /etc/management.xml.Attheveryleast,thefilemustcontainthis:

ThisconfiguresrolebasedauthorisationforJMX.ReadmoreintheManagementdocumentation.2. Ifconfigured,removetheJolokiawarfilefromthe webelementin /etc/bootstrap.xml:

ThisisnolongerrequiredastheJolokiaRESTinterfaceisnowintegratedintotheconsolewebapplication.

Ifthefollowingisabsentandyoudesiretodeploythewebconsolethenadd:

Note:theJolokiaRESTinterfaceURLwillnowbeat http://:/console/jolokia

2.3.0Fullreleasenotes.

Highlights:

Webadminconsole!

Versions

10

https://issues.apache.org/jira/browse/ARTEMIS-1644https://issues.apache.org/jira/browse/ARTEMIS-1644https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12341540https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12341247

CriticalAnalysisanddeadlockdetectiononbrokerSupportNettynativekqueueonMac.Last-valuequeueforAMQP

Upgradingfrom2.2.0

1. Ifyoudesiretodeploythewebconsolethenaddthefollowingtothe webelementin/etc/bootstrap.xml:

2.2.0Fullreleasenotes.

Highlights:

ScheduledmessageswiththeSTOMPprotocol.SupportforJNDIReferenceFactoryandJNDIStorable.Abilitytodeletequeuesandaddresseswhenbroker.xmlchanges.ClientauthenticationviaKerberosTLSCipherSuites(RFC2712).

2.1.0

Fullreleasenotes.

Highlights:

Brokerpluginsupport.SupportNettynativeepollonLinux.Abilitytoconfigurearbitrarysecurityrolemappings.AMQPperformanceimprovements.

2.0.0

Fullreleasenotes.

Highlights:

Hugeupdateinvolvingasignificantrefactoringoftheaddressingmodelyieldingthefollowingbenefits:SimplerandmoreflexibleXMLconfiguration.Supportforadditionalmessaginguse-cases.EliminatesconfusingJMS-specificqueuenamingconventions(i.e."jms.queue."&"jms.topic."prefixes).

PureencodingofmessagessoprotocolslikeAMQPdon'tneedtoconvertmessagesto"core"formatunlessabsolutelynecessary."MAPPED"journaltypeforincreasedperformanceincertainuse-cases.

1.5.6

Fullreleasenotes.

Highlights:

Versions

11

https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12340541https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12339963https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12338813https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12340547

Bugfixes.

1.5.5

Fullreleasenotes.

Highlights:

Bugfixes.

1.5.4Fullreleasenotes.

Highlights:

SupportOracle12CforJDBCpersistence.Bugfixes.

1.5.3Fullreleasenotes.

Highlights:

Support"bytenotation"(e.g."K","KB","Gb",etc.)inbrokerXMLconfiguration.CLIcommandtorecalculatedisksynctimes.Bugfixes.

1.5.2

Fullreleasenotes.

Highlights:

SupportforpagingusingJDBC.Bugfixes.

1.5.1

Fullreleasenotes.

Highlights:

SupportoutgoingconnectionsforAMQP.Bugfixes.

1.5.0

Fullreleasenotes.

Highlights:

Versions

12

https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12339947https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12339158https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12339575https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12338833https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12338661https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12338118

AMQPperformanceimprovements.JUnitruleimplementationsomessagingresourceslikebrokerscanbeeasilyconfiguredintests.BasicCDIintegration.Storeuser'spasswordinhashformbydefault.

1.4.0

Fullreleasenotes.

Highlights:

"Global"limitfordiskusage.DetectandreloadcertainXMLconfigurationchangesatruntime.MQTTinterceptors.Supportadding/deletingqueuesviaCLI.New"browse"securitypermissionforclientswhoonlywishtolookatmessages.OptiontopopulateJMSXUserID."Dualauthentication"supporttoauthenticateSSL-basedandnon-SSL-basedclientsdifferently.

1.3.0Fullreleasenotes.

Highlights:

BettersupportofOpenWirefeatures(e.g.reconnect,producerflow-control,optimizedacknowledgements)SSLkeystorereloadatruntime.InitialsupportforJDBCpersistence.Supportscheduledmessagesonlast-valuequeue.

1.2.0Fullreleasenotes.

Highlights:

ImprovementsaroundperformanceOSGisupport.Supportfunctionalityequivalenttoall5.xJAASloginmodulesincluding:

PropertiesfileLDAPSSLcertificate"Guest"

1.1.0

Fullreleasenotes.

Highlights:

MQTTsupport.TheexamplesnowusetheCLIprogrammaticallytocreate,start,stop,etc.serversreflectingrealcasesusedinproduction.

Versions

13

https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12336052https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12328978https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12333274https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12332642&projectId=12315920

CLIimprovements.Therearenewtoolstocompactthejournalandadditionalimprovementstotheuserexperience.Configurableresourcelimits.Abilitytodisableserver-sidemessageload-balancing.

1.0.0

Fullreleasenotes.

Highlights:

Firstreleaseofthedonatedcode-baseasActiveMQArtemis!LotsoffeaturesforparitywithActiveMQ5.xincluding:

OpenWiresupportAMQP1.0supportURLbasedconnectionsAuto-createaddresses/queuesJolokiaintegration

Versions

14

https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12328953http://mail-archives.apache.org/mod_mbox/activemq-dev/201407.mbox/%3cCAKF+bsovr7Hvn-rMYkb3pF6hoGjx7nuJWzT_Nh8MyC4usRBX9A@mail.gmail.com%3e

MessagingConceptsApacheActiveMQArtemisisanasynchronousmessagingsystem,anexampleofMessageOrientedMiddleware,we'lljustcallthemmessagingsystemsintheremainderofthisbook.

We'llfirstpresentabriefoverviewofwhatkindofthingsmessagingsystemsdo,wherethey'reusefulandthekindofconceptsyou'llhearaboutinthemessagingworld.

Ifyou'realreadyfamiliarwithwhatamessagingsystemisandwhatit'scapableof,thenyoucanskipthischapter.

GeneralConceptsMessagingsystemsallowyoutolooselycoupleheterogeneoussystemstogether,whilsttypicallyprovidingreliability,transactionsandmanyotherfeatures.

UnlikesystemsbasedonaRemoteProcedureCall(RPC)pattern,messagingsystemsprimarilyuseanasynchronousmessagepassingpatternwithnotightrelationshipbetweenrequestsandresponses.Mostmessagingsystemsalsosupportarequest-responsemodebutthisisnotaprimaryfeatureofmessagingsystems.

Designingsystemstobeasynchronousfromend-to-endallowsyoutoreallytakeadvantageofyourhardwareresources,minimizingtheamountofthreadsblockingonIOoperations,andtouseyournetworkbandwidthtoitsfullcapacity.WithanRPCapproachyouhavetowaitforaresponseforeachrequestyoumakesoarelimitedbythenetworkroundtriptime,orlatencyofyournetwork.Withanasynchronoussystemyoucanpipelineflowsofmessagesindifferentdirections,soarelimitedbythenetworkbandwidthnotthelatency.Thistypicallyallowsyoutocreatemuchhigherperformanceapplications.

Messagingsystemsdecouplethesendersofmessagesfromtheconsumersofmessages.Thesendersandconsumersofmessagesarecompletelyindependentandknownothingofeachother.Thisallowsyoutocreateflexible,looselycoupledsystems.

Often,largeenterprisesuseamessagingsystemtoimplementamessagebuswhichlooselycouplesheterogeneoussystemstogether.MessagebusesoftenformthecoreofanEnterpriseServiceBus.(ESB).Usingamessagebustode-coupledisparatesystemscanallowthesystemtogrowandadaptmoreeasily.Italsoallowsmoreflexibilitytoaddnewsystemsorretireoldonessincetheydon'thavebrittledependenciesoneachother.

Messagingstyles

Messagingsystemsnormallysupporttwomainstylesofasynchronousmessaging:messagequeuemessaging(alsoknownaspoint-to-pointmessaging)andpublishsubscribemessaging.We'llsummarisethembrieflyhere:

Point-to-Point

Withthistypeofmessagingyousendamessagetoaqueue.Themessageisthentypicallypersistedtoprovideaguaranteeofdelivery,thensometimelaterthemessagingsystemdeliversthemessagetoaconsumer.Theconsumerthenprocessesthemessageandwhenitisdone,itacknowledgesthemessage.Oncethemessageisacknowledgeditdisappearsfromthequeueandisnotavailabletobedeliveredagain.Ifthesystemcrashesbeforethemessagingserverreceivesanacknowledgementfromtheconsumer,thenonrecovery,themessagewillbeavailabletobedeliveredtoaconsumeragain.

Withpoint-to-pointmessaging,therecanbemanyconsumersonthequeuebutaparticularmessagewillonlyeverbeconsumedbyamaximumofoneofthem.Senders(alsoknownasproducers)tothequeuearecompletelydecoupledfromreceivers(alsoknownasconsumers)ofthequeue-theydonotknowofeachother'sexistence.

Aclassicexampleofpointtopointmessagingwouldbeanorderqueueinacompany'sbookorderingsystem.Eachorderisrepresentedasamessagewhichissenttotheorderqueue.Let'simaginetherearemanyfrontendorderingsystemswhichsend

MessagingConcepts

15

https://en.wikipedia.org/wiki/Message-oriented_middlewarehttps://en.wikipedia.org/wiki/Remote_procedure_callhttps://en.wikipedia.org/wiki/Enterprise_service_bushttps://en.wikipedia.org/wiki/Message_queuehttps://en.wikipedia.org/wiki/Publish_subscribe

Aclassicexampleofpointtopointmessagingwouldbeanorderqueueinacompany'sbookorderingsystem.Eachorderisrepresentedasamessagewhichissenttotheorderqueue.Let'simaginetherearemanyfrontendorderingsystemswhichsendorderstotheorderqueue.Whenamessagearrivesonthequeueitispersisted-thisensuresthatiftheservercrashestheorderisnotlost.Let'salsoimaginetherearemanyconsumersontheorderqueue-eachrepresentinganinstanceofanorderprocessingcomponent-thesecanbeondifferentphysicalmachinesbutconsumingfromthesamequeue.Themessagingsystemdeliverseachmessagetooneandonlyoneoftheorderingprocessingcomponents.Differentmessagescanbeprocessedbydifferentorderprocessors,butasingleorderisonlyprocessedbyoneorderprocessor-thisensuresordersaren'tprocessedtwice.

Asanorderprocessorreceivesamessage,itfulfillstheorder,sendsorderinformationtothewarehousesystemandthenupdatestheorderdatabasewiththeorderdetails.Onceit'sdonethatitacknowledgesthemessagetotelltheserverthattheorderhasbeenprocessedandcanbeforgottenabout.Oftenthesendtothewarehousesystem,updateindatabaseandacknowledgementwillbecompletedinasingletransactiontoensureACIDproperties.

Publish-Subscribe

Withpublish-subscribemessagingmanysenderscansendmessagestoanentityontheserver,oftencalledatopic(e.g.intheJMSworld).

Therecanbemanysubscriptionsonatopic,asubscriptionisjustanotherwordforaconsumerofatopic.Eachsubscriptionreceivesacopyofeachmessagesenttothetopic.Thisdiffersfromthemessagequeuepatternwhereeachmessageisonlyconsumedbyasingleconsumer.

Subscriptionscanoptionallybedurablewhichmeanstheyretainacopyofeachmessagesenttothetopicuntilthesubscriberconsumesthem-eveniftheservercrashesorisrestartedinbetween.Non-durablesubscriptionsonlylastamaximumofthelifetimeoftheconnectionthatcreatedthem.

Anexampleofpublish-subscribemessagingwouldbeanewsfeed.Asnewsarticlesarecreatedbydifferenteditorsaroundtheworldtheyaresenttoanewsfeedtopic.Therearemanysubscribersaroundtheworldwhoareinterestedinreceivingnewsitems-eachonecreatesasubscriptionandthemessagingsystemensuresthatacopyofeachnewsmessageisdeliveredtoeachsubscription.

DeliveryguaranteesAkeyfeatureofmostmessagingsystemsisreliablemessaging.Withreliablemessagingtheservergivesaguaranteethatthemessagewillbedeliveredonceandonlyoncetoeachconsumerofaqueueoreachdurablesubscriptionofatopic,evenintheeventofsystemfailure.Thisiscrucialformanybusinesses;e.g.youdon'twantyourordersfulfilledmorethanonceoranyofyourorderstobelost.

Inothercasesyoumaynotcareaboutaonceandonlyoncedeliveryguaranteeandarehappytocopewithduplicatedeliveriesorlostmessages-anexampleofthismightbetransientstockpriceupdates-whicharequicklysupersededbythenextupdateonthesamestock.Themessagingsystemallowsyoutoconfigurewhichdeliveryguaranteesyourequire.

Transactions

Messagingsystemstypicallysupportthesendingandacknowledgementofmultiplemessagesinasinglelocaltransaction.ApacheActiveMQArtemisalsosupportsthesendingandacknowledgementofmessageaspartofalargeglobaltransaction-usingtheJavamappingofXA:JTA.

Durability

MessagingConcepts

16

https://en.wikipedia.org/wiki/ACID

Messagesareeitherdurableornondurable.Durablemessageswillbepersistedinpermanentstorageandwillsurviveserverfailureorrestart.Nondurablemessageswillnotsurviveserverfailureorrestart.Examplesofdurablemessagesmightbeordersortrades,wheretheycannotbelost.Anexampleofanondurablemessagemightbeastockpriceupdatewhichistransitoryanddoesn'tneedtosurvivearestart.

MessagingAPIsandprotocols

Howdoclientapplicationsinteractwithmessagingsystemsinordertosendandconsumemessages?

SeveralmessagingsystemsprovidetheirownproprietaryAPIswithwhichtheclientcommunicateswiththemessagingsystem.

Therearealsosomestandardwaysofoperatingwithmessagingsystemsandsomeemergingstandardsinthisspace.

Let'stakeabrieflookatthese:

JavaMessageService(JMS)

JMSispartofOracle'sJavaEEspecification.It'saJavaAPIthatencapsulatesbothmessagequeueandpublish-subscribemessagingpatterns.JMSisalowestcommondenominatorspecification-i.e.itwascreatedtoencapsulatecommonfunctionalityofthealreadyexistingmessagingsystemsthatwereavailableatthetimeofitscreation.

JMSisaverypopularAPIandisimplementedbymostmessagingsystems.JMSisonlyavailabletoclientsrunningJava.

JMSdoesnotdefineastandardwireformat-itonlydefinesaprogrammaticAPIsoJMSclientsandserversfromdifferentvendorscannotdirectlyinteroperatesinceeachwillusethevendor'sowninternalwireprotocol.

ApacheActiveMQArtemisprovidesafullycompliantJMS1.1andJMS2.0clientimplementation.

SystemspecificAPIs

ManysystemsprovidetheirownprogrammaticAPIforwhichtointeractwiththemessagingsystem.Theadvantageofthisitallowsthefullsetofsystemfunctionalitytobeexposedtotheclientapplication.API'slikeJMSarenotnormallyrichenoughtoexposealltheextrafeaturesthatmostmessagingsystemsprovide.

ApacheActiveMQArtemisprovidesitsowncoreclientAPIforclientstouseiftheywishtohaveaccesstofunctionalityoverandabovethataccessibleviatheJMSAPI.

PleaseseeCoreforusingtheCoreAPIwithApacheActiveMQArtemis.

RESTfulAPI

RESTapproachestomessagingareshowingalotinterestrecently.

ItseemsplausiblethatAPIstandardsforcloudcomputingmayconvergeonaRESTstylesetofinterfacesandconsequentlyaRESTmessagingapproachisaverystrongcontenderforbecomingthede-factomethodformessaginginteroperability.

WithaRESTapproachmessagingresourcesaremanipulatedasresourcesdefinedbyaURIandtypicallyusingasimplesetofoperationsonthoseresources,e.g.PUT,POST,GETetc.RESTapproachestomessagingoftenuseHTTPastheirunderlyingprotocol.

TheadvantageofaRESTapproachwithHTTPisinitssimplicityandthefacttheinternetisalreadytunedtodealwithHTTPoptimally.

PleaseseeRestInterfaceforusingApacheActiveMQArtemis'sRESTfulinterface.

AMQP

MessagingConcepts

17

https://en.wikipedia.org/wiki/Java_Message_Servicehttps://en.wikipedia.org/wiki/Representational_State_Transferhttps://en.wikipedia.org/wiki/AMQP

AMQPisaspecificationforinteroperablemessaging.Italsodefinesawireformat,soanyAMQPclientcanworkwithanymessagingsystemthatsupportsAMQP.AMQPclientsareavailableinmanydifferentprogramminglanguages.

ApacheActiveMQArtemisimplementstheAMQP1.0specification.Anyclientthatsupportsthe1.0specificationwillbeabletointeractwithApacheActiveMQArtemis.

PleaseseeAMQPforusingAMQPwithApacheActiveMQArtemis.

MQTT

MQTTisalightweightconnectivityprotocol.Itisdesignedtoruninenvironmentswheredeviceandnetworksareconstrained.OutoftheboxApacheActiveMQArtemissupportsversionMQTT3.1.1.AnyclientsupportingthisversionoftheprotocolwillworkagainstApacheActiveMQArtemis.

PleaseseeMQTTforusingMQTTwithApacheActiveMQArtemis.

STOMP

Stompisaverysimpletextprotocolforinteroperatingwithmessagingsystems.Itdefinesawireformat,sotheoreticallyanyStompclientcanworkwithanymessagingsystemthatsupportsStomp.Stompclientsareavailableinmanydifferentprogramminglanguages.

PleaseseeStompforusingSTOMPwithApacheActiveMQArtemis.

OpenWire

ActiveMQ5.xdefinesitsownwireprotocol:OpenWire.InordertosupportActiveMQ5.xclients,ApacheActiveMQArtemissupportsOpenWire.AnyActiveMQ5.12.xorhighercanbeusedwithApacheActiveMQArtemis.

PleaseseeOpenWireforusingOpenWirewithApacheActiveMQArtemis.

HighAvailability

HighAvailability(HA)meansthatthesystemshouldremainoperationalafterfailureofoneormoreoftheservers.ThedegreeofsupportforHAvariesbetweenvariousmessagingsystems.

ApacheActiveMQArtemisprovidesautomaticfailoverwhereyoursessionsareautomaticallyreconnectedtothebackupserveroneventofliveserverfailure.

FormoreinformationonHA,pleaseseeHighAvailabilityandFailover.

Clusters

Manymessagingsystemsallowyoutocreategroupsofmessagingserverscalledclusters.Clustersallowtheloadofsendingandconsumingmessagestobespreadovermanyservers.Thisallowsyoursystemtoscalehorizontallybyaddingnewserverstothecluster.

Degreesofsupportforclustersvariesbetweenmessagingsystems,withsomesystemshavingfairlybasicclusterswiththeclustermembersbeinghardlyawareofeachother.

ApacheActiveMQArtemisprovidesveryconfigurablestate-of-the-artclusteringmodelwheremessagescanbeintelligentlyloadbalancedbetweentheserversinthecluster,accordingtothenumberofconsumersoneachnode,andwhethertheyarereadyformessages.

MessagingConcepts

18

https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqphttps://mqtt.org/https://stomp.github.io/

ApacheActiveMQArtemisalsohastheabilitytoautomaticallyredistributemessagesbetweennodesofaclustertopreventstarvationonanyparticularnode.

Forfulldetailsonclustering,pleaseseeClusters.

Bridgesandrouting

Somemessagingsystemsallowisolatedclustersorsinglenodestobebridgedtogether,typicallyoverunreliableconnectionslikeawideareanetwork(WAN),ortheinternet.

Abridgenormallyconsumesfromaqueueononeserverandforwardsmessagestoanotherqueueonadifferentserver.Bridgescopewithunreliableconnections,automaticallyreconnectingwhentheconnectionsbecomesavailableagain.

ApacheActiveMQArtemisbridgescanbeconfiguredwithfilterexpressionstoonlyforwardcertainmessages,andtransformationcanalsobehookedin.

ApacheActiveMQArtemisalsoallowsroutingbetweenqueuestobeconfiguredinserversideconfiguration.Thisallowscomplexroutingnetworkstobesetupforwardingorcopyingmessagesfromonedestinationtoanother,formingaglobalnetworkofinterconnectedbrokers.

FormoreinformationpleaseseeCoreBridgesandDivertingandSplittingMessageFlows.

MessagingConcepts

19

CoreArchitectureApacheActiveMQArtemiscoreisdesignedsimplyassetofPlainOldJavaObjects(POJOs)-wehopeyoulikeitsclean-cutdesign.

EachApacheActiveMQArtemisserverhasitsownultrahighperformancepersistentjournal,whichitusesformessageandotherpersistence.

Usingahighperformancejournalallowsoutrageouspersistencemessageperformance,somethingnotachievablewhenusingarelationaldatabaseforpersistence(althoughJDBCisstillanoptionifnecessary).

ApacheActiveMQArtemisclients,potentiallyondifferentphysicalmachines,interactwiththeApacheActiveMQArtemisbroker.ApacheActiveMQArtemiscurrentlyshipstwoAPIimplementationsformessagingattheclientside:

1. CoreclientAPI.ThisisasimpleintuitiveJavaAPIthatisalignedwiththeArtemisinternalCore.Allowingmorecontrolofbrokerobjects(e.gdirectcreationofaddressesandqueues).TheCoreAPIalsooffersafullsetofmessagingfunctionalitywithoutsomeofthecomplexitiesofJMS.

2. JMS2.0clientAPI.ThestandardJMSAPIisavailableattheclientside.

ApacheActiveMQArtemisalsoprovidesdifferentprotocolimplementationsontheserversoyoucanuserespectiveclientsfortheseprotocols:

AMQPOpenWireMQTTSTOMPHornetQ(forusewithHornetQclients).Core(ArtemisCOREprotocol)

JMSsemanticsareimplementedbyaJMSfacadelayerontheclientside.

TheApacheActiveMQArtemisbrokerdoesnotspeakJMSandinfactdoesnotknowanythingaboutJMS,itisaprotocolagnosticmessagingserverdesignedtobeusedwithmultipledifferentprotocols.

WhenauserusestheJMSAPIontheclientside,allJMSinteractionsaretranslatedintooperationsontheApacheActiveMQArtemiscoreclientAPIbeforebeingtransferredoverthewireusingthecoreprotocol.

ThebrokeralwaysjustdealswithcoreAPIinteractions.

Aschematicillustratingthisrelationshipisshowninfigure3.1below:

Architecture

20

Figure3.1showstwouserapplicationsinteractingwithanApacheActiveMQArtemisserver.UserApplication1isusingtheJMSAPI,whileUserApplication2isusingthecoreclientAPIdirectly.

YoucanseefromthediagramthattheJMSAPIisimplementedbyathinfacadelayerontheclientside.

Stand-aloneBrokerThenormalstand-alonemessagingbrokerconfigurationcomprisesacoremessagingbrokerandanumberofprotocolmanagersthatprovidesupportforthevariousprotocolmentionedearlier.

Thestand-alonebrokerconfigurationusesAirlineforbootstrappingtheBroker.

Thestand-alonebrokerarchitectureisshowninfigure3.3below:

Architecture

21

https://github.com/airlift/airline

FormoreinformationonserverconfigurationfilesseeServerConfiguration

EmbeddedBroker

ApacheActiveMQArtemiscoreisdesignedasasetofsimplePOJOssoifyouhaveanapplicationthatrequiresmessagingfunctionalityinternallybutyoudon'twanttoexposethatasanApacheActiveMQArtemisbrokeryoucandirectlyinstantiateandembedbrokersinyourownapplication.

ReadmoreaboutembeddingApacheActiveMQArtemis.

IntegratedwithaJavaEEapplicationserverApacheActiveMQArtemisprovidesitsownfullyfunctionalJavaConnectorArchitecture(JCA)adaptorwhichenablesittobeintegratedeasilyintoanyJavaEEcompliantapplicationserverorservletengine.

JavaEEapplicationserversprovideMessageDrivenBeans(MDBs),whichareaspecialtypeofEnterpriseJavaBeans(EJBs)thatcanprocessmessagesfromsourcessuchasJMSsystemsormailsystems.

ProbablythemostcommonuseofanMDBistoconsumemessagesfromaJMSmessagingsystem.

AccordingtotheJavaEEspecification,aJavaEEapplicationserverusesaJCAadaptertointegratewithaJMSmessagingsystemsoitcanconsumemessagesforMDBs.

However,theJCAadapterisnotonlyusedbytheJavaEEapplicationserverforconsumingmessagesviaMDBs,itisalsousedwhensendingmessagetotheJMSmessagingsysteme.g.frominsideanEJBorservlet.

WhenintegratingwithaJMSmessagingsystemfrominsideaJavaEEapplicationserveritisalwaysrecommendedthatthisisdoneviaaJCAadaptor.Infact,communicatingwithaJMSmessagingsystemdirectly,withoutusingJCAwouldbeillegalaccordingtotheJavaEEspecification.

Theapplicationserver'sJCAserviceprovidesextrafunctionalitysuchasconnectionpoolingandautomatictransactionenlistment,whicharedesirablewhenusingmessaging,say,frominsideanEJB.ItispossibletotalktoaJMSmessagingsystemdirectlyfromanEJB,MDBorservletwithoutgoingthroughaJCAadapter,butthisisnotrecommendedsinceyouwillnotbeabletotakeadvantageoftheJCAfeatures,suchascachingofJMSsessions,whichcanresultinpoorperformance.

Architecture

22

Figure3.2belowshowsaJavaEEapplicationserverintegratingwithaApacheActiveMQArtemisserverviatheApacheActiveMQArtemisJCAadaptor.NotethatallcommunicationbetweenEJBsessionsorentitybeansandMessageDrivenbeansgothroughtheadaptorandnotdirectlytoApacheActiveMQArtemis.

ThelargearrowwiththeprohibitedsignshowsanEJBsessionbeantalkingdirectlytotheApacheActiveMQArtemisserver.Thisisnotrecommendedasyou'llmostlikelyendupcreatinganewconnectionandsessioneverytimeyouwanttointeractfromtheEJB,whichisananti-pattern.

Architecture

23

UsingtheServerThischapterwillfamiliariseyouwithhowtousetheApacheActiveMQArtemisserver.

We'llshowwhereitis,howtostartandstopit,andwe'lldescribethedirectorylayoutandwhatallthefilesareandwhattheydo.

FortheremainderofthischapterwhenwetalkabouttheApacheActiveMQArtemisserverwemeantheApacheActiveMQArtemisstandaloneserver,initsdefaultconfigurationwithaJMSServiceenabled.

ThisdocumentwillrefertothefullpathofthedirectorywheretheActiveMQdistributionhasbeenextractedtoas${ARTEMIS_HOME}directory.

Installation

Afterdownloadingthedistribution,thefollowinghighlightssomeimportantfoldersonthedistribution:

|___bin

|

|___examples

||___common

||___features

||___perf

||___protocols

|

|___lib

||___client

|

|___schema

|

|___web

|___api

|___hacking-guide

|___migration-guide

|___user-manual

bin-binariesandscriptsneededtorunActiveMQArtemis.

examples-Allmannerofexamples.Pleaserefertotheexampleschapterfordetailsonhowtorunthem.

lib-jarsandlibrariesneededtorunActiveMQArtemis

schema-XMLSchemasusedtovalidateActiveMQArtemisconfigurationfiles

web-Thefolderwherethewebcontextisloadedwhenthebrokerruns.

api-Theapidocumentationisplacedunderthewebfolder.

user-manual-Theusermanualisplacedunderthewebfolder.

CreatingaBrokerInstance

Abrokerinstanceisthedirectorycontainingalltheconfigurationandruntimedata,suchaslogsanddatafiles,associatedwithabrokerprocess.Itisrecommendedthatyoudonotcreatetheinstancedirectoryunder ${ARTEMIS_HOME}.ThisseparationisencouragedsothatyoucanmoreeasilyupgradewhenthenextversionofActiveMQArtemisisreleased.

OnUnixsystems,itisacommonconventiontostorethiskindofruntimedataunderthe /var/libdirectory.Forexample,tocreateaninstanceat'/var/lib/mybroker',runthefollowingcommandsinyourcommandlineshell:

UsingtheServer

24

cd/var/lib

${ARTEMIS_HOME}/bin/artemiscreatemybroker

Abrokerinstancedirectorywillcontainthefollowingsubdirectories:

bin:holdsexecutionscriptsassociatedwiththisinstance.etc:holdtheinstanceconfigurationfilesdata:holdsthedatafilesusedforstoringpersistentmessageslog:holdsrotatinglogfilestmp:holdstemporaryfilesthataresafetodeletebetweenbrokerruns

Atthispointyoumaywanttoadjustthedefaultconfigurationlocatedinthe etcdirectory.

Options

Thereareseveraloptionsyoucanusewhencreatinganinstance.

Forafulllistofupdatedpropertiesalwaysuse:

$./artemishelpcreate

NAME

artemiscreate-createsanewbrokerinstance

SYNOPSIS

artemiscreate[--addresses][--aio][--allow-anonymous]

[--autocreate][--blocking][--cluster-password]

[--cluster-user][--clustered][--data]

[--default-port][--disable-persistence]

[--encoding][--etc][--failover-on-shutdown][--force]

[--global-max-size][--home][--host]

[--http-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][--paging][--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)

--blocking

Blockproducerswhenaddressbecomesfull,oppositeof--paging

(Default:false)

--cluster-password

Theclusterpasswordtouseforclustering.(Default:input)

UsingtheServer

25

--cluster-user

Theclusterusertouseforclustering.(Default:input)

--clustered

Enableclustering

--data

DirectorywhereActiveMQdataarestored.Pathscanbeabsoluteor

relativetoartemis.instancedirectory('data'bydefault)

--default-port

Theportnumbertouseforthemain'artemis'acceptor(Default:

61616)

--disable-persistence

Disablemessagepersistencetothejournal

--encoding

Theencodingthattextfilesshoulduse

--etc

DirectorywhereActiveMQconfigurationislocated.Pathscanbeabsoluteor

relativetoartemis.instancedirectory('etc'bydefault)

--failover-on-shutdown

Validforsharedstore:willshutdowntriggerafailover?(Default:

false)

--force

Overwriteconfigurationatdestinationdirectory

--global-max-size

Maximumamountofmemorywhichmessagedatamayconsume(Default:

Undefined,halfofthesystem'smemory)

--home

DirectorywhereActiveMQArtemisisinstalled

--host

Thehostnameofthebroker(Default:0.0.0.0orinputifclustered)

--http-host

Thehostnametouseforembeddedwebserver(Default:localhost)

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

UsingtheServer

26

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

Removetheweb-serverdefinitionfrombootstrap.xml

--paging

Pagemessagestodiskwhenaddressbecomesfull,oppositeof

--blocking(Default:true)

--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:amq)

--shared-store

Enablebrokersharedstore

--silent

Itwilldisablealltheinputs,anditwouldmakeabestguessfor

anyrequiredinput

--slave

Validforsharedstoreorreplication:thisisaslaveserver?

--ssl-key

Thekeystorepathforembeddedwebserver

--ssl-key-password

Thekeystorepassword

--ssl-trust

Thetruststorepathincaseofclientauthentication

UsingtheServer

27

--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:isamandatoryproperty!

Pleaseprovidethedefaultusername:

admin

--password:ismandatorywiththisconfiguration:

Pleaseprovidethedefaultpassword:

--allow-anonymous|--require-login:isamandatoryproperty!

Allowanonymousaccess?,validvaluesareY,N,True,False

y

Autotuningjournal...

done!Yoursystemcanmake0.34writespermillisecond,yourjournal-buffer-timeoutwillbe2956000

Youcannowstartthebrokerbyexecuting:

"/user/server/bin/artemis"run

Oryoucanrunthebrokerinthebackgroundusing:

"/user/server/bin/artemis-service"start

StartingandStoppingaBrokerInstance

Assumingyoucreatedthebrokerinstanceunder /var/lib/mybrokerallyouneedtodostartrunningthebrokerinstanceisexecute:

/var/lib/mybroker/bin/artemisrun

Nowthatthebrokerisrunning,youcanoptionallyrunsomeoftheincludedexamplestoverifythethebrokerisrunningproperly.

TostoptheApacheActiveMQArtemisinstanceyouwillusethesame artemisscript,butwiththe stopargument.Example:

/var/lib/mybroker/bin/artemisstop

UsingtheServer

28

PleasenotethatApacheActiveMQArtemisrequiresaJava7orlaterruntimetorun.

Bydefaultthe etc/bootstrap.xmlconfigurationisused.Theconfigurationcanbechangede.g.byrunning ./artemisrun--xml:path/to/bootstrap.xmloranotherconfigofyourchoosing.

Environmentvariablesareusedtoprovideeaseofchangingports,hostsanddatadirectoriesusedandcanbefoundinetc/artemis.profileonlinuxand etc\artemis.profile.cmdonWindows.

ServerJVMsettingsTherunscriptssetsomeJVMsettingsfortuningthegarbagecollectionpolicyandheapsize.WerecommendusingaparallelgarbagecollectionalgorithmtosmoothoutlatencyandminimiselargeGCpauses.

BydefaultApacheActiveMQArtemisrunsinamaximumof1GiBofRAM.Toincreasethememorysettingschangethe -Xmsand -XmxmemorysettingsasyouwouldforanyJavaprogram.

IfyouwishtoaddanymoreJVMargumentsortunetheexistingones,therunscriptsaretheplacetodoit.

LibraryPathIfyou'reusingtheAsynchronousIOJournalonLinux,youneedtospecify java.library.pathasapropertyonyourJavaoptions.Thisisdoneautomaticallyinthescripts.

Ifyoudon'tspecify java.library.pathatyourJavaoptionsthentheJVMwillusetheenvironmentvariable LD_LIBRARY_PATH.

YouwillneedtomakesurelibaioisinstalledonLinux.Formoreinformationrefertothelibaiochapter.

Systemproperties

ApacheActiveMQArtemiscantakeasystempropertyonthecommandlineforconfiguringlogging.

Formoreinformationonconfiguringlogging,pleaseseethesectiononLogging.

ConfigurationfilesTheconfigurationfileusedtobootstraptheserver(e.g. bootstrap.xmlbydefault)referencesthespecificbrokerconfigurationfiles.

broker.xml.ThisisthemainActiveMQconfigurationfile.Alltheparametersinthisfilearedescribedhere

Itisalsopossibletousesystempropertysubstitutioninalltheconfigurationfiles.byreplacingavaluewiththenameofasystemproperty.Hereisanexampleofthiswithaconnectorconfiguration:

tcp://${activemq.remoting.netty.host:localhost}:${activemq.remoting.netty.port:61616}

Hereyoucanseewehavereplaced2valueswithsystemproperties activemq.remoting.netty.hostandactivemq.remoting.netty.port.Thesevalueswillbereplacedbythevaluefoundinthesystempropertyifthereisone,ifnottheydefaultbacktolocalhostor61616respectively.Itisalsopossibletonotsupplyadefault.i.e.${activemq.remoting.netty.host},howeverthesystempropertymustbesuppliedinthatcase.

Bootstrapconfigurationfile

UsingtheServer

29

Thestand-aloneserverisbasicallyasetofPOJOswhichareinstantiatedbyAirlinecommands.

Thebootstrapfileisverysimple.Let'stakealookatanexample:

server-Instantiatesacoreserverusingtheconfigurationfilefromthe configurationattribute.ThisisthemainbrokerPOJOnecessarytodoalltherealmessagingwork.

jaas-security-Configuressecurityfortheserver.The domainattributereferstotherelevantloginmoduleentryinlogin.config.

web-ConfiguresanembeddedJettyinstancetoservewebapplicationsliketheadminconsole.

Brokerconfigurationfile

TheconfigurationfortheApacheActiveMQArtemiscoreserveriscontainedin broker.xml.ThisiswhattheFileConfigurationbeanusestoconfigurethemessagingserver.

TherearemanyattributeswhichyoucanconfigureApacheActiveMQArtemis.Inmostcasesthedefaultswilldofine,infacteveryattributecanbedefaultedwhichmeansafilewithasingleempty configurationelementisavalidconfigurationfile.Thedifferentconfigurationwillbeexplainedthroughoutthemanualoryoucanrefertotheconfigurationreferencehere.

WindowsServer

OnwindowsyouwillhavetheoptiontorunActiveMQArtemisasaservice.Justusethefollowingcommandtoinstallit:

$./artemis-service.exeinstall

Thecreateprocessshouldgiveyouahintoftheavailablecommandsavailablefortheartemis-service.exe

AddingRuntimeDependencies

Runtimedependencieslikediverts,transformers,brokerplugins,JDBCdrivers,passworddecoders,etc.mustbeaccessiblebythebrokeratruntime.Packagethedependencyinajar,andputitonthebroker'sclasspath.Thiscanbedonebyplacingthejarfileinthe libdirectoryofthebrokerdistributionitselforinthe libdirectoryofthebrokerinstance.Abrokerinstancedoesnothavea libdirectorybydefaultsoitmayneedtobecreated.Itshouldbeonthe"top"levelwiththe bin, data, log,etc.directories.

UsingtheServer

30

UpgradingtheBrokerApacheActiveMQ5.x(andpreviousversions)isrunnableoutoftheboxbyexecutingthecommand: ./bin/activemqrun.TheActiveMQArtemisbrokerfollowsadifferentparadigmwheretheprojectdistributionservesasthebroker"home"andoneormorebroker"instances"arecreatedwhichreferencethe"home"forresources(e.g.jarfiles)whichcanbesafelysharedbetweenbrokerinstances.Therefore,aninstanceofthebrokermustbecreatedbeforeitcanberun.Thismayseemslikeanoverheadatfirstglance,butitbecomesverypracticalwhenupdatingtoanewArtemisversionforexample.

TocreateanArtemisbrokerinstancenavigateintotheArtemishomefolderandrun: ./bin/artemiscreate/path/to/myBrokerInstanceonthecommandline.

Becauseofthisseparationit'sveryeasytoupgradeArtemisinmostcases.

Note:

It'srecommendedtochooseafolderdifferentthantheonwhereApacheArtemiswasdownloaded.ThisseparationallowsyourunmultiplebrokerinstanceswiththesameArtemis"home"forexample.ItalsosimplifiesupdatingtonewerversionsofArtemis.

GeneralUpgradeProcedureUpgradingmayrequiresomespecificstepsnotedintheversions,butthegeneralprocessisasfollows:

1. Navigatetothe etcfolderofthebrokerinstancethat'sbeingupgraded2. Open artemis.profile( artemis.profile.cmdonWindows).Itcontainsapropertywhichisrelevantfortheupgrade:

ARTEMIS_HOME='/path/to/apache-artemis-version'

IfyourunArtemisasaserviceonwindowsyouhavetodothefollowingadditionalsteps:

1. Navigatetothe binfolderofthebrokerinstancethat'sbeingupgraded2. Open artemis-service.xml.Itcontainsapropertywhichisrelevantfortheupgrade:

The ARTEMIS_HOMEpropertyisusedtolinktheinstancewiththehome.Inmostcasestheinstancecanbeupgradedtoanewerversionsimplybychangingthevalueofthispropertytothelocationofthenewbrokerhome.Pleaserefertotheaforementionedversionsdocumentforadditionalupgradesteps(ifrequired).

Upgrading

31

AddressingModelApacheActiveMQArtemishasauniqueaddressingmodelthatisbothpowerfulandflexibleandthatoffersgreatperformance.Theaddressingmodelcomprisesthreemainconcepts:addresses,queues,androutingtypes.

Address

Anaddressrepresentsamessagingendpoint.Withintheconfiguration,atypicaladdressisgivenauniquename,0ormorequeues,andaroutingtype.

Queue

Aqueueisassociatedwithanaddress.Therecanbemultiplequeuesperaddress.Onceanincomingmessageismatchedtoanaddress,themessagewillbesentontooneormoreofitsqueues,dependingontheroutingtypeconfigured.Queuescanbeconfiguredtobeautomaticallycreatedanddeleted.

RoutingTypes

Aroutingtypedetermineshowmessagesaresenttothequeuesassociatedwithanaddress.AnApacheActiveMQArtemisaddresscanbeconfiguredwithtwodifferentroutingtypes.

Table1.RoutingTypes

Ifyouwantyourmessagesroutedto... Usethisroutingtype...

Asinglequeuewithinthematchingaddress,inapoint-to-pointmanner. Anycast

Everyqueuewithinthematchingaddress,inapublish-subscribemanner. Multicast

Note:Itispossibletodefinemorethanoneroutingtypeperaddress,butthistypicallyresultsinananti-patternandisthereforenotrecommended.Ifanaddressdoesusebothroutingtypes,however,andtheclientdoesnotshowapreferenceforeitherone,thebrokertypicallydefaultstotheanycastroutingtype.

TheoneexceptioniswhentheclientusestheMQTTprotocol.Inthatcase,thedefaultroutingtypeismulticast.

Foradditionaldetailsabouttheseconceptsrefertothecorechapter.

BasicAddressConfiguration

Thefollowingexamplesshowhowtoconfigurebasicpointtopointandpublishsubscribeaddresses.

Point-to-PointMessaging

Point-to-pointmessagingisacommonscenarioinwhichamessagesentbyaproducerhasonlyoneconsumer.AMQPandJMSmessageproducersandconsumerscanmakeuseofpoint-to-pointmessagingqueues,forexample.Defineananycastroutingtypeforanaddresssothatitsqueuesreceivemessagesinapoint-to-pointmanner.

Whenamessageisreceivedonanaddressusinganycast,ApacheActiveMQArtemislocatesthequeueassociatedwiththeaddressandroutesthemessagetoit.Whenconsumersrequesttoconsumefromtheaddress,thebrokerlocatestherelevantqueueandassociatesthisqueuewiththeappropriateconsumers.Ifmultipleconsumersareconnectedtothesamequeue,messagesaredistributedamongsteachconsumerequally,providingtheconsumersareequallyabletohandlethem.

AddressModel

32

Figure1.PointtoPointMessaging

UsingtheAnycastRoutingType

Openthefile /etc/broker.xmlforediting.

Addanaddressconfigurationelementanditsassociatedqueueiftheydonotexistalready.

Note:FornormalPointtoPointsemantics,thequeuenameMUSTmatchtheaddressname.

Publish-SubscribeMessaging

Inapublish-subscribescenario,messagesaresenttoeveryconsumersubscribedtoanaddress.JMStopicsandMQTTsubscriptionsaretwoexamplesofpublish-subscribemessaging.

Toconfigureanaddresswithpublish-subscribesemantics,createanaddresswiththemulticastroutingtype.

Figure2.Publish-Subscribe

UsingtheMulticastRoutingType

AddressModel

33

Openthefile /etc/broker.xmlforediting.

Addanaddressconfigurationelementwithmulticastroutingtype.

Whenclientsconnecttoanaddresswiththemulticastelement,asubscriptionqueuefortheclientwillbeautomaticallycreatedfortheclient.Itisalsopossibletopre-configuresubscriptionqueuesandconnecttothemdirectlyusingthequeue'sFullyQualifiedQueuenames.

Optionallyaddoneormorequeueelementstotheaddressandwrapthemulticastelementaroundthem.Thisstepistypicallynotneededsincethebrokerwillautomaticallycreateaqueueforeachsubscriptionrequestedbyaclient.

Figure3.Point-to-PointwithTwoQueues

Point-to-PointAddressmultipleQueues

Itisactuallypossibletodefinemorethanonequeueonanaddresswithananycastroutingtype.Whenmessagesarereceivedonsuchanaddress,theyarefirstlydistributedevenlyacrossallthedefinedqueues.UsingFullyQualifiedQueuenames,clientsareabletoselectthequeuethattheywouldliketosubscribeto.Shouldmorethanoneconsumerconnectdirectlytoasinglequeue,ApacheActiveMQArtemiswilltakecareofdistributingmessagesbetweenthem,asintheexampleabove.

Figure3.Point-to-PointwithTwoQueues

Note:ThisishowApacheActiveMQArtemishandlesloadbalancingofqueuesacrossmultiplenodesinacluster.ConfiguringaPoint-to-PointAddresswithtwoqueues,openthefile /etc/broker.xmlforediting.

AddanaddressconfigurationwithAnycastroutingtypeelementanditsassociatedqueues.

AddressModel

34

Point-to-PointandPublish-SubscribeAddresses

Itispossibletodefineanaddresswithbothpoint-to-pointandpublish-subscribesemanticsenabled.Whilenottypicallyrecommend,thiscanbeusefulwhenyouwant,forexample,aJMSQueuesayordersandaJMSTopicnamedorders.Thedifferentroutingtypesmaketheaddressesappeartobedistinct.

UsinganexampleofJMSClients,themessagessentbyaJMSmessageproducerwillberoutedusingtheanycastroutingtype.MessagessentbyaJMStopicproducerwillusethemulticastroutingtype.InadditionwhenaJMStopicconsumerattaches,itwillbeattachedtoit’sownsubscriptionqueue.JMSqueueconsumerwillbeattachedtotheanycastqueue.

Figure4.Point-to-PointandPublish-Subscribe

Note:Thebehaviorinthisscenarioisdependentontheprotocolbeingused.ForJMSthereisacleardistinctionbetweentopicandqueueproducersandconsumers,whichmakethelogicstraightforward.OtherprotocolslikeAMQPdonotmakethisdistinction.AmessagebeingsentviaAMQPwillberoutedbybothanycastandmulticastandconsumerswilldefaulttoanycast.Formoreinformation,pleasecheckthebehaviorofeachprotocolinthesectionsonprotocols.

TheXMLsnippetbelowisanexampleofwhattheconfigurationforanaddressusingbothanycastandmulticastwouldlooklikein /etc/broker.xml.Notethatsubscriptionqueuesaretypicallycreatedondemand,sothereisnoneedtolistspecificqueueelementsinsidethemulticastroutingtype.

Howtofiltermessages

ApacheActiveMQArtemissupportstheabilitytofiltermessagesusingApacheArtemisFilterExpressions.

Filterscanbeappliedintwoplaces,onaqueueandonaconsumer.

QueueFilter

AddressModel

35

Whenafilterisappliedtoaqueue,messagesarefilteredbeforetheyaresenttothequeue.Toaddaqueuefilterusethefilterelementwhenconfiguringaqueue.Openup /etc/broker.xmlandaddanaddresswithaqueue,usingthefilterelementtoconfigureafilteronthisqueue.

Thefilterdefinedaboveensuresthatonlymessageswithanattribute "color='red'"issenttothisqueue.

ConsumerFilters

ConsumerfiltersareappliedaftermessageshavereachedaqueueandaredefinedusingtheappropriateclientAPIs.ThefollowingJMSexampleshowshowconsumerfilterswork.

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

AutomaticAddress/QueueManagement

AddressModel

36

YoucanconfigureApacheActiveMQArtemistoautomaticallycreateaddressesandqueues,andthendeletethemwhentheyarenolongerinuse.Thissavesyoufromhavingtopreconfigureeachaddressandqueuebeforeaclientcanconnecttoit.Automaticcreationanddeletionisconfiguredonaperaddressbasisandiscontrolledbyfollowing:

Parameter Description

auto-create-addresses

Whensettotrue,thebrokerwillcreatetheaddressrequestedbytheclientifitdoesnotexistalready.Thedefaultis true.

auto-delete-addresses

Whensettotrue,thebrokerwillbedeleteanyauto-createdadddressonceallofit’squeueshavebeendeleted.Thedefaultis true

default-address-routing-type

Theroutingtypetouseiftheclientdoesnotspecifyone.Possiblevaluesare MULTICASTandANYCAST.Seeearlierinthischapterformoreinformationaboutroutingtypes.ThedefaultvalueisMULTICAST.

AutoAddressCreation

Editthefile /etc/broker.xmlandaddthe auto-create-addresseselementtothe address-settingyouwantthebrokertoautomaticallycreate.

(Optional)Addthe address-settingifitdoesnotexist.Usethematchparameterandthewildcardsyntaxtomatchmorethanonespecificaddress.

Set auto-create-addressesto true

(Optional)Assign MULTICASTor ANYCASTasthedefaultroutingtypefortheaddress.

Theexamplebelowconfiguresan address-settingtobeautomaticallycreatedbythebroker.ThedefaultroutingtypetobeusedifnotspecifiedbytheclientisMULTICAST.Notethatwildcardsyntaxisused.Anyaddressstartingwith/news/politics/willbeautomaticallycreatedbythebroker.

true

MULTICAST

AutoAddressDeletion

Editthefile /etc/broker.xmlandaddthe auto-delete-addresseselementtothe address-settingyouwantthebrokertoautomaticallycreate.

(Optional)Addthe address-settingifitdoesnotexist.Usethematchparameterandthewildcardsyntaxtomatchmorethanonespecificaddress.

Set auto-delete-addressesto true

Theexamplebelowconfiguresan address-settingtobeautomaticallydeletedbythebroker.Notethatwildcardsyntaxisused.Anyaddressrequestbytheclientthatstartswith /news/politics/isconfiguredtobeautomaticallydeletedbythebroker.

true

MULTICAST

"FullyQualified"QueueNames

AddressModel

37

Internallythebrokermapsaclient’srequestforanaddresstospecificqueues.Thebrokerdecidesonbehalfoftheclientwhichqueuestosendmessagestoorfromwhichqueuetoreceivemessages.However,moreadvancedusecasesmightrequirethattheclientspecifyaqueuedirectly.Inthesesituationstheclientusesafullyqualifiedqueuename,byspecifyingboththeaddressnameandthequeuename,separatedbya::.

CurrentlyArtemissupportsfullyqualifiedqueuenamesonCore,AMQP,JMS,OpenWire,MQTTandSTOMPprotocolsforreceivingmessagesonly.

SpecifyingaFullyQualifiedQueueName

Inthisexample,theaddressfooisconfiguredwithtwoqueuesq1,q2asshownintheconfigurationbelow.

Intheclientcode,useboththeaddressnameandthequeuenamewhenrequestingaconnectionfromthebroker.Remembertousetwocolons, ::,toseparatethenames,asintheexampleJavacodebelow.

StringFQQN="foo::q1";

Queueq1session.createQueue(FQQN);

MessageConsumerconsumer=session.createConsumer(q1);

UsingPrefixestoDetermineRoutingType

Normally,ifthebrokerreceivesamessagesenttoaparticularaddress,thathasboth ANYCASTand MULTICASTroutingtypesenable,itwillrouteacopyofthemessagetooneofthe ANYCASTqueuesandtoallofthe MULTICASTqueues.

However,clientscanspecifyaspecialprefixwhenconnectingtoanaddresstoindicatewhichkindofroutingtypetouse.TheprefixesarecustomvaluesthataredesignatedusingtheanycastPrefixandmulticastPrefixparameterswithintheURLofanacceptor.

ConfiguringanAnycastPrefix

In /etc/broker.xml,addthe anycastPrefixtotheURLofthedesiredacceptor.Intheexamplebelow,theacceptorisconfiguredtouse anycast://forthe anycastPrefix.Clientcodecanspecify anycast://foo/iftheclientneedstosendamessagetoonlyoneofthe ANYCASTqueues.

tcp://0.0.0.0:61616?protocols=AMQP;anycastPrefix=anycast://

ConfiguringaMulticastPrefix

In /etc/broker.xml,addthe multicastPrefixtotheURLofthedesiredacceptor.Intheexamplebelow,theacceptorisconfiguredtouse multicast://forthe multicastPrefix.Clientcodecanspecify multicast://foo/iftheclientneedstosendamessagetoonlyoneofthe MULTICASTqueues.

tcp://0.0.0.0:61616?protocols=AMQP;multicastPrefix=multicast://

AddressModel

38

AdvancedAddressConfiguration

StaticSubscriptionQueues

Inmostcasesit’snotnecessarytostaticallyconfiguresubscriptionqueues.Therelevantprotocolmanagerstakecareofdynamicallycreatingsubscriptionqueueswhenclientsrequesttosubscribetoanaddress.Thetypeofsubscriptionqueuecreateddependsonwhatpropertiestheclientrequest.Forexample,durable,non-shared,sharedetc.Protocolmanagersusespecialqueuenamingconventionstoidentifywhichqueuesbelongtowhichconsumersandusersneednotworryaboutthedetails.

However,therearescenarioswhereausermaywanttousebrokersideconfigurationtostaticallyconfigureasubscriptionandlaterconnecttothatqueuedirectlyusingaFullyQualifiedQueuename.Theexamplesbelowshowhowtousebrokersideconfigurationtostaticallyconfigureaqueuewithpublishsubscribebehaviorforshared,non-shared,durableandnon-durablesubscriptionbehavior.

Shared,DurableSubscriptionQueueusingmax-consumers

Thedefaultbehaviorforqueuesistonotlimitthenumberconnectedqueueconsumers.Themax-consumersparameterofthequeueelementcanbeusedtolimitthenumberofconnectedconsumersallowedatanyonetime.

Openthefile /etc/broker.xmlforediting.

true

Non-shared,DurableSubscriptionQueue

Thebrokercanbeconfiguredtopreventmorethanoneconsumerfromconnectingtoaqueueatanyonetime.Thesubscriptionstoqueuesconfiguredthiswayaretherefore"non-shared".Todothissimplysetthemax-consumersparameterto 1:

true

Non-durableSubscriptionQueue

Non-durablesubscriptionsareagainusuallymanagedbytherelevantprotocolmanager,bycreatinganddeletingtemporaryqueues.

Ifauserrequirestopre-createaqueuethatbehaveslikeanon-durablesubscriptionqueuethepurge-on-no-consumersflagcanbeenabledonthequeue.Whenpurge-on-no-consumersissettotrue.Thequeuewillnotstartreceivingmessagesuntilaconsumerisattached.Whenthelastconsumerisdetachedfromthequeue.Thequeueispurged(itsmessagesareremoved)and

AddressModel

39

willnotreceiveanymoremessagesuntilanewconsumerisattached.

Openthefile /etc/broker.xmlforediting.

ExclusiveConsumerQueue

Ifauserrequirestostaticallyconfigureaqueuethatroutesexclusivelytooneactiveconsumertheexclusiveflagcanbeenabledonthequeue.

Whenexclusiveissettotruethequeuewillroutemessagestotheasingleactiveconsumer.Whentheactiveconsumerthatisbeingroutedtoisdetachedfromthequeue,ifanotheractiveconsumerexist,onewillbechosenandroutingwillnowbeexclusivetoit.

SeeExclusiveQueueforfurtherinformation.

Openthefile /etc/broker.xmlforediting.

ProtocolManagersA"protocolmanager"mapsprotocol-specificconceptsdowntothecoreaddressingmodel(usingaddresses,queuesandroutingtypes).Forexample,whenaclientsendsaMQTTsubscriptionpacketwiththeaddresses:

/house/room1/lights

/house/room2/lights

TheMQTTprotocolmanagerunderstandsthatthetwoaddressesrequire MULTICASTsemantics.Theprotocolmanagerwillthereforefirstlooktoensurethat MULTICASTisenabledforbothaddresses.Ifnot,itwillattempttodynamicallycreatethem.Ifsuccessful,theprotocolmanagerwillthencreatespecialsubscriptionqueueswithspecialnames,foreachsubscriptionrequestedbytheclient.

Thespecialnameallowstheprotocolmanagertoquicklyidentifytherequiredclientsubscriptionqueuesshouldtheclientdisconnectandreconnectatalaterdate.Ifthesubscriptionistemporarytheprotocolmanagerwilldeletethequeueoncetheclientdisconnects.

Whenaclientrequeststosubscribetoapointtopointaddress.Theprotocolmanagerwilllookupthequeueassociatedwiththepointtopointaddress.Thisqueueshouldhavethesamenameastheaddresss.

Note:Ifthequeueisautocreated,itwillbeautodeletedoncetherearenoconsumersandnomessagesinit.FormoreinformationonautocreateseethenextsectionConfiguringAddressesandQueuesviaAddressSettings

AddressModel

40

ConfiguringAddressesandQueuesviaAddressSettings

Therearesomeattributesthataredefinedagainstanaddresswildcardratherthanaspecificaddress/queue.Hereanexampleofanaddress-settingentrythatwouldbefoundinthe broker.xmlfile.

DLA

ExpiryQueue

123

5000

1.0

10000

3

100000

-1

20000

PAGE

true

true

false

0

-1

0

true

-1

NOTIFY

5

true

true

true

true

true

true

false

0

0

OFF

true

true

0

OFF

200

false

-1

Theideawithaddresssettings,isyoucanprovideablockofsettingswhichwillbeappliedagainstanyaddressesthatmatchthestringinthe matchattribute.Intheaboveexamplethesettingswouldonlybeappliedtotheaddress"order.foo"addressbutyoucanalsousewildcardstoapplysettings.

Forexample,ifyouusedthe matchstring queue.#thesettingswouldbeappliedtoalladdresseswhichstartwith queue.

Themeaningofthespecificsettingsareexplainedfullythroughouttheusermanual,howeverhereisabriefdescriptionwithalinktotheappropriatechapterifavailable.

dead-letter-addressistheaddresstowhichmessagesaresentwhentheyexceed max-delivery-attempts.Ifnoaddressisdefinedherethensuchmessageswillsimplybediscarded.Readmoreaboutundeliveredmessages.

AddressModel

41

expiry-addressdefineswheretosendamessagethathasexpired.Ifnoaddressisdefinedherethensuchmessageswillsimplybediscarded.Readmoreaboutmessageexpiry.

expiry-delaydefinestheexpirationtimethatwillbeusedformessageswhichareusingthedefaultexpirationtime(i.e.0).Forexample,if expiry-delayissetto"10"andamessagewhichisusingthedefaultexpirationtime(i.e.0)arrivesthenitsexpirationtimeof"0"willbechangedto"10."However,ifamessagewhichisusinganexpirationtimeof"20"arrivesthenitsexpirationtimewillremainunchanged.Setting expiry-delayto"-1"willdisablethisfeature.Thedefaultis"-1".Readmoreaboutmessageexpiry.

max-delivery-attemptsdefineshowmanytimeacancelledmessagecanberedeliveredbeforesendingtothe dead-letter-address.Readmoreaboutundeliveredmessages.

redelivery-delaydefineshowlongtowaitbeforeattemptingredeliveryofacancelledmessage.Defaultis 0.Readmoreaboutundeliveredmessages.

redelivery-delay-multiplierdefinesthenumberbywhichthe redelivery-delaywillbemultipliedoneachsubsequentredeliveryattempt.Defaultis 1.0.Readmoreaboutundeliveredmessages.

max-size-bytes, page-size-bytes,& page-max-cache-sizeareusedtoconfigurepagingonanaddress.Thisisexplainedhere.

max-size-bytes-reject-thresholdisusedwiththeaddressfull BLOCKpolicy,themaximumsize(inbytes)anaddresscanreachbeforemessagesstartgettingrejected.Worksincombinationwith max-size-bytesforAMQPclientsonly.Defaultis-1(i.e.nolimit).

address-full-policy.Thisattributecanhaveoneofthefollowingvalues: PAGE, DROP, FAILor BLOCKanddetermineswhathappenswhenanaddresswhere max-size-bytesisspecifiedbecomesfull.Thedefaultvalueis PAGE.IfthevalueisPAGEthenfurthermessageswillbepagedtodisk.Ifthevalueis DROPthenfurthermessageswillbesilentlydropped.Ifthevalueis FAILthenfurthermessageswillbedroppedandanexceptionwillbethrownontheclient-side.Ifthevalueis BLOCKthenclientmessageproducerswillblockwhentheytryandsendfurthermessages.SeetheFlowControlandPagingchaptersformoreinfo.

message-counter-history-day-limitisthenumberofdaystokeepmessagecounterhistoryforthisaddressassumingthatmessage-counter-enabledis true.Defaultis 0.

last-value-queueisdeprecated.See default-last-value-queue.Itdefineswhetheraqueueonlyuseslastvaluesornot.Defaultis false.Readmoreaboutlastvaluequeues.

default-last-value-queuedefineswhetheraqueueonlyuseslastvaluesornot.Defaultis false.Thisvaluecanbeoverriddenatthequeuelevelusingthe last-valueboolean.Readmoreaboutlastvaluequeues.

default-exclusive-queuedefineswhetheraqueuewillserveonlyasingleconsumer.Defaultis false.Thisvaluecanbeoverriddenatthequeuelevelusingthe exclusiveboolean.Readmoreaboutexclusivequeues.

default-consumers-before-dispatchdefinesthenumberofconsumersneededonaqueueboundtothematchingaddressbeforemessageswillbedispatchedtothoseconsumers.Defaultis 0.Thisvaluecanbeoverriddenatthequeuelevelusingtheconsumers-before-dispatchboolean.Thisbehaviorcanbetunedusing delay-before-dispatchonthequeueitselforbyusingthe default-delay-before-dispatchaddress-setting.

default-delay-before-dispatchdefinesthenumberofmillisecondsthebrokerwillwaitfortheconfigurednumberofconsumerstoconnecttothematchingqueuebeforeitwillbegintodispatchmessages.Defaultis -1(waitforever).

redistribution-delaydefineshowlongtowaitwhenthelastconsumerisclosedonaqueuebeforeredistributinganymessages.Readmoreaboutclusters.

send-to-dla-on-no-route.Ifamessageissenttoanaddress,buttheserverdoesnotrouteittoanyqueues(e.g.theremightbenoqueuesboundtothataddress,ornoneofthequeueshavefiltersthatmatch)thennormallythatmessagewouldbediscarded.However,ifthisparameteris truethensuchamessagewillinsteadbesenttothe dead-letter-address(DLA)forthat

AddressModel

42

address,ifitexists.

slow-consumer-threshold.Theminimumrateofmessageconsumptionallowedbeforeaconsumerisconsidered"slow."Measuredinmessages-per-second.Defaultis -1(i.e.disabled);anyothervalidvaluemustbegreaterthan0.Readmoreaboutslowconsumers.

slow-consumer-policy.Whatshouldhappenwhenaslowconsumerisdetected. KILLwillkilltheconsumer'sconnection(whichwillobviouslyimpactanyotherclientthreadsusingthatsameconnection). NOTIFYwillsendaCONSUMER_SLOWmanagementnotificationwhichanapplicationcouldreceiveandtakeactionwith.Readmoreaboutslowconsumers.

slow-consumer-check-period.Howoftentocheckforslowconsumersonaparticularqueue.Measuredinseconds.Defaultis5.Readmoreaboutslowconsumers.

auto-create-jms-queuesisdeprecated.See auto-create-queues.WhetherornotthebrokershouldautomaticallycreateaJMSqueuewhenaJMSmessageissenttoaqueuewhosenamefitstheaddress match(remember,aJMSqueueisjustacorequeuewhichhasthesameaddressandqueuename)oraJMSconsumertriestoconnecttoaqueuewhosenamefitstheaddressmatch.Queueswhichareauto-createdaredurable,non-temporary,andnon-transient.Defaultis true.

auto-delete-jms-queuesisdeprecated.See auto-delete-queues.Whetherornotthebrokershouldautomaticallydeleteauto-createdJMSqueueswhentheyhaveboth0consumersand0messages.Defaultis true.

auto-create-jms-topicsisdeprecated.See auto-create-addresses.WhetherornotthebrokershouldautomaticallycreateaJMStopicwhenaJMSmessageissenttoatopicwhosenamefitstheaddress match(remember,aJMStopicisjustacoreaddresswhichhasoneormorecorequeuesmappedtoit)oraJMSconsumertriestosubscribetoatopicwhosenamefitstheaddress match.Defaultis true.

auto-delete-jms-topicsisdeprecated.See auto-delete-addresses.Whetherornotthebrokershouldautomaticallydeleteauto-createdJMStopicsoncethelastsubscriptiononthetopichasbeenclosed.Defaultis true.

auto-create-queues.Whetherornotthebrokershouldautomaticallycreateaqueuewhenamessageissentoraconsumertriestoconnecttoaqueuewhosenamefitstheaddress match.Queueswhichareauto-createdaredurable,non-temporary,andnon-transient.Defaultis true.

auto-delete-queues.Whetherornotthebrokershouldautomaticallydeleteauto-createdqueueswhentheyhaveboth0consumersandthemessagecountislessthanorequalto auto-delete-queues-message-count.Defaultis true.

auto-delete-created-queues.Whetherornotthebrokershouldautomaticallydeletecreatedqueueswhentheyhaveboth0consumersandthemessagecountislessthanorequalto auto-delete-queues-message-count.Defaultis false.

auto-delete-queues-delay.Howlongtowait(inmilliseconds)beforedeletingauto-createdqueuesafterthequeuehas0consumersandthemessagecountislessthanorequalto auto-delete-queues-message-count.Defaultis 0(deleteimmediately).Thebroker's address-queue-scan-periodcontrolshowoften(inmilliseconds)queuesarescannedforpotentialdeletion.Use -1todisablescanning.Thedefaultscanvalueis 30000.

auto-delete-queues-message-count.Themessagecountthatthequeuemustbelessthanorequaltobeforedeletingauto-createdqueues.Todisablemessagecountcheck -1canbeset.Defaultis 0(emptyqueue).

Note:theaboveauto-deleteaddresssettingscanalsobeconfiguredindividuallyatthequeuelevelwhenaclientautocreatesthequeue.

ForCoreAPIitisexposedincreateQueuemethods.

ForCoreJMSyoucansetitusingthedestinationqueueattributes my.destination?auto-delete=true&auto-delete-delay=120000&auto-delete-message-count=-1

config-delete-queues.Howthebrokershouldhandlequeuesdeletedonconfigreload,bydeletepolicy: OFFor FORCE.Defaultis OFF.Readmoreaboutconfigurationreload.

AddressModel

43

auto-create-addresses.Whetherornotthebrokershouldautomaticallycreateanaddresswhenamessageissenttooraconsumertriestoconsumefromaqueuewhichismappedtoanaddresswhosenamefitstheaddress match.Defaultis true.

auto-delete-addresses.Whetherornotthebrokershouldautomaticallydeleteauto-createdaddressesoncetheaddressnolongerhasanyqueues.Defaultis true.

auto-delete-addresses-delay.Howlongtowait(inmilliseconds)beforedeletingauto-createdaddressesaftertheynolongerhaveanyqueues.Defaultis 0(deleteimmediately).Thebroker's address-queue-scan-periodcontrolshowoften(inmilliseconds)addressesarescannedforpotentialdeletion.Use -1todisablescanning.Thedefaultscanvalueis 30000.

config-delete-addresses.Howthebrokershouldhandleaddressesdeletedonconfigreload,bydeletepolicy: OFFor FORCE.Defaultis OFF.Readmoreaboutconfigurationreload.

management-browse-page-sizeisthenumberofmessagesamanagementresourcecanbrowse.Thisisrelevantforthe"browse"managementmethodexposedonthequeuecontrol.Defaultis 200.

default-purge-on-no-consumersdefinesaqueue'sdefault purge-on-no-consumerssettingifnoneisprovidedonthequeueitself.Defaultis false.Thisvaluecanbeoverriddenatthequeuelevelusingthe purge-on-no-consumersboolean.Readmoreaboutthisfunctionality.

default-max-consumersdefinesaqueue'sdefault max-consumerssettingifnoneisprovidedonthequeueitself.Defaultis -1(i.e.nolimit).Thisvaluecanbeoverriddenatthequeuelevelusingthe max-consumersboolean.Readmoreaboutthisfunctionality.

default-queue-routing-typedefinestherouting-typeforanauto-createdqueueifthebrokerisunabletodeterminetherouting-typebasedontheclientand/orprotocolsemantics.Defaultis MULTICAST.Readmoreaboutroutingtypes.

default-address-routing-typedefinestherouting-typeforanauto-createdaddressifthebrokerisunabletodeterminetherouting-typebasedontheclientand/orprotocolsemantics.Defaultis MULTICAST.Readmoreaboutroutingtypes.

default-consumer-window-sizedefinesthedefault consumerWindowSizevaluefora COREprotocolconsumer,ifnotdefinedthedefaultwillbesetto1MiB(1024*1024bytes).Theconsumerwillusethisvalueasthewindowsizeifthevalueisnotsetontheclient.Readmoreaboutflowcontrol.

AddressModel

44

ProtocolsandInteroperabilityApacheActiveMQArtemishasapowerful&flexiblecorewhichprovidesafoundationuponwhichotherprotocolscanbeimplemented.Eachprotocolimplementationtranslatestheideasofitsspecificprotocolontothiscore.

Thebrokershipswithaclientimplementationwhichinteractsdirectlywiththiscore.Ituseswhat'scalledthe"core"API,anditcommunicatesoverthenetworkusingthe"core"protocol.

SupportedProtocols&APIs

Thebrokerhasapluggableprotocolarchitecture.Protocolpluginscomeintheformofprotocolmodules.Eachprotocolmoduleisincludedonthebroker'sclasspathandloadedbythebrokeratboottime.Thebrokershipswith5protocolmodulesoutofthebox.The5modulesoffersupportforthefollowingprotocols:

AMQPOpenWireMQTTSTOMPHornetQ

APIsandOtherInterfaces

AlthoughJMSisastandardizedAPI,itdoesnotdefineanetworkprotocol.TheActiveMQArtemisJMS2.0clientisimplementedontopofthecoreprotocol.Wealsoprovideaclient-sideJNDIimplementation.

ThebrokeralsoshipswithaRESTmessaginginterface(nottobeconfusedwiththeRESTmanagementAPIprovidedviaourintegrationwithJolokia).

ConfiguringAcceptors

Inordertomakeuseofaparticularprotocol,atransportmustbeconfiguredwiththedesiredprotocolenabled.Thereisawholesectiononconfiguringtransportsthatcanbefoundhere.

ThedefaultconfigurationshippedwiththeActiveMQArtemisdistributioncomeswithanumberofacceptorsalreadydefined,oneforeachoftheaboveprotocolsplusagenericacceptorthatsupportsallprotocols.Toenableprotocolsonaparticularacceptorsimplyaddthe protocolsurlparametertotheacceptorurlwherethevalueisoneormoreprotocols(separatedbycommas).Ifthe protocolsparameterisomittedfromtheurlallprotocolsareenabled.

ThefollowingexampleenablesonlyMQTTonport1883

tcp://localhost:1883?protocols=MQTT

ThefollowingexampleenablesMQTTandAMQPonport1883

tcp://localhost:5672?protocols=MQTT,AMQP

Thefollowingexampleenablesallprotocolson 61616:

ProtocolsandInteroperability

45

tcp://localhost:61616

Herearethesupportedprotocolsandtheircorrespondingvalueusedinthe protocolsurlparameter.

Protocol protocolsvalue

Core(Artemis&HornetQnative) CORE

OpenWire(5.xnative) OPENWIRE

AMQP AMQP

MQTT MQTT

STOMP STOMP

ProtocolsandInteroperability

46

AMQPApacheActiveMQArtemissupportstheAMQP1.0specification.Bydefaultthereare acceptorelementsconfiguredtoacceptAMQPconnectionsonports 61616and 5672.

SeethegeneralProtocolsandInteroperabilitychapterfordetailsonconfiguringan acceptorforAMQP.

YoucanuseanyAMQP1.0compatibleclients.

Ashortlistincludes:

qpidclients.NETClientsJavascriptNodeJSJavaScriptRHEA...andmanyothers.

ExamplesWehaveafewexamplesaspartoftheArtemisdistribution:

.NET:./examples/protocols/amqp/dotnet

ProtonCPP./examples/protocols/amqp/proton-cpp./examples/protocols/amqp/proton-clustered-cpp

Ruby./examples/protocols/amqp/proton-ruby

Java(UsingtheqpidJMSClient)./examples/protocols/amqp/queue

Interceptors./examples/features/standard/interceptor-amqp./examples/features/standard/broker-plugin

MessageConversions

ThebrokerwillnotperformanymessageconversiontoanyotherprotocolswhensendingAMQPandreceivingAMQP.

HoweverifyouintendyourmessagetobereceivedbyanAMQPJMSClient,youmustfollowtheJMSMappingConventions.IfyousendabodytypethatisnotrecognizedbythisspecificationtheconversionbetweenAMQPandanyotherprotocolwillmakeitaBinaryMessage.Makesureyoufollowtheseconventionsifyouintendtocrossprotocolsorlanguages.Especiallyonthemessagebody.

AcompatibilitysettingallowsaligningthenamingconventionofAMQPqueues(JMSDurableandSharedSubscriptions)withCORE.Forbackwardscompatibilityreasons,youneedtoexplicitlyenablethisviabrokerconfiguration:

amqp-use-core-subscription-naming

true-usequeuenamingconventionthatisalignedwithCORE.false(default)-useoldernamingconvention.

Interceptingandchangingmessages

AMQP

47

https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqphttps://qpid.apache.org/download.htmlhttps://blogs.apache.org/activemq/entry/using-net-libraries-with-activemqhttps://github.com/noodlefrenzy/node-amqp10https://github.com/grs/rheahttps://www.oasis-open.org/committees/download.php/53086/amqp-bindmap-jms-v1.0-wd05.pdf

Interceptingandchangingmessages

Wedon'trecommendchangingmessagesattheserver'ssideforafewreasons:

AMQPmessagesaremeanttobeimmutableThemessagewon'tbetheoriginalmessagetheusersentAMQPhasthepossibilityofsigningmessages.Thesignaturewouldbebroken.Forperformancereasons.Wetrynottore-encode(orevendecode)messages.

IfregardlesstheserecommendationsyoustillneedandwanttointerceptandchangeAMQPmessages,lookattheaforementionedinterceptorexamples.

AMQPandsecurity

TheApacheActiveMQArtemisServeracceptsthePLAIN,ANONYMOUS,andGSSAPISASLmechanism.Theseareimplementedonthebroker'ssecurityinfrastructure.

AMQPanddestinations

IfanAMQPLinkisdynamicthenatemporaryqueuewillbecreatedandeithertheremotesourceorremotetargetaddresswillbesettothenameofthetemporaryqueue.IftheLinkisnotdynamicthenthetheaddressoftheremotetargetorsourcewillusedforthequeue.Ifthisdoesnotexistthenitwillbeauto-createdifthesettingsallow.

AMQPandMulticastAddresses(Topics)

AlthoughAMQPhasnonotionof"topics"itisstillpossibletotreatAMQPconsumersorreceiversassubscriptionsratherthanjustconsumersonaqueue.Bydefaultanyreceivinglinkthatattachestoanaddressthathasonly multicastenabledwillbetreatedasasubscriptionandacorrespondingsubscriptionqueuewillbecreated.IftheTerminusDurabilityiseitherUNSETTLED_STATEor CONFIGURATIONthenthequeuewillbemadedurable(similartoaJMSdurablesubscription)andgivenanamemadeupfromthecontaineridandthelinkname,somethinglike my-container-id:my-link-name.IftheTerminusDurabilityisconfiguredas NONEthenavolatile multicastqueuewillbecreated.

AMQPandCoordinations-HandlingTransactions

AnAMQPlinkstargetcanalsobeaCoordinator.ACoordinatorisusedtohandletransactions.Ifacoordinatorisusedthentheunderlyingserversessionwillbetransactedandwillbeeitherrolledbackorcommittedviathecoordinator.

Note:

AMQPallowstheuseofmultipletransactionspersession, amqp:multi-txns-per-ssn,howeverinthisversionofApacheActiveMQArtemiswillonlysupportsingletransactionspersession.

AMQPschedulingmessagedelivery

AnAMQPmessagecanprovideschedulinginformationthatcontrolsthetimeinthefuturewhenthemessagewillbedeliveredattheearliest.Thisinformationisprovidedbyaddingamessageannotationtothesentmessage.

Therearetwodifferentmessageannotationsthatcanbeusedtoscheduleamessageforlaterdelivery:

AMQP

48

x-opt-delivery-timeThespecifiedvaluemustbeapositivelongcorrespondingtothetimethemessageshouldbemadeavailablefordelivery(inmilliseconds).

x-opt-delivery-delayThespecifiedvaluemustbeapositivelongcorrespondingtotheamountofmillisecondsafterthebrokerreceivesthegivenmessagebeforeitshouldbemadeavailablefordelivery.

Ifbothannotationsarepresentinthesamemessagethenthebrokerwillpreferthemorespecific x-opt-delivery-timevalue.

ConfiguringAMQPIdleTimeoutItispossibletoconfiguretheAMQPServer'sIDLETimeoutbysettingthepropertyamqpIdleTimeoutinmillisecondsontheacceptor.

ThiswillmaketheservertosendanAMQPframeopentotheclient,withyourconfiguredtimeout/2.

So,ifyouconfiguredyourAMQPIdleTimeouttobe60000,theserverwilltelltheclienttosendframesevery30,000milliseconds.

....;amqpIdleTimeout=;.....

DisablingKeepalivechecks

ifyousetamqpIdleTimeout=0thatwilltellclientstonotsendingkeepalivepacketstowardstheserver.OnthiscaseyouwillrelyonTCPtodeterminewhenthesocketneedstobeclosed.

....;amqpIdleTimeout=0;.....

ThiscontainsarealexampleforconfiguringamqpIdleTimeout:

tcp://0.0.0.0:5672?amqpIdleTimeout=0;tcpSendBufferSize=1048576;tcpReceiveBufferSize=10485

76;protocols=AMQP;useEpoll=true;amqpCredits=1000;amqpMinCredits=300;directDeliver=false;batchDelay=10

AMQP

49

MQTTMQTTisalightweight,clienttoserver,publish/subscribemessagingprotocol.MQTThasbeenspecificallydesignedtoreducetransportoverhead(andthusnetworktraffic)andcodefootprintonclientdevices.ForthisreasonMQTTisideallysuitedtoconstraineddevicessuchassensorsandactuatorsandisquicklybecomingthedefactostandardcommunicationprotocolforIoT.

ApacheActiveMQArtemissupportsMQTTv3.1.1(andalsotheolderv3.1codemessageformat).BydefaultthereareacceptorelementsconfiguredtoacceptMQTTconnectionsonports 61616and 1883.

SeethegeneralProtocolsandInteroperabilitychapterfordetailsonconfiguringan acceptorforMQTT.

ThebestsourceofinformationontheMQTTprotocolisinthe3.1.1specification.

RefertotheMQTTexamplesforalookatsomeofthisfunctionalityinaction.

MQTTQualityofServiceMQTToffers3qualityofservicelevels.

Eachmessage(ortopicsubscription)candefineaqualityofservicethatisassociatedwithit.Thequalityofserviceleveldefinedonatopicisthemaximumlevelaclientiswillingtoaccept.Thequalityofservicelevelonamessageisthedesiredqualityofservicelevelforthismessage.Thebrokerwillattempttodelivermessagestosubscribersatthehighestqualityofservicelevelbasedonwhatisdefinedonthemessageandtopicsubscription.

Eachqualityofserviceleveloffersalevelofguaranteebywhichamessageissentorreceived:

QoS0: ATMOSTONCE

Guaranteesthataparticularmessageisonlyeverreceivedbythesubscriberamaximumofonetime.Thisdoesmeanthatthemessagemayneverarrive.Thesenderandthereceiverwillattempttodeliverthemessage,butifsomethingfailsandthemessagedoesnotreachitsdestination(sayduetoanetworkconnection)themessagemaybelost.ThisQoShastheleastnetworktrafficoverheadandtheleastburdenontheclientandthebrokerandisoftenusefulfortelemetrydatawhereitdoesn'tmatterifsomeofthedataislost.

QoS1: ATLEASTONCE

Guaranteesthatamessagewillreachitsintendedrecipientoneormoretimes.Thesenderwillcontinuetosendthemessageuntilitreceivesanacknowledgmentfromtherecipient,confirmingithasreceivedthemessage.TheresultofthisQoSisthattherecipientmayreceivethemessagemultipletimes,andalsoincreasesthenetworkoverheadthanQoS0,(duetoacks).Inadditionmoreburdenisplacedonthesenderasitneedstostorethemessageandretryshoulditfailtoreceiveanackinareasonabletime.

QoS2: EXACTLYONCE

ThemostcostlyoftheQoS(intermsofnetworktrafficandburdenonsenderandreceiver)thisQoSwillensurethatthemessageisreceivedbyarecipientexactlyonetime.Thisensuresthatthereceivernevergetsanyduplicatecopiesofthemessageandwilleventuallygetit,butattheextracostofnetworkoverheadandcomplexityrequiredonthesenderandreceiver.

MQTTRetainMessages

MQTT

50

https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html

MQTThasaninterestingfeatureinwhichmessagescanbe"retained"foraparticularaddress.Thismeansthatoncearetainmessagehasbeensenttoanaddress,anynewsubscriberstothataddresswillreceivethelastsentretainmessagebeforeanyothersmessages,thishappenseveniftheretainedmessagewassentbeforeaclienthasconnectedorsubscribed.AnexampleofwherethisfeaturemightbeusefulisinenvironmentssuchasIoTwheredevicesneedtoquicklygetthecurrentstateofasystemwhentheyareonboardedintoasystem.

WillMessages

Awillmessagecanbesentwhenaclientinitiallyconnectstoabroker.Clientsareabletoseta"willmessage"aspartoftheconnectpacket.Iftheclientabnormallydisconnects,sayduetoadeviceornetworkfailurethebrokerwillproceedtopublishthewillmessagetothespecifiedaddress(asdefinedalsointheconnectpacket).Othersubscriberstothewilltopicwillreceivethewillmessageandcanreactaccordingly.ThisfeaturecanbeusefulinanIoTstylescenariotodetecterrorsacrossapotentiallylargescaledeploymentofdevices.

DebugLogging

Detailedprotocollogging(e.g.packetsin/out)canbeactivatedviathefollowingsteps:

1. Open /etc/logging.properties

2. Add org.apac