<?xml version="1.0" encoding="utf-8"?>

<!--
 
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at
 
   http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 
-->

<section>
  <title>
    Cheat Sheet for configuring Exchange Options
  </title>

  <section role="h2" id="CheatSheetforconfiguringExchangeOptions-ConfiguringExchangeOptions">
    <title>
      Configuring Exchange Options
    </title>
          <para>
            The C++ Broker M4 or later supports the following additional
            Exchange options in addition to the standard AMQP define options
          </para><itemizedlist>
            <listitem><para>Exchange Level Message sequencing
            </para></listitem>
            <listitem><para>Initial Value Exchange
            </para></listitem>
          </itemizedlist><para>
            Note that these features can be used on any exchange type, that
            has been declared with the options set.
          </para><para>
            It also supports an additional option to the bind operation on a
            direct exchange
          </para><itemizedlist>
            <listitem><para>Exclusive binding for key
            </para></listitem>
          </itemizedlist>

	  <section role="h3" id="CheatSheetforconfiguringExchangeOptions-ExchangeLevelMessagesequencing"><title>
            Exchange Level Message sequencing
          </title>
          <para>
            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.
          </para><para>
            The field name used is "qpid.msg_sequence"
          </para><para>
            To use this feature an exchange needs to be declared specifying
            this option in the declare
          </para>
            <programlisting>
....
    FieldTable args;
    args.setInt("qpid.msg_sequence",1);

...
    // now declare the exchange
    session.exchangeDeclare(arg::exchange="direct", arg::arguments=args);
</programlisting>
          <para>
            Then each message passing through that exchange will be numbers
            in the application headers.
          </para>
            <programlisting>
    unit64_t seqNo;
    //after message transfer
    seqNo = message.getHeaders().getAsInt64("qpid.msg_sequence");
</programlisting>
	  <!--h3--></section>
          <section role="h3" id="CheatSheetforconfiguringExchangeOptions-InitialValueExchange"><title>
            Initial
            Value Exchange
          </title>
          <para>
            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.
          </para><para>
            To use this feature an exchange needs to be declared specifying
            this option in the declare
          </para>
            <programlisting>
....
    FieldTable args;
    args.setInt("qpid.ive",1);

...
    // now declare the exchange
    session.exchangeDeclare(arg::exchange="direct", arg::arguments=args);
</programlisting>
          <para>
            now use the exchange in the same way you would use any other
            exchange.
          </para>
	  <!--h3--></section>

	  <section role="h3" id="CheatSheetforconfiguringExchangeOptions-Exclusivebindingforkey"><title>
            Exclusive
            binding for key
          </title>
          <para>
            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.
          </para>
            <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);

...
</programlisting>
<!--h3--></section>
<!--h2--></section>
</section>