<?xml version="1.0"?>
<!--

 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.

-->

<appendix xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="JMS-Client-0-8-Appendix-JMS-Extensions">
  <title>JMS Extensions</title>
  <para>This section illustrates using Qpid specific extentions to JMS for the managament of queues,
  exchanges and bindings.</para>
  <!-- TODO perhaps mention ConnectionListener?-->
  <important>
    <para>It is not recommended that these extensions are generally used. These interfaces are
      subject to change and will not be supported in this form for AMQP 1.0. Instead, the reader is
      directed towards the Managment interfaces of the Broker.</para>
  </important>
  <section xml:id="JMS-Client-0-8-Appendix-JMS-Extensions-Queue">
    <title>Queue Management</title>
    <para>These extensions allow queues to be created or removed.</para>
    <section xml:id="JMS-Client-0-8-Appendix-JMS-Extensions-Queue-Creation">
      <title>Queue creation</title>
      <para>The following example illustrates the creation of the a LVQ queue from a
        javax.jms.Session object. Note that this utilises a Qpid specific extension to JMS and
        involves casting the session object back to its Qpid base-class.</para>
      <example>
        <title>Creation of an LVQ using the Qpid extension to JMS</title>
        <programlisting>Map&lt;String,Object&gt; arguments = new HashMap&lt;String, Object&gt;();
arguments.put("qpid.last_value_queue_key","ISIN");
AMQDestination amqQueue = (AMQDestination) context.lookup("myqueue");
((AMQSession&lt;?,?&gt;) session).createQueue(
        AMQShortString.valueOf(amqQueue.getQueueName()),
        amqQueue.isAutoDelete(),
        amqQueue.isDurable(),
        amqQueue.isExclusive(),
        arguments);
</programlisting>
      </example>
    </section>
  </section>

  <section xml:id="JMS-Client-0-8-Appendix-JMS-Extensions-Binding">
    <title>Binding Management</title>
    <para>These extensions allow bindings to be created or removed.</para>

    <section xml:id="JMS-Client-0-8-Appendix-JMS-Extensions-Binding-Creation">
      <title>Binding creation</title>
      <para>The following example illustrates the creation of queue binding to topic exchange with
        JMS client.</para>
      <example>
        <title>Binding a queue using JMS</title>
        <programlisting>ConnectionFactory connectionFactory = ...
Connection connection = connectionFactory.createConnection();
AMQSession&lt;?, ?&gt; session = (AMQSession&lt;?,?&gt;)connection.createSession(false, Session.AUTO_ACKNOWLEDGE);

...

AMQShortString queueName = new AMQShortString("testQueue");
AMQShortString routingKey = new AMQShortString("testRoutingKey");
AMQDestination destination = (AMQDestination) session.createQueue(queueName.asString());

...

// binding arguments
Map&lt;String, Object&gt; arguments = new HashMap&lt;String, Object&gt;();
arguments.put("x-filter-jms-selector", "application='app1'");

// create binding
session.bindQueue(queueName, routingKey, FieldTable.convertToFieldTable(arguments),
    new AMQShortString("amq.topic"), destination);</programlisting>
      </example>
    </section>
  </section>
</appendix>