http://git-wip-us.apache.org/repos/asf/qpid-site/blob/c3ab60f6/input/releases/qpid-cpp-1.39.0/cpp-broker/book/Using-message-groups.html.in ---------------------------------------------------------------------- diff --git a/input/releases/qpid-cpp-1.39.0/cpp-broker/book/Using-message-groups.html.in b/input/releases/qpid-cpp-1.39.0/cpp-broker/book/Using-message-groups.html.in new file mode 100644 index 0000000..ced3682 --- /dev/null +++ b/input/releases/qpid-cpp-1.39.0/cpp-broker/book/Using-message-groups.html.in @@ -0,0 +1,156 @@ +<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">1.11.  + Using Message Groups + </th></tr><tr><td align="left" width="20%"><a accesskey="p" href="QpidInteroperabilityDocumentation-QpidInteroperabilityDocumentation.html">Prev</a> </td><th align="center" width="60%">Chapter 1.  + Running the AMQP Messaging Broker + </th><td align="right" width="20%"> <a accesskey="n" href="chapter-ha.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="Using-message-groups"></a>1.11.  + Using Message Groups + </h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="usingmessagegroups-Overview"></a>1.11.1.  + Overview + </h3></div></div></div><p> + The broker allows messaging applications to classify a set of related messages as + belonging to a group. This allows a message producer to indicate to the consumer + that a group of messages should be considered a single logical operation with + respect to the application. + </p><p> + The broker can use this group identification to enforce policies controlling how + messages from a given group can be distributed to consumers. For instance, the + broker can be configured to guarantee all the messages from a particular group are + processed in order across multiple consumers. + </p><p> + For example, assume we have a shopping application that manages items in a virtual + shopping cart. A user may add an item to their shopping cart, then change their + mind and remove it. If the application sends an <span class="emphasis"><em>add</em></span> message to the broker, + immediately followed by a <span class="emphasis"><em>remove</em></span> message, they will be queued in the proper + order - <span class="emphasis"><em>add</em></span>, followed by <span class="emphasis"><em>remove</em></span>. + </p><p> + However, if there are multiple consumers, it is possible that once a consumer + acquires the <span class="emphasis"><em>add</em></span> message, a different consumer may acquire the + <span class="emphasis"><em>remove</em></span> message. This allows both messages to be processed in parallel, + which could result in a "race" where the <span class="emphasis"><em>remove</em></span> operation is incorrectly + performed before the <span class="emphasis"><em>add</em></span> operation. + </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="usingmessagegroups-GroupingMessages"></a>1.11.2.  + Grouping Messages + </h3></div></div></div><p> + In order to group messages, the application would designate a particular + message header as containing a message's <span class="emphasis"><em>group identifier</em></span>. The group + identifier stored in that header field would be a string value set by the message + producer. Messages from the same group would have the same group identifier + value. The key that identifies the header must also be known to the message + consumers. This allows the consumers to determine a message's assigned group. + </p><p> + The header that is used to hold the group identifier, as well as the values used + as group identifiers, are totally under control of the application. + </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="usingmessagegroups-BrokerRole"></a>1.11.3.  + The Role of the Broker + </h3></div></div></div><p> + The broker will apply the following processing on each grouped message: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Enqueue a received message on the destination queue.</li><li class="listitem">Determine the message's group by examining the message's group identifier header.</li><li class="listitem">Enforce <span class="emphasis"><em>consumption ordering</em></span> among messages belonging to the same group.</li></ul></div><p> + <span class="emphasis"><em>Consumption ordering</em></span> means that the broker will not allow outstanding + unacknowledged messages to <span class="emphasis"><em>more than one consumer for a given group</em></span>. + </p><p> + This means that only one consumer can be processing messages from a particular + group at a given time. When the consumer acknowledges all of its acquired + messages, then the broker <span class="emphasis"><em>may</em></span> pass the next pending message + from that group to a different consumer. + </p><p> + Specifically, for any given group the broker allows only the first N messages in + the group to be delivered to a consumer. The value of N would be determined by + the selected consumer's configured prefetch capacity. The broker blocks access by + any other consumer to any remaining undelivered messages in that group. Once the + receiving consumer has: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">acknowledged,</li><li class="listitem">released, or</li><li class="listitem">rejected</li></ul></div><p> + all the delivered messages, the broker allows the next messages in the group to be + delivered. The next messages <span class="emphasis"><em>may</em></span> be delivered to a different + consumer. + </p><p> + Note well that distinct message groups would not block each other from delivery. + For example, assume a queue contains messages from two different message groups - + say group "A" and group "B" - and they are enqueued such that "A"'s messages are + in front of "B". If the first message of group "A" is in the process of being + consumed by a client, then the remaining "A" messages are blocked, but the + messages of the "B" group are available for consumption by other consumers - even + though it is "behind" group "A" in the queue. + </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="usingmessagegroups-ConsumerGuide"></a>1.11.4.  + Well Behaved Consumers + </h3></div></div></div><p> + The broker can only enforce policy when delivering messages. To guarantee that + strict message ordering is preserved, the consuming application must adhere to the + following rules: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">completely process the data in a received message before accepting + that message</li><li class="listitem">acknowledge (or reject) messages in the same order as they are + received</li><li class="listitem">avoid releasing messages (see below)</li></ul></div><p> + The term <span class="emphasis"><em>processed</em></span> means that the consumer has finished + updating all application state affected by the message that has been received. + See section 2.6.2. Transfer of Responsibility, of the AMQP-0.10 specification for + more detail. + </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Be Advised</h3><p> + If a consumer does not adhere to the above rules, it may affect the ordering of + grouped messages even when the broker is enforcing consumption order. This can + be done by selectively acknowledging and releasing messages from the same group. + </p><p> + Assume a consumer has received two messages from group "A", "A-1" and "A-2", in + that order. If the consumer releases "A-1" then acknowledges "A-2", "A-1" will + be put back onto the queue and "A-2" will be removed from the queue. This + allows another consumer to acquire and process "A-1" <span class="emphasis"><em>after</em></span> + "A-2" has been processed. + </p><p> + Under some application-defined circumstances, this may be acceptable behavior. + However, if order must be preserved, the client should either release + <span class="emphasis"><em>all</em></span> currently held messages, or discard the target message + using reject. + </p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="usingmessagegroups-BrokerConfig"></a>1.11.5.  + Broker Configuration + </h3></div></div></div><p> + In order for the broker to determine a message's group, the key for the header + that contains the group identifier must be provided to the broker via + configuration. This is done on a per-queue basis, when the queue is first + configured. + </p><p> + This means that message group classification is determined by the message's destination + queue. + </p><p> + Specifically, the queue "holds" the header key that is used to find the message's + group identifier. All messages arriving at the queue are expected to use the same + header key for holding the identifer. Once the message is enqueued, the broker + looks up the group identifier in the message's header, and classifies the message + by its group. + </p><p> + Message group support can be enabled on a queue using the + <span class="command"><strong>qpid-config</strong></span> command line tool. The following options should be + provided when adding a new queue: + </p><div class="table"><a id="idm140333889996128"></a><p class="title"><strong>Table 1.26. qpid-config options for creating message group queues</strong></p><div class="table-contents"><table border="1" class="table" summary="qpid-config options for creating message group queues"><colgroup><col /><col /></colgroup><thead><tr><th>Option</th><th>Description</th></tr></thead><tbody><tr><td>--group-header=<em class="replaceable"><code>header-name</code></em></td><td>Enable message group support for this queue. Specify name of application header that holds the group identifier.</td></tr><tr><td>--shared-groups</td><td>Enforce ordered message group consumption across multiple consumers.</td></tr></tbody></table></div></div><p><br class="table-break" /> + </p><p> + Message group support may also be specified in the + <span class="command"><strong>queue.declare</strong></span> method via the <span class="command"><strong>arguments</strong></span> + parameter map, or using the messaging address syntax. The following keys must be + provided in the arguments map to enable message group support on a queue: + </p><div class="table"><a id="idm140333892166304"></a><p class="title"><strong>Table 1.27. Queue Declare/Address Syntax Message Group Configuration Arguments</strong></p><div class="table-contents"><table border="1" class="table" summary="Queue Declare/Address Syntax Message Group Configuration Arguments"><colgroup><col /><col /></colgroup><thead><tr><th>Key</th><th>Value</th></tr></thead><tbody><tr><td>qpid.group_header_key</td><td>string - key for message header that holds the group identifier value</td></tr><tr><td>qpid.shared_msg_group</td><td>1 - enforce ordering across multiple consumers</td></tr></tbody></table></div></div><br class="table-break" /><p> + It is important to note that there is no need to provide the actual group + identifer values that will be used. The broker learns this values as messages are + recieved. Also, there is no practical limit - aside from resource limitations - + to the number of different groups that the broker can track at run time. + </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Restrictions</h3><p> + Message grouping is not supported on LVQ or Priority queues. + </p></div><div class="example"><a id="idm140333888933392"></a><p class="title"><strong>Example 1.4. Creating a message group queue via qpid-config</strong></p><div class="example-contents"><p> + This example uses the qpid-config tool to create a message group queue called + "MyMsgQueue". The message header that contains the group identifier will use + the key "GROUP_KEY". + </p><pre class="programlisting"> +qpid-config add queue MyMsgQueue --group-header="GROUP_KEY" --shared-groups + </pre></div></div><br class="example-break" /><div class="example"><a id="idm140333887699152"></a><p class="title"><strong>Example 1.5. Creating a message group queue using address syntax (C++)</strong></p><div class="example-contents"><p> + This example uses the messaging address syntax to create a message group queue + with the same configuration as the previous example. + </p><pre class="programlisting"> +sender = session.createSender("MyMsgQueue;" + " {create:always, delete:receiver," + " node: {x-declare: {arguments:" + " {'qpid.group_header_key':'GROUP_KEY'," + " 'qpid.shared_msg_group':1}}}}") + </pre></div></div><br class="example-break" /><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="usingmessagegroups-DefaultGroup"></a>1.11.5.1.  + Default Group + </h4></div></div></div><p> + Should a message without a group identifier arrive at a queue configured for message grouping, the broker assigns the message to the default group. Therefore, all such "unidentified" messages are considered by the broker as part of the same group. The name of the default group is <span class="command"><strong>"qpid.no-group"</strong></span>. This default can be overridden by suppling a different value to the broker configuration item <span class="command"><strong>"default-message-group"</strong></span>: + </p><div class="example"><a id="idm140333889261888"></a><p class="title"><strong>Example 1.6. Overriding the default message group identifier for the broker</strong></p><div class="example-contents"><pre class="programlisting"> +qpidd --default-msg-group "EMPTY-GROUP" + </pre></div></div><p><br class="example-break" /> + </p></div></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="QpidInteroperabilityDocumentation-QpidInteroperabilityDocumentation.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="ch01.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="chapter-ha.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">1.10. Qpid Interoperability Documentation </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%"> 1.12. Active-Passive Messaging Clusters</td></tr></table></div></div> \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/qpid-site/blob/c3ab60f6/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01.html.in ---------------------------------------------------------------------- diff --git a/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01.html.in b/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01.html.in new file mode 100644 index 0000000..d85fd73 --- /dev/null +++ b/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01.html.in @@ -0,0 +1,547 @@ +<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Chapter 1.  + Running the AMQP Messaging Broker + </th></tr><tr><td align="left" width="20%"><a accesskey="p" href="pr01.html">Prev</a> </td><th align="center" width="60%"> </th><td align="right" width="20%"> <a accesskey="n" href="ch01s02.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="idm140333893239360"></a>Chapter 1.  + Running the AMQP Messaging Broker + </h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="ch01.html#section-Running-a-Qpid-CPP-Broker">1.1. + Running a Qpid C++ Broker + </a></span></dt><dd><dl><dt><span class="section"><a href="ch01.html#RASC-BuildingtheCppBrokerandClientLibraries">1.1.1. + Building the + C++ Broker and Client Libraries + </a></span></dt><dt><span class="section"><a href="ch01.html#RASC-RunningtheCppBroker">1.1.2. + Running the C++ Broker + </a></span></dt><dt><span class="section"><a href="ch01.html#RASC-Mostcommonquestionsgettingqpiddrunning">1.1.3. + Most + common questions getting qpidd running + </a></span></dt><dt><span class="section"><a href="ch01.html#RASC-Authentication">1.1.4. + Authentication + </a></span></dt><dt><span class="section"><a href="ch01.html#RASC-Slightlymorecomplexconfiguration">1.1.5. + Slightly more + complex configuration + </a></span></dt><dt><span class="section"><a href="ch01.html#RASC-Loadingextramodules">1.1.6. + Loading extra modules + </a></span></dt><dt><span class="section"><a href="ch01.html#RASC-message-timestamps">1.1.7. Timestamping Received Messages</a></span></dt><dt><span class="section"><a href="ch01.html#RASC-logging-options">1.1.8. Logging Options</a></span></dt></dl></dd><dt><span class="section"><a href="ch01s02.html">1.2. + Cheat Sheet for configuring Queue Options + </a></span></dt><dd><dl><dt><span class="section"><a href="ch01s02.html#CheatSheetforconfiguringQueueOptions-ConfiguringQueueOptions">1.2.1. + Configuring + Queue Options + </a></span></dt></dl></dd><dt><span class="section"><a href="ch01s03.html">1.3. + Cheat Sheet for configuring Exchange Options + </a></span></dt><dd><dl><dt><span class="section"><a href="ch01s03.html#CheatSheetforconfiguringExchangeOptions-ConfiguringExchangeOptions">1.3.1. + Configuring Exchange Options + </a></span></dt></dl></dd><dt><span class="section"><a href="chap-Messaging_User_Guide-Broker_Federation.html">1.4. Broker Federation</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Messaging_User_Guide-Broker_Federation.html#sect-Messaging_User_Guide-Broker_Federation-Message_Routes">1.4.1. Message Routes</a></span></dt><dt><span class="section"><a href="chap-Messaging_User_Guide-Broker_Federation.html#sect-Messaging_User_Guide-Broker_Federation-Federation_Topologies">1.4.2. Federation Topologies</a></span></dt><dt><span class="section"><a href="chap-Messaging_User_Guide-Broker_Federation.html#sect-Messaging_User_Guide-Broker_Federation-Federation_among_High_Availability_Message_Clusters">1.4.3. Federation among High Availability Message Clusters</a></span></dt><dt><span class="section"><a href="chap-Messaging_User_Guide-Broker_Federation.html#sect-Messaging_User_Guide-Broker_Federation-The_qpid_route_Utility">1.4.4. The qpid-route Utility</a></span></dt><dt><spa n class="section"><a href="chap-Messaging_User_Guide-Broker_Federation.html#federation-broker-options">1.4.5. Broker options affecting federation</a></span></dt></dl></dd><dt><span class="section"><a href="chap-Messaging_User_Guide-Security.html">1.5. Security</a></span></dt><dd><dl><dt><span class="section"><a href="chap-Messaging_User_Guide-Security.html#sect-Messaging_User_Guide-Security-User_Authentication">1.5.1. User Authentication</a></span></dt><dt><span class="section"><a href="chap-Messaging_User_Guide-Security.html#sect-Messaging_User_Guide-Security-Authorization">1.5.2. Authorization</a></span></dt><dt><span class="section"><a href="chap-Messaging_User_Guide-Security.html#sect-Messaging_User_Guide-Authorization-Specifying_ACL_Quotas">1.5.3. User Connection and Queue Quotas</a></span></dt><dt><span class="section"><a href="chap-Messaging_User_Guide-Security.html#sect-Messaging_User_Guide-Security-Encryption_using_SSL">1.5.4. Encryption using SSL</a></span></dt></dl></dd>< dt><span class="section"><a href="ch01s06.html">1.6. LVQ - Last Value Queue</a></span></dt><dd><dl><dt><span class="section"><a href="ch01s06.html#LVQ-UnderstandingLVQ">1.6.1. Understanding LVQ</a></span></dt><dt><span class="section"><a href="ch01s06.html#LVQ-Creating">1.6.2. Creating a Last Value Queue</a></span></dt><dt><span class="section"><a href="ch01s06.html#LVQ-Example">1.6.3. LVQ Example</a></span></dt><dt><span class="section"><a href="ch01s06.html#LVQ-Deprecated">1.6.4. Deprecated LVQ Modes</a></span></dt></dl></dd><dt><span class="section"><a href="queue-state-replication.html">1.7. + Queue State Replication + </a></span></dt><dd><dl><dt><span class="section"><a href="queue-state-replication.html#queuestatereplication-AsynchronousReplicationofQueueState">1.7.1. + Asynchronous + Replication of Queue State + </a></span></dt></dl></dd><dt><span class="section"><a href="producer-flow-control.html">1.8. + Producer Flow Control + </a></span></dt><dd><dl><dt><span class="section"><a href="producer-flow-control.html#producerflowcontrol-Overview">1.8.1. + Overview + </a></span></dt><dt><span class="section"><a href="producer-flow-control.html#producerflowcontrol-UserInterface">1.8.2. + User Interface + </a></span></dt></dl></dd><dt><span class="section"><a href="AMQP-Compatibility.html">1.9. + AMQP compatibility + </a></span></dt><dd><dl><dt><span class="section"><a href="AMQP-Compatibility.html#AMQPcompatibility-AMQPCompatibilityofQpidreleases-3A">1.9.1. + AMQP + Compatibility of Qpid releases: + </a></span></dt><dt><span class="section"><a href="AMQP-Compatibility.html#AMQPcompatibility-InteroptablebyAMQPspecificationversion">1.9.2. + Interop + table by AMQP specification version + </a></span></dt></dl></dd><dt><span class="section"><a href="QpidInteroperabilityDocumentation-QpidInteroperabilityDocumentation.html">1.10. Qpid Interoperability Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="QpidInteroperabilityDocumentation-QpidInteroperabilityDocumentation.html#QpidInteroperabilityDocumentation-SASL">1.10.1. + SASL + </a></span></dt></dl></dd><dt><span class="section"><a href="Using-message-groups.html">1.11. + Using Message Groups + </a></span></dt><dd><dl><dt><span class="section"><a href="Using-message-groups.html#usingmessagegroups-Overview">1.11.1. + Overview + </a></span></dt><dt><span class="section"><a href="Using-message-groups.html#usingmessagegroups-GroupingMessages">1.11.2. + Grouping Messages + </a></span></dt><dt><span class="section"><a href="Using-message-groups.html#usingmessagegroups-BrokerRole">1.11.3. + The Role of the Broker + </a></span></dt><dt><span class="section"><a href="Using-message-groups.html#usingmessagegroups-ConsumerGuide">1.11.4. + Well Behaved Consumers + </a></span></dt><dt><span class="section"><a href="Using-message-groups.html#usingmessagegroups-BrokerConfig">1.11.5. + Broker Configuration + </a></span></dt></dl></dd><dt><span class="section"><a href="chapter-ha.html">1.12. Active-Passive Messaging Clusters</a></span></dt><dd><dl><dt><span class="section"><a href="chapter-ha.html#ha-overview">1.12.1. Overview</a></span></dt><dt><span class="section"><a href="chapter-ha.html#ha-virtual-ip">1.12.2. Virtual IP Addresses</a></span></dt><dt><span class="section"><a href="chapter-ha.html#ha-broker-config">1.12.3. Configuring the Brokers</a></span></dt><dt><span class="section"><a href="chapter-ha.html#ha-rm">1.12.4. The Cluster Resource Manager</a></span></dt><dt><span class="section"><a href="chapter-ha.html#ha-rm-config">1.12.5. Configuring with <span class="command"><strong>rgmanager</strong></span> as resource manager</a></span></dt><dt><span class="section"><a href="chapter-ha.html#ha-broker-admin">1.12.6. Broker Administration Tools</a></span></dt><dt><span class="section"><a href="chapter-ha.html#ha-replicate-values">1.12.7. Controlling replication of queues and exchanges</a></span></dt><dt><span class="section"><a href="chapter-ha.html#ha-failover">1.12.8. Client Connection and Fail-over</a></span></dt><dt><span class="section"><a href="chapter-ha.html#ha-security">1.12.9. Security and Access Control.</a></span></dt><dt><span class="section"><a href="chapter-ha.html#ha-other-rm">1.12.10. Integrating with other Cluster Resource Managers</a></span></dt><dt><span class="section"><a href="chapter-ha.html#ha-store">1.12.11. Using a message store in a cluster</a></span></dt><dt><span class="section"><a href="chapter-ha.html#ha-troubleshoot">1.12.12. Troubleshooting a cluster</a></span></dt></dl></dd><dt><span class="section"><a href="ha-queue-replication.html">1.13. Replicating Queues with the HA module</a></span></dt><dd><dl><dt><span class="section"><a href="ha-queue-replication.html#idm140333891096176">1.13.1. Replicating queues</a></span></dt><dt><span class="section"><a href="ha-queue-replication.html#idm140333887382320">1.13.2. Replicating queues between clusters</a></span></dt></dl></dd></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="section-Running-a-Qpid-CPP-Broker"></a>1.1.  + Running a Qpid C++ Broker + </h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="RASC-BuildingtheCppBrokerandClientLibraries"></a>1.1.1.  + Building the + C++ Broker and Client Libraries + </h3></div></div></div><p> + The root directory for the C++ distribution is named + qpidc-0.4. The README file in that directory gives + instructions for building the broker and client libraries. In + most cases you will do the following: + </p><pre class="programlisting"> +[qpidc-0.4]$ ./configure +[qpidc-0.4]$ make +</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="RASC-RunningtheCppBroker"></a>1.1.2.  + Running the C++ Broker + </h3></div></div></div><p> + Once you have built the broker and client libraries, you can + start the broker from the command line: + </p><pre class="programlisting"> +[qpidc-0.4]$ src/qpidd +</pre><p> + Use the --daemon option to run the broker as a daemon + process: + </p><pre class="programlisting"> +[qpidc-0.4]$ src/qpidd --daemon +</pre><p> + You can stop a running daemon with the --quit option: + </p><pre class="programlisting"> +[qpidc-0.4]$ src/qpidd --quit +</pre><p> + You can see all available options with the --help option + </p><pre class="programlisting"> +[qpidc-0.4]$ src/qpidd --help +</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="RASC-Mostcommonquestionsgettingqpiddrunning"></a>1.1.3.  + Most + common questions getting qpidd running + </h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="RASC-Errorwhenstartingbroker-3A-22nodatadirectory-22"></a>1.1.3.1.  + Error + when starting broker: "no data directory" + </h4></div></div></div><p> + The C++ Broker requires you to set a data directory or specify + --no-data-dir (see help for more details). The data + directory is used for the journal, so it is important when + reliability counts. Make sure your process has write permission + to the data directory. + </p><p> + The default location is + </p><pre class="programlisting"> +/lib/var/qpidd +</pre><p> + An alternate location can be set with --data-dir + </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="RASC-Errorwhenstartingbroker-3A-22thatprocessislocked-22"></a>1.1.3.2.  + Error + when starting broker: "that process is locked" + </h4></div></div></div><p> + Note that when qpidd starts it creates a lock file is data + directory are being used. If you have a un-controlled exit, + please mail + the trace from the core to the d...@qpid.apache.org mailing list. + To clear the lock run + </p><pre class="programlisting"> +./qpidd -q +</pre><p> + It should also be noted that multiple brokers can be run on the + same host. To do so set alternate data directories for each qpidd + instance. + </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="RASC-Usingaconfigurationfile"></a>1.1.3.3.  + Using a configuration + file + </h4></div></div></div><p> + Each option that can be specified on the command line can also be + specified in a configuration file. To see available options, use + --help on the command line: + </p><pre class="programlisting"> +./qpidd --help +</pre><p> + A configuration file uses name/value pairs, one on each line. To + convert a command line option to a configuration file entry: + </p><p> + a.) remove the '--' from the beginning of the option. + b.) place a '=' between the option and the value (use + <span class="emphasis"><em>yes</em></span> or <span class="emphasis"><em>true</em></span> to enable options that take no + value when specified on the command line). + c.) place one option per line. + </p><p> + For instance, the --daemon option takes no value, the + --log-to-syslog option takes the values yes or + no. The following configuration file sets these two + options: + </p><pre class="programlisting"> +daemon=yes +log-to-syslog=yes +</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="RASC-CanIuseanyLanguageclientwiththeCppBroker-3F"></a>1.1.3.4.  + Can I use + any Language client with the C++ Broker? + </h4></div></div></div><p> + Yes, all the clients work with the C++ broker; it is written in + C+<span class="emphasis"><em>, but uses the AMQP wire protocol. Any broker can be used + with any client that uses the same AMQP version. When running the + C</em></span>+ broker, it is highly recommended to run AMQP 0-10. + </p><p> + Note that JMS also works with the C++ broker. + </p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="RASC-Authentication"></a>1.1.4.  + Authentication + </h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="RASC-Linux"></a>1.1.4.1.  + Linux + </h4></div></div></div><p> + The PLAIN authentication is done on a username+password, which is + stored in the sasldb_path file. Usernames and passwords can be + added to the file using the command: + </p><pre class="programlisting"> +saslpasswd2 -f /var/lib/qpidd/qpidd.sasldb -u <REALM> <USER> +</pre><p> + The REALM is important and should be the same as the + --auth-realm + option to the broker. This lets the broker properly find the user + in + the sasldb file. + </p><p> + Existing user accounts may be listed with: + </p><pre class="programlisting"> +sasldblistusers2 -f /var/lib/qpidd/qpidd.sasldb +</pre><p> + NOTE: The sasldb file must be readable by the user running the + qpidd daemon, and should be readable only by that user. + </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="RASC-Windows"></a>1.1.4.2.  + Windows + </h4></div></div></div><p> + On Windows, the users are authenticated against the local + machine. You should add the appropriate users using the standard + Windows tools (Control Panel->User Accounts). To run many of + the examples, you will need to create a user "guest" with + password "guest". + </p><p> + If you cannot or do not want to create new users, you can run + without authentication by specifying the no-auth option to the + broker. + </p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="RASC-Slightlymorecomplexconfiguration"></a>1.1.5.  + Slightly more + complex configuration + </h3></div></div></div><p> + The easiest way to get a full listing of the broker's options are + to use the --help command, run it locally for the latest set of + options. These options can then be set in the conf file for + convenience (see above) + </p><pre class="programlisting"> +./qpidd --help + +Usage: qpidd OPTIONS +Options: + -h [ --help ] Displays the help message + -v [ --version ] Displays version information + --config FILE (/etc/qpidd.conf) Reads configuration from FILE + +Module options: + --module-dir DIR (/usr/lib/qpidd) Load all .so modules in this directory + --load-module FILE Specifies additional module(s) to be loaded + --no-module-dir Don't load modules from module directory + +Broker Options: + --data-dir DIR (/var/lib/qpidd) Directory to contain persistent data generated by the broker + --no-data-dir Don't use a data directory. No persistent + configuration will be loaded or stored + -p [ --port ] PORT (5672) Tells the broker to listen on PORT + --worker-threads N (3) Sets the broker thread pool size + --max-connections N (500) Sets the maximum allowed connections + --connection-backlog N (10) Sets the connection backlog limit for the + server socket + --staging-threshold N (5000000) Stages messages over N bytes to disk + -m [ --mgmt-enable ] yes|no (1) Enable Management + --mgmt-pub-interval SECONDS (10) Management Publish Interval + --ack N (0) Send session.ack/solicit-ack at least every + N frames. 0 disables voluntary ack/solitict + -ack + +Daemon options: + -d [ --daemon ] Run as a daemon. + -w [ --wait ] SECONDS (10) Sets the maximum wait time to initialize the + daemon. If the daemon fails to initialize, prints + an error and returns 1 + -c [ --check ] Prints the daemon's process ID to stdout and + returns 0 if the daemon is running, otherwise + returns 1 + -q [ --quit ] Tells the daemon to shut down +Logging options: + -t [ --trace ] Enables all logging + --log-enable RULE (notice+) Enables logging for selected levels and components. + RULE is in the form 'LEVEL[+-][:PATTERN]' + LEVEL is one of: + trace debug info notice warning error critical + PATTERN is a logging category name, or a namespace-qualified + function name or name fragment. + Logging category names are: + Security Broker Management Protocol System HA Messaging Store + Network Test Client Model Unspecified + + For example: + '--log-enable warning+' + logs all warning, error and critical messages. + + '--log-enable trace+:Broker' + logs all category 'Broker' messages. + + '--log-enable debug:framing' + logs debug messages from all functions with 'framing' in + the namespace or function name. + + This option can be used multiple times + + --log-disable RULE Disables logging for selected levels and components. + RULE is in the form 'LEVEL[+-][:PATTERN]' + LEVEL is one of: + trace debug info notice warning error critical + PATTERN is a logging category name, or a namespace-qualified + function name or name fragment. + Logging category names are: + Security Broker Management Protocol System HA Messaging Store + Network Test Client Model Unspecified + + For example: + '--log-disable warning-' + disables logging all warning, notice, info, debug, and + trace messages. + + '--log-disable trace:Broker' + disables all category 'Broker' trace messages. + + '--log-disable debug-:qmf::' + disables logging debug and trace messages from all functions + with 'qmf::' in the namespace. + + This option can be used multiple times + + --log-time yes|no (1) Include time in log messages + --log-level yes|no (1) Include severity level in log messages + --log-source yes|no (0) Include source file:line in log + messages + --log-thread yes|no (0) Include thread ID in log messages + --log-function yes|no (0) Include function signature in log + messages + --log-hires-timestamp yes|no (0) Use hi-resolution timestamps in log + messages + --log-category yes|no (1) Include category in log messages + --log-prefix STRING Prefix to prepend to all log messages + +Logging sink options: + --log-to-stderr yes|no (1) Send logging output to stderr + --log-to-stdout yes|no (0) Send logging output to stdout + --log-to-file FILE Send log output to FILE. + --log-to-syslog yes|no (0) Send logging output to syslog; + customize using --syslog-name and + --syslog-facility + --syslog-name NAME (qpidd) Name to use in syslog messages + --syslog-facility LOG_XXX (LOG_DAEMON) + Facility to use in syslog messages + +</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="RASC-Loadingextramodules"></a>1.1.6.  + Loading extra modules + </h3></div></div></div><p> + By default the broker will load all the modules in the module + directory, however it will NOT display options for modules that + are not loaded. So to see the options for extra modules loaded + you need to load the module and then add the help command like + this: + </p><pre class="programlisting"> +./qpidd --load-module libbdbstore.so --help +Usage: qpidd OPTIONS +Options: + -h [ --help ] Displays the help message + -v [ --version ] Displays version information + --config FILE (/etc/qpidd.conf) Reads configuration from FILE + + + / .... non module options would be here ... / + + +Store Options: + --store-directory DIR Store directory location for persistence (overrides + --data-dir) + --store-async yes|no (1) Use async persistence storage - if store supports + it, enables AIO O_DIRECT. + --store-force yes|no (0) Force changing modes of store, will delete all + existing data if mode is changed. Be SURE you want + to do this! + --num-jfiles N (8) Number of files in persistence journal + --jfile-size-pgs N (24) Size of each journal file in multiples of read + pages (1 read page = 64kiB) +</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="RASC-message-timestamps"></a>1.1.7. Timestamping Received Messages</h3></div></div></div><p> + The AMQP 0-10 specification defines a <span class="emphasis"><em>timestamp</em></span> message delivery + property. The timestamp delivery property is a <span class="emphasis"><em>datetime</em></span> value + that is written to each message that arrives at the broker. See the description of + "message.delivery-properties" in the "Command Classes" section of the AMQP 0-10 + specification for more detail. + </p><p> + See the <span class="emphasis"><em>Programming in Apache Qpid</em></span> documentation for + information regarding how clients may access the timestamp value in received + messages. + </p><p> + By default, this timestamping feature is disabled. To enable timestamping, use the + <span class="emphasis"><em>enable-timestamp</em></span> broker configuration option. Setting the + enable-timestamp option to 'yes' will enable message timestamping: + </p><pre class="programlisting"> +./qpidd --enable-timestamp yes + </pre><p> + Message timestamping can also be enabled (and disabled) without restarting the broker. + The QMF Broker management object defines two methods for accessing the timestamp + configuration: + </p><div class="table"><a id="idm140333893043168"></a><p class="title"><strong>Table 1.1. QMF Management - Broker Methods for Managing the Timestamp Configuration</strong></p><div class="table-contents"><table border="1" class="table" summary="QMF Management - Broker Methods for Managing the Timestamp Configuration"><colgroup><col /><col /></colgroup><thead><tr><th>Method</th><th>Description</th></tr></thead><tbody><tr><td>getTimestampConfig</td><td>Get the message timestamping configuration. Returns True if received messages are timestamped.</td></tr><tr><td>setTimestampConfig</td><td>Set the message timestamping configuration. Set True to enable timestamping received messages, False to disable timestamping.</td></tr></tbody></table></div></div><br class="table-break" /><div class="example"><a id="idm140333893037200"></a><p class="title"><strong>Example 1.1. Enabling Message Timestamping via QMF - Python</strong></p><div class="example-contents"><p> + The following code fragment uses these QMF method calls to enable message timestamping. + </p><pre class="programlisting" lang="python" xml:lang="python"> +# get the state of the timestamp configuration +broker = self.qmf.getObjects(_class="broker")[0] +rc = broker.getTimestampConfig() +self.assertEqual(rc.status, 0) +self.assertEqual(rc.text, "OK") +print("The timestamp setting is %s" % str(rc.receive)) + +# try to enable it +rc = broker.setTimestampConfig(True) +self.assertEqual(rc.status, 0) +self.assertEqual(rc.text, "OK") + </pre></div></div><br class="example-break" /></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="RASC-logging-options"></a>1.1.8. Logging Options</h3></div></div></div><p> + The C++ Broker provides a rich set of logging options. To use logging effectively + a user must select a useful set of options to expose the log messages of interest. + This section introduces the logging options and how they are used in practice. + </p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="RASC-LogConcepts"></a>1.1.8.1. Logging Concepts</h4></div></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="RASC-LogConcept-level"></a>Log Level</h5></div></div></div><p> + The C++ Broker has a traditional set of log severity levels. The log levels + range from low frequency and high importance critical level + to high frequency and low importance trace level. + </p><div class="table"><a id="idm140333893030000"></a><p class="title"><strong>Table 1.2. C++ Broker Log Severity Levels</strong></p><div class="table-contents"><table border="1" class="table" summary="C++ Broker Log Severity Levels"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Level</th></tr></thead><tbody><tr><td>critical</td><td>high</td></tr><tr><td>error</td><td> </td></tr><tr><td>warning</td><td> </td></tr><tr><td>notice</td><td> </td></tr><tr><td>info</td><td> </td></tr><tr><td>debug</td><td> </td></tr><tr><td>trace</td><td>low</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="RASC-LogConcept-category"></a>Log Category</h5></div></div></div><p> + The C++ Broker groups log messages into categories. The log category + name may then be used to enable and disable groups of related messages + at varying log levels. + </p><div class="table"><a id="idm140333893018368"></a><p class="title"><strong>Table 1.3. C++ Broker Log Categories</strong></p><div class="table-contents"><table border="1" class="table" summary="C++ Broker Log Categories"><colgroup><col /></colgroup><thead><tr><th>Name</th></tr></thead><tbody><tr><td>Security</td></tr><tr><td>Broker</td></tr><tr><td>Management</td></tr><tr><td>Protocol</td></tr><tr><td>System</td></tr><tr><td>HA</td></tr><tr><td>Messaging</td></tr><tr><td>Store</td></tr><tr><td>Network</td></tr><tr><td>Test</td></tr><tr><td>Client</td></tr><tr><td>Model</td></tr><tr><td>Unspecified</td></tr></tbody></table></div></div><br class="table-break" /><p> + Generally speaking the log categories are groupings of messages from files + related by + thier placement in the source code directory structure. The + <span class="emphasis"><em>Model</em></span> category is an exception. Debug log entries + identified by the Model category expose the creation, deletion, and usage + statistics for managed objects in the broker. Log messages in the Model + category are emitted by source files scattered throughout the source tree. + </p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="RASC-LogConcept-StatementAttributes"></a>Log Statement Attributes</h5></div></div></div><p> + Every log statement in the C++ Broker has fixed attributes that may be + used in enabling or disabling log messages. + </p><div class="table"><a id="idm140333893004416"></a><p class="title"><strong>Table 1.4. C++ Broker Log Statement Attributes</strong></p><div class="table-contents"><table border="1" class="table" summary="C++ Broker Log Statement Attributes"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td>Level</td><td>Severity level</td></tr><tr><td>Category</td><td>Category</td></tr><tr><td>Function</td><td>Namespace-qualified source function name</td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="RASC-LogRules-EnableDisable"></a>1.1.8.2. Enabling and Disabling Log Messages</h4></div></div></div><p> + The Qpid C++ Broker has hundreds of log message statements in the source + code. Under typical conditions + most of the messages are deselected and never emitted as actual logs. + However, under some circumstances debug and trace messages must be enabled + to analyze broker behavior. This section discusses how the broker enables + and disables log messages. + </p><p> + At startup the broker processes command line and option file '--log-enable RULE' and + '--log-disable RULE' options using the following rule format: + </p><pre class="programlisting"> + LEVEL[+-][:PATTERN} + </pre><div class="table"><a id="idm140333892992656"></a><p class="title"><strong>Table 1.5. C++ Broker Log Enable/Disable RULE Format</strong></p><div class="table-contents"><table border="1" class="table" summary="C++ Broker Log Enable/Disable RULE Format"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td>LEVEL</td><td>Severity level</td></tr><tr><td>[+-]</td><td> + Option level modifiers. <span class="emphasis"><em>'+'</em></span> indicates + <span class="emphasis"><em>this level and above</em></span>. + <span class="emphasis"><em>'-'</em></span> indicates <span class="emphasis"><em>this level and below</em></span>. + </td></tr><tr><td>[:PATTERN]</td><td> + If PATTERN matches a Category name then the log option applies only + to log messages with the named category. Otherwise, the pattern is stored + as a function name match string. + </td></tr></tbody></table></div></div><br class="table-break" /><p> + As the options are procesed the results are aggregated into two pairs of tables. + </p><div class="table"><a id="idm140333892982208"></a><p class="title"><strong>Table 1.6. C++ Broker Log Enable/Disable Settings Tables</strong></p><div class="table-contents"><table border="1" class="table" summary="C++ Broker Log Enable/Disable Settings Tables"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td>Function Table</td><td> + A set of vectors of accumulated function name patterns. + There is a separate vector of name patterns for each log level. + </td></tr><tr><td>Category Table</td><td> + A simple two dimensional array of boolean values indexed by + [Level][Category] indicating + if all log statements are enabled for the Level and Category pair. + </td></tr></tbody></table></div></div><br class="table-break" /><p> + --log-enable statements and --log-disable statements are aggregated into dedicated + Function and Category tables. With this scheme multiple conflicting log enable and + disable commands may be processed in any order yet produce consistent patterns + of enabled broker log statements. + </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="RASC-LogRules-RuleMatching"></a>1.1.8.3. Determining if a Log Statement is Enabled</h4></div></div></div><p> + Function Table Lookups are simple string pattern matches where the searchable + text is the domain-name qualified function name from the log statement and the + search pattern is the set of Function Table entries for a given log level. + </p><p> + Category Table Lookups are boolean array queries where the Level and Category + indexes are from the log statement. + </p><p> + Each log statment sends its Level, Category, and FunctionName to the + Logger for evaluation. As a result the log statement is either visible or hidden. + </p><div class="table"><a id="idm140333892971088"></a><p class="title"><strong>Table 1.7. C++ Broker Log Statement Visibility Determination</strong></p><div class="table-contents"><table border="1" class="table" summary="C++ Broker Log Statement Visibility Determination"><colgroup><col /><col /></colgroup><thead><tr><th>Test</th><th>Description</th></tr></thead><tbody><tr><td>Disabled Function</td><td> + If the statement matches a Disabled Function pattern then the + statement is hidden. + </td></tr><tr><td>Disabled Category</td><td> + If the Disabled Category table for this [Level][Category] is true then the + statement is hidden. + </td></tr><tr><td>Enabled Function</td><td> + If the statement matches a Enabled Function pattern then the + statement is visible. + </td></tr><tr><td>Enabled Category</td><td> + If the Enabled Category table for this [Level][Category] is true then the + statement is visible. + </td></tr><tr><td>Unreferenced</td><td> + Log statements that are unreferenced by specific enable rules are by + default hidden. + </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="RASC-LogRules-Reenabling"></a>1.1.8.4. Changing Log Enable/Disable Settings at Run Time</h4></div></div></div><p> + The C++ Broker provides QMF management methods that allow users to query and to set + the log enable and disable settings while the broker is running. + </p><div class="table"><a id="idm140333892957792"></a><p class="title"><strong>Table 1.8. QMF Management - Broker Methods for Managing the Log Enable/Disable Settings</strong></p><div class="table-contents"><table border="1" class="table" summary="QMF Management - Broker Methods for Managing the Log Enable/Disable Settings"><colgroup><col /><col /></colgroup><thead><tr><th>Method</th><th>Description</th></tr></thead><tbody><tr><td>getLogLevel</td><td>Get the log enable/disable settings.</td></tr><tr><td>setLogLevel</td><td>Set the log enable/disable settings.</td></tr></tbody></table></div></div><br class="table-break" /><p> + The management methods use a RULE format similar to the option RULE format: + </p><pre class="programlisting"> + [!]LEVEL[+-][:PATTERN] + </pre><p> + The difference is the leading exclamation point that identifies disable rules. + </p><div class="example"><a id="idm140333892949648"></a><p class="title"><strong>Example 1.2.  + Querying Log Settings via qpid-ctrl utility + </strong></p><div class="example-contents"><p> + At start up a C++ Broker may have the following options: + </p><pre class="programlisting"> + --log-enable debug+ + --log-enable trace+:Protocol + --log-disable info-:Management + </pre><p> + The following command: + </p><pre class="programlisting"> + qpid-ctrl getLogLevel + </pre><p> + will return the following result: + </p><pre class="programlisting"> + level=debug+,trace+:Protocol,!info-:Management + </pre></div></div><br class="example-break" /><div class="example"><a id="idm140333892945792"></a><p class="title"><strong>Example 1.3.  + Setting Log Settings via qpid-ctrl utility + </strong></p><div class="example-contents"><p> + New broker log options may be set at any time using qpid-ctrl + </p><pre class="programlisting"> + qpid-ctrl setLogLevel level='debug+:Broker !debug-:broker::Broker::ManagementMethod' + </pre></div></div><br class="example-break" /></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="RASC-LogRules-Explorer"></a>1.1.8.5. Discovering Log Sources</h4></div></div></div><p> + A common condition for a user is being swamped by log messages that are not + interesting for some debug situation. Conversely, a particular log entry + may be of interest all the time but enabling all log levels just to see a + single log entry is too much. How can a user find and specify a pattern + to single out logs of interest? + </p><p> + The easiest way to hide messages it to disable logs at log level and + category combinations. This may not always work since using only these + coarse controls the log messages of interest may also be hidden. + To discover a more precise filter to specify the messages you want + to show or to hide you may temporarily enable the + <span class="emphasis"><em>"--log-function=yes"</em></span> option. + The following log entries show a typical log message without and + with the log function names enabled: + </p><pre class="programlisting"> + 2013-05-01 11:16:01 [Broker] notice Broker running + 2013-05-01 11:16:54 [Broker] notice qpid::broker::Broker::run: Broker running + </pre><p> + This log entry is emitted by function <span class="emphasis"><em>qpid::broker::Broker::run</em></span> + and this is the function name pattern to be used in specific log enable and + disable rules. + For example, this log entry could be disabled with any of the following: + </p><pre class="programlisting"> + --log-disable notice [1] + --log-disable notice:qpid:: [2] + --log-disable notice:Broker [3] + --log-disable notice-:Broker::run [4] + --log-disable notice:qpid::broker::Broker::run [5] + </pre><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + [1] Disables all messages at notice level. + </li><li class="listitem"> + [2] Disables all messages at notice level in qpid:: name space. This is + very broad and disables many log messages. + </li><li class="listitem"> + [3] Disables the category <span class="emphasis"><em>[Broker]</em></span> and is not specific + to the function. Category names supercede function name fragments in + log option processing + </li><li class="listitem"> + [4] Disables the function. + </li><li class="listitem"> + [5] Disables the function. + </li></ul></div><p> + Remember that the log filter matching PATTERN strings are matched against the + domain-name qualified function names associated with the log statement + and not against the log message text itself. That is, in the previous example + log filters cannot be set on the log text <span class="emphasis"><em>Broker running</em></span> + </p></div></div></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="pr01.html">Prev</a> </td><td align="center" width="20%"> </td><td align="right" width="40%"> <a accesskey="n" href="ch01s02.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">Introduction </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%"> 1.2.  + Cheat Sheet for configuring Queue Options + </td></tr></table></div></div> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-site/blob/c3ab60f6/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01s02.html.in ---------------------------------------------------------------------- diff --git a/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01s02.html.in b/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01s02.html.in new file mode 100644 index 0000000..e708965 --- /dev/null +++ b/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01s02.html.in @@ -0,0 +1,143 @@ +<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">1.2.  + Cheat Sheet for configuring Queue Options + </th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch01.html">Prev</a> </td><th align="center" width="60%">Chapter 1.  + Running the AMQP Messaging Broker + </th><td align="right" width="20%"> <a accesskey="n" href="ch01s03.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="idm140333893072912"></a>1.2.  + Cheat Sheet for configuring Queue Options + </h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="CheatSheetforconfiguringQueueOptions-ConfiguringQueueOptions"></a>1.2.1.  + Configuring + Queue Options + </h3></div></div></div><p> + The C++ Broker M4 or later supports the following additional + Queue constraints. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + <a class="xref" href="ch01s02.html#CheatSheetforconfiguringQueueOptions-ConfiguringQueueOptions" title="1.2.1.  Configuring Queue Options">Section 1.2.1, “ + Configuring + Queue Options + ”</a> + </p></li><li class="listitem"><p> + </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p> + <a class="xref" href="ch01s02.html#CheatSheetforconfiguringQueueOptions-ApplyingQueueSizingConstraints" title="1.2.1.1.  Applying Queue Sizing Constraints">Section 1.2.1.1, “ + Applying Queue Sizing Constraints + ”</a> + </p></li><li class="listitem"><p> + <a class="xref" href="ch01s02.html#CheatSheetforconfiguringQueueOptions-ChangingtheQueueorderingBehaviors-28FIFO-2FLVQ-29" title="1.2.1.2.  Changing the Queue ordering Behaviors (FIFO/LVQ)">Section 1.2.1.2, “ + Changing the Queue ordering Behaviors (FIFO/LVQ) + ”</a> + </p></li><li class="listitem"><p> + <a class="xref" href="ch01s02.html#CheatSheetforconfiguringQueueOptions-Settingadditionalbehaviors" title="1.2.1.3.  Setting additional behaviors">Section 1.2.1.3, “ + Setting additional behaviors + ”</a> + </p></li><li class="listitem"><p> + </p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p> + <a class="xref" href="">???</a> + </p></li></ul></div><p> + </p></li><li class="listitem"><p> + <a class="xref" href="ch01s02.html#CheatSheetforconfiguringQueueOptions-OtherClients" title="1.2.1.4.  Other Clients">Section 1.2.1.4, “ + Other + Clients + ”</a> + </p></li></ul></div><p> + </p></li></ul></div><p> + The 0.10 C++ Broker supports the following additional Queue configuration options: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + <a class="xref" href="producer-flow-control.html" title="1.8.  Producer Flow Control">Section 1.8, “ + Producer Flow Control + ”</a> + </p></li></ul></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="CheatSheetforconfiguringQueueOptions-ApplyingQueueSizingConstraints"></a>1.2.1.1.  + Applying Queue Sizing Constraints + </h4></div></div></div><p> + This allows to specify how to size a queue and what to do when + the sizing constraints have been reached. The queue size can be + limited by the number messages (message depth) or byte depth on + the queue. + </p><p> + Once the Queue meets/ exceeds these constraints the follow + policies can be applied + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>REJECT - Reject the published message + </p></li><li class="listitem"><p>FLOW_TO_DISK - Flow the messages to disk, to preserve memory + </p></li><li class="listitem"><p>RING - start overwriting messages in a ring based on sizing. + If head meets tail, advance head + </p></li><li class="listitem"><p>RING_STRICT - start overwriting messages in a ring based on + sizing. If head meets tail, AND the consumer has the tail message + acquired it will reject + </p></li></ul></div><p> + Examples: + </p><p> + Create a queue an auto delete queue that will support 100 000 + bytes, and then REJECT + </p><pre class="programlisting"> +#include "qpid/client/QueueOptions.h" + + QueueOptions qo; + qo.setSizePolicy(REJECT,100000,0); + + session.queueDeclare(arg::queue=queue, arg::autoDelete=true, arg::arguments=qo); +</pre><p> + Create a queue that will support 1000 messages into a RING buffer + </p><pre class="programlisting"> +#include "qpid/client/QueueOptions.h" + + QueueOptions qo; + qo.setSizePolicy(RING,0,1000); + + session.queueDeclare(arg::queue=queue, arg::arguments=qo); +</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="CheatSheetforconfiguringQueueOptions-ChangingtheQueueorderingBehaviors-28FIFO-2FLVQ-29"></a>1.2.1.2.  + Changing the Queue ordering Behaviors (FIFO/LVQ) + </h4></div></div></div><p> + The default ordering in a queue in Qpid is FIFO. However + additional ordering semantics can be used namely LVQ (Last Value + Queue). Last Value Queue is define as follows. + </p><p> + If I publish symbols RHT, IBM, JAVA, MSFT, and then publish RHT + before the consumer is able to consume RHT, that message will be + over written in the queue and the consumer will receive the last + published value for RHT. + </p><p> + Example: + </p><pre class="programlisting"> +#include "qpid/client/QueueOptions.h" + + QueueOptions qo; + qo.setOrdering(LVQ); + + session.queueDeclare(arg::queue=queue, arg::arguments=qo); + + ..... + string key; + qo.getLVQKey(key); + + .... + for each message, set the into application headers before transfer + message.getHeaders().setString(key,"RHT"); + +</pre><p> + Notes: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Messages that are dequeued and the re-queued will have the + following exceptions. a.) if a new message has been queued with + the same key, the re-queue from the consumer, will combine these + two messages. b.) If an update happens for a message of the same + key, after the re-queue, it will not update the re-queued + message. This is done to protect a client from being able to + adversely manipulate the queue. + </p></li><li class="listitem"><p>Acquire: When a message is acquired from the queue, no matter + it's position, it will behave the same as a dequeue + </p></li><li class="listitem"><p>LVQ does not support durable messages. If the queue or + messages are declared durable on an LVQ, the durability will be + ignored. + </p></li></ul></div><p> + A fully worked <a class="xref" href="ch01s06.html#LVQ-Example" title="1.6.3. LVQ Example">Section 1.6.3, “LVQ Example”</a> can be found here + </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="CheatSheetforconfiguringQueueOptions-Settingadditionalbehaviors"></a>1.2.1.3.  + Setting additional behaviors + </h4></div></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="CheatSheetforconfiguringQueueOptions-OtherClients"></a>1.2.1.4.  + Other + Clients + </h4></div></div></div><p> + Note that these options can be set from any client. QueueOptions + just correctly formats the arguments passed to the QueueDeclare() + method. + </p></div></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch01.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="ch01.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="ch01s03.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">Chapter 1.  + Running the AMQP Messaging Broker +  </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%"> 1.3.  + Cheat Sheet for configuring Exchange Options + </td></tr></table></div></div> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-site/blob/c3ab60f6/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01s03.html.in ---------------------------------------------------------------------- diff --git a/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01s03.html.in b/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01s03.html.in new file mode 100644 index 0000000..e708cf1 --- /dev/null +++ b/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01s03.html.in @@ -0,0 +1,98 @@ +<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">1.3.  + Cheat Sheet for configuring Exchange Options + </th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch01s02.html">Prev</a> </td><th align="center" width="60%">Chapter 1.  + Running the AMQP Messaging Broker + </th><td align="right" width="20%"> <a accesskey="n" href="chap-Messaging_User_Guide-Broker_Federation.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="idm140333893065376"></a>1.3.  + Cheat Sheet for configuring Exchange Options + </h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="CheatSheetforconfiguringExchangeOptions-ConfiguringExchangeOptions"></a>1.3.1.  + Configuring Exchange Options + </h3></div></div></div><p> + The C++ Broker M4 or later supports the following additional + Exchange options in addition to the standard AMQP define options + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Exchange Level Message sequencing + </p></li><li class="listitem"><p>Initial Value Exchange + </p></li></ul></div><p> + Note that these features can be used on any exchange type, that + has been declared with the options set. + </p><p> + It also supports an additional option to the bind operation on a + direct exchange + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Exclusive binding for key + </p></li></ul></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="CheatSheetforconfiguringExchangeOptions-ExchangeLevelMessagesequencing"></a>1.3.1.1.  + Exchange Level Message sequencing + </h4></div></div></div><p> + This feature can be used to place a sequence number into each + message's headers, based on the order they pass through an + exchange. The sequencing starts at 0 and then wraps in an AMQP + int64 type. + </p><p> + The field name used is "qpid.msg_sequence" + </p><p> + To use this feature an exchange needs to be declared specifying + this option in the declare + </p><pre class="programlisting"> +.... + FieldTable args; + args.setInt("qpid.msg_sequence",1); + +... + // now declare the exchange + session.exchangeDeclare(arg::exchange="direct", arg::arguments=args); +</pre><p> + Then each message passing through that exchange will be numbers + in the application headers. + </p><pre class="programlisting"> + unit64_t seqNo; + //after message transfer + seqNo = message.getHeaders().getAsInt64("qpid.msg_sequence"); +</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="CheatSheetforconfiguringExchangeOptions-InitialValueExchange"></a>1.3.1.2.  + Initial + Value Exchange + </h4></div></div></div><p> + This feature caches a last message sent to an exchange. When a + new binding is created onto the exchange it will then attempt to + route this cached messaged to the queue, based on the binding. + This allows for topics or the creation of configurations where a + new consumer can receive the last message sent to the broker, + with matching routing. + </p><p> + To use this feature an exchange needs to be declared specifying + this option in the declare + </p><pre class="programlisting"> +.... + FieldTable args; + args.setInt("qpid.ive",1); + +... + // now declare the exchange + session.exchangeDeclare(arg::exchange="direct", arg::arguments=args); +</pre><p> + now use the exchange in the same way you would use any other + exchange. + </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="CheatSheetforconfiguringExchangeOptions-Exclusivebindingforkey"></a>1.3.1.3.  + Exclusive + binding for key + </h4></div></div></div><p> + Direct exchanges in qpidd support a qpid.exclusive-binding option + on the bind operation that causes the binding specified to be the + only one for the given key. I.e. if there is already a binding at + this exchange with this key it will be atomically updated to bind + the new queue. This means that the binding can be changed + concurrently with an incoming stream of messages and each message + will be routed to exactly one queue. + </p><pre class="programlisting"> +.... + FieldTable args; + args.setInt("qpid.exclusive-binding",1); + + //the following will cause the only binding from amq.direct with 'my-key' + //to be the one to 'my-queue'; if there were any previous bindings for that + //key they will be removed. This is atomic w.r.t message routing through the + //exchange. + session.exchangeBind(arg::exchange="amq.direct", arg::queue="my-queue", + arg::bindingKey="my-key", arg::arguments=args); + +... +</pre></div></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch01s02.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="ch01.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="chap-Messaging_User_Guide-Broker_Federation.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">1.2.  + Cheat Sheet for configuring Queue Options +  </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%"> 1.4. Broker Federation</td></tr></table></div></div> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-site/blob/c3ab60f6/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01s06.html.in ---------------------------------------------------------------------- diff --git a/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01s06.html.in b/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01s06.html.in new file mode 100644 index 0000000..c4bcd3d --- /dev/null +++ b/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch01s06.html.in @@ -0,0 +1,107 @@ +<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">1.6. LVQ - Last Value Queue</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="chap-Messaging_User_Guide-Security.html">Prev</a> </td><th align="center" width="60%">Chapter 1.  + Running the AMQP Messaging Broker + </th><td align="right" width="20%"> <a accesskey="n" href="queue-state-replication.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="idm140333887752800"></a>1.6. LVQ - Last Value Queue</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="LVQ-UnderstandingLVQ"></a>1.6.1. Understanding LVQ</h3></div></div></div><p> + A Last Value Queue is configured with the name of a message header that + is used as a key. The queue behaves as a normal FIFO queue with the + exception that when a message is enqueued, any other message in the + queue with the same value in the key header is removed and discarded. + Thus, for any given key value, the queue holds only the most recent + message. + </p><p> + The following example illustrates the operation of a Last Value Queue. + The example shows an empty queue with no consumers and a sequence of + produced messages. The numbers represent the key for each message. + </p><pre class="programlisting"> + <empty queue> + 1 => + 1 + 2 => + 1 2 + 3 => + 1 2 3 + 4 => + 1 2 3 4 + 2 => + 1 3 4 2 + 1 => + 3 4 2 1 + </pre><p> + Note that the first four messages are enqueued normally in FIFO order. + The fifth message has key '2' and is also enqueued on the tail of the + queue. However the message already in the queue with the same key is + discarded. + </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> + If the set of keys used in the messages in a LVQ is constrained, the + number of messages in the queue shall not exceed the number of + distinct keys in use. + </p></div><p> + </p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="LVQ-UnderstandingLVQ-UseCases"></a>1.6.1.1. Common Use-Cases</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + LVQ with zero or one consuming subscriptions - In this case, if + the consumer drops momentarily or is slower than the producer(s), + it will only receive current information relative to the message + keys. + </p></li><li class="listitem"><p> + LVQ with zero or more browsing subscriptions - A browsing consumer + can subscribe to the LVQ and get an immediate dump of all of the + "current" messages and track updates thereafter. Any number of + independent browsers can subscribe to the same LVQ with the same + effect. Since messages are never consumed, they only disappear + when replaced with a newer message with the same key or when their + TTL expires. + </p></li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="LVQ-Creating"></a>1.6.2. Creating a Last Value Queue</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="LVQ-Creating-Address"></a>1.6.2.1. Using Addressing Syntax</h4></div></div></div><p> + A LVQ may be created using directives in the API's address syntax. + The important argument is "qpid.last_value_queue_key". The following + Python example shows how a producer of stock price updates can create + a LVQ to hold the latest stock prices for each ticker symbol. The + message header used to hold the ticker symbol is called "ticker". + </p><pre class="programlisting"> + conn = Connection(url) + conn.open() + sess = conn.session() + tx = sess.sender("prices;{create:always, node:{type:queue, x-declare:{arguments:{'qpid.last_value_queue_key':'ticker'}}}}") + </pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="LVQ-Creating-Tool"></a>1.6.2.2. Using qpid-config</h4></div></div></div><p> + The same LVQ as shown in the previous example can be created using the + qpid-config utility: + </p><pre class="programlisting"> + $ qpid-config add queue prices --lvq-key ticker + </pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="LVQ-Example"></a>1.6.3. LVQ Example</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="LVQ-Example-Sender"></a>1.6.3.1. LVQ Sender</h4></div></div></div><pre class="programlisting"> + from qpid.messaging import Connection, Message + + def send(sender, key, message): + message.properties["ticker"] = key + sender.send(message) + + conn = Connection("localhost") + conn.open() + sess = conn.session() + tx = sess.sender("prices;{create:always, node:{type:queue,x-declare:{arguments:{'qpid.last_value_queue_key':ticker}}}}") + + msg = Message("Content") + send(tx, "key1", msg); + send(tx, "key2", msg); + send(tx, "key3", msg); + send(tx, "key4", msg); + send(tx, "key2", msg); + send(tx, "key1", msg); + + conn.close() + </pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="LVQ-Example-Receiver"></a>1.6.3.2. LVQ Browsing Receiver</h4></div></div></div><pre class="programlisting"> + from qpid.messaging import Connection, Message + + conn = Connection("localhost") + conn.open() + sess = conn.session() + rx = sess.receiver("prices;{mode:browse}") + + while True: + msg = rx.fetch() + sess.acknowledge() + print msg + </pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="LVQ-Deprecated"></a>1.6.4. Deprecated LVQ Modes</h3></div></div></div><p> + There are two legacy modes (still implemented as of Qpid 0.14) + controlled by the qpid.last_value_queue and + qpid.last_value_queue_no_browse argument values. These modes are + deprecated and should not be used. + </p></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="chap-Messaging_User_Guide-Security.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="ch01.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="queue-state-replication.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">1.5. Security </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%"> 1.7.  + Queue State Replication + </td></tr></table></div></div> \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org
