.. 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. AMQP Mapping ============ Dispatch Router is an AMQP router and as such, it provides extensions, code-points, and semantics for routing over AMQP. This page documents the details of Dispatch Router's use of AMQP. Message Annotations ------------------- The following Message Annotation fields are defined by Dispatch Router: +--------------------+------------------+-------------------------------------------------------+ | *Field* | *Type* | *Description* | +====================+==================+=======================================================+ | x-opt-qd.ingress | string |The identity of the ingress router for a message-routed| | | |message. The ingress router is the first router | | | |encountered by a transiting message. The router will, | | | |if this field is present, leave it unaltered. If the | | | |field is not present, the router shall insert the field| | | |with its own identity. | | | | | | | | | | | | | +--------------------+------------------+-------------------------------------------------------+ | x-opt-qd.trace | list of string |The list of routers through which this message-routed | | | |message has transited. If this field is not present, | | | |the router shall do nothing. If the field is present, | | | |the router shall append its own identity to the end of | | | |the list. | | | | | | | | | +--------------------+------------------+-------------------------------------------------------+ | x-opt-qd.to | string |To-Override for message-routed messages. If this field | | | |is present, the address in this field shall be used for| | | |routing in lieu of the *to* field in the message | | | |properties. A router may append, remove, or modify this| | | |annotation field depending on the policy in place for | | | |routing the message. | | | | | | | | | | | | | +--------------------+------------------+-------------------------------------------------------+ | x-opt-qd.class | string |Message class. This is used to allow the router to | | | |provide separate paths for different classes of | | | |traffic. | +--------------------+------------------+-------------------------------------------------------+ Source/Target Capabilities -------------------------- The following Capability values are used in Sources and Targets. +----------------+----------------------------------------------------------------------------+ | *Capability* | *Description* | +================+============================================================================+ | qd.router |This capability is added to sources and targets that are used for | | |inter-router message exchange. | | | | +----------------+----------------------------------------------------------------------------+ Dynamic-Node-Properties ----------------------- The following dynamic-node-properties are used by Dispatch in Sources. +--------------------+-----------------------------------------------------------------------+ | *Property* | *Description* | +====================+=======================================================================+ | x-opt-qd.address |The node address describing the destination desired for a dynamic | | |source. If this is absent, the router will terminate any dynamic | | |receivers. If this address is present, the router will use the address | | |to route the dynamic link attach to the proper destination container. | | | | +--------------------+-----------------------------------------------------------------------+ Addresses and Address Formats ----------------------------- The following AMQP addresses and address patterns are used within Dispatch Router. Address Patterns ~~~~~~~~~~~~~~~~ +--------------------------------+-------------------------------------------------------+ | *Pattern* | *Description* | +================================+=======================================================+ | `_local/` |An address that references a locally attached | | |endpoint. Messages using this address pattern shall not| | |be routed over more than one link. | | | | | | | | | | | | | | | | | | | +--------------------------------+-------------------------------------------------------+ | `_topo///` |An address that references an endpoint attached to a | | |specific router node in the network topology. Messages | | |with addresses that follow this pattern shall be routed| | |along the shortest path to the specified router. Note | | |that addresses of this form are a-priori routable in | | |that the address itself contains enough information to | | |route the message to its destination. | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | +--------------------------------+-------------------------------------------------------+ | `` |A mobile address. An address of this format represents | | |an endpoint or a set of distinct endpoints that are | | |attached to the network in arbitrary locations. It is | | |the responsibility of the router network to determine | | |which router nodes are valid destinations for mobile | | |addresses. | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | +--------------------------------+-------------------------------------------------------+ Supported Addresses ~~~~~~~~~~~~~~~~~~~ +------------------------------+------------------------------------------------------------+ | *Address* | *Description* | +==============================+============================================================+ | `$management` |The management agent on the attached router/container. This | | |address would be used by an endpoint that is a management | | |client/console/tool wishing to access management data from | | |the attached container. | +------------------------------+------------------------------------------------------------+ | `_topo/0/Router.E/agent` |The management agent at Router.E in area 0. This address | | |would be used by a management client wishing to access | | |management data from a specific container that is reachable | | |within the network. | +------------------------------+------------------------------------------------------------+ | `_local/qdhello` |The router entity in each of the connected routers. This | | |address is used to communicate with neighbor routers and is | | |exclusively for the HELLO discovery protocol. | +------------------------------+------------------------------------------------------------+ | `_local/qdrouter` |The router entity in each of the connected routers. This | | |address is used by a router to communicate with other | | |routers in the network. | +------------------------------+------------------------------------------------------------+ | `_topo/0/Router.E/qdrouter` |The router entity at the specifically indicated router. This| | |address form is used by a router to communicate with a | | |specific router that may or may not be a neighbor. | +------------------------------+------------------------------------------------------------+ Implementation of the AMQP Management Specification --------------------------------------------------- Qpid Dispatch is manageable remotely via AMQP. It is compliant with the emerging AMQP Management specification (draft 9). Differences from the specification: - The `name` attribute is not required when an entity is created. If not supplied it will be set to the same value as the system-generated "identity" attribute. Otherwise it is treated as per the standard. - The `REGISTER` and `DEREGISTER` operations are not implemented. The router automatically discovers peer routers via the router network and makes their management addresses available via the standard GET-MGMT-NODES operation.