http://git-wip-us.apache.org/repos/asf/qpid-site/blob/c3ab60f6/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch02s02.html.in ---------------------------------------------------------------------- diff --git a/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch02s02.html.in b/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch02s02.html.in new file mode 100644 index 0000000..ac2c39e --- /dev/null +++ b/input/releases/qpid-cpp-1.39.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="idm140333888730320"></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="idm140333888351904"></a><p class="title"><strong>Table 2.1. XML Attributes for QMF Properties and Statistics</strong></p><div class="table-contents"><table border="1" class="table" 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="idm140333888279792"></a><p class="title"><strong>Table 2.2. QMF Datatypes</strong></p><div class="table-contents"><table border="1" class="table" 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="idm140333892269424"></a><p class="title"><strong>Table 2.3. XML Schema Mapping for QMF Types</strong></p><div class="table-contents"><table border="1" class="table" 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/c3ab60f6/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch02s03.html.in ---------------------------------------------------------------------- diff --git a/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch02s03.html.in b/input/releases/qpid-cpp-1.39.0/cpp-broker/book/ch02s03.html.in new file mode 100644 index 0000000..f0fa600 --- /dev/null +++ b/input/releases/qpid-cpp-1.39.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="idm140333892842608"></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="idm140333887861504"></a><p class="title"><strong>Table 2.4. QMF Python Console Class Methods</strong></p><div class="table-contents"><table border="1" class="table" 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: [email protected] For additional commands, e-mail: [email protected]
