path: root/qpid/doc/book/src/Management-Design-notes.xml

<?xml version="1.0" encoding="utf-8"?>
<!--
 
 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.
 
-->

<section><title>
      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-Management-Framework"/> 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-Gateway"/>
          </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.&lt;bank#&gt; or broker
            </para></listitem>
            <listitem><para>
              <emphasis>Unsolicited</emphasis> keys have the structure:
              mgmt.&lt;agent&gt;.&lt;type&gt;.&lt;package&gt;.&lt;class&gt;.&lt;severity&gt;
              where
              <itemizedlist>
                <listitem><para>
                  &lt;agent&gt; is the uuid of the originating
                  management agent,
                </para></listitem>
                <listitem><para>
                  &lt;type&gt; is one of "schema", "prop", "stat",
                  or "event",
                </para></listitem>
                <listitem><para>
                  &lt;package&gt; is the namespace in which the
                  &lt;class&gt; name is valid, and
                </para></listitem>
                <listitem><para>
                  &lt;class&gt; is the name of the class as defined
                  in the schema.
                </para></listitem>
                <listitem><para>
                  &lt;severity&gt; 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 &lt;package&gt; 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) ------------------------------------------&gt; |
        |                                                               |
        | &lt;----------------------------------------- Response (seq) --- |
        |                                                               |
</programlisting>
          
            <programlisting>
    Requestor                                                          Peer
        |                                                               |
        | --- Request (seq) ------------------------------------------&gt; |
        |                                                               |
        | &lt;-------------------------- 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) --------------------------------------------&gt; |
        |                                                               |
        | &lt;--------------------------------------- Indication (seq) --- |
        | &lt;--------------------------------------- Indication (seq) --- |
        | &lt;--------------------------------------- Indication (seq) --- |
        | &lt;--------------------------------------- Indication (seq) --- |
        | &lt;--------------------------------------- Indication (seq) --- |
        |                                                               |
        | &lt;------------------------ Command Complete (seq, success) --- |
        |                                                               |
</programlisting>
          
            <programlisting>
    Requestor                                                          Peer
        |                                                               |
        | --- Query (seq) --------------------------------------------&gt; |
        |                                                               |
        | &lt;-------------------------- 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
        |                                                               |
        | &lt;----------------------------------- Indication (seq = 0) --- |
        | &lt;----------------------------------- Indication (seq = 0) --- |
        | &lt;----------------------------------- Indication (seq = 0) --- |
        | &lt;----------------------------------- 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>&gt; 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 ----------------------&gt; |
        |                                                               |
        | --- Queue.declare (private data queue) ---------------------&gt; |
        | --- Bind queue to exchange 'qpid.management' key 'mgmt.#' --&gt; |
        |                                                               |
        | --- Queue.declare (private method-reply queue) -------------&gt; |
        | --- Bind queue to exchange 'amq.direct' --------------------&gt; |
        |                                                               |
        | --- Broker Request -----------------------------------------&gt; |
        | &lt;---------------------------------------- Broker Response --- |
        |                                                               |
        |                                                               |
        |                                                               |
        | &lt;------- 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
        |                                                               |
        | &lt;------------------ Object properties via 'mgmt.*.prop.#' --- | |
        | &lt;------------------ Object statistics via 'mgmt.*.stat.#' --- | |
        |                                                               | |
        |                                                               | | Publish Interval
        |                                                               | |
        |                                                               | |
        |                                                               | V
        | &lt;------------------ Object properties via 'mgmt.*.prop.#' --- |
        | &lt;------------------ 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') ---------&gt; |
        |                                                               |
        |                                                               |
        | &lt;--------------- 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
        |                                                               |
        | &lt;----------------------------------------- Attach Request --- |
        | --- Attach Response ----------------------------------------&gt; |
        |                                                               |
        | &lt;------------------------------------- Package Indication --- |
        | &lt;------------------------------------- Package Indication --- |
        |                                                               |
        | &lt;--------------------------------------- Class Indication --- |
        | &lt;--------------------------------------- Class Indication --- |
        | &lt;--------------------------------------- Class Indication --- |
        | &lt;--------------------------------------- Class Indication --- |
        | &lt;--------------------------------------- Class Indication --- |
        |                                                               |
        | --- Schema Request (class key) -----------------------------&gt; |
        | &lt;---------------------------------------- Schema Response --- |
        |                                                               |
        | --- Schema Request (class key) -----------------------------&gt; |
        | &lt;---------------------------------------- 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>

	 
</section>