You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by jo...@apache.org on 2010/01/12 15:05:44 UTC
svn commit: r898329 [4/5] - /qpid/trunk/qpid/doc/book/src/
Added: qpid/trunk/qpid/doc/book/src/QMF Python Console Tutorial.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/QMF%20Python%20Console%20Tutorial.xml?rev=898329&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/QMF Python Console Tutorial.xml (added)
+++ qpid/trunk/qpid/doc/book/src/QMF Python Console Tutorial.xml Tue Jan 12 14:05:42 2010
@@ -0,0 +1,873 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns:html="http://www.w3.org/1999/xhtml"><title>
+ Apache Qpid : QMF Python Console Tutorial
+ </title>
+ <itemizedlist>
+ <listitem><para>
+ <xref linkend="QMFPythonConsoleTutorial-PrerequisiteInstallQpidMessaging"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QMFPythonConsoleTutorial-SynchronousConsoleOperations"/>
+ </para></listitem>
+ <listitem><para>
+ <itemizedlist>
+ <listitem><para>
+ <xref linkend="QMFPythonConsoleTutorial-CreatingaQMFConsoleSessionandAttachingtoaBroker"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QMFPythonConsoleTutorial-AccessingManagedObjects"/>
+ </para></listitem>
+ <listitem><para>
+ <itemizedlist>
+ <listitem><para>
+ <xref linkend="QMFPythonConsoleTutorial-ViewingPropertiesandStatisticsofanObject"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QMFPythonConsoleTutorial-InvokingMethodsonanObject"/>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QMFPythonConsoleTutorial-AsynchronousConsoleOperations"/>
+ </para></listitem>
+ <listitem><para>
+ <itemizedlist>
+ <listitem><para>
+ <xref linkend="QMFPythonConsoleTutorial-CreatingaConsoleClasstoReceiveAsynchronousData"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QMFPythonConsoleTutorial-ReceivingEvents"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QMFPythonConsoleTutorial-ReceivingObjects"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QMFPythonConsoleTutorial-AsynchronousMethodCallsandMethodTimeouts"/>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QMFPythonConsoleTutorial-DiscoveringwhatKindsofObjectsareAvailable"/>
+ </para></listitem>
+ </itemizedlist>
+ <section role="h1" id="QMFPythonConsoleTutorial-PrerequisiteInstallQpidMessaging"><title>
+ Prerequisite
+ - Install Qpid Messaging
+ </title>
+
+ <para>
+ 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
+ <xref linkend="qpid_Download"/> for
+ information as to where to get Qpid Messaging.
+ </para><para>
+ 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.
+ </para><para>
+ 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.
+ </para><para>
+ 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.
+ </para>
+<!--h1--></section>
+
+ <section role="h1" id="QMFPythonConsoleTutorial-SynchronousConsoleOperations"><title>
+ Synchronous
+ Console Operations
+ </title>
+
+ <para>
+ 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.
+ </para><section role="h2" id="QMFPythonConsoleTutorial-CreatingaQMFConsoleSessionandAttachingtoaBroker"><title>
+ Creating a QMF Console Session and Attaching to a Broker
+ </title>
+
+ <para>
+ For the purposes of this tutorial, code examples will be shown as
+ they are entered in an interactive python session.
+ </para>
+ <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.
+>>>
+</programlisting>
+ <para>
+ 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.
+ </para>
+ <programlisting>
+>>> from qmf.console import Session
+</programlisting>
+ <para>
+ We must now create a <emphasis>Session</emphasis> object to manage this QMF
+ console session.
+ </para>
+ <programlisting>
+>>> sess = Session()
+</programlisting>
+ <para>
+ If no arguments are supplied to the creation of <emphasis>Session</emphasis>,
+ it defaults to synchronous-only operation. It also defaults to
+ user-management of connections. More on this in a moment.
+ </para><para>
+ We will now establish a connection to the messaging broker. If
+ the broker daemon is running on the local host, simply use the
+ following:
+ </para>
+ <programlisting>
+>>> broker = sess.addBroker()
+</programlisting>
+ <para>
+ If the messaging broker is on a remote host, supply the URL to
+ the broker in the <emphasis>addBroker</emphasis> function call. Here's how to
+ connect to a local broker using the URL.
+ </para>
+ <programlisting>
+>>> broker = sess.addBroker("amqp://localhost")
+</programlisting>
+ <para>
+ The call to <emphasis>addBroker</emphasis> is synchronous and will return
+ only after the connection has been successfully established or
+ has failed. If a failure occurs, <emphasis>addBroker</emphasis> will raise an
+ exception that can be handled by the console script.
+ </para>
+ <programlisting>
+>>> try:
+... broker = sess.addBroker("amqp://localhost:1000")
+... except:
+... print "Connection Failed"
+...
+Connection Failed
+>>>
+</programlisting>
+ <para>
+ This operation fails because there is no Qpid Messaging broker
+ listening on port 1000 (the default port for qpidd is 5672).
+ </para><para>
+ If preferred, the QMF session can manage the connection for you.
+ In this case, <emphasis>addBroker</emphasis> 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.
+ </para>
+<!--h2--></section>
+
+ <section role="h2" id="QMFPythonConsoleTutorial-AccessingManagedObjects"><title>
+ Accessing
+ Managed Objects
+ </title>
+
+ <para>
+ The Python console API provides access to remotely managed
+ objects via a <emphasis>proxy</emphasis> 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.
+ </para><para>
+ 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.
+ </para><para>
+ Proxy objects are obtained by calling the
+ <emphasis>Session.getObjects</emphasis> function.
+ </para><para>
+ To illustrate, we'll get a list of objects representing queues in
+ the message broker itself.
+ </para>
+ <programlisting>
+>>> queues = sess.getObjects(_class="queue", _package="org.apache.qpid.broker")
+</programlisting>
+ <para>
+ <emphasis>queues</emphasis> 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.
+ </para>
+ <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
+>>>
+</programlisting>
+ <section role="h3" id="QMFPythonConsoleTutorial-ViewingPropertiesandStatisticsofanObject"><title>
+ Viewing Properties and Statistics of an Object
+ </title>
+
+ <para>
+ Let us now focus our attention on one of the queue objects.
+ </para>
+ <programlisting>
+>>> queue = queues[0]
+</programlisting>
+ <para>
+ The attributes of an object are partitioned into
+ <emphasis>properties</emphasis> and <emphasis>statistics</emphasis>. Though the
+ distinction is somewhat arbitrary, <emphasis>properties</emphasis> tend to
+ be fairly static and may also be large and <emphasis>statistics</emphasis>
+ tend to change rapidly and are relatively small (counters, etc.).
+ </para><para>
+ There are two ways to view the properties of an object. An array
+ of properties can be obtained using the <emphasis>getProperties</emphasis>
+ function:
+ </para>
+ <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, {})
+>>>
+</programlisting>
+ <para>
+ The <emphasis>getProperties</emphasis> function returns an array of tuples.
+ Each tuple consists of the property descriptor and the property
+ value.
+ </para><para>
+ A more convenient way to access properties is by using the
+ attribute of the proxy object directly:
+ </para>
+ <programlisting>
+>>> queue.autoDelete
+True
+>>> queue.name
+u'reply-localhost.localdomain.32004'
+>>>
+</programlisting>
+ <para>
+ Statistics are accessed in the same way:
+ </para>
+ <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)
+>>>
+</programlisting>
+ <para>
+ or alternatively:
+ </para>
+ <programlisting>
+>>> queue.byteTotalEnqueues
+19116
+>>>
+</programlisting>
+ <para>
+ 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 <emphasis>byteTotalEnqueues</emphasis> statistic will show
+ the same number as it did the first time. To get updated data on
+ a proxy object, use the <emphasis>update</emphasis> function call:
+ </para>
+ <programlisting>
+>>> queue.update()
+>>> queue.byteTotalEnqueues
+19783
+>>>
+</programlisting>
+
+ <note><title>Be Advised</title>
+ <para>
+ The <emphasis>update</emphasis> method was added after the M4 release
+ of Qpid/Qmf. It may not be available in your
+ distribution.
+ </para>
+ </note>
+<!--h3--></section>
+
+ <section role="h3" id="QMFPythonConsoleTutorial-InvokingMethodsonanObject"><title>
+ Invoking
+ Methods on an Object
+ </title>
+
+ <para>
+ 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.
+ </para><para>
+ First, we'll cover some background information about methods. A
+ <emphasis>QMF object class</emphasis> (of which a <emphasis>QMF object</emphasis> is an
+ instance), may have zero or more methods. To obtain a list of
+ methods available for an object, use the <emphasis>getMethods</emphasis>
+ function.
+ </para>
+ <programlisting>
+>>> methodList = queue.getMethods()
+</programlisting>
+ <para>
+ <emphasis>getMethods</emphasis> returns an array of method descriptors (of
+ type qmf.console.SchemaMethod). To get a summary of a method, you
+ can simply print it. The _<emphasis>repr</emphasis>_ function returns a
+ string that looks like a function prototype.
+ </para>
+ <programlisting>
+>>> print methodList
+[purge(request)]
+>>>
+</programlisting>
+ <para>
+ For the purposes of illustration, we'll use a more interesting
+ method available on the <emphasis>broker</emphasis> object which represents
+ the connected Qpid message broker.
+ </para>
+ <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)
+>>>
+</programlisting>
+ <para>
+ We have just learned that the <emphasis>broker</emphasis> object has three
+ methods: <emphasis>echo</emphasis>, <emphasis>connect</emphasis>, and
+ <emphasis>queueMoveMessages</emphasis>. We'll use the <emphasis>echo</emphasis> method to
+ "ping" the broker.
+ </para>
+ <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}
+>>>
+</programlisting>
+ <para>
+ In the above example, we have invoked the <emphasis>echo</emphasis> 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).
+ </para><para>
+ To be more precise... Calling <emphasis>echo</emphasis> 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.
+ </para><para>
+ 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.
+ </para>
+<!--h3--></section>
+<!--h2--></section>
+<!--h1--></section>
+
+ <section role="h1" id="QMFPythonConsoleTutorial-AsynchronousConsoleOperations"><title>
+ Asynchronous
+ Console Operations
+ </title>
+
+ <para>
+ 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
+ <emphasis>Publication and Subscription</emphasis> pattern (pub-sub for
+ short). In the pub-sub pattern, data sources <emphasis>publish</emphasis>
+ information without a particular destination in mind. Data sinks
+ (destinations) <emphasis>subscribe</emphasis> 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.
+ </para><para>
+ 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.
+ </para><para>
+ Note that console applications may always use the synchronous
+ mechanisms.
+ </para>
+
+ <section role="h2" id="QMFPythonConsoleTutorial-CreatingaConsoleClasstoReceiveAsynchronousData"><title>
+ Creating a Console Class to Receive Asynchronous Data
+ </title>
+
+ <para>
+ Asynchronous API operation occurs when the console application
+ supplies a <emphasis>Console</emphasis> object to the session manager. The
+ <emphasis>Console</emphasis> object (which overrides the
+ <emphasis>qmf.console.Console</emphasis> class) handles all asynchronously
+ arriving data. The <emphasis>Console</emphasis> 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.
+ </para><table><title/><tgroup cols="3">
+ <tbody>
+ <row>
+ <entry>
+ Method
+ </entry>
+ <entry>
+ Arguments
+ </entry>
+ <entry>
+ Invoked when...
+ </entry>
+ </row>
+ <row>
+ <entry>
+ brokerConnected
+ </entry>
+ <entry>
+ broker
+ </entry>
+ <entry>
+ a connection to a broker is established
+ </entry>
+ </row>
+ <row>
+ <entry>
+ brokerDisconnected
+ </entry>
+ <entry>
+ broker
+ </entry>
+ <entry>
+ a connection to a broker is lost
+ </entry>
+ </row>
+ <row>
+ <entry>
+ newPackage
+ </entry>
+ <entry>
+ name
+ </entry>
+ <entry>
+ a new package is seen on the QMF bus
+ </entry>
+ </row>
+ <row>
+ <entry>
+ newClass
+ </entry>
+ <entry>
+ kind, classKey
+ </entry>
+ <entry>
+ a new class (event or object) is seen on the QMF bus
+ </entry>
+ </row>
+ <row>
+ <entry>
+ newAgent
+ </entry>
+ <entry>
+ agent
+ </entry>
+ <entry>
+ a new agent appears on the QMF bus
+ </entry>
+ </row>
+ <row>
+ <entry>
+ delAgent
+ </entry>
+ <entry>
+ agent
+ </entry>
+ <entry>
+ an agent disconnects from the QMF bus
+ </entry>
+ </row>
+ <row>
+ <entry>
+ objectProps
+ </entry>
+ <entry>
+ broker, object
+ </entry>
+ <entry>
+ the properties of an object are published
+ </entry>
+ </row>
+ <row>
+ <entry>
+ objectStats
+ </entry>
+ <entry>
+ broker, object
+ </entry>
+ <entry>
+ the statistics of an object are published
+ </entry>
+ </row>
+ <row>
+ <entry>
+ event
+ </entry>
+ <entry>
+ broker, event
+ </entry>
+ <entry>
+ an event is published
+ </entry>
+ </row>
+ <row>
+ <entry>
+ heartbeat
+ </entry>
+ <entry>
+ agent, timestamp
+ </entry>
+ <entry>
+ a heartbeat is published by an agent
+ </entry>
+ </row>
+ <row>
+ <entry>
+ brokerInfo
+ </entry>
+ <entry>
+ broker
+ </entry>
+ <entry>
+ information about a connected broker is available to be
+ queried
+ </entry>
+ </row>
+ <row>
+ <entry>
+ methodResponse
+ </entry>
+ <entry>
+ broker, seq, response
+ </entry>
+ <entry>
+ the result of an asynchronous method call is received
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table><para>
+ Supplied with the API is a class called <emphasis>DebugConsole</emphasis>.
+ This is a test <emphasis>Console</emphasis> 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.
+ </para>
+ <!--h2--></section>
+
+ <section role="h2" id="QMFPythonConsoleTutorial-ReceivingEvents"><title>
+ Receiving
+ Events
+ </title>
+
+ <para>
+ We'll start the example from the beginning to illustrate the
+ reception and handling of events. In this example, we will create
+ a <emphasis>Console</emphasis> class that handles broker-connect,
+ broker-disconnect, and event messages. We will also allow the
+ session manager to manage the broker connection for us.
+ </para><para>
+ Begin by importing the necessary classes:
+ </para>
+ <programlisting>
+>>> from qmf.console import Session, Console
+</programlisting>
+ <para>
+ Now, create a subclass of <emphasis>Console</emphasis> that handles the three
+ message types:
+ </para>
+ <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
+...
+>>>
+</programlisting>
+ <para>
+ Make an instance of the new class:
+ </para>
+ <programlisting>
+>>> myConsole = EventConsole()
+</programlisting>
+ <para>
+ Create a <emphasis>Session</emphasis> 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.
+ </para>
+ <programlisting>
+>>> sess = Session(myConsole, manageConnections=True, rcvObjects=False, rcvHeartbeats=False)
+>>> broker = sess.addBroker()
+>>>
+</programlisting>
+ <para>
+ Once the broker is added, we will begin to receive asynchronous
+ events (assuming there is a functioning broker available to
+ connect to).
+ </para>
+ <programlisting>
+brokerConnected: Broker connected at: localhost:5672
+event: Thu Jan 29 19:53:19 2009 INFO org.apache.qpid.broker:bind broker=localhost:5672 ...
+</programlisting>
+<!--h2--></section>
+
+ <section role="h2" id="QMFPythonConsoleTutorial-ReceivingObjects"><title>
+ Receiving
+ Objects
+ </title>
+
+ <para>
+ 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.
+ </para><para>
+ This console program receives object updates and displays a set
+ of statistics as they change. It focuses on broker queue objects.
+ </para>
+ <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)
+</programlisting>
+ <para>
+ 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 <emphasis>getObjects</emphasis> 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.
+ </para><para>
+ 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 <emphasis>ObjectId</emphasis> that
+ uniquely identifies the object.
+ </para>
+ <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
+</programlisting>
+ <para>
+ 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.
+ </para>
+ <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)
+</programlisting>
+ <para>
+ This code fragment detects the deletion of a managed object.
+ After reporting the statistics, it checks the timestamps of the
+ proxy. <emphasis>getTimestamps</emphasis> returns a list of timestamps in the
+ order:
+ </para><itemizedlist>
+ <listitem><para>
+ <emphasis>Current</emphasis> - The timestamp of the sending of this update.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create</emphasis> - The time of the object's creation
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Delete</emphasis> - The time of the object's deletion (or zero if
+ not deleted)
+ </para></listitem>
+ </itemizedlist><para>
+ 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.
+ </para>
+ <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")
+</programlisting>
+ <para>
+ The above code is illustrative of the way a console application
+ can tune its use of the QMF bus. Note that <emphasis>rcvEvents</emphasis> is
+ set to False. This prevents the reception of events. Note also
+ the use of <emphasis>userBindings=True</emphasis> and the call to
+ <emphasis>sess.bindClass</emphasis>. If <emphasis>userBindings</emphasis> 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.
+ <emphasis>bindClass</emphasis> may be called as many times as desired to add
+ classes to the list of subscribed classes.
+ </para>
+<!--h2--></section>
+
+ <section role="h2" id="QMFPythonConsoleTutorial-AsynchronousMethodCallsandMethodTimeouts"><title>
+ Asynchronous Method Calls and Method Timeouts
+ </title>
+
+ <para>
+ 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.
+ </para><para>
+ Method calls are synchronous by default. They can be made
+ asynchronous by adding the keyword-argument _<emphasis>async=True</emphasis>
+ to the method call.
+ </para><para>
+ 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 <emphasis>methodResponse</emphasis> function in the
+ <emphasis>Console</emphasis> interface.
+ </para><para>
+ It is important to realize that the <emphasis>methodResponse</emphasis>
+ function may be invoked before the asynchronous call returns.
+ Make sure your code is written to handle this possibility.
+ </para>
+ <!--h2--></section>
+ <!--h1--></section>
+
+ <section role="h1" id="QMFPythonConsoleTutorial-DiscoveringwhatKindsofObjectsareAvailable"><title>
+ Discovering what Kinds of Objects are Available
+ </title>
+ <para/>
+ <!--h1--></section>
+
+
+</chapter>
Added: qpid/trunk/qpid/doc/book/src/QMan - Qpid Management bridge.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/QMan%20-%20Qpid%20Management%20bridge.xml?rev=898329&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/QMan - Qpid Management bridge.xml (added)
+++ qpid/trunk/qpid/doc/book/src/QMan - Qpid Management bridge.xml Tue Jan 12 14:05:42 2010
@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns:html="http://www.w3.org/1999/xhtml"><title>
+ Apache Qpid : QMan - Qpid Management bridge
+ </title><section role="h1" id="QMan-QpidManagementbridge-QMan-3AQpidManagementBridge"><title>
+ QMan
+ : Qpid Management Bridge
+ </title>
+ <para>
+ QMan is a management bridge for Qpid. It allows external clients
+ to manage and monitor one or more Qpid brokers.
+ </para>
+ <para>
+ Please note: All WS-DM related concerns have to be considered
+ part of M5 release.
+ </para><para>
+ QMan exposes the broker management interfaces using Java
+ Management Extensions (JMX) and / or OASIS Web Services
+ Distributed Management (WSDM). While the first one is supposed to
+ be used by java based clients only the latter is an interoperable
+ protocol that enables management clients to access and receive
+ notifications of management-enabled resources using Web Services.
+ </para><para>
+ QMan can be easily integrated in your preexisting system in
+ different ways :
+ </para><itemizedlist>
+ <listitem><para>As a standalone application : in this case it runs as a
+ server. More specifically it enables communication via RMI (for
+ JMX) or via HTTP (for WS-DM); Note that when the WS-DM adapter is
+ used the JMX interface is not exposed;
+ </para></listitem>
+ <listitem><para>As a deployable unit : it is also available as a standard
+ Java web application (war); This is useful when there's a
+ preexisting Application Server in your environment and you don't
+ want start another additional server in order to run QMan.
+ </para></listitem>
+ </itemizedlist>
+
+ <section role="h2" id="QMan-QpidManagementbridge-UserDocumentation"><title>
+ User
+ Documentation
+ </title>
+ <para>
+ With "User Documentation" we mean all information that you need
+ to know in order to use QMan from a user perspective. Those
+ information include :
+ </para><table><title/><tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ Section
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <xref linkend="qpid_Get-20me-20up-20and-20running"/>
+ </entry>
+ <entry>
+ How to install & start QMan.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <xref linkend="qpid_QMan-20User-20Guide"/>
+ </entry>
+ <entry>
+ QMan (WS-DM version only) Administration Console.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <xref linkend="qpid_JMX-20Interface-20Specification"/>
+ </entry>
+ <entry>
+ Describes each JMX interface exposed by QMan.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <xref linkend="qpid_WS-DM-20Interface-20Specification"/>
+ </entry>
+ <entry>
+ Describes each WS-DM interface exposed by QMan.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <xref linkend="qpid_QMan-20Messages-20Catalogue"/>
+ </entry>
+ <entry>
+ Informational / Debug / Error / Warning messages catalogue.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table>
+ <!--h2--></section>
+
+
+ <section role="h2" id="QMan-QpidManagementbridge-TechnicalDocumentation"><title>
+ Technical
+ Documentation
+ </title>
+ <para>
+ If you are interested in technical details about QMan and related
+ technologies this is a good starting point. In general this
+ section provides information about QMan design, interfaces,
+ patterns and so on...
+ </para>
+
+ <table><title/><tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ Section
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <xref linkend="qpid_QMan-20System-20Overview"/>
+ </entry>
+ <entry>
+ A short introduction about QMan deployment context.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <xref linkend="qpid_QMan-20Components-20View"/>
+ </entry>
+ <entry>
+ Describes QMan components, their interactions and
+ responsibilities.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table>
+
+<!--h2--></section>
+<!--h1--></section>
+
+</chapter>
Added: qpid/trunk/qpid/doc/book/src/Qpid ACLs.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/Qpid%20ACLs.xml?rev=898329&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/Qpid ACLs.xml (added)
+++ qpid/trunk/qpid/doc/book/src/Qpid ACLs.xml Tue Jan 12 14:05:42 2010
@@ -0,0 +1,20 @@
+<?xml version="1.0"?>
+<section><title>
+ ACL Formats
+ </title>Apache Qpid : Qpid ACLs
+ This page last changed on Nov 18, 2008 by ritchiem.
+ <para>
+ The Qpid project has two ACL implementations. An initial version
+ of ACLs was added to the Java Broker for M2.1 that uses XML
+ configuration. For M4 a new format was designed to be implemented
+ by both C++ and Java brokers. M4 release includes the initial C++
+ implementation and M5 is expected to include the Java
+ implementation.
+ </para><bridgehead id="QpidACLs-Specifications"><anchor id="QpidACLs-Specifications"/>Specifications
+ </bridgehead><para>
+ The specifications for each of the ACL formats are linked here:
+ </para><para><xref linkend="JavaXMLACLs-specification"/><xref linkend="ACL-specification"/></para><bridgehead id="QpidACLs-UserGuides"><anchor id="QpidACLs-UserGuides"/>User Guides
+ </bridgehead><para>
+ To aid users in defining their ACLs we have a user guide for each
+ of the ACL formats.
+ </para><para><xref linkend="JavaXMLACLs-userguide"/><xref linkend="ACL-userguide"/></para></section>
Added: qpid/trunk/qpid/doc/book/src/Qpid Management Framework.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/Qpid%20Management%20Framework.xml?rev=898329&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/Qpid Management Framework.xml (added)
+++ qpid/trunk/qpid/doc/book/src/Qpid Management Framework.xml Tue Jan 12 14:05:42 2010
@@ -0,0 +1,923 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns:html="http://www.w3.org/1999/xhtml"><title>
+ Apache Qpid : Qpid Management Framework
+ </title>
+ <itemizedlist>
+ <listitem><para>
+ <xref linkend="QpidManagementFramework-WhatIsQMF"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QpidManagementFramework-GettingStartedwithQMF"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QpidManagementFramework-QMFConcepts"/>
+ </para></listitem>
+ <listitem><para>
+ <itemizedlist>
+ <listitem><para>
+ <xref linkend="QpidManagementFramework-Console-2CAgent-2CandBroker"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QpidManagementFramework-Schema"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QpidManagementFramework-ClassKeysandClassVersioning"/>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QpidManagementFramework-TheQMFProtocol"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QpidManagementFramework-HowtoWriteaQMFConsole"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QpidManagementFramework-HowtoWriteaQMFAgent"/>
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+ Please visit the <xref linkend="qpid_QMFv2-20Project-20Page"/> for information
+ about the future of QMF.
+ </para>
+ <section role="h1" id="QpidManagementFramework-WhatIsQMF"><title>
+ What Is QMF
+ </title>
+
+ <para>
+ 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.
+ </para>
+ <!--h1--></section>
+
+ <section role="h1" id="QpidManagementFramework-GettingStartedwithQMF"><title>
+ Getting
+ Started with QMF
+ </title>
+
+ <para>
+ QMF is used through two primary APIs. The <emphasis>console</emphasis> API is
+ used for console applications that wish to access and manipulate
+ manageable components through QMF. The <emphasis>agent</emphasis> API is used
+ for application that wish to be managed through QMF.
+ </para><para>
+ 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 <emphasis>Qmf Concepts</emphasis> section.
+ </para>
+ <!--h1--></section>
+
+ <section role="h1" id="QpidManagementFramework-QMFConcepts"><title>
+ QMF Concepts
+ </title>
+
+ <para>
+ This section introduces important concepts underlying QMF.
+ </para>
+
+
+ <section role="h2" id="QpidManagementFramework-Console-2CAgent-2CandBroker"><title>
+ Console,
+ Agent, and Broker
+ </title>
+
+ <para>
+ 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.
+ </para><para>
+ 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.
+ </para><para>
+ An agent application is any application that has been enhanced to
+ allow itself to be managed via QMF.
+ </para>
+ <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 |
+ +----------------+ +----------------+ +----------------+
+</programlisting>
+ <para>
+ In the above diagram, the <emphasis>Manageable apps</emphasis> are agents,
+ the <emphasis>CLI utility</emphasis>, <emphasis>Web app</emphasis>, and <emphasis>Audit
+ storage</emphasis> are consoles, and <emphasis>Event correlation</emphasis> is both
+ a console and an agent because it can create events based on the
+ aggregation of what it sees.
+ </para>
+<!--h2--></section>
+
+ <section role="h2" id="QpidManagementFramework-Schema"><title>
+ Schema
+ </title>
+
+ <para>
+ A <emphasis>schema</emphasis> describes the structure of management data.
+ Each <emphasis>agent</emphasis> 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.
+ </para><section role="h3" id="QpidManagementFramework-Package"><title>
+ Package
+ </title>
+
+ <para>
+ Each agent that exports a schema identifies itself using a
+ <emphasis>package</emphasis> 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.
+ </para><para>
+ 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.
+ </para><para>
+ The XML document for a package's schema uses an enclosing
+ <schema> tag. For example:
+ </para>
+ <programlisting>
+<schema package="org.apache.qpid.broker">
+
+</schema>
+</programlisting>
+<!--h3--></section>
+
+ <section role="h3" id="QpidManagementFramework-ObjectClasses"><title>
+ Object
+ Classes
+ </title>
+
+ <para>
+ <emphasis>Object classes</emphasis> 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.
+ </para>
+ <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>
+</programlisting>
+<!--h3--></section>
+
+
+ <section role="h3" id="QpidManagementFramework-PropertiesandStatistics"><title>
+ Properties
+ and Statistics
+ </title>
+
+ <para>
+ <property> and <statistic> tags must be placed within
+ <schema> and </schema> tags.
+ </para><para>
+ 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 <emphasis>property</emphasis>. If an
+ attribute is rapidly changing or is used to instrument the object
+ (counters, etc.), it should be defined as a <emphasis>statistic</emphasis>.
+ </para><para>
+ The XML syntax for <property> and <statistic> have
+ the following XML-attributes:
+ </para><table><title/><tgroup cols="4">
+ <tbody>
+ <row>
+ <entry>
+ Attribute
+ </entry>
+ <entry>
+ <property>
+ </entry>
+ <entry>
+ <statistic>
+ </entry>
+ <entry>
+ Meaning
+ </entry>
+ </row>
+ <row>
+ <entry>
+ name
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ The name of the attribute
+ </entry>
+ </row>
+ <row>
+ <entry>
+ type
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ The data type of the attribute
+ </entry>
+ </row>
+ <row>
+ <entry>
+ unit
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ Optional unit name - use the singular (i.e. MByte)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ desc
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ Description to annotate the attribute
+ </entry>
+ </row>
+ <row>
+ <entry>
+ references
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ Â
+ </entry>
+ <entry>
+ If the type is "objId", names the referenced class
+ </entry>
+ </row>
+ <row>
+ <entry>
+ access
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ Â
+ </entry>
+ <entry>
+ Access rights (RC, RW, RO)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ index
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ Â
+ </entry>
+ <entry>
+ "y" if this property is used to uniquely identify the
+ object. There may be more than one index property in a
+ class
+ </entry>
+ </row>
+ <row>
+ <entry>
+ parentRef
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ Â
+ </entry>
+ <entry>
+ "y" if this property references an object in which this
+ object is in a child-parent relationship.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ optional
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ Â
+ </entry>
+ <entry>
+ "y" if this property is optional (i.e. may be
+ NULL/not-present)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ min
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ Â
+ </entry>
+ <entry>
+ Minimum value of a numeric attribute
+ </entry>
+ </row>
+ <row>
+ <entry>
+ max
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ Â
+ </entry>
+ <entry>
+ Maximum value of a numeric attribute
+ </entry>
+ </row>
+ <row>
+ <entry>
+ maxLen
+ </entry>
+ <entry>
+ Y
+ </entry>
+ <entry>
+ Â
+ </entry>
+ <entry>
+ Maximum length of a string attribute
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table>
+<!--h3--></section>
+
+
+ <section role="h3" id="QpidManagementFramework-Methods"><title>
+ Methods
+ </title>
+
+ <para>
+ <method> tags must be placed within <schema> and
+ </schema> tags.
+ </para><para>
+ A <emphasis>method</emphasis> 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:
+ </para>
+ <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>
+</programlisting>
+<!--h3--></section>
+
+ <section role="h3" id="QpidManagementFramework-EventClasses"><title>
+ Event Classes
+ </title>
+ <para/>
+ <!--h3--></section>
+
+ <section role="h3" id="QpidManagementFramework-DataTypes"><title>
+ Data Types
+ </title>
+
+ <para>
+ 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:
+ </para><table><title/><tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ QMF Type
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ <row>
+ <entry>
+ REF
+ </entry>
+ <entry>
+ QMF Object ID - Used to reference another QMF object.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ U8
+ </entry>
+ <entry>
+ 8-bit unsigned integer
+ </entry>
+ </row>
+ <row>
+ <entry>
+ U16
+ </entry>
+ <entry>
+ 16-bit unsigned integer
+ </entry>
+ </row>
+ <row>
+ <entry>
+ U32
+ </entry>
+ <entry>
+ 32-bit unsigned integer
+ </entry>
+ </row>
+ <row>
+ <entry>
+ U64
+ </entry>
+ <entry>
+ 64-bit unsigned integer
+ </entry>
+ </row>
+ <row>
+ <entry>
+ S8
+ </entry>
+ <entry>
+ 8-bit signed integer
+ </entry>
+ </row>
+ <row>
+ <entry>
+ S16
+ </entry>
+ <entry>
+ 16-bit signed integer
+ </entry>
+ </row>
+ <row>
+ <entry>
+ S32
+ </entry>
+ <entry>
+ 32-bit signed integer
+ </entry>
+ </row>
+ <row>
+ <entry>
+ S64
+ </entry>
+ <entry>
+ 64-bit signed integer
+ </entry>
+ </row>
+ <row>
+ <entry>
+ BOOL
+ </entry>
+ <entry>
+ Boolean - True or False
+ </entry>
+ </row>
+ <row>
+ <entry>
+ SSTR
+ </entry>
+ <entry>
+ Short String - String of up to 255 bytes
+ </entry>
+ </row>
+ <row>
+ <entry>
+ LSTR
+ </entry>
+ <entry>
+ Long String - String of up to 65535 bytes
+ </entry>
+ </row>
+ <row>
+ <entry>
+ ABSTIME
+ </entry>
+ <entry>
+ Absolute time since the epoch in nanoseconds (64-bits)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ DELTATIME
+ </entry>
+ <entry>
+ Delta time in nanoseconds (64-bits)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ FLOAT
+ </entry>
+ <entry>
+ Single precision floating point number
+ </entry>
+ </row>
+ <row>
+ <entry>
+ DOUBLE
+ </entry>
+ <entry>
+ Double precision floating point number
+ </entry>
+ </row>
+ <row>
+ <entry>
+ UUID
+ </entry>
+ <entry>
+ UUID - 128 bits
+ </entry>
+ </row>
+ <row>
+ <entry>
+ FTABLE
+ </entry>
+ <entry>
+ Field-table - std::map in C++, dictionary in Python
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table><para>
+ 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.
+ </para><table><title/><tgroup cols="4">
+ <tbody>
+ <row>
+ <entry>
+ XML Type
+ </entry>
+ <entry>
+ QMF Type
+ </entry>
+ <entry>
+ Accessor Style
+ </entry>
+ <entry>
+ Special Characteristics
+ </entry>
+ </row>
+ <row>
+ <entry>
+ objId
+ </entry>
+ <entry>
+ REF
+ </entry>
+ <entry>
+ Direct (get, set)
+ </entry>
+ <entry>
+ Â
+ </entry>
+ </row>
+ <row>
+ <entry>
+ uint8,16,32,64
+ </entry>
+ <entry>
+ U8,16,32,64
+ </entry>
+ <entry>
+ Direct (get, set)
+ </entry>
+ <entry>
+ Â
+ </entry>
+ </row>
+ <row>
+ <entry>
+ int8,16,32,64
+ </entry>
+ <entry>
+ S8,16,32,64
+ </entry>
+ <entry>
+ Direct (get, set)
+ </entry>
+ <entry>
+ Â
+ </entry>
+ </row>
+ <row>
+ <entry>
+ bool
+ </entry>
+ <entry>
+ BOOL
+ </entry>
+ <entry>
+ Direct (get, set)
+ </entry>
+ <entry>
+ Â
+ </entry>
+ </row>
+ <row>
+ <entry>
+ sstr
+ </entry>
+ <entry>
+ SSTR
+ </entry>
+ <entry>
+ Direct (get, set)
+ </entry>
+ <entry>
+ Â
+ </entry>
+ </row>
+ <row>
+ <entry>
+ lstr
+ </entry>
+ <entry>
+ LSTR
+ </entry>
+ <entry>
+ Direct (get, set)
+ </entry>
+ <entry>
+ Â
+ </entry>
+ </row>
+ <row>
+ <entry>
+ absTime
+ </entry>
+ <entry>
+ ABSTIME
+ </entry>
+ <entry>
+ Direct (get, set)
+ </entry>
+ <entry>
+ Â
+ </entry>
+ </row>
+ <row>
+ <entry>
+ deltaTime
+ </entry>
+ <entry>
+ DELTATIME
+ </entry>
+ <entry>
+ Direct (get, set)
+ </entry>
+ <entry>
+ Â
+ </entry>
+ </row>
+ <row>
+ <entry>
+ float
+ </entry>
+ <entry>
+ FLOAT
+ </entry>
+ <entry>
+ Direct (get, set)
+ </entry>
+ <entry>
+ Â
+ </entry>
+ </row>
+ <row>
+ <entry>
+ double
+ </entry>
+ <entry>
+ DOUBLE
+ </entry>
+ <entry>
+ Direct (get, set)
+ </entry>
+ <entry>
+ Â
+ </entry>
+ </row>
+ <row>
+ <entry>
+ uuid
+ </entry>
+ <entry>
+ UUID
+ </entry>
+ <entry>
+ Direct (get, set)
+ </entry>
+ <entry>
+ Â
+ </entry>
+ </row>
+ <row>
+ <entry>
+ map
+ </entry>
+ <entry>
+ FTABLE
+ </entry>
+ <entry>
+ Direct (get, set)
+ </entry>
+ <entry>
+ Â
+ </entry>
+ </row>
+ <row>
+ <entry>
+ hilo8,16,32,64
+ </entry>
+ <entry>
+ U8,16,32,64
+ </entry>
+ <entry>
+ Counter (inc, dec)
+ </entry>
+ <entry>
+ Generates value, valueMin, valueMax
+ </entry>
+ </row>
+ <row>
+ <entry>
+ count8,16,32,64
+ </entry>
+ <entry>
+ U8,16,32,64
+ </entry>
+ <entry>
+ Counter (inc, dec)
+ </entry>
+ <entry>
+ Â
+ </entry>
+ </row>
+ <row>
+ <entry>
+ mma32,64
+ </entry>
+ <entry>
+ U32,64
+ </entry>
+ <entry>
+ Direct
+ </entry>
+ <entry>
+ Generates valueMin, valueMax, valueAverage, valueSamples
+ </entry>
+ </row>
+ <row>
+ <entry>
+ mmaTime
+ </entry>
+ <entry>
+ DELTATIME
+ </entry>
+ <entry>
+ Direct
+ </entry>
+ <entry>
+ Generates valueMin, valueMax, valueAverage, valueSamples
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table>
+
+ <note><title>Important</title>
+ <para>
+ When writing a schema using the XML format, types used in
+ <property> or <arg> must be types that have
+ <emphasis>Direct</emphasis> accessor style. Any type may be used in
+ <statistic> tags.
+ </para>
+ </note>
+
+<!--h3--></section>
+<!--h2--></section>
+
+ <section role="h2" id="QpidManagementFramework-ClassKeysandClassVersioning"><title>
+ Class
+ Keys and Class Versioning
+ </title>
+
+ <para/>
+
+<!--h2--></section>
+
+ <!--h1--></section>
+
+ <section role="h1" id="QpidManagementFramework-TheQMFProtocol"><title>
+ The QMF
+ Protocol
+ </title>
+
+ <para>
+ The QMF protocol defines the message formats and communication
+ patterns used by the different QMF components to communicate with
+ one another.
+ </para><para>
+ A description of the current version of the QMF protocol can be
+ found at <xref linkend="qpid_QMF-20Protocol"/>.
+ </para><para>
+ A proposal for an updated protocol based on map-messages is in
+ progress and can be found at <xref linkend="qpid_QMF-20Map-20Message-20Protocol"/>.
+ </para>
+<!--h1--></section>
+
+ <section role="h1" id="QpidManagementFramework-HowtoWriteaQMFConsole"><title>
+ How
+ to Write a QMF Console
+ </title>
+
+ <para>
+ Please see the <xref linkend="qpid_QMF-20Python-20Console-20Tutorial"/> for information about using the console API with
+ Python.
+ </para>
+<!--h1--></section>
+
+ <section role="h1" id="QpidManagementFramework-HowtoWriteaQMFAgent"><title>
+ How to
+ Write a QMF Agent
+ </title>
+ <para/>
+ <!--h1--></section>
+
+
+</chapter>
Added: qpid/trunk/qpid/doc/book/src/RASC.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/RASC.xml?rev=898329&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/RASC.xml (added)
+++ qpid/trunk/qpid/doc/book/src/RASC.xml Tue Jan 12 14:05:42 2010
@@ -0,0 +1,306 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns:html="http://www.w3.org/1999/xhtml"><title>
+ Apache Qpid : RASC
+ </title>
+
+ <section role="h2" id="RASC-BuildingtheC-5CBrokerandClientLibraries"><title>
+ Building the
+ C++ Broker and Client Libraries
+ </title>
+ <para>
+ The root directory for the C++ distribution is named
+ qpidc-0.4. The README file in that directory gives
+ instructions for building the broker and client libraries. In
+ most cases you will do the following:
+ </para>
+ <programlisting>
+[qpidc-0.4]$ ./configure}}
+[qpidc-0.4]$ make
+</programlisting>
+ <!--h2--></section>
+ <section role="h2" id="RASC-RunningtheC-5CBroker"><title>
+ Running the C++ Broker
+ </title>
+ <para>
+ Once you have built the broker and client libraries, you can
+ start the broker from the command line:
+ </para>
+ <programlisting>
+[qpidc-0.4]$ src/qpidd
+</programlisting>
+ <para>
+ Use the --daemon option to run the broker as a daemon
+ process:
+ </para>
+ <programlisting>
+[qpidc-0.4]$ src/qpidd --daemon
+</programlisting>
+ <para>
+ You can stop a running daemon with the --quit option:
+ </para>
+ <programlisting>
+[qpidc-0.4]$ src/qpidd --quit
+</programlisting>
+ <para>
+ You can see all available options with the --help option
+ </para>
+ <programlisting>
+[qpidc-0.4]$ src/qpidd --help
+</programlisting>
+ <!--h2--></section>
+ <section role="h2" id="RASC-Mostcommonquestionsgettingqpiddrunning"><title>
+ Most
+ common questions getting qpidd running
+ </title>
+ <section role="h3" id="RASC-Errorwhenstartingbroker-3A-22nodatadirectory-22"><title>
+ Error
+ when starting broker: "no data directory"
+ </title>
+ <para>
+ The qpidd broker requires you to set a data directory or specify
+ --no-data-dir (see help for more details). The data
+ directory is used for the journal, so it is important when
+ reliability counts. Make sure your process has write permission
+ to the data directory.
+ </para><para>
+ The default location is
+ </para>
+ <programlisting>
+/lib/var/qpidd
+</programlisting>
+ <para>
+ An alternate location can be set with --data-dir
+ </para>
+ <!--h3--></section>
+ <section role="h3" id="RASC-Errorwhenstartingbroker-3A-22thatprocessislocked-22"><title>
+ Error
+ when starting broker: "that process is locked"
+ </title>
+ <para>
+ Note that when qpidd starts it creates a lock file is data
+ directory are being used. If you have a un-controlled exit,
+ please mail
+ the trace from the core to the dev@qpid.apache.org mailing list.
+ To clear the lock run
+ </para>
+ <programlisting>
+./qpidd -q
+</programlisting>
+ <para>
+ It should also be noted that multiple brokers can be run on the
+ same host. To do so set alternate data directories for each qpidd
+ instance.
+ </para>
+ <!--h3--></section>
+ <section role="h3" id="RASC-Usingaconfigurationfile"><title>
+ Using a configuration
+ file
+ </title>
+ <para>
+ Each option that can be specified on the command line can also be
+ specified in a configuration file. To see available options, use
+ --help on the command line:
+ </para>
+ <programlisting>
+./qpidd --help
+</programlisting>
+ <para>
+ A configuration file uses name/value pairs, one on each line. To
+ convert a command line option to a configuration file entry:
+ </para><para>
+ a.) remove the '--' from the beginning of the option.
+ b.) place a '=' between the option and the value (use
+ <emphasis>yes</emphasis> or <emphasis>true</emphasis> to enable options that take no
+ value when specified on the command line).
+ c.) place one option per line.
+ </para><para>
+ For instance, the --daemon option takes no value, the
+ --log-to-syslog option takes the values yes or
+ no. The following configuration file sets these two
+ options:
+ </para>
+ <programlisting>
+daemon=yes
+log-to-syslog=yes
+</programlisting>
+ <!--h3--></section>
+ <section role="h3" id="RASC-CanIuseanyLanguageclientwiththeC-5CBroker-3F"><title>
+ Can I use
+ any Language client with the C++ Broker?
+ </title>
+ <para>
+ Yes, all the clients work with the C++ broker; it is written in
+ C+<emphasis>, but uses the AMQP wire protocol. Any broker can be used
+ with any client that uses the same AMQP version. When running the
+ C</emphasis>+ broker, it is highly recommended to run AMQP 0-10.
+ </para><para>
+ Note that JMS also works with the C++ broker. For more details on
+ using the Java client refer to these pages:
+ </para><itemizedlist>
+ <listitem><para>
+ <xref linkend="qpid_How-20to-20Use-20JNDI"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="qpid_URL-20Formats"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="qpid_Example-20Classes"/>
+ </para></listitem>
+ </itemizedlist>
+ <!--h3--></section>
+ <!--h2--></section>
+ <section role="h2" id="RASC-Authentication"><title>
+ Authentication
+ </title>
+ <section role="h3" id="RASC-Linux"><title>
+ Linux
+ </title>
+ <para>
+ The PLAIN authentication is done on a username+password, which is
+ stored in the sasldb_path file. Usernames and passwords can be
+ added to the file using the command:
+ </para>
+ <programlisting>
+saslpasswd2 -f /var/lib/qpidd/qpidd.sasldb -u <REALM> <USER>
+</programlisting>
+ <para>
+ The REALM is important and should be the same as the
+ --auth-realm
+ option to the broker. This lets the broker properly find the user
+ in
+ the sasldb file.
+ </para><para>
+ Existing user accounts may be listed with:
+ </para>
+ <programlisting>
+sasldblistusers2 -f /var/lib/qpidd/qpidd.sasldb
+</programlisting>
+ <para>
+ NOTE: The sasldb file must be readable by the user running the
+ qpidd daemon, and should be readable only by that user.
+ </para>
+ <!--h3--></section>
+ <section role="h3" id="RASC-Windows"><title>
+ Windows
+ </title>
+ <para>
+ On Windows, the users are authenticated against the local
+ machine. You should add the appropriate users using the standard
+ Windows tools (Control Panel->User Accounts). To run many of
+ the examples, you will need to create a user "guest" with
+ password "guest".
+ </para><para>
+ If you cannot or do not want to create new users, you can run
+ without authentication by specifying the no-auth option to the
+ broker.
+ </para>
+ <!--h3--></section>
+ <!--h2--></section>
+
+ <section role="h2" id="RASC-Slightlymorecomplexconfiguration"><title>
+ Slightly more
+ complex configuration
+ </title>
+ <para>
+ The easiest way to get a full listing of the broker's options are
+ to use the --help command, run it locally for the latest set of
+ options. These options can then be set in the conf file for
+ convenience (see above)
+ </para>
+ <programlisting>
+./qpidd --help
+
+Usage: qpidd OPTIONS
+Options:
+ -h [ --help ] Displays the help message
+ -v [ --version ] Displays version information
+ --config FILE (/etc/qpidd.conf) Reads configuration from FILE
+
+Module options:
+ --module-dir DIR (/usr/lib/qpidd) Load all .so modules in this directory
+ --load-module FILE Specifies additional module(s) to be loaded
+ --no-module-dir Don't load modules from module directory
+
+Broker Options:
+ --data-dir DIR (/var/lib/qpidd) Directory to contain persistent data generated by the broker
+ --no-data-dir Don't use a data directory. No persistent
+ configuration will be loaded or stored
+ -p [ --port ] PORT (5672) Tells the broker to listen on PORT
+ --worker-threads N (3) Sets the broker thread pool size
+ --max-connections N (500) Sets the maximum allowed connections
+ --connection-backlog N (10) Sets the connection backlog limit for the
+ server socket
+ --staging-threshold N (5000000) Stages messages over N bytes to disk
+ -m [ --mgmt-enable ] yes|no (1) Enable Management
+ --mgmt-pub-interval SECONDS (10) Management Publish Interval
+ --ack N (0) Send session.ack/solicit-ack at least every
+ N frames. 0 disables voluntary ack/solitict
+ -ack
+
+Daemon options:
+ -d [ --daemon ] Run as a daemon.
+ -w [ --wait ] SECONDS (10) Sets the maximum wait time to initialize the
+ daemon. If the daemon fails to initialize, prints
+ an error and returns 1
+ -c [ --check ] Prints the daemon's process ID to stdout and
+ returns 0 if the daemon is running, otherwise
+ returns 1
+ -q [ --quit ] Tells the daemon to shut down
+Logging options:
+ --log-output FILE (stderr) Send log output to FILE. FILE can be a file name
+ or one of the special values:
+ stderr, stdout, syslog
+ -t [ --trace ] Enables all logging
+ --log-enable RULE (error+) Enables logging for selected levels and component
+ s. RULE is in the form 'LEVEL+:PATTERN'
+ Levels are one of:
+ trace debug info notice warning error critical
+ For example:
+ '--log-enable warning+' logs all warning, error
+ and critical messages.
+ '--log-enable debug:framing' logs debug messages
+ from the framing namespace. This option can be
+ used multiple times
+ --log-time yes|no (1) Include time in log messages
+ --log-level yes|no (1) Include severity level in log messages
+ --log-source yes|no (0) Include source file:line in log messages
+ --log-thread yes|no (0) Include thread ID in log messages
+ --log-function yes|no (0) Include function signature in log messages
+</programlisting>
+ <!--h2--></section>
+ <section role="h2" id="RASC-Loadingextramodules"><title>
+ Loading extra modules
+ </title>
+ <para>
+ By default the broker will load all the modules in the module
+ directory, however it will NOT display options for modules that
+ are not loaded. So to see the options for extra modules loaded
+ you need to load the module and then add the help command like
+ this:
+ </para>
+ <programlisting>
+./qpidd --load-module libbdbstore.so --help
+Usage: qpidd OPTIONS
+Options:
+ -h [ --help ] Displays the help message
+ -v [ --version ] Displays version information
+ --config FILE (/etc/qpidd.conf) Reads configuration from FILE
+
+
+ / .... non module options would be here ... /
+
+
+Store Options:
+ --store-directory DIR Store directory location for persistence (overrides
+ --data-dir)
+ --store-async yes|no (1) Use async persistence storage - if store supports
+ it, enables AIO O_DIRECT.
+ --store-force yes|no (0) Force changing modes of store, will delete all
+ existing data if mode is changed. Be SURE you want
+ to do this!
+ --num-jfiles N (8) Number of files in persistence journal
+ --jfile-size-pgs N (24) Size of each journal file in multiples of read
+ pages (1 read page = 64kiB)
+</programlisting>
+<!--h2--></section>
+</chapter>
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org