Added: qpid/site/docs/books/0.7/Qpid-Book/html/ch06s03.html URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.7/Qpid-Book/html/ch06s03.html?rev=956304&view=auto ============================================================================== --- qpid/site/docs/books/0.7/Qpid-Book/html/ch06s03.html (added) +++ qpid/site/docs/books/0.7/Qpid-Book/html/ch06s03.html Sat Jun 19 22:15:03 2010 @@ -0,0 +1,586 @@ +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>3. Qpid Management Framework</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="Apache Qpid"><link rel="up" href="ch06.html" title="Chapter 6. Managing the AMQP Messaging Broker"><link rel="prev" href="ch06s02.html" title="2. QMan - Qpid Management bridge"><link rel="next" href="ch06s04.html" title="4. Management Design notes"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3. + Qpid Management Framework + </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch06s02.html">Prev</a> </td><th width="60%" align="center">Chapter 6. + Managing the AMQP Messaging Broker + </th><td width="20%" align="right"> <a accesskey="n" href="ch06s04.html">Next</a></td></tr></table><hr></div><div class="section" title="3. Qpid Management Framework"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2976372"></a>3. + Qpid Management Framework + </h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + <a class="xref" href="ch06s03.html#QpidManagementFramework-WhatIsQMF" title="3.1. What Is QMF">Section 3.1, “ + What Is QMF + ”</a> + </p></li><li class="listitem"><p> + <a class="xref" href="ch06s03.html#QpidManagementFramework-GettingStartedwithQMF" title="3.2. Getting Started with QMF">Section 3.2, “ + Getting + Started with QMF + ”</a> + </p></li><li class="listitem"><p> + <a class="xref" href="ch06s03.html#QpidManagementFramework-QMFConcepts" title="3.3. QMF Concepts">Section 3.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="ch06s03.html#QpidManagementFramework-Console-2CAgent-2CandBroker" title="3.3.1. Console, Agent, and Broker">Section 3.3.1, “ + Console, + Agent, and Broker + ”</a> + </p></li><li class="listitem"><p> + <a class="xref" href="ch06s03.html#QpidManagementFramework-Schema" title="3.3.2. Schema">Section 3.3.2, “ + Schema + ”</a> + </p></li><li class="listitem"><p> + <a class="xref" href="ch06s03.html#QpidManagementFramework-ClassKeysandClassVersioning" title="3.3.3. Class Keys and Class Versioning">Section 3.3.3, “ + Class + Keys and Class Versioning + ”</a> + </p></li></ul></div><p> + </p></li><li class="listitem"><p> + <a class="xref" href="ch06s03.html#QpidManagementFramework-TheQMFProtocol" title="3.4. The QMF Protocol">Section 3.4, “ + The QMF + Protocol + ”</a> + </p></li><li class="listitem"><p> + <a class="xref" href="ch06s03.html#QpidManagementFramework-HowtoWriteaQMFConsole" title="3.5. How to Write a QMF Console">Section 3.5, “ + How + to Write a QMF Console + ”</a> + </p></li><li class="listitem"><p> + <a class="xref" href="ch06s03.html#QpidManagementFramework-HowtoWriteaQMFAgent" title="3.6. How to Write a QMF Agent">Section 3.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" title="3.1. What Is QMF"><div class="titlepage"><div><div><h3 class="title"><a name="QpidManagementFramework-WhatIsQMF"></a>3.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" title="3.2. Getting Started with QMF"><div class="titlepage"><div><div><h3 class="title"><a name="QpidManagementFramework-GettingStartedwithQMF"></a>3.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" title="3.3. QMF Concepts"><div class="titlepage"><div><div><h3 class="title"><a name="QpidManagementFramework-QMFConcepts"></a>3.3. + QMF Concepts + </h3></div></div></div><p> + This section introduces important concepts underlying QMF. + </p><div class="section" title="3.3.1. Console, Agent, and Broker"><div class="titlepage"><div><div><h4 class="title"><a name="QpidManagementFramework-Console-2CAgent-2CandBroker"></a>3.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" title="3.3.2. Schema"><div class="titlepage"><div><div><h4 class="title"><a name="QpidManagementFramework-Schema"></a>3.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" title="3.3.2.1. Package"><div class="titlepage"><div><div><h5 class="title"><a name="QpidManagementFramework-Package"></a>3.3.2.1. + 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" title="3.3.2.2. Object Classes"><div class="titlepage"><div><div><h5 class="title"><a name="QpidManagementFramework-ObjectClasses"></a>3.3.2.2. + 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" title="3.3.2.3. Properties and Statistics"><div class="titlepage"><div><div><h5 class="title"><a name="QpidManagementFramework-PropertiesandStatistics"></a>3.3.2.3. + 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 name="id3001056"></a><p class="title"><b>Table 6.3. XML Attributes for QMF Properties and Statistics</b></p><div class="table-contents"><table summary="XML Attributes for QMF Properties and Statistics" border="1"><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" title="3.3.2.4. Methods"><div class="titlepage"><div><div><h5 class="title"><a name="QpidManagementFramework-Methods"></a>3.3.2.4. + 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" title="3.3.2.5. Event Classes"><div class="titlepage"><div><div><h5 class="title"><a name="QpidManagementFramework-EventClasses"></a>3.3.2.5. + Event Classes + </h5></div></div></div><p></p></div><div class="section" title="3.3.2.6. Data Types"><div class="titlepage"><div><div><h5 class="title"><a name="QpidManagementFramework-DataTypes"></a>3.3.2.6. + 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 name="id3001438"></a><p class="title"><b>Table 6.4. QMF Datatypes</b></p><div class="table-contents"><table summary="QMF Datatypes" border="1"><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 name="id2981888"></a><p class="title"><b>Table 6.5. XML Schema Mapping for QMF Types</b></p><div class="table-contents"><table summary="XML Schema Mapping for QMF Types" border="1"><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" title="Important" 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" title="3.3.3. Class Keys and Class Versioning"><div class="titlepage"><div><div><h4 class="title"><a name="QpidManagementFramework-ClassKeysandClassVersioning"></a>3.3.3. + Class + Keys and Class Versioning + </h4></div></div></div><p></p></div></div><div class="section" title="3.4. The QMF Protocol"><div class="titlepage"><div><div><h3 class="title"><a name="QpidManagementFramework-TheQMFProtocol"></a>3.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" title="3.5. How to Write a QMF Console"><div class="titlepage"><div><div><h3 class="title"><a name="QpidManagementFramework-HowtoWriteaQMFConsole"></a>3.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" title="3.6. How to Write a QMF Agent"><div class="titlepage"><div><div><h3 class="title"><a name="QpidManagementFramework-HowtoWriteaQMFAgent"></a>3.6. + How to + Write a QMF Agent + </h3></div></div></div><p></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch06s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch06.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch06s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2. + QMan - Qpid Management bridge + </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 4. + Management Design notes + </td></tr></table></div></body></html>
--------------------------------------------------------------------- Apache Qpid - AMQP Messaging Implementation Project: http://qpid.apache.org Use/Interact: mailto:commits-subscr...@qpid.apache.org
