qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Qpid > QMF Map Message Protocol
Date Tue, 08 Dec 2009 17:00:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=qpid&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="http://cwiki.apache.org/confluence/display/qpid/QMF+Map+Message+Protocol">QMF
Map Message Protocol</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~tross">Ted
Ross</a>
    </h4>
     
          <br/>
     <div class="notificationGreySide">
         <h1><a name="QMFMapMessageProtocol-QMFv2MapMessageProtocol"></a>QMFv2
Map Message Protocol</h1>
<h2><a name="QMFMapMessageProtocol-Introduction"></a>Introduction</h2>

<p>This document describes the design of a proposed protocol for QMF based on map-messages
(offered by the new C++ and Python APIs as well as the existing JMS API).</p>

<p>If adopted, this new protocol will change the formats of the messages used by QMF
components to communicate.  It will also change some of the message exchange patterns.  It
will <b>not</b> significantly impact the console and agent APIs and is intended
to operate with applications that use the current QMF APIs.</p>

<p>Some highlights of the new design:</p>

<ul>
	<li>Current QMF message bodies are in packed binary formats.  While quite efficient,
this style of formatting makes it difficult to make changes to the format and content for
new features.  The proposed format is based on encoded maps (a.k.a. dictionaries, field-tables)
which are very easily extended and require less context to be useful.</li>
	<li>QMF currently requires the message broker to participate in the QMF protocol. 
The proposed protocol removes this requirement and will run properly on any AMQP message broker.</li>
	<li>QMF Agents currently publish periodic updates of their managed content to a globally
accessible topic.  This has security implications with regard to access to data.  This is
also inflexible in that updates to all data are sent at the same intervals.  The proposed
protocol removes the global publishing of data and introduces a subscription-query whereby
a console may request that an agent publish certain data at a certain interval to an indicated
target.  Such requests can be subject to access control and may be focused on only the data
that is needed for a particular application.</li>
	<li>The proposed protocol allows for more general use of data.  For example:
	<ul>
		<li>Free-form data, that has no object-identifier nor schema, can be transferred.
 This is useful for complex queries (joins, reports, etc.).</li>
		<li>Methods can be invoked against an agent in the absence of a managed object.</li>
	</ul>
	</li>
</ul>


<h2><a name="QMFMapMessageProtocol-QMFProtocol"></a>QMF Protocol</h2>

<h3><a name="QMFMapMessageProtocol-UseofMessageHeaders"></a>Use of Message
Headers</h3>

<h4><a name="QMFMapMessageProtocol-StandardHeaders"></a>Standard Headers</h4>

<h4><a name="QMFMapMessageProtocol-ApplicationHeaders"></a>Application Headers</h4>

<h3><a name="QMFMapMessageProtocol-MessageTypeCodes"></a>Message Type Codes</h3>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'>Type Code</th>
<th class='confluenceTh'>Name</th>
<th class='confluenceTh'>Description</th>
</tr>
<tr>
<td class='confluenceTd'>agent</td>
<td class='confluenceTd'>Agent Indication</td>
<td class='confluenceTd'>Indication sent from an agent periodically or immediately upon
receiving an agent-locate with matching criteria.  This message is used in agent discovery
and as a keep-alive/heartbeat indication.</td>
</tr>
<tr>
<td class='confluenceTd'>agent-locate</td>
<td class='confluenceTd'>Agent Locate Indication</td>
<td class='confluenceTd'>Indication sent from a console when the console wishes to discover
agents in the network.  This message may contain a selector indicating which subset of all
agents it wishes to discover.</td>
</tr>
<tr>
<td class='confluenceTd'>response</td>
<td class='confluenceTd'>Response</td>
<td class='confluenceTd'>General-purpose response to a request.  A response message
is always correlated to a specific request and is sent to the reply-to of the request.  A
response may optionally contain a structured exception or it may optionally contain a list
of values (i.e. output arguments from a method call).</td>
</tr>
<tr>
<td class='confluenceTd'>schema-query</td>
<td class='confluenceTd'>Schema Query Request</td>
<td class='confluenceTd'>A request sent by a console to an agent to discover information
about the schemata of data offered by the agent.  A schema query may request a list of packages
(i.e. namespaces), a list of schema keys, or full schema details from the agent.</td>
</tr>
<tr>
<td class='confluenceTd'>schema</td>
<td class='confluenceTd'>Schema Indication</td>
<td class='confluenceTd'>Indication sent from an agent either to announce newly added
schema information or as a side effect of having received a schema query request from a console.</td>
</tr>
<tr>
<td class='confluenceTd'>get-query</td>
<td class='confluenceTd'>Get Query Request</td>
<td class='confluenceTd'>A request sent from a console to an agent to get data from
the agent.  Generally, a get query is used to access managed objects owned by the agent. 
This message is extensible such that an agent may offer advanced query capabilities (SQL,
Reporting, etc.) to consoles that know how to use the capabilities.</td>
</tr>
<tr>
<td class='confluenceTd'>managed-object</td>
<td class='confluenceTd'>Managed Object Indication</td>
<td class='confluenceTd'>Indication sent from an agent as a side effect of having received
a get-query or a create-subscription.  Managed objects have object-identifiers, schema keys,
and create/destroy timestamps in addition to their attributes.</td>
</tr>
<tr>
<td class='confluenceTd'>object</td>
<td class='confluenceTd'>Object Indication</td>
<td class='confluenceTd'>Indication sent from an agent as a side effect of having received
a get-query.  Unmanaged objects have schema keys but no object-identifiers or timestamps as
they are not managed, can't be addressed, and have no lifecycle.</td>
</tr>
<tr>
<td class='confluenceTd'>data</td>
<td class='confluenceTd'>Data Indication</td>
<td class='confluenceTd'>Indication sent from an agent as a side effect of having received
a get-query.  Data has attributes only and can be used for any general purpose.</td>
</tr>
<tr>
<td class='confluenceTd'>event</td>
<td class='confluenceTd'>Event Indication</td>
<td class='confluenceTd'>Indication sent from an agent when the agent application raises
an event.</td>
</tr>
<tr>
<td class='confluenceTd'>create-subscription</td>
<td class='confluenceTd'>Create Subscription Request</td>
<td class='confluenceTd'>Request sent from a console to an agent to create a subscription
query.  Such a query behaves like a get-query except that once the matching objects are sent,
the query remains open and sends updates when matching objects are changed, added, or deleted.
 A subscription query has a target (not necessarily the address of the requesting console),
a publishing interval to control the frequency of updates, and a time-to-live.  If the subscription
is not renewed after the time-to-live has expired, the subscription will be cancelled by the
agent.</td>
</tr>
<tr>
<td class='confluenceTd'>cancel-subscription</td>
<td class='confluenceTd'>Cancel Subscription Request</td>
<td class='confluenceTd'>Request sent from a console to an agent to cancel an existing
subscription query.</td>
</tr>
<tr>
<td class='confluenceTd'>renew-subscription</td>
<td class='confluenceTd'>Renew Subscription Request</td>
<td class='confluenceTd'>Request sent from a console to an agent to renew an existing
subscription query.  This causes the time-to-live timer to be reset.</td>
</tr>
<tr>
<td class='confluenceTd'>method</td>
<td class='confluenceTd'>Method Request</td>
<td class='confluenceTd'>Request sent from a console to an agent to invoke a method
on either the agent itself or on a managed object controlled by the agent.</td>
</tr>
</tbody></table>

<h3><a name="QMFMapMessageProtocol-Operations"></a>Operations</h3>

<h4><a name="QMFMapMessageProtocol-AgentAnnounce"></a>Agent Announce</h4>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>          Console                      Topic                         Agent
             |                           |                             |
             |                           | &lt;---- Agent Indication ---- |
             | &lt;------------------------ |                             |
             |                           |                             |
</pre>
</div></div>

<h4><a name="QMFMapMessageProtocol-AgentLocate"></a>Agent Locate</h4>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>          Console                            Topic                         Agent
             |                                 |                             |
             | ---- Agent Locate Indication -&gt; |                             |
             |                                 | --------------------------&gt; |
             |                                 |                             |
             | &lt;-------------------------------------- Agent Indication ---- |
             |                                 |                             |
             |                                 |                             |
             | ---- Agent Locate Indication -------------------------------&gt; |
             |                                 |                             |
             | &lt;-------------------------------------- Agent Indication ---- |
             |                                 |                             |
</pre>
</div></div>

<h4><a name="QMFMapMessageProtocol-SchemaQuery"></a>Schema Query</h4>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>          Console                                  Agent
             |                                       |
             | ---- Schema Request ----------------&gt; |
             |                                       |
             | &lt;------------- Schema Indication ---- |
             | &lt;------------- Schema Indication ---- |             
             |                                       |
             | &lt;---------------------- Response ---- |
             |                                       |
</pre>
</div></div>

<h4><a name="QMFMapMessageProtocol-SchemaAnnounce"></a>Schema Announce</h4>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>          Console                      Topic                         Agent
             |                           |                             |
             |                           | &lt;--- Schema Indication ---- |
             | &lt;------------------------ |                             |
             |                           |                             |
</pre>
</div></div>

<h4><a name="QMFMapMessageProtocol-GetQuery"></a>Get Query</h4>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>          Console                                  Agent
             |                                       |
             | ---- Get Query Request -------------&gt; |
             |                                       |
             | &lt;--------------- Data Indication ---- |
             | &lt;--------------- Data Indication ---- |
             | &lt;--------------- Data Indication ---- |
             | &lt;--------------- Data Indication ---- |
             | &lt;--------------- Data Indication ---- |
             | &lt;---------- Last Data Indication ---- |
             |                                       |
             | &lt;------------------------ Result ---- |
             |                                       |
</pre>
</div></div>

<h4><a name="QMFMapMessageProtocol-CreateSubscriptionQuery"></a>Create Subscription
Query</h4>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>          Console                Target                              Agent
             |                     |                                   |
             | ---- Create Subscription Request ---------------------&gt; |
             |                     |                                   |
             |                     | &lt;----------- Data Indication ---- |
             |                     | &lt;----------- Data Indication ---- |
             |                     | &lt;----------- Data Indication ---- |
             |                     | &lt;----------- Data Indication ---- |
             |                     | &lt;----------- Data Indication ---- |
             |                     |                                   |
             | &lt;------------------------------------------ Result ---- |
             |                     |                                   |
             |                     | &lt;----------- Data Indication ---- |
             |                     |                                   |
             |                     | &lt;----------- Data Indication ---- |
             |                     |                                   |
</pre>
</div></div>

<h4><a name="QMFMapMessageProtocol-CancelSubscriptionQuery"></a>Cancel Subscription
Query</h4>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>          Console               Target                              Agent
             |                     |                                   |
             | ---- Cancel Subscription Request ---------------------&gt; |
             |                     |                                   |
             | &lt;------------------------------------------ Result ---- |
             |                     |                                   |
             |                     | &lt;----------- Data Indication ---- |
             |                     | &lt;------ Last Data Indication ---- |
             |                     |                                   |
</pre>
</div></div>

<h4><a name="QMFMapMessageProtocol-RenewSubscriptionQuery"></a>Renew Subscription
Query</h4>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>          Console                Target                              Agent
             |                     |                                   |
             | ---- Renew Subscription Request ----------------------&gt; |
             |                     |                                   |
             | &lt;------------------------------------------ Result ---- |
             |                     |                                   |
</pre>
</div></div>

<h4><a name="QMFMapMessageProtocol-InvokeMethod"></a>Invoke Method</h4>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>          Console                                  Agent
             |                                       |
             | ---- Method Request ----------------&gt; |
             |                                       |
             | &lt;------------------------ Result ---- |
             |                                       |
</pre>
</div></div>

<h4><a name="QMFMapMessageProtocol-RaiseEvent"></a>Raise Event</h4>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>          Console                Topic                               Agent
             |                     |                                   |
             |                     | &lt;---------- Event Indication ---- |
             | &lt;------------------ |                                   |
             |                     |                                   |
</pre>
</div></div>

<h3><a name="QMFMapMessageProtocol-MapBodyFormats"></a>Map Body Formats</h3>

<h4><a name="QMFMapMessageProtocol-QMFDataFormats"></a>QMF Data Formats</h4>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>    qmfData := {values: mapOfValues}

    qmfDescribedData := {class_id: qmfClassId,
                         values: mapOfValues }

    qmfManagedData := {object_id: (lstr),
                       class_id: qmfClassId,
                       create_time: (datetime),
                       delete_time: (datetime),
                       update_time: (datetime),
                       values: mapOfValues }

    qmfClassId := {package: (sstr),
                   name: (sstr),
                   hash: (bin128) }
</pre>
</div></div>
     </div>
     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       </div>

       <a href="http://cwiki.apache.org/confluence/display/qpid/QMF+Map+Message+Protocol">View
Online</a>
       |
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=5603679&revisedVersion=10&originalVersion=9">View
Change</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/qpid/QMF+Map+Message+Protocol?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org


Mime
View raw message