| <?xml version="1.0"?> |
| <?xml-stylesheet type="text/xsl" href="amqp.xsl"?> |
| |
| <!-- |
| Copyright Notice |
| ================ |
| (c) Copyright Bank of America, N.A., Barclays Bank PLC, Cisco Systems, Credit Suisse, Deutsche |
| Boerse, Envoy Technologies Inc., Goldman Sachs, HCL Technologies Ltd, IIT Software GmbH, iMatix |
| Corporation, INETCO Systems Limited, Informatica Corporation, JPMorgan Chase & Co., Kaazing |
| Corporation, N.A, Microsoft Corporation, my-Channels, Novell, Progress Software, Red Hat Inc., |
| Software AG, Solace Systems Inc., StormMQ Ltd., Tervela Inc., TWIST Process Innovations Ltd, |
| VMware, Inc., and WS02 Inc. |
| 2006-2011. All rights reserved. |
| |
| License |
| ======= |
| |
| Bank of America, N.A., Barclays Bank PLC, Cisco Systems, Credit Suisse, Deutsche Boerse, Goldman |
| Sachs, HCL Technologies Ltd, IIT Software GmbH, INETCO Systems Limited, Informatica Corporation, |
| JPMorgan Chase & Co., Kaazing Corporation, N.A, Microsoft Corporation, my-Channels, Novell, |
| Progress Software, Red Hat Inc., Software AG, Solace Systems Inc., StormMQ Ltd., Tervela Inc., |
| TWIST Process Innovations Ltd, VMware, Inc., and WS02 Inc. (collectively, the "Authors") each |
| hereby grants to you a worldwide, perpetual, royalty-free, nontransferable, nonexclusive license |
| to (i) copy, display, distribute and implement the Advanced Message Queuing Protocol ("AMQP") |
| Specification and (ii) the Licensed Claims that are held by the Authors, all for the purpose of |
| implementing the Advanced Message Queuing Protocol Specification. Your license and any rights |
| under this Agreement will terminate immediately without notice from any Author if you bring any |
| claim, suit, demand, or action related to the Advanced Message Queuing Protocol Specification |
| against any Author. Upon termination, you shall destroy all copies of the Advanced Message Queuing |
| Protocol Specification in your possession or control. |
| |
| As used hereunder, "Licensed Claims" means those claims of a patent or patent application, |
| throughout the world, excluding design patents and design registrations, owned or controlled, or |
| that can be sublicensed without fee and in compliance with the requirements of this Agreement, by |
| an Author or its affiliates now or at any future time and which would necessarily be infringed by |
| implementation of the Advanced Message Queuing Protocol Specification. A claim is necessarily |
| infringed hereunder only when it is not possible to avoid infringing it because there is no |
| plausible non-infringing alternative for implementing the required portions of the Advanced |
| Message Queuing Protocol Specification. Notwithstanding the foregoing, Licensed Claims shall not |
| include any claims other than as set forth above even if contained in the same patent as Licensed |
| Claims; or that read solely on any implementations of any portion of the Advanced Message Queuing |
| Protocol Specification that are not required by the Advanced Message Queuing Protocol |
| Specification, or that, if licensed, would require a payment of royalties by the licensor to |
| unaffiliated third parties. Moreover, Licensed Claims shall not include (i) any enabling |
| technologies that may be necessary to make or use any Licensed Product but are not themselves |
| expressly set forth in the Advanced Message Queuing Protocol Specification (e.g., semiconductor |
| manufacturing technology, compiler technology, object oriented technology, networking technology, |
| operating system technology, and the like); or (ii) the implementation of other published |
| standards developed elsewhere and merely referred to in the body of the Advanced Message Queuing |
| Protocol Specification, or (iii) any Licensed Product and any combinations thereof the purpose or |
| function of which is not required for compliance with the Advanced Message Queuing Protocol |
| Specification. For purposes of this definition, the Advanced Message Queuing Protocol |
| Specification shall be deemed to include both architectural and interconnection requirements |
| essential for interoperability and may also include supporting source code artifacts where such |
| architectural, interconnection requirements and source code artifacts are expressly identified as |
| being required or documentation to achieve compliance with the Advanced Message Queuing Protocol |
| Specification. |
| |
| As used hereunder, "Licensed Products" means only those specific portions of products (hardware, |
| software or combinations thereof) that implement and are compliant with all relevant portions of |
| the Advanced Message Queuing Protocol Specification. |
| |
| The following disclaimers, which you hereby also acknowledge as to any use you may make of the |
| Advanced Message Queuing Protocol Specification: |
| |
| THE ADVANCED MESSAGE QUEUING PROTOCOL SPECIFICATION IS PROVIDED "AS IS," AND THE AUTHORS MAKE NO |
| REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF |
| MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS |
| OF THE ADVANCED MESSAGE QUEUING PROTOCOL SPECIFICATION ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE |
| IMPLEMENTATION OF THE ADVANCED MESSAGE QUEUING PROTOCOL SPECIFICATION WILL NOT INFRINGE ANY THIRD |
| PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. |
| |
| THE AUTHORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL |
| DAMAGES ARISING OUT OF OR RELATING TO ANY USE, IMPLEMENTATION OR DISTRIBUTION OF THE ADVANCED |
| MESSAGE QUEUING PROTOCOL SPECIFICATION. |
| |
| The name and trademarks of the Authors may NOT be used in any manner, including advertising or |
| publicity pertaining to the Advanced Message Queuing Protocol Specification or its contents |
| without specific, written prior permission. Title to copyright in the Advanced Message Queuing |
| Protocol Specification will at all times remain with the Authors. |
| |
| No other rights are granted by implication, estoppel or otherwise. |
| |
| Upon termination of your license or rights under this Agreement, you shall destroy all copies of |
| the Advanced Message Queuing Protocol Specification in your possession or control. |
| |
| Trademarks |
| ========== |
| "JPMorgan", "JPMorgan Chase", "Chase", the JPMorgan Chase logo and the Octagon Symbol are |
| trademarks of JPMorgan Chase & Co. |
| |
| RED HAT is a registered trademarks of Red Hat, Inc. in the US and other countries. |
| |
| Other company, product, or service names may be trademarks or service marks of others. |
| |
| Link to full AMQP specification: |
| ================================= |
| http://www.amqp.org/confluence/display/AMQP/AMQP+Specification |
| --> |
| |
| <!DOCTYPE amqp SYSTEM "amqp.dtd"> |
| |
| <amqp xmlns="http://www.amqp.org/schema/amqp.xsd" |
| name="types" label="working version"> |
| |
| <!-- == Section: types ======================================================================= --> |
| |
| <section name="types" title="Type System" label="AMQP Type System"> |
| <doc> |
| <p> |
| The AMQP type system defines a set of commonly used primitive types used for interoperable |
| data representation. AMQP values may be annotated with additional semantic information |
| beyond that associated with the primitive type. This allows for the association of an AMQP |
| value with an external type that is not present as an AMQP primitive. For example, a URL is |
| commonly represented as a string, however not all strings are valid URLs, and many |
| programming languages and/or applications define a specific type to represent URLs. The AMQP |
| type system would allow for the definition of a code with which to annotate strings when the |
| value is intended to represent a URL. |
| </p> |
| </doc> |
| |
| <doc title="Primitive Types"> |
| <p> |
| The following primitive types are defined: |
| </p> |
| |
| <!--TypeListTable--> |
| </doc> |
| |
| <doc title="Described Types"> |
| <p> |
| The primitive types defined by AMQP can directly represent many of the basic types present |
| in most popular programming languages, and therefore may be trivially used to exchange basic |
| data. In practice, however, even the simplest applications have their own set of custom |
| types used to model concepts within the application's domain, and, for messaging |
| applications, these custom types need to be externalized for transmission. |
| </p> |
| |
| <p> |
| AMQP provides a means to do this by allowing any AMQP type to be annotated with |
| a <i>descriptor</i>. A <i>descriptor</i> forms an association between a custom type, and an |
| AMQP type. This association indicates that the AMQP type is actually a <i>representation</i> |
| of the custom type. The resulting combination of the AMQP type and its descriptor is |
| referred to as a <i>described type</i>. |
| </p> |
| |
| <p> |
| A described type contains two distinct kinds of type information. It identifies both an AMQP |
| type and a custom type (as well as the relationship between them), and so can be understood |
| at two different levels. An application with intimate knowledge of a given domain can |
| understand described types as the custom types they represent, thereby decoding and |
| processing them according to the complete semantics of the domain. An application with no |
| intimate knowledge can still understand the described types as AMQP types, decoding and |
| processing them as such. |
| </p> |
| </doc> |
| |
| <doc title="Descriptor Values"> |
| <p> |
| Descriptor values other than symbolic (<xref name="symbol"/>) or numeric |
| (<xref name="ulong"/>) are, while not syntactically invalid, reserved - this includes |
| numeric types other than <xref name="ulong"/>. To allow for users of the type system to |
| define their own descriptors without collision of descriptor values, an assignment policy |
| for symbolic and numeric descriptors is given below. |
| </p> |
| |
| <p> |
| The namespace for both symbolic and numeric descriptors is divided into distinct domains. |
| Each domain has a defined symbol and/or 4 byte numeric id assigned by the AMQP working |
| group. For numeric ids the assigned domain-id will be equal to the IANA Private Enterprise |
| Number (PEN) of the requesting organisation (<xref type="extern" |
| name="http://www.iana.org/assignments/enterprise-numbers"/>) with domain-id 0 reserved for |
| descriptors defined in the AMQP Specification. |
| </p> |
| |
| <p> |
| Descriptors are then assigned within each domain according to the following rules: |
| </p> |
| |
| <dl> |
| <dt>symbolic descriptors</dt> |
| <dd> |
| <p><i><domain></i><b>:</b><i><name></i></p> |
| </dd> |
| |
| <dt>numeric descriptors</dt> |
| <dd> |
| <p> |
| (<i>domain-id</i> << 32) | <i>descriptor-id</i> |
| </p> |
| </dd> |
| </dl> |
| </doc> |
| </section> |
| |
| <section name="encodings" title="Type Encodings" label="standard type encodings"> |
| <doc> |
| <p> |
| An AMQP encoded data stream consists of untyped bytes with embedded constructors. The |
| embedded constructor indicates how to interpret the untyped bytes that follow. Constructors |
| can be thought of as functions that consume untyped bytes from an open ended byte stream and |
| construct a typed value. An AMQP encoded data stream always begins with a constructor. |
| </p> |
| |
| <picture title="Primitive Format Code (String)"><![CDATA[ |
| constructor untyped bytes |
| | | |
| +--+ +-----------------+-----------------+ |
| | | | | |
| ... 0xA1 0x1E "Hello Glorious Messaging World" ... |
| | | | | | |
| | | | utf8 bytes | |
| | | | | |
| | | # of data octets | |
| | | | |
| | +-----------------+-----------------+ |
| | | |
| | string value encoded according |
| | to the str8-utf8 encoding |
| | |
| primitive format code |
| for the str8-utf8 encoding |
| ]]> |
| </picture> |
| |
| <p> |
| An AMQP constructor consists of either a primitive format code, or a described format code. |
| A primitive format code is a constructor for an AMQP primitive type. A described format code |
| consists of a descriptor and a primitive format-code. A descriptor defines how to produce a |
| domain specific type from an AMQP primitive value. |
| </p> |
| |
| <picture title="Described Format Code (URL)"><![CDATA[ |
| constructor untyped bytes |
| | | |
| +-----------+-----------+ +-----------------+-----------------+ |
| | | | | |
| ... 0x00 0xA1 0x03 "URL" 0xA1 0x1E "http://example.org/hello-world" ... |
| | | | | | |
| +------+------+ | | | |
| | | | | |
| descriptor | +------------------+----------------+ |
| | | |
| | string value encoded according |
| | to the str8-utf8 encoding |
| | |
| primitive format code |
| for the str8-utf8 encoding |
| |
| (Note: this example shows a string-typed descriptor, which should be |
| considered reserved) |
| ]]> |
| </picture> |
| |
| <p> |
| The descriptor portion of a described format code is itself any valid AMQP encoded value, |
| including other described values. The formal BNF for constructors is given below. |
| </p> |
| |
| <picture title="Constructor BNF"><![CDATA[ |
| constructor = format-code |
| / %x00 descriptor constructor |
| |
| format-code = fixed / variable / compound / array |
| fixed = empty / fixed-one / fixed-two / fixed-four |
| / fixed-eight / fixed-sixteen |
| variable = variable-one / variable-four |
| compound = compound-one / compound-four |
| array = array-one / array-four |
| |
| descriptor = value |
| value = constructor untyped-bytes |
| untyped-bytes = *OCTET ; this is not actually *OCTET, the |
| ; valid byte sequences are restricted |
| ; by the constructor |
| |
| ; fixed width format codes |
| empty = %x40-4E / %x4F %x00-FF |
| fixed-one = %x50-5E / %x5F %x00-FF |
| fixed-two = %x60-6E / %x6F %x00-FF |
| fixed-four = %x70-7E / %x7F %x00-FF |
| fixed-eight = %x80-8E / %x8F %x00-FF |
| fixed-sixteen = %x90-9E / %x9F %x00-FF |
| |
| ; variable width format codes |
| variable-one = %xA0-AE / %xAF %x00-FF |
| variable-four = %xB0-BE / %xBF %x00-FF |
| |
| ; compound format codes |
| compound-one = %xC0-CE / %xCF %x00-FF |
| compound-four = %xD0-DE / %xDF %x00-FF |
| |
| ; array format codes |
| array-one = %xE0-EE / %xEF %x00-FF |
| array-four = %xF0-FE / %xFF %x00-FF |
| ]]> |
| </picture> |
| |
| <p> |
| Format codes map to one of four different categories: fixed width, variable width, compound |
| and array. Values encoded within each category share the same basic structure parameterized |
| by width. The subcategory within a format-code identifies both the category and width. |
| </p> |
| |
| <dl> |
| <dt>Fixed Width</dt> |
| <dd> |
| <p> |
| The size of fixed-width data is determined based solely on the subcategory of the format |
| code for the fixed width value. |
| </p> |
| </dd> |
| </dl> |
| |
| <dl> |
| <dt>Variable Width</dt> |
| <dd> |
| <p> |
| The size of variable-width data is determined based on an encoded size that prefixes the |
| data. The width of the encoded size is determined by the subcategory of the format code |
| for the variable width value. |
| </p> |
| </dd> |
| |
| <dt>Compound</dt> |
| <dd> |
| <p> |
| Compound data is encoded as a size and a count followed by a polymorphic sequence |
| of <i>count</i> constituent values. Each constituent value is preceded by a constructor |
| that indicates the semantics and encoding of the data that follows. The width of the |
| size and count is determined by the subcategory of the format code for the compound |
| value. |
| </p> |
| </dd> |
| |
| <dt>Array</dt> |
| <dd> |
| <p> |
| Array data is encoded as a size and count followed by an array element constructor |
| followed by a monomorphic sequence of values encoded according to the supplied array |
| element constructor. The width of the size and count is determined by the subcategory of |
| the format code for the array. |
| </p> |
| </dd> |
| </dl> |
| |
| <p> |
| The bits within a format code may be interpreted according to the following layout: |
| </p> |
| |
| <picture><![CDATA[ |
| Bit: 7 6 5 4 3 2 1 0 |
| +------------------------------------+ +----------+ |
| | subcategory | subtype | | ext-type | |
| +------------------------------------+ +----------+ |
| 1 octet 1 octet |
| | | |
| +-------------------------------------------------+ |
| | |
| format-code |
| |
| ext-type: only present if subtype is 0xF |
| ]]> |
| </picture> |
| |
| <p> |
| The following table describes the subcategories of format-codes: |
| </p> |
| |
| <picture> |
| Subcategory Category Format |
| ============================================================================== |
| 0x4 Fixed Width Zero octets of data. |
| 0x5 Fixed Width One octet of data. |
| 0x6 Fixed Width Two octets of data. |
| 0x7 Fixed Width Four octets of data. |
| 0x8 Fixed Width Eight octets of data. |
| 0x9 Fixed Width Sixteen octets of data. |
| |
| 0xA Variable Width One octet of size, 0-255 octets of data. |
| 0xB Variable Width Four octets of size, 0-4294967295 octets of data. |
| |
| 0xC Compound One octet each of size and count, 0-255 distinctly |
| typed values. |
| 0xD Compound Four octets each of size and count, 0-4294967295 |
| distinctly typed values. |
| |
| 0xE Array One octet each of size and count, 0-255 uniformly |
| typed values. |
| 0xF Array Four octets each of size and count, 0-4294967295 |
| uniformly typed values. |
| </picture> |
| |
| <p> |
| Please note, unless otherwise specified, AMQP uses network byte order for all numeric |
| values. |
| </p> |
| </doc> |
| |
| <doc title="Fixed Width"> |
| <p> |
| The width of a specific fixed width encoding may be computed from the subcategory of the |
| format code for the fixed width value: |
| </p> |
| |
| <picture><![CDATA[ |
| n OCTETs |
| +----------+ |
| | data | |
| +----------+ |
| |
| Subcategory n |
| ================= |
| 0x4 0 |
| 0x5 1 |
| 0x6 2 |
| 0x7 4 |
| 0x8 8 |
| 0x9 16 |
| ]]> |
| </picture> |
| </doc> |
| |
| <type class="primitive" name="null" label="indicates an empty value"> |
| <encoding code="0x40" category="fixed" width="0" label="the null value"/> |
| </type> |
| |
| <type class="primitive" name="boolean" label="represents a true or false value"> |
| <encoding code="0x56" category="fixed" width="1" |
| label="boolean with the octet 0x00 being false and octet 0x01 being true"/> |
| <encoding name="true" code="0x41" category="fixed" width="0" label="the boolean value true"/> |
| <encoding name="false" code="0x42" category="fixed" width="0" |
| label="the boolean value false"/> |
| </type> |
| |
| <type class="primitive" name="ubyte" label="integer in the range 0 to 2^8 - 1 inclusive"> |
| <encoding code="0x50" category="fixed" width="1" label="8-bit unsigned integer"/> |
| </type> |
| |
| <type class="primitive" name="ushort" label="integer in the range 0 to 2^16 - 1 inclusive"> |
| <encoding code="0x60" category="fixed" width="2" |
| label="16-bit unsigned integer in network byte order"/> |
| </type> |
| |
| <type class="primitive" name="uint" label="integer in the range 0 to 2^32 - 1 inclusive"> |
| <encoding code="0x70" category="fixed" width="4" |
| label="32-bit unsigned integer in network byte order"/> |
| <encoding name="smalluint" code="0x52" category="fixed" width="1" |
| label="unsigned integer value in the range 0 to 255 inclusive"/> |
| <encoding name="uint0" code="0x43" category="fixed" width="0" label="the uint value 0"/> |
| </type> |
| |
| <type class="primitive" name="ulong" label="integer in the range 0 to 2^64 - 1 inclusive"> |
| <encoding code="0x80" category="fixed" width="8" |
| label="64-bit unsigned integer in network byte order"/> |
| <encoding name="smallulong" code="0x53" category="fixed" width="1" |
| label="unsigned long value in the range 0 to 255 inclusive"/> |
| <encoding name="ulong0" code="0x44" category="fixed" width="0" label="the ulong value 0"/> |
| </type> |
| |
| <type class="primitive" name="byte" label="integer in the range -(2^7) to 2^7 - 1 inclusive"> |
| <encoding code="0x51" category="fixed" width="1" label="8-bit two's-complement integer"/> |
| </type> |
| |
| <type class="primitive" name="short" label="integer in the range -(2^15) to 2^15 - 1 inclusive"> |
| <encoding code="0x61" category="fixed" width="2" |
| label="16-bit two's-complement integer in network byte order"/> |
| </type> |
| |
| <type class="primitive" name="int" label="integer in the range -(2^31) to 2^31 - 1 inclusive"> |
| <encoding code="0x71" category="fixed" width="4" |
| label="32-bit two's-complement integer in network byte order"/> |
| <encoding name="smallint" code="0x54" category="fixed" width="1" |
| label="signed integer value in the range -128 to 127 inclusive"/> |
| </type> |
| |
| <type class="primitive" name="long" label="integer in the range -(2^63) to 2^63 - 1 inclusive"> |
| <encoding code="0x81" category="fixed" width="8" |
| label="64-bit two's-complement integer in network byte order"/> |
| <encoding name="smalllong" code="0x55" category="fixed" width="1" |
| label="signed long value in the range -128 to 127 inclusive"/> |
| </type> |
| |
| <type class="primitive" name="float" |
| label="32-bit floating point number (IEEE 754-2008 binary32)"> |
| <encoding name="ieee-754" code="0x72" category="fixed" width="4" |
| label="IEEE 754-2008 binary32"/> |
| </type> |
| |
| <type class="primitive" name="double" |
| label="64-bit floating point number (IEEE 754-2008 binary64)"> |
| <encoding name="ieee-754" code="0x82" category="fixed" width="8" |
| label="IEEE 754-2008 binary64"/> |
| </type> |
| |
| <type class="primitive" name="decimal32" |
| label="32-bit decimal number (IEEE 754-2008 decimal32)"> |
| <encoding name="ieee-754" code="0x74" category="fixed" width="4" |
| label="IEEE 754-2008 decimal32 using the Binary Integer Decimal encoding"/> |
| </type> |
| |
| <type class="primitive" name="decimal64" |
| label="64-bit decimal number (IEEE 754-2008 decimal64)"> |
| <encoding name="ieee-754" code="0x84" category="fixed" width="8" |
| label="IEEE 754-2008 decimal64 using the Binary Integer Decimal encoding"/> |
| </type> |
| |
| <type class="primitive" name="decimal128" |
| label="128-bit decimal number (IEEE 754-2008 decimal128)"> |
| <encoding name="ieee-754" code="0x94" category="fixed" width="16" |
| label="IEEE 754-2008 decimal128 using the Binary Integer Decimal encoding"/> |
| </type> |
| |
| <type class="primitive" name="char" label="a single unicode character"> |
| <encoding name="utf32" code="0x73" category="fixed" width="4" |
| label="a UTF-32BE encoded unicode character"/> |
| </type> |
| |
| <type class="primitive" name="timestamp" label="an absolute point in time"> |
| <encoding name="ms64" code="0x83" category="fixed" width="8" |
| label="64-bit signed integer representing milliseconds since the unix epoch"> |
| <doc> |
| <p> |
| Represents an approximate point in time using the Unix time_t encoding of UTC, but with |
| a precision of milliseconds. For example, 1311704463521 represents the moment |
| 2011-07-26T18:21:03.521Z. |
| </p> |
| </doc> |
| </encoding> |
| </type> |
| |
| <type class="primitive" name="uuid" |
| label="a universally unique id as defined by RFC-4122 section 4.1.2"> |
| <encoding code="0x98" category="fixed" width="16" |
| label="UUID as defined in section 4.1.2 of RFC-4122"/> |
| </type> |
| |
| <doc title="Variable Width"> |
| <p> |
| All variable width encodings consist of a size in octets followed by <i>size</i> octets of |
| encoded data. The width of the size for a specific variable width encoding may be computed |
| from the subcategory of the format code: |
| </p> |
| |
| <picture><![CDATA[ |
| n OCTETs size OCTETs |
| +----------+-------------+ |
| | size | value | |
| +----------+-------------+ |
| |
| Subcategory n |
| ================= |
| 0xA 1 |
| 0xB 4 |
| ]]> |
| </picture> |
| </doc> |
| |
| <type class="primitive" name="binary" label="a sequence of octets"> |
| <encoding name="vbin8" code="0xa0" category="variable" width="1" |
| label="up to 2^8 - 1 octets of binary data"/> |
| |
| <encoding name="vbin32" code="0xb0" category="variable" width="4" |
| label="up to 2^32 - 1 octets of binary data"/> |
| </type> |
| |
| <type class="primitive" name="string" label="a sequence of unicode characters"> |
| <doc> |
| <p> |
| A string represents a sequence of unicode characters as defined by the Unicode V6.0.0 |
| standard (see http://www.unicode.org/versions/Unicode6.0.0). |
| </p> |
| </doc> |
| <encoding name="str8-utf8" code="0xa1" category="variable" width="1" |
| label="up to 2^8 - 1 octets worth of UTF-8 unicode (with no byte order mark)"/> |
| |
| <encoding name="str32-utf8" code="0xb1" category="variable" width="4" |
| label="up to 2^32 - 1 octets worth of UTF-8 unicode (with no byte order mark)"/> |
| </type> |
| |
| <type class="primitive" name="symbol" label="symbolic values from a constrained domain"> |
| <doc> |
| <p> |
| Symbols are values from a constrained domain. Although the set of possible domains is |
| open-ended, typically the both number and size of symbols in use for any given application |
| will be small, e.g. small enough that it is reasonable to cache all the distinct values. |
| </p> |
| </doc> |
| |
| <encoding name="sym8" code="0xa3" category="variable" width="1" |
| label="up to 2^8 - 1 seven bit ASCII characters representing a symbolic value"/> |
| |
| <encoding name="sym32" code="0xb3" category="variable" width="4" |
| label="up to 2^32 - 1 seven bit ASCII characters representing a symbolic value"/> |
| </type> |
| |
| <doc title="Compound"> |
| <p> |
| All compound encodings consist of a size and a count followed by <i>count</i> encoded items. |
| The width of the size and count for a specific compound encoding may be computed from the |
| category of the format code: |
| </p> |
| |
| <picture><![CDATA[ |
| +----------= count items =----------+ |
| | | |
| n OCTETs n OCTETs | | |
| +----------+----------+--------------+------------+-------+ |
| | size | count | ... /| item |\ ... | |
| +----------+----------+------------/ +------------+ \-----+ |
| / / \ \ |
| / / \ \ |
| / / \ \ |
| +-------------+----------+ |
| | constructor | data | |
| +-------------+----------+ |
| |
| Subcategory n |
| ================= |
| 0xC 1 |
| 0xD 4 |
| ]]> |
| </picture> |
| </doc> |
| |
| <type class="primitive" name="list" label="a sequence of polymorphic values"> |
| <encoding name="list0" code="0x45" category="fixed" width="0" |
| label="the empty list (i.e. the list with no elements)"/> |
| <encoding name="list8" code="0xc0" category="compound" width="1" |
| label="up to 2^8 - 1 list elements with total size less than 2^8 octets"/> |
| <encoding name="list32" code="0xd0" category="compound" width="4" |
| label="up to 2^32 - 1 list elements with total size less than 2^32 octets"/> |
| </type> |
| |
| <type class="primitive" name="map" |
| label="a polymorphic mapping from distinct keys to values"> |
| <doc> |
| <p> |
| A map is encoded as a compound value where the constituent elements form alternating key |
| value pairs. |
| </p> |
| |
| <picture><![CDATA[ |
| item 0 item 1 item n-1 item n |
| +-------+-------+----+---------+---------+ |
| | key 1 | val 1 | .. | key n/2 | val n/2 | |
| +-------+-------+----+---------+---------+ |
| ]]> |
| </picture> |
| <p> |
| Map encodings must contain an even number of items (i.e. an equal number of keys and |
| values). A map in which there exist two identical key values is invalid. Unless known to |
| be otherwise, maps must be considered to be ordered - that is the order of the key-value |
| pairs is semantically important and two maps which are different only in the order in |
| which their key-value pairs are encoded are not equal. |
| </p> |
| </doc> |
| <encoding name="map8" code="0xc1" category="compound" width="1" |
| label="up to 2^8 - 1 octets of encoded map data"/> |
| <encoding name="map32" code="0xd1" category="compound" width="4" |
| label="up to 2^32 - 1 octets of encoded map data"/> |
| </type> |
| |
| <doc title="Array"> |
| <p> |
| All array encodings consist of a size followed by a count followed by an element constructor |
| followed by <i>count</i> elements of encoded data formated as required by the element |
| constructor: |
| </p> |
| |
| <picture><![CDATA[ |
| +--= count elements =--+ |
| | | |
| n OCTETs n OCTETs | | |
| +----------+----------+---------------------+-------+------+-------+ |
| | size | count | element-constructor | ... | data | ... | |
| +----------+----------+---------------------+-------+------+-------+ |
| |
| Subcategory n |
| ================= |
| 0xE 1 |
| 0xF 4 |
| ]]> |
| </picture> |
| </doc> |
| |
| <type class="primitive" name="array" label="a sequence of values of a single type"> |
| <encoding name="array8" code="0xe0" category="array" width="1" |
| label="up to 2^8 - 1 array elements with total size less than 2^8 octets"/> |
| <encoding name="array32" code="0xf0" category="array" width="4" |
| label="up to 2^32 - 1 array elements with total size less than 2^32 octets"/> |
| </type> |
| |
| <doc title="List of Encodings"> |
| <!--EncodingListTable--> |
| </doc> |
| |
| </section> |
| |
| <!-- == Section: composite-types ============================================================= --> |
| |
| <section name="composite-types" title="Composite Types" |
| label="composite type notation and encoding"> |
| <doc> |
| <p> |
| AMQP defines a number of <i>composite types</i> used for encoding structured data such as |
| frame bodies. A composite type describes a composite value where each constituent value is |
| identified by a well known named <i>field</i>. Each composite type definition includes an |
| ordered sequence of fields, each with a specified name, type, and multiplicity. Composite |
| type definitions also include one or more descriptors (symbolic and/or numeric) for |
| identifying their defined representations. |
| </p> |
| |
| <p> |
| Composite types are formally defined in the XML documents included with the specification. |
| The following notation is used to define them: |
| </p> |
| |
| <picture title="Example Composite Type"><![CDATA[ |
| <type class="composite" name="book" label="example composite type"> |
| <doc> |
| <p>An example composite type.</p> |
| </doc> |
| |
| <descriptor name="example:book:list" code="0x00000003:0x00000002"/> |
| |
| <field name="title" type="string" mandatory="true" label="title of the book"/> |
| |
| <field name="authors" type="string" multiple="true"/> |
| |
| <field name="isbn" type="string" label="the ISBN code for the book"/> |
| </type> |
| ]]> |
| </picture> |
| |
| <p> |
| The <i>mandatory</i> attribute of a field description controls whether a null element value |
| is permitted in the representation. |
| </p> |
| <p> |
| The <i>multiple</i> attribute of a field description controls whether multiple element |
| values are permitted in the representation. A single element of the type specified in the |
| field description is always permitted. Multiple values are represented by the use of an |
| array where the type of the elements in the array is the type defined in the field |
| definition. Note that a null value and a zero-length array (with a correct type for its |
| elements) both describe an absence of a value and should be treated as semantically |
| identical. |
| </p> |
| <p> |
| A field which is defined as both multiple and mandatory MUST contain at least one value |
| (i.e. for such a field both <i>null</i> and an array with no entries are invalid). |
| </p> |
| </doc> |
| |
| <doc title="List Encoding"> |
| <p> |
| AMQP composite values are encoded as a described list. Each element in the list is |
| positionally correlated with the fields listed in the composite type definition. The |
| permitted element values are determined by the type specification and multiplicity of the |
| corresponding field definitions. When the trailing elements of the list representation are |
| null, they MAY be omitted. The descriptor of the list indicates the specific composite type |
| being represented. |
| </p> |
| |
| <p> |
| The described list shown below is an example composite value of the <i>book</i> type defined |
| above. A trailing null element corresponding to the absence of an ISBN value is depicted in |
| the example, but may optionally be omitted according to the encoding rules. |
| </p> |
| |
| <picture title="Example Composite Value"><![CDATA[ |
| constructor list representation of a book |
| | | |
| +-----------------+-------------------+ +-------------+---------------+ |
| | | | | |
| 0x00 0xA3 0x11 "example:book:list" 0xC0 0x40 0x03 title authors isbn |
| | | | | | |
| | identifies composite type | | | |
| | | | 0x40 |
| sym8 +----------------------+ | | |
| (symbol) | | null value |
| +--------------+----------------+ | |
| | | | |
| 0xA1 0x15 "AMQP for & by Dummies" | |
| | |
| +------------------------------------------------------------+-----+ |
| | | |
| 0xE0 0x25 0x02 0xA1 0x0E "Rob J. Godfrey" 0x13 "Rafael H. Schloming" |
| | | | | | | | |
| size | | +---------+---------+ +-----------+------------+ |
| | | | | |
| count | first element second element |
| | |
| element constructor |
| ]]> |
| </picture> |
| </doc> |
| </section> |
| |
| </amqp> |
