You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by jo...@apache.org on 2010/01/12 15:05:44 UTC
svn commit: r898329 [3/5] - /qpid/trunk/qpid/doc/book/src/
Added: qpid/trunk/qpid/doc/book/src/Management Design notes.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/Management%20Design%20notes.xml?rev=898329&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/Management Design notes.xml (added)
+++ qpid/trunk/qpid/doc/book/src/Management Design notes.xml Tue Jan 12 14:05:42 2010
@@ -0,0 +1,2115 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns:html="http://www.w3.org/1999/xhtml"><title>
+ Apache Qpid : Management Design notes
+ </title><section role="h2" id="ManagementDesignnotes-StatusofThisDocument"><title>
+ Status
+ of This Document
+ </title>
+
+ <para>
+ This document does not track any current development activity. It
+ is the specification of the management framework implemented in
+ the M3 release of the C++ broker and will be left here for user
+ and developer reference.
+ </para><para>
+ Development continues on the Qpid Management Framework (QMF) for
+ M4. If you are using M3, this is the document you need. If you
+ are using the SVN trunk, please refer to <xref linkend="qpid_Qpid-20Management-20Framework"/> for
+ up-to-date information.
+ </para>
+ <!--h2--></section>
+
+ <section role="h2" id="ManagementDesignnotes-Introduction"><title>
+ Introduction
+ </title>
+
+ <para>
+ This document describes the management features that are used in
+ the QPID C++ broker as of the M3 milestone. These features do not
+ appear in earlier milestones nor are they implemented in the Java
+ broker.
+ </para><para>
+ This specification is <emphasis>not</emphasis> a standard and is not endorsed
+ by the AMQP working group. When such a standard is adopted, the
+ QPID implementation will be brought into compliance with that
+ standard.
+ </para>
+ <!--h2--></section>
+
+ <section role="h2" id="ManagementDesignnotes-Links"><title>
+ Links
+ </title>
+
+ <itemizedlist>
+ <listitem><para>The schema is checked into <xref linkend="qpid_management-schema.xml"/>.
+ </para></listitem>
+ </itemizedlist><section role="h3" id="ManagementDesignnotes-DesignnoteforgettinginfoinandoutviaJMX"><title>
+ Design
+ note for getting info in and out via JMX
+ </title>
+
+ <para>
+ <xref linkend="qpid_JMX-20Gateway"/>
+ </para>
+ <!--h3--></section>
+
+ <!--h2--></section>
+
+ <section role="h2" id="ManagementDesignnotes-ManagementRequirements"><title>
+ Management
+ Requirements
+ </title>
+
+ <itemizedlist>
+ <listitem><para>Must operate from a formally defined management schema.
+ </para></listitem>
+ <listitem><para>Must natively use the AMQP protocol and its type system.
+ </para></listitem>
+ <listitem><para>Must support the following operations
+ <itemizedlist>
+ <listitem><para>SET operation on configurable (persistent) aspects of
+ objects
+ </para></listitem>
+ <listitem><para>GET operation on all aspects of objects
+ </para></listitem>
+ <listitem><para>METHOD invocation on schema-defined object-specific
+ methods
+ </para></listitem>
+ <listitem><para>Distribution of unsolicited periodic updates of
+ instrumentation data
+ <itemizedlist>
+ <listitem><para>Data updates shall carry an accurate sample timestamp
+ for rate calculation
+ </para></listitem>
+ <listitem><para>Updates shall carry object create/delete timestamps.
+ </para></listitem>
+ <listitem><para>Transient objects shall be fully accounted for via
+ updates. Note that short-lived transient objects may come
+ and go within a single update interval. All of the
+ information pertaining to such an object must be captured
+ and transmitted.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>Distribution of unsolicited event and/or alert
+ indications (schema defined)
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>Role-based access control at object, operation, and method
+ granularity
+ </para></listitem>
+ <listitem><para>End-to-end encryption and signing of management content
+ </para></listitem>
+ <listitem><para>Schema must be self-describing so the management client need
+ not have prior knowledge of the management model of the system
+ under management.
+ </para></listitem>
+ <listitem><para>Must be extensible to support the management of objects
+ beyond the QPID component set. This allows AMQP to be used as a
+ general-purpose management protocol.
+ </para></listitem>
+ </itemizedlist>
+ <!--h2--></section>
+
+ <section role="h2" id="ManagementDesignnotes-DefinitionofTerms"><title>
+ Definition
+ of Terms
+ </title>
+
+ <table><title/><tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ class
+ </entry>
+ <entry>
+ A type definition for a manageable object.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ package
+ </entry>
+ <entry>
+ A grouping of class definitions that are related to a
+ single software component. The package concept is used to
+ extend the management schema beyond just the QPID software
+ components.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ object
+ </entry>
+ <entry>
+ Also "manageable object". An instantiation of a class. An
+ object represents a physical or logical component in the
+ core function of the system under management.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ property
+ </entry>
+ <entry>
+ A typed member of a class which represents a configurable
+ attribute of the class. In general, properties don't change
+ frequently or may not change at all.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ statistic
+ </entry>
+ <entry>
+ A typed member of a class which represents an
+ instrumentation attribute of the class. Statistics are
+ always read-only in nature and tend to change rapidly.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ method
+ </entry>
+ <entry>
+ A member of a class which represents a callable procedure
+ on an object of the class. Methods may have an arbitrary
+ set of typed arguments and may supply a return code.
+ Methods typically have side effects on the associated
+ object.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ event
+ </entry>
+ <entry>
+ A member of a class which represents the occurence of an
+ event of interest within the system under management.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ management broker
+ </entry>
+ <entry>
+ A software component built into the messaging broker that
+ handles management traffic and distributes management data.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ management agent
+ </entry>
+ <entry>
+ A software component that is separate from the messaging
+ broker, connected to the management broker via an AMQP
+ connection, which allows any software component to be
+ managed remotely by QPID.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table>
+ <!--h2--></section>
+
+
+ <section role="h2" id="ManagementDesignnotes-OperationalScenarios-3ABasicvs.Extended"><title>
+ Operational
+ Scenarios: Basic vs. Extended
+ </title>
+
+ <para>
+ The extensibility requirement introduces complexity to the
+ management protocol that is unnecessary and undesirable for the
+ user/developer that wishes only to manage QPID message brokers.
+ For this reason, the protocol is partitioned into two parts: The
+ <emphasis>basic protocol</emphasis>, which contains only the capability to
+ manage a single broker; and the <emphasis>extended protocol</emphasis>, which
+ provides the hooks for managing an extended set of components. A
+ management console can be implemented using only the basic
+ protocol if the extended capabilities are not needed.
+ </para>
+<!--h2--></section>
+
+
+ <section role="h2" id="ManagementDesignnotes-ArchitecturalFramework"><title>
+ Architectural
+ Framework
+ </title>
+
+ <para>
+ <xref linkend="qpid_qmf_architecture"/>
+ </para>
+ <!--h2--></section>
+
+ <section role="h2" id="ManagementDesignnotes-TheManagementExchange"><title>
+ The
+ Management Exchange
+ </title>
+
+ <para>
+ The management exchange (called "qpid.management" currently) is a
+ special type of exchange used for remote management access to the
+ Qpid broker. The management exchange is an extension of the
+ standard "Topic" exchange. It behaves like a topic exchange with
+ the following exceptions:
+ </para><orderedlist>
+ <listitem><para>When a queue is successfully bound to the exchange, a method
+ is invoked on the broker's management agent to notify it of the
+ presence of a new remote managment client.
+ </para></listitem>
+ <listitem><para>When messages arrive at the exchange for routing, the
+ exchange examines the message's routing key and if the key
+ represents a management command or method, it routes it directly
+ to the management agent rather than routing it to queues using
+ the topic algorithm.
+ The management exchange is used by the management agent to
+ distribute unsolicited management data. Such data is classified
+ by the routing key allowing management clients to register for
+ only the data they need.
+ </para></listitem>
+ </orderedlist><section role="h3" id="ManagementDesignnotes-RoutingKeyStructure"><title>
+ Routing
+ Key Structure
+ </title>
+
+ <para>
+ As noted above, the structure of the binding and routing keys
+ used on the management exchange is important to the function of
+ the management architecture. The routing key of a management
+ message determines:
+ </para><orderedlist>
+ <listitem><para>The type of message (i.e. operation request or unsolicited
+ update).
+ </para></listitem>
+ <listitem><para>The class of the object that the message pertains to.
+ </para></listitem>
+ <listitem><para>The specific operation or update type.
+ </para></listitem>
+ <listitem><para>The namespace in which the class belongs. This allows for
+ plug-in expansion of the management schema for manageable objects
+ that are outside of the broker itself.
+ </para></listitem>
+ </orderedlist><para>
+ Placing this information in the routing key provides the ability
+ to enforce access control at class, operation, and method
+ granularity. It also separates the command structure from the
+ content of the management message (i.e. element values) allowing
+ the content to be encrypted and signed end-to-end while still
+ allowing access control at the message-transport level. This
+ means that special access control code need not be written for
+ the management agent.
+ There are two general types of routing/binding key:
+ </para><itemizedlist>
+ <listitem><para>
+ <emphasis>Command</emphasis> messages use the key:
+ agent.<bank#> or broker
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Unsolicited</emphasis> keys have the structure:
+ mgmt.<agent>.<type>.<package>.<class>.<severity>
+ where
+ <itemizedlist>
+ <listitem><para>
+ <agent> is the uuid of the originating
+ management agent,
+ </para></listitem>
+ <listitem><para>
+ <type> is one of "schema", "prop", "stat",
+ or "event",
+ </para></listitem>
+ <listitem><para>
+ <package> is the namespace in which the
+ <class> name is valid, and
+ </para></listitem>
+ <listitem><para>
+ <class> is the name of the class as defined
+ in the schema.
+ </para></listitem>
+ <listitem><para>
+ <severity> is relevant for events only. It
+ is one of "critical", "error", "warning", or "info".
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </itemizedlist><para>
+ In both cases, the content of the message (i.e. method arguments,
+ element values, etc.) is carried in the body segment of the
+ message.
+ </para><para>
+ The <package> namespace allows this management
+ framework to be extended with the addition of other software
+ packages.
+ </para>
+ <!--h3--></section>
+ <!--h2--></section>
+
+ <section role="h2" id="ManagementDesignnotes-TheProtocol"><title>
+ The Protocol
+ </title>
+
+ <section role="h3" id="ManagementDesignnotes-ProtocolHeader"><title>
+ Protocol
+ Header
+ </title>
+
+ <para>
+ The body segments of management messages are composed of
+ sequences of binary-encoded data fields, in a manner consistent
+ with the 0-10 version of the AMQP specification.
+ </para><para>
+ All management messages begin with a message header:
+ </para>
+ <programlisting>
+ octet 0 1 2 3 4 5 6 7
+ +---------+---------+---------+---------+---------+---------+---------+---------+
+ | 'A' | 'M' | '1' | op-code | sequence |
+ +---------+---------+---------+---------+---------+---------+---------+---------+
+</programlisting>
+ <para>
+ The first three octets contain the protocol <emphasis>magic number</emphasis>
+ "AM1" which is used to identify the type and version of the
+ message.
+ </para><para>
+ The <emphasis>opcode</emphasis> field identifies the operation represented by
+ the message
+ </para>
+ <!--h3--></section>
+
+ <section role="h3" id="ManagementDesignnotes-ProtocolExchangePatterns"><title>
+ Protocol
+ Exchange Patterns
+ </title>
+
+ <para>
+ The following patterns are followed in the design of the
+ protocol:
+ </para><itemizedlist>
+ <listitem><para>Request-Response
+ </para></listitem>
+ <listitem><para>Query-Indication
+ </para></listitem>
+ <listitem><para>Unsolicited Indication
+ </para></listitem>
+ </itemizedlist><section role="h4" id="ManagementDesignnotes-TheRequestResponsePattern"><title>
+ The
+ Request-Response Pattern
+ </title>
+
+ <para>
+ In the request-response pattern, a requestor sends a
+ <emphasis>request</emphasis> message to one of its peers. The peer then does
+ one of two things: If the request can be successfully processed,
+ a single <emphasis>response</emphasis> message is sent back to the requestor.
+ This response contains the requested results and serves as the
+ positive acknowledgement that the request was successfully
+ completed.
+ </para><para>
+ If the request cannot be successfully completed, the peer sends a
+ <emphasis>command complete</emphasis> message back to the requestor with an
+ error code and error text describing what went wrong.
+ </para><para>
+ The sequence number in the <emphasis>response</emphasis> or <emphasis>command
+ complete</emphasis> message is the same as the sequence number in the
+ <emphasis>request</emphasis>.
+ </para>
+ <programlisting>
+ Requestor Peer
+ | |
+ | --- Request (seq) ------------------------------------------> |
+ | |
+ | <----------------------------------------- Response (seq) --- |
+ | |
+</programlisting>
+
+ <programlisting>
+ Requestor Peer
+ | |
+ | --- Request (seq) ------------------------------------------> |
+ | |
+ | <-------------------------- Command Complete (seq, error) --- |
+ | |
+</programlisting>
+<!--h4--></section>
+
+ <section role="h4" id="ManagementDesignnotes-TheQueryIndicationPattern"><title>
+ The
+ Query-Indication Pattern
+ </title>
+
+ <para>
+ The query-indication pattern is used when there may be zero or
+ more answers to a question. In this case, the requestor sends a
+ <emphasis>query</emphasis> message to its peer. The peer processes the query,
+ sending as many <emphasis>indication</emphasis> messages as needed back to the
+ requestor (zero or more). Once the last <emphasis>indication</emphasis> has
+ been sent, the peer then sends a <emphasis>command complete</emphasis> message
+ with a success code indicating that the query is complete.
+ </para><para>
+ If there is an error in the <emphasis>query</emphasis>, the peer may reply with
+ a <emphasis>command complete</emphasis> message containg an error code. In this
+ case, no <emphasis>indication</emphasis> messages may be sent.
+ </para><para>
+ All <emphasis>indication</emphasis> and <emphasis>command complete</emphasis> messages shall
+ have the same sequence number that appeared in the <emphasis>query</emphasis>
+ message.
+ </para>
+ <programlisting>
+ Requestor Peer
+ | |
+ | --- Query (seq) --------------------------------------------> |
+ | |
+ | <--------------------------------------- Indication (seq) --- |
+ | <--------------------------------------- Indication (seq) --- |
+ | <--------------------------------------- Indication (seq) --- |
+ | <--------------------------------------- Indication (seq) --- |
+ | <--------------------------------------- Indication (seq) --- |
+ | |
+ | <------------------------ Command Complete (seq, success) --- |
+ | |
+</programlisting>
+
+ <programlisting>
+ Requestor Peer
+ | |
+ | --- Query (seq) --------------------------------------------> |
+ | |
+ | <-------------------------- Command Complete (seq, error) --- |
+ | |
+</programlisting>
+<!--h4--></section>
+
+ <section role="h4" id="ManagementDesignnotes-TheUnsolicitedIndicationPattern"><title>
+ The
+ Unsolicited-Indication Pattern
+ </title>
+
+ <para>
+ The unsolicited-indication pattern is used when one peer needs to
+ send unsolicited information to another peer, or to broadcast
+ information to multiple peers via a topic exchange. In this case,
+ indication messages are sent with the sequence number field set
+ to zero.
+ </para>
+ <programlisting>
+ Peer Peer
+ | |
+ | <----------------------------------- Indication (seq = 0) --- |
+ | <----------------------------------- Indication (seq = 0) --- |
+ | <----------------------------------- Indication (seq = 0) --- |
+ | <----------------------------------- Indication (seq = 0) --- |
+ | |
+</programlisting>
+<!--h4--></section>
+<!--h3--></section>
+
+ <section role="h3" id="ManagementDesignnotes-ObjectIdentifiers"><title>
+ Object
+ Identifiers
+ </title>
+
+ <para>
+ Manageable objects are tagged with a unique 64-bit object
+ identifier. The object identifier space is owned and managed by
+ the management broker. Objects managed by a single management
+ broker shall have unique object identifiers. Objects managed by
+ separate management brokers may have the same object identifier.
+ </para><para>
+ If a management console is designed to manage multiple management
+ brokers, it must use the broker identifier as well as the object
+ identifier to ensure global uniqueness.
+ </para>
+ <programlisting>
+ 62 48 47 24 23 0
+ +-+-------------+-----------------------+-----------------------+
+ |0| sequence | bank | object |
+ +-+-------------+-----------------------+-----------------------+
+
+ bit 63 - reserved, must be zero
+ bits 63 .. 48 - broker boot sequence (32K)
+ bits 47 .. 24 - bank (16M)
+ bits 23 .. 0 - object (16M)
+</programlisting>
+ <itemizedlist>
+ <listitem><para>For persistent IDs, boot-sequence is zero
+ </para></listitem>
+ <listitem><para>For non-persistent IDs, boot sequence is a constant number
+ which increments each time the management broker is restarted.
+ </para></listitem>
+ <listitem><para>Bank number:
+ <itemizedlist>
+ <listitem><para>0 - reserved
+ </para></listitem>
+ <listitem><para>1 - broker-persistent objects
+ </para></listitem>
+ <listitem><para>2..4 - store-persistent objects
+ </para></listitem>
+ <listitem><para>> 4 - transient objects
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </itemizedlist>
+<!--h3--></section>
+
+
+ <section role="h3" id="ManagementDesignnotes-EstablishingCommunicationBetweenClientandAgent"><title>
+ Establishing Communication Between Client and Agent
+ </title>
+
+ <para>
+ Communication is established between the management client and
+ management agent using normal AMQP procedures. The client creates
+ a connection to the broker and then establishes a session with
+ its corresponding channel.
+ </para><para>
+ Two private queues are then declared (only one if method
+ invocation is not needed). A management queue is declared and
+ bound to the qpid.management exchange. If the binding key is
+ "mgmt.#", all management-related messages sent to the exchange
+ will be received by this client. A more specific binding key will
+ result in a more restricted set of messages being received (see
+ the section on Routing Key Structure below).
+ </para><para>
+ If methods are going to be invoked on managed objects, a second
+ private queue must be declared so the client can receive method
+ replies. This queue is bound to the amq.direct exchange using a
+ routing key equal to the name of the queue.
+ </para><para>
+ When a client successfully binds to the qpid.management exchange,
+ the management agent schedules a schema broadcast to be sent to
+ the exchange. The agent will publish, via the exchange, a
+ description of the schema for all manageable objects in its
+ control.
+ </para>
+ <programlisting>
+ Client Broker
+ | |
+ | --- AMQP Connection and Session Setup ----------------------> |
+ | |
+ | --- Queue.declare (private data queue) ---------------------> |
+ | --- Bind queue to exchange 'qpid.management' key 'mgmt.#' --> |
+ | |
+ | --- Queue.declare (private method-reply queue) -------------> |
+ | --- Bind queue to exchange 'amq.direct' --------------------> |
+ | |
+ | --- Broker Request -----------------------------------------> |
+ | <---------------------------------------- Broker Response --- |
+ | |
+ | |
+ | |
+ | <------- Management schema via exchange 'qpid.management' --- |
+ | |
+</programlisting>
+<!--h3--></section>
+
+ <section role="h3" id="ManagementDesignnotes-BroadcastofConfigurationandInstrumentationUpdates"><title>
+ Broadcast of Configuration and Instrumentation Updates
+ </title>
+
+ <para>
+ The management agent will periodically publish updates to the
+ configuration and instrumentation of management objects under its
+ control. Under normal circumstances, these updates are published
+ only if they have changed since the last time they were
+ published. Configuration updates are only published if
+ configuration has changed and instrumentation updates are only
+ published if instrumentation has changed. The exception to this
+ rule is that after a management client binds to the
+ qpid.management exchange, all configuration and instrumentation
+ records are published as though they had changed whether or not
+ they actually did.
+ </para>
+ <programlisting>
+ Client Broker
+ | |
+ | <------------------ Object properties via 'mgmt.*.prop.#' --- | |
+ | <------------------ Object statistics via 'mgmt.*.stat.#' --- | |
+ | | |
+ | | | Publish Interval
+ | | |
+ | | |
+ | | V
+ | <------------------ Object properties via 'mgmt.*.prop.#' --- |
+ | <------------------ Object statistics via 'mgmt.*.stat.#' --- |
+ | |
+</programlisting>
+<!--h3--></section>
+
+ <section role="h3" id="ManagementDesignnotes-InvokingaMethodonaManagedObject"><title>
+ Invoking
+ a Method on a Managed Object
+ </title>
+
+ <para>
+ When the management client wishes to invoke a method on a managed
+ object, it sends a method request message to the qpid.management
+ exchange. The routing key contains the object class and method
+ name (refer to Routing Key Structure below). The method request
+ must have a header entry (reply-to) that contains the name of the
+ method-reply queue so that the method response can be properly
+ routed back to the requestor.
+ </para><para>
+ The method request contains a sequence number that is copied to
+ the method reply. This number is opaque to the management agent
+ and may be used by the management client to correlate the reply
+ to the request. The asynchronous nature of requests and replies
+ allows any number of methods to be in-flight at a time. Note that
+ there is no guarantee that methods will be replied to in the
+ order in which they were requested.
+ </para>
+ <programlisting>
+ Client Broker
+ | |
+ | --- Method Request (to exchange 'qpid.management') ---------> |
+ | |
+ | |
+ | <--------------- Method Reply (via exchange 'amq.direct') --- |
+ | |
+</programlisting>
+<!--h3--></section>
+
+
+ <section role="h3" id="ManagementDesignnotes-MessagesfortheBasicScenario"><title>
+ Messages
+ for the Basic Scenario
+ </title>
+
+ <para>
+ The principals in a management exchange are the <emphasis>management
+ client</emphasis> and the <emphasis>management agent</emphasis>. The management
+ agent is integrated into the QPID broker and the management
+ client is a remote entity. A management agent may be managed by
+ zero or more management clients at any given time. Additionally,
+ a management client may manage multiple management agents at the
+ same time.
+ </para><para>
+ For authentication and access control, management relies on the
+ mechanisms supplied by the AMQP protocol.
+ </para><section role="h4" id="ManagementDesignnotes-BasicOpcodes"><title>
+ Basic Opcodes
+ </title>
+
+ <table><title/><tgroup cols="3">
+ <tbody>
+ <row>
+ <entry>
+ <emphasis>opcode</emphasis>
+ </entry>
+ <entry>
+ <emphasis>message</emphasis>
+ </entry>
+ <entry>
+ <emphasis>description</emphasis>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'B'
+ </entry>
+ <entry>
+ Broker Request
+ </entry>
+ <entry>
+ This message contains a broker request, sent from the
+ management console to the broker to initiate a management
+ session.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'b'
+ </entry>
+ <entry>
+ Broker Response
+ </entry>
+ <entry>
+ This message contains a broker response, sent from the
+ broker in response to a broker request message.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'z'
+ </entry>
+ <entry>
+ Command Completion
+ </entry>
+ <entry>
+ This message is sent to indicate the completion of a
+ request.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'Q'
+ </entry>
+ <entry>
+ Class Query
+ </entry>
+ <entry>
+ Class query messages are used by a management console to
+ request a list of schema classes that are known by the
+ management broker.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'q'
+ </entry>
+ <entry>
+ Class Indication
+ </entry>
+ <entry>
+ Sent by the management broker, a class indication notifies
+ the peer of the existence of a schema class.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'S'
+ </entry>
+ <entry>
+ Schema Request
+ </entry>
+ <entry>
+ Schema request messages are used to request the full schema
+ details for a class.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 's'
+ </entry>
+ <entry>
+ Schema Response
+ </entry>
+ <entry>
+ Schema response message contain a full description of the
+ schema for a class.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'h'
+ </entry>
+ <entry>
+ Heartbeat Indication
+ </entry>
+ <entry>
+ This message is published once per publish-interval. It can
+ be used by a client to positively determine which objects
+ did not change during the interval (since updates are not
+ published for objects with no changes).
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'c', 'i', 'g'
+ </entry>
+ <entry>
+ Content Indication
+ </entry>
+ <entry>
+ This message contains a content record. Content records
+ contain the values of all properties or statistics in an
+ object. Such records are broadcast on a periodic interval
+ if 1) a change has been made in the value of one of the
+ elements, or 2) if a new management client has bound a
+ queue to the management exchange.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'G'
+ </entry>
+ <entry>
+ Get Query
+ </entry>
+ <entry>
+ Sent by a management console, a get query requests that the
+ management broker provide content indications for all
+ objects that match the query criteria.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'M'
+ </entry>
+ <entry>
+ Method Request
+ </entry>
+ <entry>
+ This message contains a method request.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'm'
+ </entry>
+ <entry>
+ Method Response
+ </entry>
+ <entry>
+ This message contains a method result.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table>
+<!--h4--></section>
+
+ <section role="h4" id="ManagementDesignnotes-BrokerRequestMessage"><title>
+ Broker
+ Request Message
+ </title>
+
+ <para>
+ When a management client first establishes contact with the
+ broker, it sends a Hello message to initiate the exchange.
+ </para>
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 'B' | 0 |
+ +-----+-----+-----+-----+-----------------------+
+</programlisting>
+ <para>
+ The Broker Request message has no payload.
+ </para>
+<!--h4--></section>
+
+ <section role="h4" id="ManagementDesignnotes-BrokerResponseMessage"><title>
+ Broker
+ Response Message
+ </title>
+
+ <para>
+ When the broker receives a Broker Request message, it responds
+ with a Broker Response message. This message contains an
+ identifier unique to the broker.
+ </para>
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 'b' | 0 |
+ +-----+-----+-----+-----+-----------------------+----------------------------+
+ | brokerId (uuid) |
+ +----------------------------------------------------------------------------+
+</programlisting>
+<!--h4--></section>
+
+ <section role="h4" id="ManagementDesignnotes-CommandCompletionMessage"><title>
+ Command
+ Completion Message
+ </title>
+
+
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 'z' | seq |
+ +-----+-----+-----+-----+-----------------------+
+ | Completion Code |
+ +-----------------------+-----------------------------------------+
+ | Completion Text |
+ +-----------------------------------------------------------------+
+</programlisting>
+<!--h4--></section>
+
+
+ <section role="h4" id="ManagementDesignnotes-ClassQuery"><title>
+ Class Query
+ </title>
+
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 'Q' | seq |
+ +-----+-----+-----+-----+-----------------------+----------+
+ | package name (str8) |
+ +----------------------------------------------------------+
+</programlisting>
+<!--h4--></section>
+
+
+ <section role="h4" id="ManagementDesignnotes-ClassIndication"><title>
+ Class
+ Indication
+ </title>
+
+
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 'q' | seq |
+ +-----+-----+-----+-----+-----------------------+----------+
+ | package name (str8) |
+ +----------------------------------------------------------+
+ | class name (str8) |
+ +----------------------------------------------------------+
+ | schema hash (bin128) |
+ +----------------------------------------------------------+
+</programlisting>
+<!--h4--></section>
+
+
+ <section role="h4" id="ManagementDesignnotes-SchemaRequest"><title>
+ Schema Request
+ </title>
+
+
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 'S' | seq |
+ +-----+-----+-----+-----+-----------------------+----------+
+ | packageName (str8) |
+ +----------------------------------------------------------+
+ | className (str8) |
+ +----------------------------------------------------------+
+ | schema-hash (bin128) |
+ +----------------------------------------------------------+
+</programlisting>
+<!--h4--></section>
+
+ <section role="h4" id="ManagementDesignnotes-SchemaResponse"><title>
+ Schema
+ Response
+ </title>
+
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 's' | seq |
+ +-----+-----+-----+-----+-----------------------+----------+
+ | packageName (str8) |
+ +----------------------------------------------------------+
+ | className (str8) |
+ +----------------------------------------------------------+
+ | schema-hash (bin128) |
+ +-----------+-----------+-----------+-----------+----------+
+ | propCnt | statCnt | methodCnt | eventCnt |
+ +-----------+-----------+-----------+-----------+----------------------------+
+ | propCnt property records |
+ +----------------------------------------------------------------------------+
+ | statCnt statistic records |
+ +----------------------------------------------------------------------------+
+ | methodCnt method records |
+ +----------------------------------------------------------------------------+
+ | eventCnt event records |
+ +----------------------------------------------------------------------------+
+</programlisting>
+ <para>
+ Each <emphasis>property</emphasis> record is an AMQP map with the following
+ fields. Optional fields may optionally be omitted from the map.
+ </para><table><title/><tgroup cols="3">
+ <tbody>
+ <row>
+ <entry>
+ <emphasis>field name</emphasis>
+ </entry>
+ <entry>
+ <emphasis>optional</emphasis>
+ </entry>
+ <entry>
+ <emphasis>description</emphasis>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ name
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ Name of the property
+ </entry>
+ </row>
+ <row>
+ <entry>
+ type
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ Type code for the property
+ </entry>
+ </row>
+ <row>
+ <entry>
+ access
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ Access code for the property
+ </entry>
+ </row>
+ <row>
+ <entry>
+ index
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ 1 = index element, 0 = not an index element
+ </entry>
+ </row>
+ <row>
+ <entry>
+ optional
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ 1 = optional element (may be not present), 0 = mandatory
+ (always present)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ unit
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ Units for numeric values (i.e. seconds, bytes, etc.)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ min
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ Minimum value for numerics
+ </entry>
+ </row>
+ <row>
+ <entry>
+ max
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ Maximum value for numerics
+ </entry>
+ </row>
+ <row>
+ <entry>
+ maxlen
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ Maximum length for strings
+ </entry>
+ </row>
+ <row>
+ <entry>
+ desc
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ Description of the property
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table><para>
+ Each <emphasis>statistic</emphasis> record is an AMQP map with the following
+ fields:
+ </para><table><title/><tgroup cols="3">
+ <tbody>
+ <row>
+ <entry>
+ <emphasis>field name</emphasis>
+ </entry>
+ <entry>
+ <emphasis>optional</emphasis>
+ </entry>
+ <entry>
+ <emphasis>description</emphasis>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ name
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ Name of the statistic
+ </entry>
+ </row>
+ <row>
+ <entry>
+ type
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ Type code for the statistic
+ </entry>
+ </row>
+ <row>
+ <entry>
+ unit
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ Units for numeric values (i.e. seconds, bytes, etc.)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ desc
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ Description of the statistic
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table><para>
+ <emphasis>method</emphasis> and <emphasis>event</emphasis> records contain a main map that
+ describes the method or header followed by zero or more maps
+ describing arguments. The main map contains the following fields:
+ </para><table><title/><tgroup cols="3">
+ <tbody>
+ <row>
+ <entry>
+ <emphasis>field name</emphasis>
+ </entry>
+ <entry>
+ <emphasis>optional</emphasis>
+ </entry>
+ <entry>
+ <emphasis>description</emphasis>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ name
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ Name of the method or event
+ </entry>
+ </row>
+ <row>
+ <entry>
+ argCount
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ Number of argument records to follow
+ </entry>
+ </row>
+ <row>
+ <entry>
+ desc
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ Description of the method or event
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table><para>
+ Argument maps contain the following fields:
+ </para><table><title/><tgroup cols="5">
+ <tbody>
+ <row>
+ <entry>
+ <emphasis>field name</emphasis>
+ </entry>
+ <entry>
+ <emphasis>method</emphasis>
+ </entry>
+ <entry>
+ <emphasis>event</emphasis>
+ </entry>
+ <entry>
+ <emphasis>optional</emphasis>
+ </entry>
+ <entry>
+ <emphasis>description</emphasis>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ name
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ Argument name
+ </entry>
+ </row>
+ <row>
+ <entry>
+ type
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ Type code for the argument
+ </entry>
+ </row>
+ <row>
+ <entry>
+ dir
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ Direction code for method arguments
+ </entry>
+ </row>
+ <row>
+ <entry>
+ unit
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ Units for numeric values (i.e. seconds, bytes, etc.)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ min
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ Minimum value for numerics
+ </entry>
+ </row>
+ <row>
+ <entry>
+ max
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ Maximum value for numerics
+ </entry>
+ </row>
+ <row>
+ <entry>
+ maxlen
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ Maximum length for strings
+ </entry>
+ </row>
+ <row>
+ <entry>
+ desc
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ Description of the argument
+ </entry>
+ </row>
+ <row>
+ <entry>
+ default
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ Default value for the argument
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table><para>
+ <emphasis>type codes</emphasis> are numerics with the following values:
+ </para><table><title/><tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <emphasis>value</emphasis>
+ </entry>
+ <entry>
+ <emphasis>type</emphasis>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 1
+ </entry>
+ <entry>
+ uint8
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 2
+ </entry>
+ <entry>
+ uint16
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 3
+ </entry>
+ <entry>
+ uint32
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 4
+ </entry>
+ <entry>
+ uint64
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 6
+ </entry>
+ <entry>
+ str8
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 7
+ </entry>
+ <entry>
+ str16
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 8
+ </entry>
+ <entry>
+ absTime(uint64)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 9
+ </entry>
+ <entry>
+ deltaTime(uint64)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 10
+ </entry>
+ <entry>
+ objectReference(uint64)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 11
+ </entry>
+ <entry>
+ boolean(uint8)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 12
+ </entry>
+ <entry>
+ float
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 13
+ </entry>
+ <entry>
+ double
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 14
+ </entry>
+ <entry>
+ uuid
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 15
+ </entry>
+ <entry>
+ map
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 16
+ </entry>
+ <entry>
+ int8
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 17
+ </entry>
+ <entry>
+ int16
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 18
+ </entry>
+ <entry>
+ int32
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 19
+ </entry>
+ <entry>
+ int64
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table><para>
+ <emphasis>access codes</emphasis> are numerics with the following values:
+ </para><table><title/><tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <emphasis>value</emphasis>
+ </entry>
+ <entry>
+ <emphasis>access</emphasis>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 1
+ </entry>
+ <entry>
+ Read-Create access
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 2
+ </entry>
+ <entry>
+ Read-Write access
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 3
+ </entry>
+ <entry>
+ Read-Only access
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table><para>
+ <emphasis>direction codes</emphasis> are numerics with the following values:
+ </para><table><title/><tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <emphasis>value</emphasis>
+ </entry>
+ <entry>
+ <emphasis>direction</emphasis>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 1
+ </entry>
+ <entry>
+ Input (from client to broker)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 2
+ </entry>
+ <entry>
+ Output (from broker to client)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 3
+ </entry>
+ <entry>
+ IO (bidirectional)
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table>
+<!--h4--></section>
+
+
+ <section role="h4" id="ManagementDesignnotes-HeartbeatIndication"><title>
+ Heartbeat
+ Indication
+ </title>
+
+
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 'h' | 0 |
+ +-----+-----+-----+-----+-----------------------+
+ | timestamp of current interval (datetime) |
+ +-----------------------------------------------+
+</programlisting>
+<!--h4--></section>
+
+ <section role="h4" id="ManagementDesignnotes-ConfigurationandInstrumentationContentMessages"><title>
+ Configuration and Instrumentation Content Messages
+ </title>
+
+ <para>
+ Content messages are published when changes are made to the
+ values of properties or statistics or when new management clients
+ bind a queue to the management exchange.
+ </para>
+ <programlisting>
+ +-----+-----+-----+-------+-----------------------+
+ | 'A' | 'M' | '1' |'g/c/i'| seq |
+ +-----+-----+-----+-------+-----------------------+--------+
+ | packageName (str8) |
+ +----------------------------------------------------------+
+ | className (str8) |
+ +----------------------------------------------------------+
+ | class hash (bin128) |
+ +-----+-----+-----+-----+-----+-----+-----+-----+----------+
+ | timestamp of current sample (datetime) |
+ +-----+-----+-----+-----+-----+-----+-----+-----+
+ | time object was created (datetime) |
+ +-----+-----+-----+-----+-----+-----+-----+-----+
+ | time object was deleted (datetime) |
+ +-----+-----+-----+-----+-----+-----+-----+-----+
+ | objectId (uint64) |
+ +-----+-----+-----+-----+-----+-----+-----+-----+
+ | presence bitmasks (0 or more uint8 fields) |
+ +-----+-----+-----+-----+-----+-----+-----+-----+------------------------+
+ | config/inst values (in schema order) |
+ +------------------------------------------------------------------------+
+</programlisting>
+ <para>
+ All timestamps are uint64 values representing nanoseconds since
+ the epoch (January 1, 1970). The objectId is a uint64 value that
+ uniquely identifies this object instance.
+ </para><para>
+ If any of the properties in the object are defined as optional,
+ there will be 1 or more "presence bitmask" octets. There are as
+ many octets as are needed to provide one bit per optional
+ property. The bits are assigned to the optional properties in
+ schema order (first octet first, lowest order bit first).
+ </para><para>
+ For example: If there are two optional properties in the schema
+ called "option1" and "option2" (defined in that order), there
+ will be one presence bitmask octet and the bits will be assigned
+ as bit 0 controls option1 and bit 1 controls option2.
+ </para><para>
+ If the bit for a particular optional property is set (1), the
+ property will be encoded normally in the "values" portion of the
+ message. If the bit is clear (0), the property will be omitted
+ from the list of encoded values and will be considered "NULL" or
+ "not present".
+ </para><para>
+ The element values are encoded by their type into the message in
+ the order in which they appeared in the schema message.
+ </para>
+<!--h4--></section>
+
+ <section role="h4" id="ManagementDesignnotes-GetQueryMessage"><title>
+ Get Query
+ Message
+ </title>
+
+ <para>
+ A Get Request may be sent by the management console to cause a
+ management agent to immediately send content information for
+ objects of a class.
+ </para>
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 'G' | seq |
+ +-----+-----+-----+-----+-----------------------+----------+
+ | Get request field table |
+ +----------------------------------------------------------+
+</programlisting>
+ <para>
+ The content of a get request is a field table that specifies what
+ objects are being requested. Most of the fields are optional and
+ are available for use in more extensive deployments.
+ </para><table><title/><tgroup cols="4">
+ <tbody>
+ <row>
+ <entry>
+ <emphasis>Field Key</emphasis>
+ </entry>
+ <entry>
+ <emphasis>Mandatory</emphasis>
+ </entry>
+ <entry>
+ <emphasis>Type</emphasis>
+ </entry>
+ <entry>
+ <emphasis>Description</emphasis>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ "_class"
+ </entry>
+ <entry>
+ yes
+ </entry>
+ <entry>
+ short-string
+ </entry>
+ <entry>
+ The name of the class of objects being requested.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ "_package"
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ short-string
+ </entry>
+ <entry>
+ The name of the extension package the class belongs to. If
+ omitted, the package defaults to "qpid" for access to
+ objects in the connected broker.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ "_agent"
+ </entry>
+ <entry>
+ no
+ </entry>
+ <entry>
+ uuid
+ </entry>
+ <entry>
+ The management agent that is the target of the request. If
+ omitted, agent defaults to the connected broker.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table><para>
+ When the management agent receives a get request, it sends
+ content messages describing the requested objects. Once the last
+ content message is sent, it then sends a Command Completion
+ message with the same sequence number supplied in the request to
+ indicate to the requestor that there are no more messages coming.
+ </para>
+<!--h4--></section>
+
+
+ <section role="h4" id="ManagementDesignnotes-MethodRequest"><title>
+ Method Request
+ </title>
+
+ <para>
+ Method request messages have the following structure. The
+ sequence number is opaque to the management agent. It is returned
+ unchanged in the method reply so the calling client can correctly
+ associate the reply to the request. The objectId is the unique ID
+ of the object on which the method is to be executed.
+ </para>
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 'M' | seq |
+ +-----+-----+-----+-----+-----------------------+
+ | objectId (uint64) |
+ +-----------------------------------------------+
+ | methodName (str8) |
+ +-----------------------------------------------+------------------------+
+ | input and bidirectional argument values (in schema order) |
+ +------------------------------------------------------------------------+
+</programlisting>
+<!--h4--></section>
+
+ <section role="h4" id="ManagementDesignnotes-MethodResponse"><title>
+ Method
+ Response
+ </title>
+
+ <para>
+ Method reply messages have the following structure. The sequence
+ number is identical to that supplied in the method request. The
+ status code (and text) indicate whether or not the method was
+ successful and if not, what the error was. Output and
+ bidirectional arguments are only included if the status code was
+ 0 (STATUS_OK).
+ </para>
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 'm' | seq |
+ +-----+-----+-----+-----+-----------------------+
+ | status code |
+ +-----------------------+----------------------------------+
+ | status text (str8) |
+ +-----------------------+----------------------------------+-------------+
+ | output and bidirectional argument values (in schema order) |
+ +------------------------------------------------------------------------+
+</programlisting>
+ <para>
+ <emphasis>status code</emphasis> values are:
+ </para><table><title/><tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <emphasis>value</emphasis>
+ </entry>
+ <entry>
+ <emphasis>description</emphasis>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 0
+ </entry>
+ <entry>
+ STATUS_OK - successful completion
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 1
+ </entry>
+ <entry>
+ STATUS_UNKNOWN_OBJECT - objectId not found in the agent
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 2
+ </entry>
+ <entry>
+ STATUS_UNKNOWN_METHOD - method is not known by the object
+ type
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 3
+ </entry>
+ <entry>
+ STATUS_NOT_IMPLEMENTED - method is not currently
+ implemented
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table>
+<!--h4--></section>
+<!--h3--></section>
+
+ <section role="h3" id="ManagementDesignnotes-MessagesforExtendedScenario"><title>
+ Messages
+ for Extended Scenario
+ </title>
+
+ <section role="h4" id="ManagementDesignnotes-ExtendedManagementProtocol"><title>
+ Extended
+ Management Protocol
+ </title>
+
+ <para>
+ Qpid supports management extensions that allow the management
+ broker to be a central point for the management of multiple
+ external entities with their own management schemas.
+ </para>
+ <programlisting>
+ Broker Remote Agent
+ | |
+ | <----------------------------------------- Attach Request --- |
+ | --- Attach Response ----------------------------------------> |
+ | |
+ | <------------------------------------- Package Indication --- |
+ | <------------------------------------- Package Indication --- |
+ | |
+ | <--------------------------------------- Class Indication --- |
+ | <--------------------------------------- Class Indication --- |
+ | <--------------------------------------- Class Indication --- |
+ | <--------------------------------------- Class Indication --- |
+ | <--------------------------------------- Class Indication --- |
+ | |
+ | --- Schema Request (class key) -----------------------------> |
+ | <---------------------------------------- Schema Response --- |
+ | |
+ | --- Schema Request (class key) -----------------------------> |
+ | <---------------------------------------- Schema Response --- |
+ | |
+ | |
+</programlisting>
+<!--h4--></section>
+
+ <section role="h4" id="ManagementDesignnotes-ExtendedOpcodes"><title>
+ Extended
+ Opcodes
+ </title>
+
+ <table><title/><tgroup cols="3">
+ <tbody>
+ <row>
+ <entry>
+ <emphasis>opcode</emphasis>
+ </entry>
+ <entry>
+ <emphasis>message</emphasis>
+ </entry>
+ <entry>
+ <emphasis>description</emphasis>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'P'
+ </entry>
+ <entry>
+ Package Query
+ </entry>
+ <entry>
+ This message contains a schema package query request,
+ requesting that the broker dump the list of known packages
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'p'
+ </entry>
+ <entry>
+ Package Indication
+ </entry>
+ <entry>
+ This message contains a schema package indication,
+ identifying a package known by the broker
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'A'
+ </entry>
+ <entry>
+ Agent Attach Request
+ </entry>
+ <entry>
+ This message is sent by a remote agent when it wishes to
+ attach to a management broker
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'a'
+ </entry>
+ <entry>
+ Agent Attach Response
+ </entry>
+ <entry>
+ The management broker sends this response if an attaching
+ remote agent is permitted to join
+ </entry>
+ </row>
+ <row>
+ <entry>
+ 'x'
+ </entry>
+ <entry>
+ Console Added Indication
+ </entry>
+ <entry>
+ This message is sent to all remote agents by the management
+ broker when a new console binds to the management exchange
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table>
+<!--h4--></section>
+
+
+ <section role="h4" id="ManagementDesignnotes-PackageQuery"><title>
+ Package Query
+ </title>
+
+
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 'P' | seq |
+ +-----+-----+-----+-----+-----------------------+
+</programlisting>
+<!--h4--></section>
+
+ <section role="h4" id="ManagementDesignnotes-PackageIndication"><title>
+ Package
+ Indication
+ </title>
+
+
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 'p' | seq |
+ +-----+-----+-----+-----+-----------------------+----------+
+ | package name (str8) |
+ +----------------------------------------------------------+
+</programlisting>
+<!--h4--></section>
+
+ <section role="h4" id="ManagementDesignnotes-AttachRequest"><title>
+ Attach Request
+ </title>
+
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 'A' | seq |
+ +-----+-----+-----+-----+-----------------------+----------+
+ | label (str8) |
+ +-----------------------+----------------------------------+
+ | system-id (uuid) |
+ +-----------------------+----------------------------------+
+ | requested objId bank |
+ +-----------------------+
+</programlisting>
+<!--h4--></section>
+
+ <section role="h4" id="ManagementDesignnotes-AttachResponse-28success-29"><title>
+ Attach
+ Response (success)
+ </title>
+
+
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 'a' | seq |
+ +-----+-----+-----+-----+-----------------------+
+ | assigned broker bank |
+ +-----------------------+
+ | assigned objId bank |
+ +-----------------------+
+</programlisting>
+<!--h4--></section>
+
+ <section role="h4" id="ManagementDesignnotes-ConsoleAddedIndication"><title>
+ Console Added
+ Indication
+ </title>
+
+
+ <programlisting>
+ +-----+-----+-----+-----+-----------------------+
+ | 'A' | 'M' | '1' | 'x' | seq |
+ +-----+-----+-----+-----+-----------------------+
+</programlisting>
+
+
+
+ <!--h4--></section>
+ <!--h3--></section>
+ <!--h2--></section>
+
+
+</chapter>
+
\ No newline at end of file
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org