You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by jr...@apache.org on 2016/09/06 16:59:35 UTC
[12/51] [partial] qpid-site git commit: QPID-7353: Update for the
Qpid C++ 1.35.0 release
http://git-wip-us.apache.org/repos/asf/qpid-site/blob/eff0fe55/input/releases/qpid-cpp-1.35.0/cpp-broker/book/ch02s02.html.in
----------------------------------------------------------------------
diff --git a/input/releases/qpid-cpp-1.35.0/cpp-broker/book/ch02s02.html.in b/input/releases/qpid-cpp-1.35.0/cpp-broker/book/ch02s02.html.in
new file mode 100644
index 0000000..e0c0cb7
--- /dev/null
+++ b/input/releases/qpid-cpp-1.35.0/cpp-broker/book/ch02s02.html.in
@@ -0,0 +1,586 @@
+<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">2.2. 
+ Qpid Management Framework
+ </th></tr><tr><td align="left" width="20%"><a accesskey="p" href="chapter-Managing-CPP-Broker.html">Prev</a> </td><th align="center" width="60%">Chapter 2. 
+ Managing the AMQP Messaging Broker
+ </th><td align="right" width="20%"> <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="idm140173358554528"></a>2.2. 
+ 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.  What Is QMF">Section 2.2.1, “
+ What Is QMF
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="ch02s02.html#QpidManagementFramework-GettingStartedwithQMF" title="2.2.2.  Getting Started with QMF">Section 2.2.2, “
+ Getting
+ Started with QMF
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="ch02s02.html#QpidManagementFramework-QMFConcepts" title="2.2.3.  QMF Concepts">Section 2.2.3, “
+ QMF Concepts
+ ”</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.  Console, Agent, and Broker">Section 2.2.3.1, “
+ Console,
+ Agent, and Broker
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="ch02s02.html#QpidManagementFramework-Schema" title="2.2.3.2.  Schema">Section 2.2.3.2, “
+ Schema
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="ch02s02.html#QpidManagementFramework-ClassKeysandClassVersioning" title="2.2.3.3.  Class Keys and Class Versioning">Section 2.2.3.3, “
+ Class
+ Keys and Class Versioning
+ ”</a>
+ </p></li></ul></div><p>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="ch02s02.html#QpidManagementFramework-TheQMFProtocol" title="2.2.4.  The QMF Protocol">Section 2.2.4, “
+ The QMF
+ Protocol
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="ch02s02.html#QpidManagementFramework-HowtoWriteaQMFConsole" title="2.2.5.  How to Write a QMF Console">Section 2.2.5, “
+ How
+ to Write a QMF Console
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="ch02s02.html#QpidManagementFramework-HowtoWriteaQMFAgent" title="2.2.6.  How to Write a QMF Agent">Section 2.2.6, “
+ How to
+ Write a QMF Agent
+ ”</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. 
+ 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. 
+ 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. 
+ 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. 
+ 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. 
+ 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
+ <schema> tag. For example:
+ </p><pre class="programlisting">
+<schema package="org.apache.qpid.broker">
+
+</schema>
+</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 <class> tag. An object class is
+ composed of properties, statistics, and methods.
+ </p><pre class="programlisting">
+ <class name="Exchange">
+ <property name="vhostRef" type="objId" references="Vhost" access="RC" index="y" parentRef="y"/>
+ <property name="name" type="sstr" access="RC" index="y"/>
+ <property name="type" type="sstr" access="RO"/>
+ <property name="durable" type="bool" access="RC"/>
+ <property name="arguments" type="map" access="RO" desc="Arguments supplied in exchange.declare"/>
+
+ <statistic name="producerCount" type="hilo32" desc="Current producers on exchange"/>
+ <statistic name="bindingCount" type="hilo32" desc="Current bindings"/>
+ <statistic name="msgReceives" type="count64" desc="Total messages received"/>
+ <statistic name="msgDrops" type="count64" desc="Total messages dropped (no matching key)"/>
+ <statistic name="msgRoutes" type="count64" desc="Total routed messages"/>
+ <statistic name="byteReceives" type="count64" desc="Total bytes received"/>
+ <statistic name="byteDrops" type="count64" desc="Total bytes dropped (no matching key)"/>
+ <statistic name="byteRoutes" type="count64" desc="Total routed bytes"/>
+ </class>
+</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>
+ <property> and <statistic> tags must be placed within
+ <schema> and </schema> 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 <property> and <statistic> have
+ the following XML-attributes:
+ </p><div class="table"><a id="idm140173358965968"></a><p class="title"><strong>Table 2.1. 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>
+ <property>
+ </td><td>
+ <statistic>
+ </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>
+  
+ </td><td>
+ If the type is "objId", names the referenced class
+ </td></tr><tr><td>
+ access
+ </td><td>
+ Y
+ </td><td>
+  
+ </td><td>
+ Access rights (RC, RW, RO)
+ </td></tr><tr><td>
+ index
+ </td><td>
+ Y
+ </td><td>
+  
+ </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>
+  
+ </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>
+  
+ </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>
+  
+ </td><td>
+ Minimum value of a numeric attribute
+ </td></tr><tr><td>
+ max
+ </td><td>
+ Y
+ </td><td>
+  
+ </td><td>
+ Maximum value of a numeric attribute
+ </td></tr><tr><td>
+ maxLen
+ </td><td>
+ Y
+ </td><td>
+  
+ </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>
+ <method> tags must be placed within <schema> and
+ </schema> 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
+ <method> tag has a name, an optional description, and
+ encloses zero or more arguments. Method arguments are defined by
+ the <arg> 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">
+ <method name="echo" desc="Request a response to test the path to the management broker">
+ <arg name="sequence" dir="IO" type="uint32"/>
+ <arg name="body" dir="IO" type="lstr"/>
+ </method>
+</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="idm140173355554944"></a><p class="title"><strong>Table 2.2. 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="idm140173353645952"></a><p class="title"><strong>Table 2.3. 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>
+  
+ </td></tr><tr><td>
+ uint8,16,32,64
+ </td><td>
+ U8,16,32,64
+ </td><td>
+ Direct (get, set)
+ </td><td>
+  
+ </td></tr><tr><td>
+ int8,16,32,64
+ </td><td>
+ S8,16,32,64
+ </td><td>
+ Direct (get, set)
+ </td><td>
+  
+ </td></tr><tr><td>
+ bool
+ </td><td>
+ BOOL
+ </td><td>
+ Direct (get, set)
+ </td><td>
+  
+ </td></tr><tr><td>
+ sstr
+ </td><td>
+ SSTR
+ </td><td>
+ Direct (get, set)
+ </td><td>
+  
+ </td></tr><tr><td>
+ lstr
+ </td><td>
+ LSTR
+ </td><td>
+ Direct (get, set)
+ </td><td>
+  
+ </td></tr><tr><td>
+ absTime
+ </td><td>
+ ABSTIME
+ </td><td>
+ Direct (get, set)
+ </td><td>
+  
+ </td></tr><tr><td>
+ deltaTime
+ </td><td>
+ DELTATIME
+ </td><td>
+ Direct (get, set)
+ </td><td>
+  
+ </td></tr><tr><td>
+ float
+ </td><td>
+ FLOAT
+ </td><td>
+ Direct (get, set)
+ </td><td>
+  
+ </td></tr><tr><td>
+ double
+ </td><td>
+ DOUBLE
+ </td><td>
+ Direct (get, set)
+ </td><td>
+  
+ </td></tr><tr><td>
+ uuid
+ </td><td>
+ UUID
+ </td><td>
+ Direct (get, set)
+ </td><td>
+  
+ </td></tr><tr><td>
+ map
+ </td><td>
+ FTABLE
+ </td><td>
+ Direct (get, set)
+ </td><td>
+  
+ </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>
+  
+ </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
+ <property> or <arg> must be types that have
+ <span class="emphasis"><em>Direct</em></span> accessor style. Any type may be used in
+ <statistic> 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. 
+ 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. 
+ 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. 
+ 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. 
+ 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> </td><td align="center" width="20%"><a accesskey="u" href="chapter-Managing-CPP-Broker.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="ch02s03.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">Chapter 2. 
+ Managing the AMQP Messaging Broker
+  </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%"> 2.3. 
+ QMF Python Console Tutorial
+ </td></tr></table></div></div>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/qpid-site/blob/eff0fe55/input/releases/qpid-cpp-1.35.0/cpp-broker/book/ch02s03.html.in
----------------------------------------------------------------------
diff --git a/input/releases/qpid-cpp-1.35.0/cpp-broker/book/ch02s03.html.in b/input/releases/qpid-cpp-1.35.0/cpp-broker/book/ch02s03.html.in
new file mode 100644
index 0000000..1ea5dbe
--- /dev/null
+++ b/input/releases/qpid-cpp-1.35.0/cpp-broker/book/ch02s03.html.in
@@ -0,0 +1,704 @@
+<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">2.3. 
+ QMF Python Console Tutorial
+ </th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch02s02.html">Prev</a> </td><th align="center" width="60%">Chapter 2. 
+ Managing the AMQP Messaging Broker
+ </th><td align="right" width="20%"> </td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="idm140173356666272"></a>2.3. 
+ 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.  Prerequisite - Install Qpid Messaging">Section 2.3.1, “
+ Prerequisite
+ - Install Qpid Messaging
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-SynchronousConsoleOperations" title="2.3.2.  Synchronous Console Operations">Section 2.3.2, “
+ Synchronous
+ Console Operations
+ ”</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.  Creating a QMF Console Session and Attaching to a Broker">Section 2.3.2.1, “
+ Creating a QMF Console Session and Attaching to a Broker
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-AccessingManagedObjects" title="2.3.2.2.  Accessing Managed Objects">Section 2.3.2.2, “
+ Accessing
+ Managed Objects
+ ”</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 “
+ Viewing Properties and Statistics of an Object
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-InvokingMethodsonanObject" title="Invoking Methods on an Object">the section called “
+ Invoking
+ Methods on an Object
+ ”</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.  Asynchronous Console Operations">Section 2.3.3, “
+ Asynchronous
+ Console Operations
+ ”</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.  Creating a Console Class to Receive Asynchronous Data">Section 2.3.3.1, “
+ Creating a Console Class to Receive Asynchronous Data
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-ReceivingEvents" title="2.3.3.2.  Receiving Events">Section 2.3.3.2, “
+ Receiving
+ Events
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-ReceivingObjects" title="2.3.3.3.  Receiving Objects">Section 2.3.3.3, “
+ Receiving
+ Objects
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-AsynchronousMethodCallsandMethodTimeouts" title="2.3.3.4.  Asynchronous Method Calls and Method Timeouts">Section 2.3.3.4, “
+ Asynchronous Method Calls and Method Timeouts
+ ”</a>
+ </p></li></ul></div><p>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="ch02s03.html#QMFPythonConsoleTutorial-DiscoveringwhatKindsofObjectsareAvailable" title="2.3.4.  Discovering what Kinds of Objects are Available">Section 2.3.4, “
+ Discovering what Kinds of Objects are Available
+ ”</a>
+ </p></li></ul></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="QMFPythonConsoleTutorial-PrerequisiteInstallQpidMessaging"></a>2.3.1. 
+ 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. 
+ 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. 
+ 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.
+>>>
+</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">
+>>> 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">
+>>> 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">
+>>> 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">
+>>> 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">
+>>> try:
+... broker = sess.addBroker("amqp://localhost:1000")
+... except:
+... print "Connection Failed"
+...
+Connection Failed
+>>>
+</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. 
+ 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">
+>>> 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">
+>>> 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
+>>>
+</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">
+>>> 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">
+>>> props = queue.getProperties()
+>>> 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, {})
+>>>
+</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">
+>>> queue.autoDelete
+True
+>>> queue.name
+u'reply-localhost.localdomain.32004'
+>>>
+</pre><p>
+ Statistics are accessed in the same way:
+ </p><pre class="programlisting">
+>>> stats = queue.getStatistics()
+>>> 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)
+>>>
+</pre><p>
+ or alternatively:
+ </p><pre class="programlisting">
+>>> queue.byteTotalEnqueues
+19116
+>>>
+</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">
+>>> queue.update()
+>>> queue.byteTotalEnqueues
+19783
+>>>
+</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">
+>>> 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">
+>>> print methodList
+[purge(request)]
+>>>
+</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">
+>>> br = sess.getObjects(_class="broker", _package="org.apache.qpid.broker")[0]
+>>> mlist = br.getMethods()
+>>> for m in mlist:
+... print m
+...
+echo(sequence, body)
+connect(host, port, durable, authMechanism, username, password, transport)
+queueMoveMessages(srcQueue, destQueue, qty)
+>>>
+</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">
+>>> result = br.echo(1, "Message Body")
+>>> print result
+OK (0) - {'body': u'Message Body', 'sequence': 1}
+>>> print result.status
+0
+>>> print result.text
+OK
+>>> print result.outArgs
+{'body': u'Message Body', 'sequence': 1}
+>>>
+</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. 
+ 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. 
+ 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="idm140173354776496"></a><p class="title"><strong>Table 2.4. 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. 
+ 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">
+>>> 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">
+>>> 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
+...
+>>>
+</pre><p>
+ Make an instance of the new class:
+ </p><pre class="programlisting">
+>>> 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">
+>>> sess = Session(myConsole, manageConnections=True, rcvObjects=False, rcvHeartbeats=False)
+>>> broker = sess.addBroker()
+>>>
+</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. 
+ 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] > 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] > 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. 
+ 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. 
+ 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> </td><td align="center" width="20%"><a accesskey="u" href="chapter-Managing-CPP-Broker.html">Up</a></td><td align="right" width="40%"> </td></tr><tr><td align="left" valign="top" width="40%">2.2. 
+ Qpid Management Framework
+  </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%"> </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