qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rob...@apache.org
Subject svn commit: r1688840 [11/15] - in /qpid/site: ./ docs/ docs/components/cpp-broker/ docs/components/messaging-api/ docs/releases/ docs/releases/qpid-cpp-0.34/ docs/releases/qpid-cpp-0.34/cpp-broker/ docs/releases/qpid-cpp-0.34/cpp-broker/book/ docs/rele...
Date Thu, 02 Jul 2015 14:53:55 GMT
Added: qpid/site/input/releases/qpid-cpp-0.34/cpp-broker/book/ch02s02.html.in
URL: http://svn.apache.org/viewvc/qpid/site/input/releases/qpid-cpp-0.34/cpp-broker/book/ch02s02.html.in?rev=1688840&view=auto
==============================================================================
--- qpid/site/input/releases/qpid-cpp-0.34/cpp-broker/book/ch02s02.html.in (added)
+++ qpid/site/input/releases/qpid-cpp-0.34/cpp-broker/book/ch02s02.html.in Thu Jul  2 14:53:53 2015
@@ -0,0 +1,586 @@
+<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">2.2.&#160;
+      Qpid Management Framework
+    </th></tr><tr><td align="left" width="20%"><a accesskey="p" href="chapter-Managing-CPP-Broker.html">Prev</a>&#160;</td><th align="center" width="60%">Chapter&#160;2.&#160;
+      Managing the AMQP Messaging Broker
+    </th><td align="right" width="20%">&#160;<a accesskey="n" href="ch02s03.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="idm221066520256"></a>2.2.&#160;
+      Qpid Management Framework
+    </h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
+                <a class="xref" href="ch02s02.html#QpidManagementFramework-WhatIsQMF" title="2.2.1.&#160; What Is QMF">Section&#160;2.2.1, &#8220;
+            What Is QMF
+          &#8221;</a>
+              </p></li><li class="listitem"><p>
+                <a class="xref" href="ch02s02.html#QpidManagementFramework-GettingStartedwithQMF" title="2.2.2.&#160; Getting Started with QMF">Section&#160;2.2.2, &#8220;
+            Getting
+            Started with QMF
+          &#8221;</a>
+              </p></li><li class="listitem"><p>
+                <a class="xref" href="ch02s02.html#QpidManagementFramework-QMFConcepts" title="2.2.3.&#160; QMF Concepts">Section&#160;2.2.3, &#8220;
+            QMF Concepts
+          &#8221;</a>
+              </p></li><li class="listitem"><p>
+                </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>
+                    <a class="xref" href="ch02s02.html#QpidManagementFramework-Console-2CAgent-2CandBroker" title="2.2.3.1.&#160; Console, Agent, and Broker">Section&#160;2.2.3.1, &#8220;
+            Console,
+            Agent, and Broker
+          &#8221;</a>
+                  </p></li><li class="listitem"><p>
+                    <a class="xref" href="ch02s02.html#QpidManagementFramework-Schema" title="2.2.3.2.&#160; Schema">Section&#160;2.2.3.2, &#8220;
+            Schema
+          &#8221;</a>
+                  </p></li><li class="listitem"><p>
+                    <a class="xref" href="ch02s02.html#QpidManagementFramework-ClassKeysandClassVersioning" title="2.2.3.3.&#160; Class Keys and Class Versioning">Section&#160;2.2.3.3, &#8220;
+            Class
+            Keys and Class Versioning
+          &#8221;</a>
+                  </p></li></ul></div><p>
+              </p></li><li class="listitem"><p>
+                <a class="xref" href="ch02s02.html#QpidManagementFramework-TheQMFProtocol" title="2.2.4.&#160; The QMF Protocol">Section&#160;2.2.4, &#8220;
+            The QMF
+            Protocol
+          &#8221;</a>
+              </p></li><li class="listitem"><p>
+                <a class="xref" href="ch02s02.html#QpidManagementFramework-HowtoWriteaQMFConsole" title="2.2.5.&#160; How to Write a QMF Console">Section&#160;2.2.5, &#8220;
+            How
+            to Write a QMF Console
+          &#8221;</a>
+              </p></li><li class="listitem"><p>
+                <a class="xref" href="ch02s02.html#QpidManagementFramework-HowtoWriteaQMFAgent" title="2.2.6.&#160; How to Write a QMF Agent">Section&#160;2.2.6, &#8220;
+            How to
+            Write a QMF Agent
+          &#8221;</a>
+              </p></li></ul></div><p>
+              Please visit the <a class="xref" href="">???</a> for information
+              about the future of QMF.
+            </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="QpidManagementFramework-WhatIsQMF"></a>2.2.1.&#160;
+            What Is QMF
+          </h3></div></div></div><p>
+            QMF (Qpid Management Framework) is a general-purpose management
+            bus built on Qpid Messaging. It takes advantage of the
+            scalability, security, and rich capabilities of Qpid to provide
+            flexible and easy-to-use manageability to a large set of
+            applications.
+          </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="QpidManagementFramework-GettingStartedwithQMF"></a>2.2.2.&#160;
+            Getting
+            Started with QMF
+          </h3></div></div></div><p>
+            QMF is used through two primary APIs. The <span class="emphasis"><em>console</em></span> API is
+            used for console applications that wish to access and manipulate
+            manageable components through QMF. The <span class="emphasis"><em>agent</em></span> API is used
+            for application that wish to be managed through QMF.
+          </p><p>
+            The fastest way to get started with QMF is to work through the
+            "How To" tutorials for consoles and agents. For a deeper
+            understanding of what is happening in the tutorials, it is
+            recommended that you look at the <span class="emphasis"><em>Qmf Concepts</em></span> section.
+          </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="QpidManagementFramework-QMFConcepts"></a>2.2.3.&#160;
+            QMF Concepts
+          </h3></div></div></div><p>
+            This section introduces important concepts underlying QMF.
+          </p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="QpidManagementFramework-Console-2CAgent-2CandBroker"></a>2.2.3.1.&#160;
+            Console,
+            Agent, and Broker
+          </h4></div></div></div><p>
+            The major architectural components of QMF are the Console, the
+            Agent, and the Broker. Console components are the "managing"
+            components of QMF and agent components are the "managed" parts.
+            The broker is a central (possibly distributed, clustered and
+            fault-tolerant) component that manages name spaces and caches
+            schema information.
+          </p><p>
+            A console application may be a command-line utility, a
+            three-tiered web-based GUI, a collection and storage device, a
+            specialized application that monitors and reacts to events and
+            conditions, or anything else somebody wishes to develop that uses
+            QMF management data.
+          </p><p>
+            An agent application is any application that has been enhanced to
+            allow itself to be managed via QMF.
+          </p><pre class="programlisting">
+       +-------------+    +---------+    +---------------+    +-------------------+
+       | CLI utility |    | Web app |    | Audit storage |    | Event correlation |
+       +-------------+    +---------+    +---------------+    +-------------------+
+              ^                ^                 ^                ^          |
+              |                |                 |                |          |
+              v                v                 v                v          v
+    +---------------------------------------------------------------------------------+
+    |                Qpid Messaging Bus (with QMF Broker capability)                  |
+    +---------------------------------------------------------------------------------+
+                    ^                     ^                     ^
+                    |                     |                     |
+                    v                     v                     v
+           +----------------+    +----------------+    +----------------+
+           | Manageable app |    | Manageable app |    | Manageable app |
+           +----------------+    +----------------+    +----------------+
+</pre><p>
+            In the above diagram, the <span class="emphasis"><em>Manageable apps</em></span> are agents,
+            the <span class="emphasis"><em>CLI utility</em></span>, <span class="emphasis"><em>Web app</em></span>, and <span class="emphasis"><em>Audit
+            storage</em></span> are consoles, and <span class="emphasis"><em>Event correlation</em></span> is both
+            a console and an agent because it can create events based on the
+            aggregation of what it sees.
+          </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="QpidManagementFramework-Schema"></a>2.2.3.2.&#160;
+            Schema
+          </h4></div></div></div><p>
+            A <span class="emphasis"><em>schema</em></span> describes the structure of management data.
+            Each <span class="emphasis"><em>agent</em></span> provides a schema that describes its
+            management model including the object classes, methods, events,
+            etc. that it provides. In the current QMF distribution, the
+            agent's schema is codified in an XML document. In the near
+            future, there will also be ways to programatically create QMF
+            schemata.
+          </p><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="QpidManagementFramework-Package"></a>
+            Package
+          </h5></div></div></div><p>
+            Each agent that exports a schema identifies itself using a
+            <span class="emphasis"><em>package</em></span> name. The package provides a unique namespace
+            for the classes in the agent's schema that prevent collisions
+            with identically named classes in other agents' schemata.
+          </p><p>
+            Package names are in "reverse domain name" form with levels of
+            hierarchy separated by periods. For example, the Qpid messaging
+            broker uses package "org.apache.qpid.broker" and the Access
+            Control List plugin for the broker uses package
+            "org.apache.qpid.acl". In general, the package name should be the
+            reverse of the internet domain name assigned to the organization
+            that owns the agent software followed by identifiers to uniquely
+            identify the agent.
+          </p><p>
+            The XML document for a package's schema uses an enclosing
+            &lt;schema&gt; tag. For example:
+          </p><pre class="programlisting">
+&lt;schema package="org.apache.qpid.broker"&gt;
+
+&lt;/schema&gt;
+</pre></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="QpidManagementFramework-ObjectClasses"></a>
+            Object
+            Classes
+          </h5></div></div></div><p>
+            <span class="emphasis"><em>Object classes</em></span> define types for manageable objects. The
+            agent may create and destroy objects which are instances of
+            object classes in the schema. An object class is defined in the
+            XML document using the &lt;class&gt; tag. An object class is
+            composed of properties, statistics, and methods.
+          </p><pre class="programlisting">
+  &lt;class name="Exchange"&gt;
+    &lt;property name="vhostRef"   type="objId" references="Vhost" access="RC" index="y" parentRef="y"/&gt;
+    &lt;property name="name"       type="sstr"  access="RC" index="y"/&gt;
+    &lt;property name="type"       type="sstr"  access="RO"/&gt;
+    &lt;property name="durable"    type="bool"  access="RC"/&gt;
+    &lt;property name="arguments"  type="map"   access="RO" desc="Arguments supplied in exchange.declare"/&gt;
+
+    &lt;statistic name="producerCount" type="hilo32"  desc="Current producers on exchange"/&gt;
+    &lt;statistic name="bindingCount"  type="hilo32"  desc="Current bindings"/&gt;
+    &lt;statistic name="msgReceives"   type="count64" desc="Total messages received"/&gt;
+    &lt;statistic name="msgDrops"      type="count64" desc="Total messages dropped (no matching key)"/&gt;
+    &lt;statistic name="msgRoutes"     type="count64" desc="Total routed messages"/&gt;
+    &lt;statistic name="byteReceives"  type="count64" desc="Total bytes received"/&gt;
+    &lt;statistic name="byteDrops"     type="count64" desc="Total bytes dropped (no matching key)"/&gt;
+    &lt;statistic name="byteRoutes"    type="count64" desc="Total routed bytes"/&gt;
+  &lt;/class&gt;
+</pre></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="QpidManagementFramework-PropertiesandStatistics"></a>
+            Properties
+            and Statistics
+          </h5></div></div></div><p>
+            &lt;property&gt; and &lt;statistic&gt; tags must be placed within
+            &lt;schema&gt; and &lt;/schema&gt; tags.
+          </p><p>
+            Properties, statistics, and methods are the building blocks of an
+            object class. Properties and statistics are both object
+            attributes, though they are treated differently. If an object
+            attribute is defining, seldom or never changes, or is large in
+            size, it should be defined as a <span class="emphasis"><em>property</em></span>. If an
+            attribute is rapidly changing or is used to instrument the object
+            (counters, etc.), it should be defined as a <span class="emphasis"><em>statistic</em></span>.
+          </p><p>
+            The XML syntax for &lt;property&gt; and &lt;statistic&gt; have
+            the following XML-attributes:
+          </p><div class="table"><a id="idm221066568848"></a><p class="title"><strong>Table&#160;2.1.&#160;XML Attributes for QMF Properties and Statistics</strong></p><div class="table-contents"><table border="1" summary="XML Attributes for QMF Properties and Statistics"><colgroup><col /><col /><col /><col /></colgroup><tbody><tr><td>
+                  Attribute
+                </td><td>
+                  &lt;property&gt;
+                </td><td>
+                  &lt;statistic&gt;
+                </td><td>
+                  Meaning
+                </td></tr><tr><td>
+                  name
+                </td><td>
+                  Y
+                </td><td>
+                  Y
+                </td><td>
+                  The name of the attribute
+                </td></tr><tr><td>
+                  type
+                </td><td>
+                  Y
+                </td><td>
+                  Y
+                </td><td>
+                  The data type of the attribute
+                </td></tr><tr><td>
+                  unit
+                </td><td>
+                  Y
+                </td><td>
+                  Y
+                </td><td>
+                  Optional unit name - use the singular (i.e. MByte)
+                </td></tr><tr><td>
+                  desc
+                </td><td>
+                  Y
+                </td><td>
+                  Y
+                </td><td>
+                  Description to annotate the attribute
+                </td></tr><tr><td>
+                  references
+                </td><td>
+                  Y
+                </td><td>
+                  &#160;
+                </td><td>
+                  If the type is "objId", names the referenced class
+                </td></tr><tr><td>
+                  access
+                </td><td>
+                  Y
+                </td><td>
+                  &#160;
+                </td><td>
+                  Access rights (RC, RW, RO)
+                </td></tr><tr><td>
+                  index
+                </td><td>
+                  Y
+                </td><td>
+                  &#160;
+                </td><td>
+                  "y" if this property is used to uniquely identify the
+                  object. There may be more than one index property in a
+                  class
+                </td></tr><tr><td>
+                  parentRef
+                </td><td>
+                  Y
+                </td><td>
+                  &#160;
+                </td><td>
+                  "y" if this property references an object in which this
+                  object is in a child-parent relationship.
+                </td></tr><tr><td>
+                  optional
+                </td><td>
+                  Y
+                </td><td>
+                  &#160;
+                </td><td>
+                  "y" if this property is optional (i.e. may be
+                  NULL/not-present)
+                </td></tr><tr><td>
+                  min
+                </td><td>
+                  Y
+                </td><td>
+                  &#160;
+                </td><td>
+                  Minimum value of a numeric attribute
+                </td></tr><tr><td>
+                  max
+                </td><td>
+                  Y
+                </td><td>
+                  &#160;
+                </td><td>
+                  Maximum value of a numeric attribute
+                </td></tr><tr><td>
+                  maxLen
+                </td><td>
+                  Y
+                </td><td>
+                  &#160;
+                </td><td>
+                  Maximum length of a string attribute
+                </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="QpidManagementFramework-Methods"></a>
+            Methods
+          </h5></div></div></div><p>
+            &lt;method&gt; tags must be placed within &lt;schema&gt; and
+            &lt;/schema&gt; tags.
+          </p><p>
+            A <span class="emphasis"><em>method</em></span> is an invokable function to be performed on
+            instances of the object class (i.e. a Remote Procedure Call). A
+            &lt;method&gt; tag has a name, an optional description, and
+            encloses zero or more arguments. Method arguments are defined by
+            the &lt;arg&gt; tag and have a name, a type, a direction, and an
+            optional description. The argument direction can be "I", "O", or
+            "IO" indicating input, output, and input/output respectively. An
+            example:
+          </p><pre class="programlisting">
+   &lt;method name="echo" desc="Request a response to test the path to the management broker"&gt;
+     &lt;arg name="sequence" dir="IO" type="uint32"/&gt;
+     &lt;arg name="body"     dir="IO" type="lstr"/&gt;
+   &lt;/method&gt;
+</pre></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="QpidManagementFramework-EventClasses"></a>
+            Event Classes
+          </h5></div></div></div><p /></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="QpidManagementFramework-DataTypes"></a>
+            Data Types
+          </h5></div></div></div><p>
+            Object attributes, method arguments, and event arguments have
+            data types. The data types are based on the rich data typing
+            system provided by the AMQP messaging protocol. The following
+            table describes the data types available for QMF:
+          </p><div class="table"><a id="idm221066641472"></a><p class="title"><strong>Table&#160;2.2.&#160;QMF Datatypes</strong></p><div class="table-contents"><table border="1" summary="QMF Datatypes"><colgroup><col /><col /></colgroup><tbody><tr><td>
+                  QMF Type
+                </td><td>
+                  Description
+                </td></tr><tr><td>
+                  REF
+                </td><td>
+                  QMF Object ID - Used to reference another QMF object.
+                </td></tr><tr><td>
+                  U8
+                </td><td>
+                  8-bit unsigned integer
+                </td></tr><tr><td>
+                  U16
+                </td><td>
+                  16-bit unsigned integer
+                </td></tr><tr><td>
+                  U32
+                </td><td>
+                  32-bit unsigned integer
+                </td></tr><tr><td>
+                  U64
+                </td><td>
+                  64-bit unsigned integer
+                </td></tr><tr><td>
+                  S8
+                </td><td>
+                  8-bit signed integer
+                </td></tr><tr><td>
+                  S16
+                </td><td>
+                  16-bit signed integer
+                </td></tr><tr><td>
+                  S32
+                </td><td>
+                  32-bit signed integer
+                </td></tr><tr><td>
+                  S64
+                </td><td>
+                  64-bit signed integer
+                </td></tr><tr><td>
+                  BOOL
+                </td><td>
+                  Boolean - True or False
+                </td></tr><tr><td>
+                  SSTR
+                </td><td>
+                  Short String - String of up to 255 bytes
+                </td></tr><tr><td>
+                  LSTR
+                </td><td>
+                  Long String - String of up to 65535 bytes
+                </td></tr><tr><td>
+                  ABSTIME
+                </td><td>
+                  Absolute time since the epoch in nanoseconds (64-bits)
+                </td></tr><tr><td>
+                  DELTATIME
+                </td><td>
+                  Delta time in nanoseconds (64-bits)
+                </td></tr><tr><td>
+                  FLOAT
+                </td><td>
+                  Single precision floating point number
+                </td></tr><tr><td>
+                  DOUBLE
+                </td><td>
+                  Double precision floating point number
+                </td></tr><tr><td>
+                  UUID
+                </td><td>
+                  UUID - 128 bits
+                </td></tr><tr><td>
+                  FTABLE
+                </td><td>
+                  Field-table - std::map in C++, dictionary in Python
+                </td></tr></tbody></table></div></div><br class="table-break" /><p>
+            In the XML schema definition, types go by different names and
+            there are a number of special cases. This is because the XML
+            schema is used in code-generation for the agent API. It provides
+            options that control what kind of accessors are generated for
+            attributes of different types. The following table enumerates the
+            types available in the XML format, which QMF types they map to,
+            and other special handling that occurs.
+          </p><div class="table"><a id="idm221068539888"></a><p class="title"><strong>Table&#160;2.3.&#160;XML Schema Mapping for QMF Types</strong></p><div class="table-contents"><table border="1" summary="XML Schema Mapping for QMF Types"><colgroup><col /><col /><col /><col /></colgroup><tbody><tr><td>
+                  XML Type
+                </td><td>
+                  QMF Type
+                </td><td>
+                  Accessor Style
+                </td><td>
+                  Special Characteristics
+                </td></tr><tr><td>
+                  objId
+                </td><td>
+                  REF
+                </td><td>
+                  Direct (get, set)
+                </td><td>
+                  &#160;
+                </td></tr><tr><td>
+                  uint8,16,32,64
+                </td><td>
+                  U8,16,32,64
+                </td><td>
+                  Direct (get, set)
+                </td><td>
+                  &#160;
+                </td></tr><tr><td>
+                  int8,16,32,64
+                </td><td>
+                  S8,16,32,64
+                </td><td>
+                  Direct (get, set)
+                </td><td>
+                  &#160;
+                </td></tr><tr><td>
+                  bool
+                </td><td>
+                  BOOL
+                </td><td>
+                  Direct (get, set)
+                </td><td>
+                  &#160;
+                </td></tr><tr><td>
+                  sstr
+                </td><td>
+                  SSTR
+                </td><td>
+                  Direct (get, set)
+                </td><td>
+                  &#160;
+                </td></tr><tr><td>
+                  lstr
+                </td><td>
+                  LSTR
+                </td><td>
+                  Direct (get, set)
+                </td><td>
+                  &#160;
+                </td></tr><tr><td>
+                  absTime
+                </td><td>
+                  ABSTIME
+                </td><td>
+                  Direct (get, set)
+                </td><td>
+                  &#160;
+                </td></tr><tr><td>
+                  deltaTime
+                </td><td>
+                  DELTATIME
+                </td><td>
+                  Direct (get, set)
+                </td><td>
+                  &#160;
+                </td></tr><tr><td>
+                  float
+                </td><td>
+                  FLOAT
+                </td><td>
+                  Direct (get, set)
+                </td><td>
+                  &#160;
+                </td></tr><tr><td>
+                  double
+                </td><td>
+                  DOUBLE
+                </td><td>
+                  Direct (get, set)
+                </td><td>
+                  &#160;
+                </td></tr><tr><td>
+                  uuid
+                </td><td>
+                  UUID
+                </td><td>
+                  Direct (get, set)
+                </td><td>
+                  &#160;
+                </td></tr><tr><td>
+                  map
+                </td><td>
+                  FTABLE
+                </td><td>
+                  Direct (get, set)
+                </td><td>
+                  &#160;
+                </td></tr><tr><td>
+                  hilo8,16,32,64
+                </td><td>
+                  U8,16,32,64
+                </td><td>
+                  Counter (inc, dec)
+                </td><td>
+                  Generates value, valueMin, valueMax
+                </td></tr><tr><td>
+                  count8,16,32,64
+                </td><td>
+                  U8,16,32,64
+                </td><td>
+                  Counter (inc, dec)
+                </td><td>
+                  &#160;
+                </td></tr><tr><td>
+                  mma32,64
+                </td><td>
+                  U32,64
+                </td><td>
+                  Direct
+                </td><td>
+                  Generates valueMin, valueMax, valueAverage, valueSamples
+                </td></tr><tr><td>
+                  mmaTime
+                </td><td>
+                  DELTATIME
+                </td><td>
+                  Direct
+                </td><td>
+                  Generates valueMin, valueMax, valueAverage, valueSamples
+                </td></tr></tbody></table></div></div><br class="table-break" /><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>
+                    When writing a schema using the XML format, types used in
+                    &lt;property&gt; or &lt;arg&gt; must be types that have
+                    <span class="emphasis"><em>Direct</em></span> accessor style. Any type may be used in
+                    &lt;statistic&gt; tags.
+                  </p></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="QpidManagementFramework-ClassKeysandClassVersioning"></a>2.2.3.3.&#160;
+            Class
+            Keys and Class Versioning
+          </h4></div></div></div><p /></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="QpidManagementFramework-TheQMFProtocol"></a>2.2.4.&#160;
+            The QMF
+            Protocol
+          </h3></div></div></div><p>
+            The QMF protocol defines the message formats and communication
+            patterns used by the different QMF components to communicate with
+            one another.
+          </p><p>
+            A description of the current version of the QMF protocol can be
+            found at <a class="xref" href="">???</a>.
+          </p><p>
+            A proposal for an updated protocol based on map-messages is in
+            progress and can be found at <a class="xref" href="">???</a>.
+          </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="QpidManagementFramework-HowtoWriteaQMFConsole"></a>2.2.5.&#160;
+            How
+            to Write a QMF Console
+          </h3></div></div></div><p>
+            Please see the <a class="xref" href="">???</a> for information about using the console API with
+            Python.
+          </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="QpidManagementFramework-HowtoWriteaQMFAgent"></a>2.2.6.&#160;
+            How to
+            Write a QMF Agent
+          </h3></div></div></div><p /></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="chapter-Managing-CPP-Broker.html">Prev</a>&#160;</td><td align="center" width="20%"><a accesskey="u" href="chapter-Managing-CPP-Broker.html">Up</a></td><td align="right" width="40%">&#160;<a accesskey="n" href="ch02s03.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">Chapter&#160;2.&#160;
+      Managing the AMQP Messaging Broker
+    &#160;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%">&#160;2.3.&#160;
+      QMF Python Console Tutorial
+    </td></tr></table></div></div>
\ No newline at end of file

Added: qpid/site/input/releases/qpid-cpp-0.34/cpp-broker/book/ch02s03.html.in
URL: http://svn.apache.org/viewvc/qpid/site/input/releases/qpid-cpp-0.34/cpp-broker/book/ch02s03.html.in?rev=1688840&view=auto
==============================================================================
--- qpid/site/input/releases/qpid-cpp-0.34/cpp-broker/book/ch02s03.html.in (added)
+++ qpid/site/input/releases/qpid-cpp-0.34/cpp-broker/book/ch02s03.html.in Thu Jul  2 14:53:53 2015
@@ -0,0 +1,704 @@
+<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">2.3.&#160;
+      QMF Python Console Tutorial
+    </th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch02s02.html">Prev</a>&#160;</td><th align="center" width="60%">Chapter&#160;2.&#160;
+      Managing the AMQP Messaging Broker
+    </th><td align="right" width="20%">&#160;</td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="idm221066572960"></a>2.3.&#160;
+      QMF Python Console Tutorial
+    </h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
+                <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-PrerequisiteInstallQpidMessaging" title="2.3.1.&#160; Prerequisite - Install Qpid Messaging">Section&#160;2.3.1, &#8220;
+            Prerequisite
+            - Install Qpid Messaging
+          &#8221;</a>
+              </p></li><li class="listitem"><p>
+                <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-SynchronousConsoleOperations" title="2.3.2.&#160; Synchronous Console Operations">Section&#160;2.3.2, &#8220;
+            Synchronous
+            Console Operations
+          &#8221;</a>
+              </p></li><li class="listitem"><p>
+                </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>
+                    <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-CreatingaQMFConsoleSessionandAttachingtoaBroker" title="2.3.2.1.&#160; Creating a QMF Console Session and Attaching to a Broker">Section&#160;2.3.2.1, &#8220;
+            Creating a QMF Console Session and Attaching to a Broker
+          &#8221;</a>
+                  </p></li><li class="listitem"><p>
+                    <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-AccessingManagedObjects" title="2.3.2.2.&#160; Accessing Managed Objects">Section&#160;2.3.2.2, &#8220;
+            Accessing
+            Managed Objects
+          &#8221;</a>
+                  </p></li><li class="listitem"><p>
+                    </p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p>
+                        <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-ViewingPropertiesandStatisticsofanObject" title="Viewing Properties and Statistics of an Object">the section called &#8220;
+            Viewing Properties and Statistics of an Object
+          &#8221;</a>
+                      </p></li><li class="listitem"><p>
+                        <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-InvokingMethodsonanObject" title="Invoking Methods on an Object">the section called &#8220;
+            Invoking
+            Methods on an Object
+          &#8221;</a>
+                      </p></li></ul></div><p>
+                  </p></li></ul></div><p>
+              </p></li><li class="listitem"><p>
+                <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-AsynchronousConsoleOperations" title="2.3.3.&#160; Asynchronous Console Operations">Section&#160;2.3.3, &#8220;
+            Asynchronous
+            Console Operations
+          &#8221;</a>
+              </p></li><li class="listitem"><p>
+                </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>
+                    <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-CreatingaConsoleClasstoReceiveAsynchronousData" title="2.3.3.1.&#160; Creating a Console Class to Receive Asynchronous Data">Section&#160;2.3.3.1, &#8220;
+            Creating a Console Class to Receive Asynchronous Data
+          &#8221;</a>
+                  </p></li><li class="listitem"><p>
+                    <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-ReceivingEvents" title="2.3.3.2.&#160; Receiving Events">Section&#160;2.3.3.2, &#8220;
+            Receiving
+            Events
+          &#8221;</a>
+                  </p></li><li class="listitem"><p>
+                    <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-ReceivingObjects" title="2.3.3.3.&#160; Receiving Objects">Section&#160;2.3.3.3, &#8220;
+            Receiving
+            Objects
+          &#8221;</a>
+                  </p></li><li class="listitem"><p>
+                    <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-AsynchronousMethodCallsandMethodTimeouts" title="2.3.3.4.&#160; Asynchronous Method Calls and Method Timeouts">Section&#160;2.3.3.4, &#8220;
+            Asynchronous Method Calls and Method Timeouts
+          &#8221;</a>
+                  </p></li></ul></div><p>
+              </p></li><li class="listitem"><p>
+                <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-DiscoveringwhatKindsofObjectsareAvailable" title="2.3.4.&#160; Discovering what Kinds of Objects are Available">Section&#160;2.3.4, &#8220;
+            Discovering what Kinds of Objects are Available
+          &#8221;</a>
+              </p></li></ul></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="QMFPythonConsoleTutorial-PrerequisiteInstallQpidMessaging"></a>2.3.1.&#160;
+            Prerequisite
+            - Install Qpid Messaging
+          </h3></div></div></div><p>
+            QMF uses AMQP Messaging (QPid) as its means of communication. To
+            use QMF, Qpid messaging must be installed somewhere in the
+            network. Qpid can be downloaded as source from Apache, is
+            packaged with a number of Linux distributions, and can be
+            purchased from commercial vendors that use Qpid. Please see
+            <a class="ulink" href="http://qpid.apache.org" target="_top">http://qpid.apache.org</a>for
+            information as to where to get Qpid Messaging.
+          </p><p>
+            Qpid Messaging includes a message broker (qpidd) which typically
+            runs as a daemon on a system. It also includes client bindings in
+            various programming languages. The Python-language client library
+            includes the QMF console libraries needed for this tutorial.
+          </p><p>
+            Please note that Qpid Messaging has two broker implementations.
+            One is implemented in C++ and the other in Java. At press time,
+            QMF is supported only by the C++ broker.
+          </p><p>
+            If the goal is to get the tutorial examples up and running as
+            quickly as possible, all of the Qpid components can be installed
+            on a single system (even a laptop). For more realistic
+            deployments, the broker can be deployed on a server and the
+            client/QMF libraries installed on other systems.
+          </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="QMFPythonConsoleTutorial-SynchronousConsoleOperations"></a>2.3.2.&#160;
+            Synchronous
+            Console Operations
+          </h3></div></div></div><p>
+            The Python console API for QMF can be used in a synchronous
+            style, an asynchronous style, or a combination of both.
+            Synchronous operations are conceptually simple and are well
+            suited for user-interactive tasks. All operations are performed
+            in the context of a Python function call. If communication over
+            the message bus is required to complete an operation, the
+            function call blocks and waits for the expected result (or
+            timeout failure) before returning control to the caller.
+          </p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="QMFPythonConsoleTutorial-CreatingaQMFConsoleSessionandAttachingtoaBroker"></a>2.3.2.1.&#160;
+            Creating a QMF Console Session and Attaching to a Broker
+          </h4></div></div></div><p>
+            For the purposes of this tutorial, code examples will be shown as
+            they are entered in an interactive python session.
+          </p><pre class="programlisting">
+$ python
+Python 2.5.2 (r252:60911, Sep 30 2008, 15:41:38) 
+[GCC 4.3.2 20080917 (Red Hat 4.3.2-4)] on linux2
+Type "help", "copyright", "credits" or "license" for more information.
+&gt;&gt;&gt; 
+</pre><p>
+            We will begin by importing the required libraries. If the Python
+            client is properly installed, these libraries will be found
+            normally by the Python interpreter.
+          </p><pre class="programlisting">
+&gt;&gt;&gt; from qmf.console import Session
+</pre><p>
+            We must now create a <span class="emphasis"><em>Session</em></span> object to manage this QMF
+            console session.
+          </p><pre class="programlisting">
+&gt;&gt;&gt; sess = Session()
+</pre><p>
+            If no arguments are supplied to the creation of <span class="emphasis"><em>Session</em></span>,
+            it defaults to synchronous-only operation. It also defaults to
+            user-management of connections. More on this in a moment.
+          </p><p>
+            We will now establish a connection to the messaging broker. If
+            the broker daemon is running on the local host, simply use the
+            following:
+          </p><pre class="programlisting">
+&gt;&gt;&gt; broker = sess.addBroker()
+</pre><p>
+            If the messaging broker is on a remote host, supply the URL to
+            the broker in the <span class="emphasis"><em>addBroker</em></span> function call. Here's how to
+            connect to a local broker using the URL.
+          </p><pre class="programlisting">
+&gt;&gt;&gt; broker = sess.addBroker("amqp://localhost")
+</pre><p>
+            The call to <span class="emphasis"><em>addBroker</em></span> is synchronous and will return
+            only after the connection has been successfully established or
+            has failed. If a failure occurs, <span class="emphasis"><em>addBroker</em></span> will raise an
+            exception that can be handled by the console script.
+          </p><pre class="programlisting">
+&gt;&gt;&gt; try:
+...   broker = sess.addBroker("amqp://localhost:1000")
+... except:
+...   print "Connection Failed"
+... 
+Connection Failed
+&gt;&gt;&gt; 
+</pre><p>
+            This operation fails because there is no Qpid Messaging broker
+            listening on port 1000 (the default port for qpidd is 5672).
+          </p><p>
+            If preferred, the QMF session can manage the connection for you.
+            In this case, <span class="emphasis"><em>addBroker</em></span> returns immediately and the
+            session attempts to establish the connection in the background.
+            This will be covered in detail in the section on asynchronous
+            operations.
+          </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="QMFPythonConsoleTutorial-AccessingManagedObjects"></a>2.3.2.2.&#160;
+            Accessing
+            Managed Objects
+          </h4></div></div></div><p>
+            The Python console API provides access to remotely managed
+            objects via a <span class="emphasis"><em>proxy</em></span> model. The API gives the client an
+            object that serves as a proxy representing the "real" object
+            being managed on the agent application. Operations performed on
+            the proxy result in the same operations on the real object.
+          </p><p>
+            The following examples assume prior knowledge of the kinds of
+            objects that are actually available to be managed. There is a
+            section later in this tutorial that describes how to discover
+            what is manageable on the QMF bus.
+          </p><p>
+            Proxy objects are obtained by calling the
+            <span class="emphasis"><em>Session.getObjects</em></span> function.
+          </p><p>
+            To illustrate, we'll get a list of objects representing queues in
+            the message broker itself.
+          </p><pre class="programlisting">
+&gt;&gt;&gt; queues = sess.getObjects(_class="queue", _package="org.apache.qpid.broker")
+</pre><p>
+            <span class="emphasis"><em>queues</em></span> is an array of proxy objects representing real
+            queues on the message broker. A proxy object can be printed to
+            display a description of the object.
+          </p><pre class="programlisting">
+&gt;&gt;&gt; for q in queues:
+...   print q
+... 
+org.apache.qpid.broker:queue[0-1537-1-0-58] 0-0-1-0-1152921504606846979:reply-localhost.localdomain.32004
+org.apache.qpid.broker:queue[0-1537-1-0-61] 0-0-1-0-1152921504606846979:topic-localhost.localdomain.32004
+&gt;&gt;&gt; 
+</pre><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="QMFPythonConsoleTutorial-ViewingPropertiesandStatisticsofanObject"></a>
+            Viewing Properties and Statistics of an Object
+          </h5></div></div></div><p>
+            Let us now focus our attention on one of the queue objects.
+          </p><pre class="programlisting">
+&gt;&gt;&gt; queue = queues[0]
+</pre><p>
+            The attributes of an object are partitioned into
+            <span class="emphasis"><em>properties</em></span> and <span class="emphasis"><em>statistics</em></span>. Though the
+            distinction is somewhat arbitrary, <span class="emphasis"><em>properties</em></span> tend to
+            be fairly static and may also be large and <span class="emphasis"><em>statistics</em></span>
+            tend to change rapidly and are relatively small (counters, etc.).
+          </p><p>
+            There are two ways to view the properties of an object. An array
+            of properties can be obtained using the <span class="emphasis"><em>getProperties</em></span>
+            function:
+          </p><pre class="programlisting">
+&gt;&gt;&gt; props = queue.getProperties()
+&gt;&gt;&gt; for prop in props:
+...   print prop
+... 
+(vhostRef, 0-0-1-0-1152921504606846979)
+(name, u'reply-localhost.localdomain.32004')
+(durable, False)
+(autoDelete, True)
+(exclusive, True)
+(arguments, {})
+&gt;&gt;&gt; 
+</pre><p>
+            The <span class="emphasis"><em>getProperties</em></span> function returns an array of tuples.
+            Each tuple consists of the property descriptor and the property
+            value.
+          </p><p>
+            A more convenient way to access properties is by using the
+            attribute of the proxy object directly:
+          </p><pre class="programlisting">
+&gt;&gt;&gt; queue.autoDelete
+True
+&gt;&gt;&gt; queue.name
+u'reply-localhost.localdomain.32004'
+&gt;&gt;&gt; 
+</pre><p>
+            Statistics are accessed in the same way:
+          </p><pre class="programlisting">
+&gt;&gt;&gt; stats = queue.getStatistics()
+&gt;&gt;&gt; for stat in stats:
+...   print stat
+... 
+(msgTotalEnqueues, 53)
+(msgTotalDequeues, 53)
+(msgTxnEnqueues, 0)
+(msgTxnDequeues, 0)
+(msgPersistEnqueues, 0)
+(msgPersistDequeues, 0)
+(msgDepth, 0)
+(byteDepth, 0)
+(byteTotalEnqueues, 19116)
+(byteTotalDequeues, 19116)
+(byteTxnEnqueues, 0)
+(byteTxnDequeues, 0)
+(bytePersistEnqueues, 0)
+(bytePersistDequeues, 0)
+(consumerCount, 1)
+(consumerCountHigh, 1)
+(consumerCountLow, 1)
+(bindingCount, 2)
+(bindingCountHigh, 2)
+(bindingCountLow, 2)
+(unackedMessages, 0)
+(unackedMessagesHigh, 0)
+(unackedMessagesLow, 0)
+(messageLatencySamples, 0)
+(messageLatencyMin, 0)
+(messageLatencyMax, 0)
+(messageLatencyAverage, 0)
+&gt;&gt;&gt; 
+</pre><p>
+            or alternatively:
+          </p><pre class="programlisting">
+&gt;&gt;&gt; queue.byteTotalEnqueues
+19116
+&gt;&gt;&gt;
+</pre><p>
+            The proxy objects do not automatically track changes that occur
+            on the real objects. For example, if the real queue enqueues more
+            bytes, viewing the <span class="emphasis"><em>byteTotalEnqueues</em></span> statistic will show
+            the same number as it did the first time. To get updated data on
+            a proxy object, use the <span class="emphasis"><em>update</em></span> function call:
+          </p><pre class="programlisting">
+&gt;&gt;&gt; queue.update()
+&gt;&gt;&gt; queue.byteTotalEnqueues
+19783
+&gt;&gt;&gt;
+</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Be Advised</h3><p>
+                    The <span class="emphasis"><em>update</em></span> method was added after the M4 release
+                    of Qpid/Qmf. It may not be available in your
+                    distribution.
+                  </p></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="QMFPythonConsoleTutorial-InvokingMethodsonanObject"></a>
+            Invoking
+            Methods on an Object
+          </h5></div></div></div><p>
+            Up to this point, we have used the QMF Console API to find
+            managed objects and view their attributes, a read-only activity.
+            The next topic to illustrate is how to invoke a method on a
+            managed object. Methods allow consoles to control the managed
+            agents by either triggering a one-time action or by changing the
+            values of attributes in an object.
+          </p><p>
+            First, we'll cover some background information about methods. A
+            <span class="emphasis"><em>QMF object class</em></span> (of which a <span class="emphasis"><em>QMF object</em></span> is an
+            instance), may have zero or more methods. To obtain a list of
+            methods available for an object, use the <span class="emphasis"><em>getMethods</em></span>
+            function.
+          </p><pre class="programlisting">
+&gt;&gt;&gt; methodList = queue.getMethods()
+</pre><p>
+            <span class="emphasis"><em>getMethods</em></span> returns an array of method descriptors (of
+            type qmf.console.SchemaMethod). To get a summary of a method, you
+            can simply print it. The _<span class="emphasis"><em>repr</em></span>_ function returns a
+            string that looks like a function prototype.
+          </p><pre class="programlisting">
+&gt;&gt;&gt; print methodList
+[purge(request)]
+&gt;&gt;&gt;
+</pre><p>
+            For the purposes of illustration, we'll use a more interesting
+            method available on the <span class="emphasis"><em>broker</em></span> object which represents
+            the connected Qpid message broker.
+          </p><pre class="programlisting">
+&gt;&gt;&gt; br = sess.getObjects(_class="broker", _package="org.apache.qpid.broker")[0]
+&gt;&gt;&gt; mlist = br.getMethods()
+&gt;&gt;&gt; for m in mlist:
+...   print m
+... 
+echo(sequence, body)
+connect(host, port, durable, authMechanism, username, password, transport)
+queueMoveMessages(srcQueue, destQueue, qty)
+&gt;&gt;&gt;
+</pre><p>
+            We have just learned that the <span class="emphasis"><em>broker</em></span> object has three
+            methods: <span class="emphasis"><em>echo</em></span>, <span class="emphasis"><em>connect</em></span>, and
+            <span class="emphasis"><em>queueMoveMessages</em></span>. We'll use the <span class="emphasis"><em>echo</em></span> method to
+            "ping" the broker.
+          </p><pre class="programlisting">
+&gt;&gt;&gt; result = br.echo(1, "Message Body")
+&gt;&gt;&gt; print result
+OK (0) - {'body': u'Message Body', 'sequence': 1}
+&gt;&gt;&gt; print result.status
+0
+&gt;&gt;&gt; print result.text
+OK
+&gt;&gt;&gt; print result.outArgs
+{'body': u'Message Body', 'sequence': 1}
+&gt;&gt;&gt;
+</pre><p>
+            In the above example, we have invoked the <span class="emphasis"><em>echo</em></span> method on
+            the instance of the broker designated by the proxy "br" with a
+            sequence argument of 1 and a body argument of "Message Body". The
+            result indicates success and contains the output arguments (in
+            this case copies of the input arguments).
+          </p><p>
+            To be more precise... Calling <span class="emphasis"><em>echo</em></span> on the proxy causes
+            the input arguments to be marshalled and sent to the remote agent
+            where the method is executed. Once the method execution
+            completes, the output arguments are marshalled and sent back to
+            the console to be stored in the method result.
+          </p><p>
+            You are probably wondering how you are supposed to know what
+            types the arguments are and which arguments are input, which are
+            output, or which are both. This will be addressed later in the
+            "Discovering what Kinds of Objects are Available" section.
+          </p></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="QMFPythonConsoleTutorial-AsynchronousConsoleOperations"></a>2.3.3.&#160;
+            Asynchronous
+            Console Operations
+          </h3></div></div></div><p>
+            QMF is built on top of a middleware messaging layer (Qpid
+            Messaging). Because of this, QMF can use some communication
+            patterns that are difficult to implement using network transports
+            like UDP, TCP, or SSL. One of these patterns is called the
+            <span class="emphasis"><em>Publication and Subscription</em></span> pattern (pub-sub for
+            short). In the pub-sub pattern, data sources <span class="emphasis"><em>publish</em></span>
+            information without a particular destination in mind. Data sinks
+            (destinations) <span class="emphasis"><em>subscribe</em></span> using a set of criteria that
+            describes what kind of data they are interested in receiving.
+            Data published by a source may be received by zero, one, or many
+            subscribers.
+          </p><p>
+            QMF uses the pub-sub pattern to distribute events, object
+            creation and deletion, and changes to properties and statistics.
+            A console application using the QMF Console API can receive these
+            asynchronous and unsolicited events and updates. This is useful
+            for applications that store and analyze events and/or statistics.
+            It is also useful for applications that react to certain events
+            or conditions.
+          </p><p>
+            Note that console applications may always use the synchronous
+            mechanisms.
+          </p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="QMFPythonConsoleTutorial-CreatingaConsoleClasstoReceiveAsynchronousData"></a>2.3.3.1.&#160;
+            Creating a Console Class to Receive Asynchronous Data
+          </h4></div></div></div><p>
+            Asynchronous API operation occurs when the console application
+            supplies a <span class="emphasis"><em>Console</em></span> object to the session manager. The
+            <span class="emphasis"><em>Console</em></span> object (which overrides the
+            <span class="emphasis"><em>qmf.console.Console</em></span> class) handles all asynchronously
+            arriving data. The <span class="emphasis"><em>Console</em></span> class has the following
+            methods. Any number of these methods may be overridden by the
+            console application. Any method that is not overridden defaults
+            to a null handler which takes no action when invoked.
+          </p><div class="table"><a id="idm221064043488"></a><p class="title"><strong>Table&#160;2.4.&#160;QMF Python Console Class Methods</strong></p><div class="table-contents"><table border="1" summary="QMF Python Console Class Methods"><colgroup><col /><col /><col /></colgroup><tbody><tr><td>
+                  Method
+                </td><td>
+                  Arguments
+                </td><td>
+                  Invoked when...
+                </td></tr><tr><td>
+                  brokerConnected
+                </td><td>
+                  broker
+                </td><td>
+                  a connection to a broker is established
+                </td></tr><tr><td>
+                  brokerDisconnected
+                </td><td>
+                  broker
+                </td><td>
+                  a connection to a broker is lost
+                </td></tr><tr><td>
+                  newPackage
+                </td><td>
+                  name
+                </td><td>
+                  a new package is seen on the QMF bus
+                </td></tr><tr><td>
+                  newClass
+                </td><td>
+                  kind, classKey
+                </td><td>
+                  a new class (event or object) is seen on the QMF bus
+                </td></tr><tr><td>
+                  newAgent
+                </td><td>
+                  agent
+                </td><td>
+                  a new agent appears on the QMF bus
+                </td></tr><tr><td>
+                  delAgent
+                </td><td>
+                  agent
+                </td><td>
+                  an agent disconnects from the QMF bus
+                </td></tr><tr><td>
+                  objectProps
+                </td><td>
+                  broker, object
+                </td><td>
+                  the properties of an object are published
+                </td></tr><tr><td>
+                  objectStats
+                </td><td>
+                  broker, object
+                </td><td>
+                  the statistics of an object are published
+                </td></tr><tr><td>
+                  event
+                </td><td>
+                  broker, event
+                </td><td>
+                  an event is published
+                </td></tr><tr><td>
+                  heartbeat
+                </td><td>
+                  agent, timestamp
+                </td><td>
+                  a heartbeat is published by an agent
+                </td></tr><tr><td>
+                  brokerInfo
+                </td><td>
+                  broker
+                </td><td>
+                  information about a connected broker is available to be
+                  queried
+                </td></tr><tr><td>
+                  methodResponse
+                </td><td>
+                  broker, seq, response
+                </td><td>
+                  the result of an asynchronous method call is received
+                </td></tr></tbody></table></div></div><br class="table-break" /><p>
+            Supplied with the API is a class called <span class="emphasis"><em>DebugConsole</em></span>.
+            This is a test <span class="emphasis"><em>Console</em></span> instance that overrides all of
+            the methods such that arriving asynchronous data is printed to
+            the screen. This can be used to see all of the arriving
+            asynchronous data.
+          </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="QMFPythonConsoleTutorial-ReceivingEvents"></a>2.3.3.2.&#160;
+            Receiving
+            Events
+          </h4></div></div></div><p>
+            We'll start the example from the beginning to illustrate the
+            reception and handling of events. In this example, we will create
+            a <span class="emphasis"><em>Console</em></span> class that handles broker-connect,
+            broker-disconnect, and event messages. We will also allow the
+            session manager to manage the broker connection for us.
+          </p><p>
+            Begin by importing the necessary classes:
+          </p><pre class="programlisting">
+&gt;&gt;&gt; from qmf.console import Session, Console
+</pre><p>
+            Now, create a subclass of <span class="emphasis"><em>Console</em></span> that handles the three
+            message types:
+          </p><pre class="programlisting">
+&gt;&gt;&gt; class EventConsole(Console):
+...   def brokerConnected(self, broker):
+...     print "brokerConnected:", broker
+...   def brokerDisconnected(self, broker):
+...     print "brokerDisconnected:", broker
+...   def event(self, broker, event):
+...     print "event:", event
+...
+&gt;&gt;&gt;
+</pre><p>
+            Make an instance of the new class:
+          </p><pre class="programlisting">
+&gt;&gt;&gt; myConsole = EventConsole()
+</pre><p>
+            Create a <span class="emphasis"><em>Session</em></span> class using the console instance. In
+            addition, we shall request that the session manager do the
+            connection management for us. Notice also that we are requesting
+            that the session manager not receive objects or heartbeats. Since
+            this example is concerned only with events, we can optimize the
+            use of the messaging bus by telling the session manager not to
+            subscribe for object updates or heartbeats.
+          </p><pre class="programlisting">
+&gt;&gt;&gt; sess = Session(myConsole, manageConnections=True, rcvObjects=False, rcvHeartbeats=False)
+&gt;&gt;&gt; broker = sess.addBroker()
+&gt;&gt;&gt;
+</pre><p>
+            Once the broker is added, we will begin to receive asynchronous
+            events (assuming there is a functioning broker available to
+            connect to).
+          </p><pre class="programlisting">
+brokerConnected: Broker connected at: localhost:5672
+event: Thu Jan 29 19:53:19 2009 INFO  org.apache.qpid.broker:bind broker=localhost:5672 ...
+</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="QMFPythonConsoleTutorial-ReceivingObjects"></a>2.3.3.3.&#160;
+            Receiving
+            Objects
+          </h4></div></div></div><p>
+            To illustrate asynchronous handling of objects, a small console
+            program is supplied. The entire program is shown below for
+            convenience. We will then go through it part-by-part to explain
+            its design.
+          </p><p>
+            This console program receives object updates and displays a set
+            of statistics as they change. It focuses on broker queue objects.
+          </p><pre class="programlisting">
+# Import needed classes
+from qmf.console import Session, Console
+from time        import sleep
+
+# Declare a dictionary to map object-ids to queue names
+queueMap = {}
+
+# Customize the Console class to receive object updates.
+class MyConsole(Console):
+
+  # Handle property updates
+  def objectProps(self, broker, record):
+
+    # Verify that we have received a queue object.  Exit otherwise.
+    classKey = record.getClassKey()
+    if classKey.getClassName() != "queue":
+      return
+
+    # If this object has not been seen before, create a new mapping from objectID to name
+    oid = record.getObjectId()
+    if oid not in queueMap:
+      queueMap[oid] = record.name
+
+  # Handle statistic updates
+  def objectStats(self, broker, record):
+    
+    # Ignore updates for objects that are not in the map
+    oid = record.getObjectId()
+    if oid not in queueMap:
+      return
+
+    # Print the queue name and some statistics
+    print "%s: enqueues=%d dequeues=%d" % (queueMap[oid], record.msgTotalEnqueues, record.msgTotalDequeues)
+
+    # if the delete-time is non-zero, this object has been deleted.  Remove it from the map.
+    if record.getTimestamps()[2] &gt; 0:
+      queueMap.pop(oid)
+
+# Create an instance of the QMF session manager.  Set userBindings to True to allow
+# this program to choose which objects classes it is interested in.
+sess = Session(MyConsole(), manageConnections=True, rcvEvents=False, userBindings=True)
+
+# Register to receive updates for broker:queue objects.
+sess.bindClass("org.apache.qpid.broker", "queue")
+broker = sess.addBroker()
+
+# Suspend processing while the asynchronous operations proceed.
+try:
+  while True:
+    sleep(1)
+except:
+  pass
+
+# Disconnect the broker before exiting.
+sess.delBroker(broker)
+</pre><p>
+            Before going through the code in detail, it is important to
+            understand the differences between synchronous object access and
+            asynchronous object access. When objects are obtained
+            synchronously (using the <span class="emphasis"><em>getObjects</em></span> function), the
+            resulting proxy contains all of the object's attributes, both
+            properties and statistics. When object data is published
+            asynchronously, the properties and statistics are sent separately
+            and only when the session first connects or when the content
+            changes.
+          </p><p>
+            The script wishes to print the queue name with the updated
+            statistics, but the queue name is only present with the
+            properties. For this reason, the program needs to keep some state
+            to correlate property updates with their corresponding statistic
+            updates. This can be done using the <span class="emphasis"><em>ObjectId</em></span> that
+            uniquely identifies the object.
+          </p><pre class="programlisting">
+    # If this object has not been seen before, create a new mapping from objectID to name
+    oid = record.getObjectId()
+    if oid not in queueMap:
+      queueMap[oid] = record.name
+</pre><p>
+            The above code fragment gets the object ID from the proxy and
+            checks to see if it is in the map (i.e. has been seen before). If
+            it is not in the map, a new map entry is inserted mapping the
+            object ID to the queue's name.
+          </p><pre class="programlisting">
+    # if the delete-time is non-zero, this object has been deleted.  Remove it from the map.
+    if record.getTimestamps()[2] &gt; 0:
+      queueMap.pop(oid)
+</pre><p>
+            This code fragment detects the deletion of a managed object.
+            After reporting the statistics, it checks the timestamps of the
+            proxy. <span class="emphasis"><em>getTimestamps</em></span> returns a list of timestamps in the
+            order:
+          </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
+              <span class="emphasis"><em>Current</em></span> - The timestamp of the sending of this update.
+            </p></li><li class="listitem"><p>
+              <span class="emphasis"><em>Create</em></span> - The time of the object's creation
+            </p></li><li class="listitem"><p>
+              <span class="emphasis"><em>Delete</em></span> - The time of the object's deletion (or zero if
+              not deleted)
+            </p></li></ul></div><p>
+            This code structure is useful for getting information about
+            very-short-lived objects. It is possible that an object will be
+            created, used, and deleted within an update interval. In this
+            case, the property update will arrive first, followed by the
+            statistic update. Both will indicate that the object has been
+            deleted but a full accounting of the object's existence and final
+            state is reported.
+          </p><pre class="programlisting">
+# Create an instance of the QMF session manager.  Set userBindings to True to allow
+# this program to choose which objects classes it is interested in.
+sess = Session(MyConsole(), manageConnections=True, rcvEvents=False, userBindings=True)
+
+# Register to receive updates for broker:queue objects.
+sess.bindClass("org.apache.qpid.broker", "queue")
+</pre><p>
+            The above code is illustrative of the way a console application
+            can tune its use of the QMF bus. Note that <span class="emphasis"><em>rcvEvents</em></span> is
+            set to False. This prevents the reception of events. Note also
+            the use of <span class="emphasis"><em>userBindings=True</em></span> and the call to
+            <span class="emphasis"><em>sess.bindClass</em></span>. If <span class="emphasis"><em>userBindings</em></span> is set to False
+            (its default), the session will receive object updates for all
+            classes of object. In the case above, the application is only
+            interested in broker:queue objects and reduces its bus bandwidth
+            usage by requesting updates to only that class.
+            <span class="emphasis"><em>bindClass</em></span> may be called as many times as desired to add
+            classes to the list of subscribed classes.
+          </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="QMFPythonConsoleTutorial-AsynchronousMethodCallsandMethodTimeouts"></a>2.3.3.4.&#160;
+            Asynchronous Method Calls and Method Timeouts
+          </h4></div></div></div><p>
+            Method calls can also be invoked asynchronously. This is useful
+            if a large number of calls needs to be made in a short time
+            because the console application will not need to wait for the
+            complete round-trip delay for each call.
+          </p><p>
+            Method calls are synchronous by default. They can be made
+            asynchronous by adding the keyword-argument _<span class="emphasis"><em>async=True</em></span>
+            to the method call.
+          </p><p>
+            In a synchronous method call, the return value is the method
+            result. When a method is called asynchronously, the return value
+            is a sequence number that can be used to correlate the eventual
+            result to the request. This sequence number is passed as an
+            argument to the <span class="emphasis"><em>methodResponse</em></span> function in the
+            <span class="emphasis"><em>Console</em></span> interface.
+          </p><p>
+            It is important to realize that the <span class="emphasis"><em>methodResponse</em></span>
+            function may be invoked before the asynchronous call returns.
+            Make sure your code is written to handle this possibility.
+          </p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="QMFPythonConsoleTutorial-DiscoveringwhatKindsofObjectsareAvailable"></a>2.3.4.&#160;
+            Discovering what Kinds of Objects are Available
+          </h3></div></div></div><p /></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch02s02.html">Prev</a>&#160;</td><td align="center" width="20%"><a accesskey="u" href="chapter-Managing-CPP-Broker.html">Up</a></td><td align="right" width="40%">&#160;</td></tr><tr><td align="left" valign="top" width="40%">2.2.&#160;
+      Qpid Management Framework
+    &#160;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%">&#160;</td></tr></table></div></div>
\ No newline at end of file



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message