gdl
    title     = AMQ DRAFT
    subtitle  = AMQ URI Syntax
    product   = OpenAMQ
    author    = iMatix Corporation <amq@imatix.com>
    date      = 2004/11/21
    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 Pieter Hintjens <ph@imatix.com>

Abstract
========

AMQ defines the concept of "destination", an abstract shared data store
that is held on a server within a "service-oriented area network".
Destinations implement queues, topics, and peer services.  Destinations
are held on servers in a service-oriented area network (SOAN), in which
client applications do not ask for servers by name, but by service.

This document defines a standard URI syntax whereby client applications
tell the client API layer which destination they want to access.

Quick Reference
===============

The general AMQ URI syntax is:

    amqp://soan-name[:port]/servicepath/destination-name[#property]

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

Assumptions and Definitions
===========================

We refer to IETF RFC2396 for the general syntax of URIs.

The URI syntax makes these assumptions:

 - A SOAN is managed by a root server which acts as a name server for
   the network.  The translation of a servicepath into a physical server
   address is done by unspecified services running on the root server.
 - The client API layer is capable of talking to these services so that
   it can translate the servicepath part of a URI into a server DNS name
   or IP address.

The AMQ URI syntax is:

    scheme://soan-name[:port]/servicepath/destination[#property]

Which is based on the following components.

scheme:
    Always "amqp".
soan-name:
    The DNS name of the SOAN root server.  A degenerate AMQ network may
    operate without a root server, and without any name services.  In
    this case the application does not use AMQ URIs: it simply tells the
    API layer which server and destinations to use.
port:
    Optionally, a port on which to connect to the root server.
servicepath:
    The service path, a logical name that selects one of the servers on
    the SOAN.  The servicepath can be empty, in which case the URI refers
    to the root server.  The service path can consist of multiple parts
    separated by '/'.
destination:
    The name of a destination, which may not be empty.
property:
    Optionally, the name of a destination property.  Applications may
    be allowed to read and write destination properties.

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

This proposal does not have any specific security considerations.

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

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

No comments at present.
