gdl
    title     = AMQ DRAFT
    subtitle  = AMQP/Fast Semantics for JMS
    product   = OpenAMQ
    author    = James Strachan <jstrachan@protique.com>
    date      = 2004/10/18
    copyright = Copyright (c) 2004 JPMorgan
    version   = 0.1
end gdl

Cover
*****

State of this Document
======================

This document is a working draft.  Distribution of this document is
currently limited to iMatix and JPMorgan internal use.

This document describes a work in progress.

Copyright Notice
================

This document is copyright (c) 2004 JPMorgan Inc.

Authors
=======

This document was written by James Strachan <jstrachan@protique.com>.

Abstract
========

This proposal defines a mapping of the JMS specification onto the AMQ protocol.

Design Proposal
***************

Detailed Proposal
=================

We map the message-oriented semantics of JMS onto AMQP/Fast as follows:

1. JMS connections and sessions are mapped cleanly onto AMQP connections
   and channels.
2. JMS MessageConsumers will each use a single AMQP handle.
3. JMS MessageProducers will each use at least one AMQP handle.
   For a MessageProducer created with a specific Destination, then
   a single AMQP handle will be used; though JMS supports other
   destinations to be used and so other handles will be used.
4. Though there is nothing in JMS which naturally maps to HANDLE REQUEST, a
   provider may wish to use this mechanism, outside of the JMS specification
   such as to implement a remote JMX protocol.
5. The MIME type for the request field in CHANNEL SUBSCRIBE commands will
   be "Application/JMS".
6. The JMS destination types are mapped to the AMQP 'path' somehow (TBD)

destinationType Semantics
=========================

JMS supports the following destinationType values and associated semantics.

/topic/durable:
    A durable topic; messages must be persisted to disk before ACKs
    and subscriptions do not terminate when the channel closes. Messages
    are never removed unless consumed or some administrator deletes them.

/queue/durable:
    A durable queue; messages must be persisted to disk before ACKs.
    Messages are never removed unless consumed or some administrator deletes
    them.

/topic/transient:
    A transient topic; messages may be buffered into disk/RAM for a period of time.
    If a client disconnects and reconnects some form of recovery/replay
    may be used but this is provider dependent

/transient/queue:
    A transient queue; messages may be buffered to disk/in RAM up for a period of time
    and if a client disconnects and reconnects some form of recovery/replay
    may be used but this is provider dependent

/tmp/queue:
    A temporary queue which survives only as long as the current connection does.
    On reconnection, the queue no longer exists.

/topic/tmp:
    A temporary topic which survives only as long as the current connection does.
    On reconnection, the topic no longer exists.

MessageProducer mapping
=======================

A handle in AMQP is bound to a single destinationType (such as
/queue/durable or /topic/tmp). However in the JMS API a MessageProducer
can send/receive to any destination and can use both temporary
destinations or permanent ones as well as using topics and queues.

So to map to AMQP, a MessageProducer must remember the current
destinationType of the AMQP channel, and if a new destination or delivery
mode is different, it must explicitly open a new HANDLE for the new 
destination.

Some providers may find this inefficient and may wish to create, lazily,
up to 6 different AMQP channels for each JMS MessageProducer, and use
the correct one each time to avoid the rebind.

TBD
===

We need to come up with MIME types for the 5 standard JMS message bodies
types

- Java serialized object
- text (application/text?)
- binary (BytesMessage and StreamMessage)
- MapMessage (key-value pairs of primitive types)


Future Considerations
=====================

If multiple MessageConsumer instances are consuming on similar topics
with overlapping selectors, then a single message could be delivered to
several MessageConsumers. Currently there is no optimisation in the AMQP
protocol to cater for this scenario.

There could be, in future AMQP versions, a custom header used to indicate
all other matching handle subscriptions that a given message matches; allowing a JMS
client to map a single message to multiple channels.

Currently this is only an issue for multiple consumers on overlapping
topics. It is advisable to use a single MessageConsumer channel in the JMS
client to minimise the redundant use of the network in this particular
case.


Security Considerations
=======================

This proposal does not have any specific security considerations.

Appendices
**********

[For other information you want to include with this document. If you
do not have any appendices, you can delete this heading.]

Comments on this Document
*************************

Comments by readers; these comments may be edited, incoporated, or removed
by the author(s) of the document at any time.

Date, name
==========

No comments at present.
