Skip to Content.
Sympa Menu

perfsonar-dev - perfsonar: r3936 - trunk/perfsonar-doc/protocol/base

Subject: perfsonar development work

List archive

perfsonar: r3936 - trunk/perfsonar-doc/protocol/base


Chronological Thread 
  • From:
  • To:
  • Subject: perfsonar: r3936 - trunk/perfsonar-doc/protocol/base
  • Date: Mon, 2 Jun 2008 08:03:54 -0400
Author: zurawski
Date: 2008-06-02 08:03:53 -0400 (Mon, 02 Jun 2008)
New Revision: 3936

Added:
trunk/perfsonar-doc/protocol/base/chain.dia
trunk/perfsonar-doc/protocol/base/chain.png
trunk/perfsonar-doc/protocol/base/chain2.dia
trunk/perfsonar-doc/protocol/base/chain2.png
trunk/perfsonar-doc/protocol/base/exchange3.dia
trunk/perfsonar-doc/protocol/base/exchange3.png
trunk/perfsonar-doc/protocol/base/filter.dia
trunk/perfsonar-doc/protocol/base/filter.png
trunk/perfsonar-doc/protocol/base/ven.dia
trunk/perfsonar-doc/protocol/base/ven.png
Modified:
trunk/perfsonar-doc/protocol/base/base_protocol.html
trunk/perfsonar-doc/protocol/base/base_protocol.xml
Log:
Long overdue updates to the base document that include action items from
previous call. Still requires additional work on:

- Result Codes
- Request/Response pairs
- Examples

-jason



Modified: trunk/perfsonar-doc/protocol/base/base_protocol.html
===================================================================
--- trunk/perfsonar-doc/protocol/base/base_protocol.html 2008-06-02
10:18:00 UTC (rev 3935)
+++ trunk/perfsonar-doc/protocol/base/base_protocol.html 2008-06-02
12:03:53 UTC (rev 3936)
@@ -1,42 +1,50 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
-<html xmlns="http://www.w3.org/1999/xhtml";><head><meta
http-equiv="Content-Type" content="text/html; charset=UTF-8"
/><title>perfSONAR Base Protocol</title><meta name="generator"
content="DocBook XSL Stylesheets V1.71.0" /></head><body><div class="article"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h1 class="title"><a
id="id2479485"></a>perfSONAR Base Protocol</h1></div><div><div
class="authorgroup"><div class="author"><h3 class="author"><span
class="firstname">J.</span> <span class="surname">Zurawski</span></h3><div
class="affiliation"><span class="orgname">Internet2<br /></span><div
class="address"><p>   <br />
+<html xmlns="http://www.w3.org/1999/xhtml";><head><meta
http-equiv="Content-Type" content="text/html; charset=UTF-8"
/><title>perfSONAR Base Protocol</title><meta name="generator"
content="DocBook XSL Stylesheets V1.72.0" /></head><body><div class="article"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h1 class="title"><a
id="id2486755"></a>perfSONAR Base Protocol</h1></div><div><div
class="authorgroup"><div class="author"><h3 class="author"><span
class="firstname">J.</span> <span class="surname">Zurawski</span></h3><div
class="affiliation"><span class="orgname">Internet2<br /></span><div
class="address"><p>   <br />
            <code class="email">&lt;<a
href="mailto:"></a>&gt;</code><br
/>
          </p></div></div></div><div class="author"><h3 class="author"><span
class="firstname">M.</span> <span class="surname">Swany</span></h3><div
class="affiliation"><span class="orgname">University of Delaware<br
/></span><div class="address"><p>   <br />
            <code class="email">&lt;<a
href="mailto:"></a>&gt;</code><br
/>
-          </p></div></div></div></div></div></div><hr /></div><div
class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a
href="#changes">1. Document Changes</a></span></dt><dt><span
class="section"><a href="#introduction">2.
Introduction</a></span></dt><dt><span class="section"><a
href="#motivation">3. Motivation</a></span></dt><dt><span class="section"><a
href="#messages">4. Messages</a></span></dt><dd><dl><dt><span
class="section"><a href="#messages_example">4.1. Preliminary
Example</a></span></dt><dt><span class="section"><a
href="#messages_actions">4.2. Message Actions</a></span></dt><dt><span
class="section"><a href="#messages_request">4.3. Request
Message</a></span></dt><dd><dl><dt><span class="section"><a
href="#messages_request_schema">4.3.1. Request Message
Schema</a></span></dt><dt><span class="section"><a
href="#messages_request_analysis">4.3.2. Request Message
Analysis</a></span></dt><dd><dl><dt><span class="section"><a href="#mess
ages_request_analysis_message">4.3.2.1. Message</a></span></dt><dt><span
class="section"><a href="#messages_request_analysis_parameters">4.3.2.2.
Parameters</a></span></dt><dt><span class="section"><a
href="#messages_request_analysis_parameter">4.3.2.3.
Parameter</a></span></dt><dt><span class="section"><a
href="#messages_request_analysis_metadata">4.3.2.4.
Metadata</a></span></dt><dt><span class="section"><a
href="#messages_request_analysis_data">4.3.2.5.
Data</a></span></dt></dl></dd><dt><span class="section"><a
href="#messages_request_example">4.3.3. Request Message
Example</a></span></dt></dl></dd><dt><span class="section"><a
href="#messages_response">4.4. Response
Message</a></span></dt><dd><dl><dt><span class="section"><a
href="#messages_response_schema">4.4.1. Response Message
Schema</a></span></dt><dt><span class="section"><a
href="#messages_response_analysis">4.4.2. Response Message
Analysis</a></span></dt><dd><dl><dt><span class="section"><a
href="#messages_respons
e_analysis_message">4.4.2.1. Message</a></span></dt><dt><spa!
n class=
"section"><a href="#messages_response_analysis_parameters">4.4.2.2.
Parameters</a></span></dt><dt><span class="section"><a
href="#messages_response_analysis_parameter">4.4.2.3.
Parameter</a></span></dt><dt><span class="section"><a
href="#messages_response_analysis_metadata">4.4.2.4.
Metadata</a></span></dt><dt><span class="section"><a
href="#messages_response_analysis_data">4.4.2.5.
Data</a></span></dt></dl></dd><dt><span class="section"><a
href="#messages_response_example">4.4.3. Response Message
Example</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a
href="#result_codes">5. Result Codes</a></span></dt><dt><span
class="section"><a href="#extension">6.
Extension</a></span></dt><dd><dl><dt><span class="section"><a
href="#extension_echo">6.1. Echo Protocol</a></span></dt><dd><dl><dt><span
class="section"><a href="#extension_echo_architecture">6.1.1.
Architecture</a></span></dt><dt><span class="section"><a
href="#extension_echo_request_message">6.1.2. Request Mes
sage</a></span></dt><dd><dl><dt><span class="section"><a
href="#extension_echo_request_schema">6.1.2.1. Request Message
Schema</a></span></dt><dt><span class="section"><a
href="#extension_echo_request_analysis">6.1.2.2. Request Message
Analysis</a></span></dt><dd><dl><dt><span class="section"><a
href="#extension_echo_request_analysis_message">6.1.2.2.1.
Message</a></span></dt><dt><span class="section"><a
href="#extension_echo_request_analysis_metadata">6.1.2.2.2.
Metadata</a></span></dt><dt><span class="section"><a
href="#extension_echo_request_analysis_eventtype">6.1.2.2.3.
EventType</a></span></dt><dt><span class="section"><a
href="#extension_echo_request_analysis_data">6.1.2.2.4.
Data</a></span></dt></dl></dd><dt><span class="section"><a
href="#extension_echo_request_example">6.1.2.3. Request Message
Example</a></span></dt></dl></dd><dt><span class="section"><a
href="#extension_echo_response_message">6.1.3. Response
Message</a></span></dt><dd><dl><dt><span class="section"
><a href="#extension_echo_response_schema">6.1.3.1. Response!
Message
Schema</a></span></dt><dt><span class="section"><a
href="#extension_echo_response_analysis">6.1.3.2. Response Message
Analysis</a></span></dt><dd><dl><dt><span class="section"><a
href="#extension_echo_response_analysis_message">6.1.3.2.1.
Message</a></span></dt><dt><span class="section"><a
href="#extension_echo_response_analysis_metadata">6.1.3.2.2.
Metadata</a></span></dt><dt><span class="section"><a
href="#extension_echo_response_analysis_eventtype">6.1.3.2.3.
EventType</a></span></dt><dt><span class="section"><a
href="#extension_echo_response_analysis_data">6.1.3.2.4.
Data</a></span></dt><dt><span class="section"><a
href="#extension_echo_response_analysis_datum">6.1.3.2.5.
Datum</a></span></dt></dl></dd><dt><span class="section"><a
href="#extension_echo_response_example">6.1.3.3. Response Message
Example</a></span></dt></dl></dd><dt><span class="section"><a
href="#extension_echo_result_codes">6.1.4. Result
Codes</a></span></dt><dt><span class="section"><a href="#extension
_echo_protocol_extension">6.1.5. Protocol
Extension</a></span></dt><dd><dl><dt><span class="section"><a
href="#extension_echo_protocol_extension_eventType">6.1.5.1. eventType
Extension</a></span></dt><dt><span class="section"><a
href="#extension_echo_protocol_extension_other">6.1.5.2. Other
Extensions</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a
href="#extension_aa">6.2. Authentication and Authorization
Protocol</a></span></dt></dl></dd><dt><span class="section"><a
href="#conclusion">7. Conclusion</a></span></dt><dt><span class="glossary"><a
href="#glossary">Terms</a></span></dt><dt><span class="bibliography"><a
href="#bibliography">References</a></span></dt></dl></div><div
class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2
class="title" style="clear: both"><a id="changes"></a>1. Document
Changes</h2></div></div></div><div class="table"><a id="table.1"></a><p
class="title"><b>Table 1. Change Log</b></p><div class="table-content
s"><table summary="Change Log" border="1"><colgroup><col ali!
gn="left
" /></colgroup><thead><tr><th align="left">Version</th><th
align="left">Date</th><th align="left">Description</th><th
align="left">Author(s)</th></tr></thead><tbody><tr><td
align="left">1.0</td><td align="left">4/3/2008</td><td align="left">Initial
Preparation</td><td align="left">J. Zurawski</td></tr></tbody><tbody><tr><td
align="left">1.01</td><td align="left">4/7/2008</td><td align="left">Wording
Edits</td><td align="left">M. Swany</td></tr></tbody></table></div></div><br
class="table-break" /></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
id="introduction"></a>2. Introduction</h2></div></div></div><p>
- <a href="#id2533338">perfSONAR</a> is an infrastructure for network
+          </p></div></div></div></div></div></div><hr /></div><div
class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a
href="#changes">1. Document Changes</a></span></dt><dt><span
class="section"><a href="#introduction">2.
Introduction</a></span></dt><dt><span class="section"><a
href="#motivation">3. Motivation</a></span></dt><dt><span class="section"><a
href="#messages">4. Messages</a></span></dt><dd><dl><dt><span
class="section"><a href="#messages_example">4.1. Preliminary
Example</a></span></dt><dt><span class="section"><a
href="#messages_actions">4.2. Message Actions</a></span></dt><dt><span
class="section"><a href="#messages_request">4.3. Request
Message</a></span></dt><dd><dl><dt><span class="section"><a
href="#messages_request_schema">4.3.1. Request Message
Schema</a></span></dt><dt><span class="section"><a
href="#messages_request_analysis">4.3.2. Request Message
Analysis</a></span></dt><dd><dl><dt><span class="section"><a href="#mess
ages_request_analysis_message">4.3.2.1. Message</a></span></dt><dt><span
class="section"><a href="#messages_request_analysis_parameters">4.3.2.2.
Parameters</a></span></dt><dt><span class="section"><a
href="#messages_request_analysis_parameter">4.3.2.3.
Parameter</a></span></dt><dt><span class="section"><a
href="#messages_request_analysis_metadata">4.3.2.4.
Metadata</a></span></dt><dt><span class="section"><a
href="#messages_request_analysis_subject">4.3.2.5.
Subject</a></span></dt><dt><span class="section"><a
href="#messages_request_analysis_key">4.3.2.6. Key</a></span></dt><dt><span
class="section"><a href="#messages_request_analysis_eventType">4.3.2.7.
EventType</a></span></dt><dt><span class="section"><a
href="#messages_request_analysis_data">4.3.2.8.
Data</a></span></dt></dl></dd><dt><span class="section"><a
href="#messages_request_example">4.3.3. Request Message
Example</a></span></dt></dl></dd><dt><span class="section"><a
href="#messages_response">4.4. Response Messag
e</a></span></dt><dd><dl><dt><span class="section"><a href="!
#message
s_response_schema">4.4.1. Response Message Schema</a></span></dt><dt><span
class="section"><a href="#messages_response_analysis">4.4.2. Response Message
Analysis</a></span></dt><dd><dl><dt><span class="section"><a
href="#messages_response_analysis_message">4.4.2.1.
Message</a></span></dt><dt><span class="section"><a
href="#messages_response_analysis_parameters">4.4.2.2.
Parameters</a></span></dt><dt><span class="section"><a
href="#messages_response_analysis_parameter">4.4.2.3.
Parameter</a></span></dt><dt><span class="section"><a
href="#messages_response_analysis_metadata">4.4.2.4.
Metadata</a></span></dt><dt><span class="section"><a
href="#messages_response_analysis_data">4.4.2.5.
Data</a></span></dt></dl></dd><dt><span class="section"><a
href="#messages_response_example">4.4.3. Response Message
Example</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a
href="#chaining_info">5. Chaining</a></span></dt><dd><dl><dt><span
class="section"><a href="#merge_chaining_in
fo">5.1. Merge Chaining</a></span></dt><dd><dl><dt><span class="section"><a
href="#merge_chaining_recurse">5.1.1. Mergeable Elements and
Recursion</a></span></dt><dt><span class="section"><a
href="#merge_chaining_rules">5.1.2. Duplication, Augmentation, and
Replacement</a></span></dt><dt><span class="section"><a
href="#merge_chaining_ex">5.1.3. Merge Chaining
Examples</a></span></dt></dl></dd><dt><span class="section"><a
href="#filter_chaining_info">5.2. Operator (Filter)
Chaining</a></span></dt><dd><dl><dt><span class="section"><a
href="#filter_chaining_ex">5.2.1. Operator Chaining
Examples</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a
href="#result_codes">6. Result Codes</a></span></dt><dt><span
class="section"><a href="#extension">7.
Extension</a></span></dt><dd><dl><dt><span class="section"><a
href="#extension_echo">7.1. Echo Protocol</a></span></dt><dd><dl><dt><span
class="section"><a href="#extension_echo_architecture">7.1.1.
Architecture</a></span></
dt><dt><span class="section"><a href="#extension_echo_reques!
t_messag
e">7.1.2. Request Message</a></span></dt><dd><dl><dt><span class="section"><a
href="#extension_echo_request_schema">7.1.2.1. Request Message
Schema</a></span></dt><dt><span class="section"><a
href="#extension_echo_request_analysis">7.1.2.2. Request Message
Analysis</a></span></dt><dd><dl><dt><span class="section"><a
href="#extension_echo_request_analysis_message">7.1.2.2.1.
Message</a></span></dt><dt><span class="section"><a
href="#extension_echo_request_analysis_metadata">7.1.2.2.2.
Metadata</a></span></dt><dt><span class="section"><a
href="#extension_echo_request_analysis_eventtype">7.1.2.2.3.
EventType</a></span></dt><dt><span class="section"><a
href="#extension_echo_request_analysis_data">7.1.2.2.4.
Data</a></span></dt></dl></dd><dt><span class="section"><a
href="#extension_echo_request_example">7.1.2.3. Request Message
Example</a></span></dt></dl></dd><dt><span class="section"><a
href="#extension_echo_response_message">7.1.3. Response
Message</a></span></dt><dd><dl><dt><
span class="section"><a href="#extension_echo_response_schema">7.1.3.1.
Response Message Schema</a></span></dt><dt><span class="section"><a
href="#extension_echo_response_analysis">7.1.3.2. Response Message
Analysis</a></span></dt><dd><dl><dt><span class="section"><a
href="#extension_echo_response_analysis_message">7.1.3.2.1.
Message</a></span></dt><dt><span class="section"><a
href="#extension_echo_response_analysis_metadata">7.1.3.2.2.
Metadata</a></span></dt><dt><span class="section"><a
href="#extension_echo_response_analysis_eventtype">7.1.3.2.3.
EventType</a></span></dt><dt><span class="section"><a
href="#extension_echo_response_analysis_data">7.1.3.2.4.
Data</a></span></dt><dt><span class="section"><a
href="#extension_echo_response_analysis_datum">7.1.3.2.5.
Datum</a></span></dt></dl></dd><dt><span class="section"><a
href="#extension_echo_response_example">7.1.3.3. Response Message
Example</a></span></dt></dl></dd><dt><span class="section"><a
href="#extension_echo_resul
t_codes">7.1.4. Result Codes</a></span></dt><dt><span class=!
"section
"><a href="#extension_echo_protocol_extension">7.1.5. Protocol
Extension</a></span></dt><dd><dl><dt><span class="section"><a
href="#extension_echo_protocol_extension_eventType">7.1.5.1. eventType
Extension</a></span></dt><dt><span class="section"><a
href="#extension_echo_protocol_extension_other">7.1.5.2. Other
Extensions</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a
href="#extension_aa">7.2. Authentication and Authorization
Protocol</a></span></dt></dl></dd><dt><span class="section"><a
href="#conclusion">8. Conclusion</a></span></dt><dt><span class="glossary"><a
href="#glossary">Terms</a></span></dt><dt><span class="bibliography"><a
href="#bibliography">References</a></span></dt></dl></div><div
class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2
class="title" style="clear: both"><a id="changes"></a>1. Document
Changes</h2></div></div></div><div class="table"><a id="table.1"></a><p
class="title"><b>Table 1. Change Log</b></p><div
class="table-contents"><table summary="Change Log" border="1"><colgroup><col
align="left" /></colgroup><thead><tr><th align="left">Version</th><th
align="left">Date</th><th align="left">Description</th><th
align="left">Author(s)</th></tr></thead><tbody><tr><td
align="left">1.00</td><td align="left">04/03/2008</td><td
align="left">Initial Preparation</td><td align="left">J.
Zurawski</td></tr><tr><td align="left">1.01</td><td
align="left">04/07/2008</td><td align="left">Wording Edits</td><td
align="left">M. Swany</td></tr><tr><td align="left">1.02</td><td
align="left">05/30/2008</td><td align="left">Pre-OGF Cleanup</td><td
align="left">J. Zurawski</td></tr></tbody></table></div></div><br
class="table-break" /></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
id="introduction"></a>2. Introduction</h2></div></div></div><p>
+ [<a href="#id2546112"><span class="citation">perfSONAR</span></a>] is
an infrastructure for network
performance monitoring and data exchange. It consists of a set of
services
- delivering performance measurements in a federated environment. These
- services act as an intermediate layer, between the performance
measurement
- tools and the diagnostic or visualization applications.
+ capable of performing, storing, and exchanging performance measurements
+ in a federated environment. These services act as an intermediate
layer,
+ between the performance measurement tools and the diagnostic or
+ visualization applications.
</p><p>
This framework is designed in the <span
class="emphasis"><em>service-oriented</em></span>
style, implying that a set of elementary functions has been isolated
and
- can be provided by different software entities. In this model, all
- services must communicate using well-defined protocols. This document
- describes the base communication protocol to be used by all services
and
- clients in the
- <span class="emphasis"><em>perfSONAR</em></span> framework. These
communication protocols
- are based on and utilize the same <a href="#id2533357">XML</a>
structure used
- to exchange and store measurement data as defined by
- the <a href="#id2533320">NM-WG</a> in the <a href="#id2533375">OGF</a>.
+ can be delivered by potentially different software entities. In this
+ model, all services must communicate using well-defined protocols.
+ This document describes the base communication protocol to be used by
+ all services and clients in the <span
class="emphasis"><em>perfSONAR</em></span>
+ framework. These communication protocols are based on and utilize the
+ same [<a href="#id2546130"><span class="citation">XML</span></a>]
structure used to exchange and store
+ measurement data as defined by the [<a href="#id2546093"><span
class="citation">NM-WG</span></a>] in the
+ [<a href="#id2546148"><span class="citation">OGF</span></a>].
</p><p>
- This document will proceed as follows: we first examine why this
document
- is necessary and what it will achieve. We follow with a discussion of
the
- syntactic details and a semantic description of the major message
types.
- After, we introduce two common protocols used by every service in the
- <span class="emphasis"><em>perfSONAR</em></span> infrastructure: the
Echo and Authentication
- protocols. Finally we conclude with some description of other protocol
- documents.
+ This document will proceed as follows: in <a href="#motivation"
title="3. Motivation">Motivation</a> we
+ examine why this document is necessary and what it will achieve. In
+ <a href="#messages" title="4. Messages">Messages</a> a discussion of
the syntactic details and a
+ semantic description of the major message types is discussed. To
motivate
+ some future work, a discussion of <a href="#chaining_info"
title="5. Chaining">Chaining</a> is
+ included next. A discussion of some of the common error and status
codes
+ is brought up in <a href="#result_codes" title="6. Result
Codes">Result Codes</a>. After this we introduce
+ two common protocols in <a href="#extension"
title="7. Extension">Extension</a> used by every
+ service in the <span class="emphasis"><em>perfSONAR</em></span>
infrastructure: the Echo and
+ Authentication protocols. Finally we conclude with some description of
+ other protocol documents in <a href="#conclusion"
title="8. Conclusion">Conclusion</a>.
</p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
id="motivation"></a>3. Motivation</h2></div></div></div><p>
- A common message exchange pattern in <span
class="emphasis"><em>perfSONAR</em></span> is
- a <span class="emphasis"><em>Request</em></span> followed by
- a <span class="emphasis"><em>Response</em></span>. As this pattern
is important, we will
- show a basic interaction and build on it. Consider this example of
a
- client application interacting with some <span
class="emphasis"><em>perfSONAR</em></span>
- service in search of data.
- </p><p>
+ A common message exchange pattern in <span
class="emphasis"><em>perfSONAR</em></span> is
+ a <span class="emphasis"><em>Request</em></span> followed by
+ a <span class="emphasis"><em>Response</em></span>. As this
pattern is important, we will
+ show a basic interaction and build on it. Consider this example
of a
+ client application interacting with some <span
class="emphasis"><em>perfSONAR</em></span>
+ service in search of data.
+ </p><p>
+ Consider the following exchange diagram demonstrating the exchange
pattern
+ between two <span class="emphasis"><em>perfSONAR</em></span> entities.
+ </p><p>
</p><div class="mediaobject"><img src="exchange.png" /></div><p>
</p><p>
It becomes the burden of <span class="emphasis"><em>both</em></span>
the service developer
@@ -46,6 +54,15 @@
</p><p>
</p><div class="mediaobject"><img src="exchange2.png" /></div><p>
</p><p>
+ A less common interaction is the notion of a
+ <span><strong class="command">subscription</strong></span>,
<span><strong class="command">notification</strong></span> or
+ other form of <span class="emphasis"><em>one-sided</em></span>
exchange.
+ <span class="emphasis"><em>perfSONAR</em></span> currently uses this
to perform tasks such
+ as <span class="emphasis"><em>subscribing</em></span> to a service, or
otherwise notifying
+ a service or client about the existence of some key piece of
information.
+ </p><p>
+ </p><div class="mediaobject"><img src="exchange3.png" /></div><p>
+ </p><p>
Essentially, the acts of sending messages, receiving responses, and
being
able to discern success or failure are common across many specific
interactions. One aim of this document is to prevent the following
@@ -53,16 +70,20 @@
</p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong class="command">Duplicate
Schemata</strong></span> - Messages will differ
from service to service, but the overarching concepts will not; we
present some of the common features that must be present in every
- exchange and describe how extension is possible.</p></li><li
style="list-style-type: circle"><p><span><strong class="command">Duplicate
Error Conditions</strong></span> - Some errors will
+ exchange and describe how extension is possible.</p></li><li
style="list-style-type: circle"><p><span><strong class="command">Duplicate
Semantic Principals</strong></span> - Concepts used
+ in services designed in the past will more than likely carryover into
+ future releases. Identifying and describing common practices will
+ save time in the documentation of common features.</p></li><li
style="list-style-type: circle"><p><span><strong class="command">Duplicate
Error Conditions</strong></span> - Some errors will
occur across services and do not need to be defined repeatedly
(e.g. Unknown Message Type).</p></li><li style="list-style-type:
circle"><p><span><strong class="command">Duplication of Common
Exchanges</strong></span> - Every service
in perfSONAR is capable of receiving and acting upon common protocols
such as <span class="emphasis"><em>Echo</em></span> and <span
class="emphasis"><em>AA</em></span>. These
will be presented as the first two <span
class="emphasis"><em>extensions</em></span> to
this base.</p></li></ul></div><p>
- With this base, it will be possible to define protocol extensions on
- a <span class="emphasis"><em>type-by-type</em></span> basis instead of
- <span class="emphasis"><em>service by service</em></span>. This also
allows for a
+ With a set design and format to this base functionality, it is
+ possible to define protocol extensions on a
+ <span class="emphasis"><em>type-by-type</em></span> basis instead of
through the current
+ <span class="emphasis"><em>service by service</em></span> approach.
This also allows for a
sufficient reduction in documentation due to service types implementing
the same underlying format of messages (e.g. Measurement Archives
mostly
implement the same message types with notable exceptions and data
@@ -99,10 +120,12 @@
</p></li><li style="list-style-type: circle"><p><span><strong
class="command">Message Structure</strong></span> - There may be many
metadata and data elements in each message, and there does not
need to
be a matching data for <span
class="emphasis"><em>every</em></span> metadata (e.g.
- chaining)
- </p></li><li style="list-style-type: circle"><p><span><strong
class="command">Metadata</strong></span> - Can contain measurement data, or
- perhaps identifying information about a service, note that we
still
- loosely observe the <span class="emphasis"><em>static</em></span>
rule of thumb</p></li><li style="list-style-type: circle"><p><span><strong
class="command">Data</strong></span> - Serves a dual role: in request
+ <a href="#chaining_info" title="5. Chaining">Chaining</a>)
+ </p></li><li style="list-style-type: circle"><p><span><strong
class="command">Metadata</strong></span> - Can contain measurement data,
+ identifying information about a service, or even information meant
to
+ serve as a modifier (see <a href="#chaining_info"
title="5. Chaining">Chaining</a>). Note that
+ we still loosely observe the <span
class="emphasis"><em>static</em></span> rule of
+ thumb</p></li><li style="list-style-type: circle"><p><span><strong
class="command">Data</strong></span> - Serves a dual role: in request
messages this may be empty (e.g. this is a data trigger, it lets
the
service know we need action on the accompanying metadata), or it
can
contain <span class="emphasis"><em>dynamic</em></span> measurement
data or even other
@@ -111,12 +134,12 @@
getting back some data that matches the sent metadata. This metadata
may be partial or complete. When the service receives this request
it
will check for several things:
- </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">Syntax</strong></span> - Does the XML parse</p></li><li
style="list-style-type: circle"><p><span><strong class="command">Message
Type</strong></span> - Can this service accept and
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">Syntax</strong></span> - Does the request parse
+ correctly</p></li><li style="list-style-type:
circle"><p><span><strong class="command">Message Type</strong></span> - Can
this service accept and
act on this kind of message</p></li><li style="list-style-type:
circle"><p><span><strong class="command">Structure</strong></span> - Is there
at least a single
- metadata and data pair that is capable of being acted on; do any
- chains resolve properly</p></li><li style="list-style-type:
circle"><p><span><strong class="command">Semantics</strong></span> - Does the
request make sense, can
- the metadata be acted upon</p></li></ul></div><p>
- The service has two options at this point: acting on the message and
+ metadata and data pair that is capable of being acted
on</p></li><li style="list-style-type: circle"><p><span><strong
class="command">Semantics</strong></span> - Does the request make sense, can
+ the metadata be acted upon; are the chains resolved
properly</p></li></ul></div><p>
+ The service has two options at this point: acting on the message
returning data or reporting some other form of status. We will
explore
the first option initially:
</p><pre class="programlisting">
@@ -165,7 +188,7 @@
&lt;message type="response"&gt;

&lt;metadata id="m1"&gt;
- &lt;!-- some error code --&gt;
+ &lt;!-- some error information --&gt;
&lt;/metadata&gt;

&lt;data id="d1" metadatIdRef="m1"&gt;
@@ -175,7 +198,7 @@
&lt;/message&gt;

</pre></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
id="messages_actions"></a>4.2. Message Actions</h3></div></div></div><p>
- The example from <a href="#messages_example">Preliminary Example</a>
characterizes many
+ The example from <a href="#messages_example" title="4.1. Preliminary
Example">Preliminary Example</a> characterizes many
of the common actions services perform on receipt of a request
message.
A more formal description of this interaction is described below.
Note
that this is a generalized attempt, and does not directly reflect the
@@ -196,16 +219,16 @@
communication to <span class="emphasis"><em>perfSONAR</em></span>
capable services.
Enclosed in this simple envelope will be a series of metadata and
data
pairs containing various instructions to act on. We first present
- a very simple schema in <a href="#messages_request_schema">Request
Message Schema</a> along
+ a very simple schema in <a href="#messages_request_schema"
title="4.3.1. Request Message Schema">Request Message Schema</a> along
with an analysis of the elements in
- <a href="#messages_request_analysis">Request Message Analysis</a>.
We conclude with examples
- in <a href="#messages_request_example">Request Message Example</a>.
+ <a href="#messages_request_analysis" title="4.3.2. Request Message
Analysis">Request Message Analysis</a>. We conclude with examples
+ in <a href="#messages_request_example" title="4.3.3. Request Message
Example">Request Message Example</a>.
</p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="messages_request_schema"></a>4.3.1. Request Message
Schema</h4></div></div></div><p>
The following schema is a native description of the request schema
as
- in the <a href="#id2533392">RELAX-NG</a> language. Through the
use of
- tools such as <a href="#id2533411">Trang</a> and <a
href="#id2533430">Multi-Schema XML Validator</a>
+ in the [<a href="#id2546166"><span
class="citation">RELAX-NG</span></a>] language. Through the use of
+ tools such as [<a href="#id2546184"><span
class="citation">Trang</span></a>] and [<a href="#id2546203"><span
class="citation">MSV</span></a>]
it is possible to convert this to other widely accepted formats
such
- as <a href="#id2533448">XSD</a>.
+ as [<a href="#id2546222"><span class="citation">XSD</span></a>].
</p><pre class="programlisting">

<font color=red># Begin Schema</font>
@@ -311,9 +334,9 @@
There are three major elements that may be contained in the
message
element:
</p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">Parameters</strong></span> - Described in
- <a
href="#messages_request_analysis_parameters">Parameters</a></p></li><li
style="list-style-type: circle"><p><span><strong
class="command">Metadata</strong></span> - Described in
- <a
href="#messages_request_analysis_metadata">Metadata</a></p></li><li
style="list-style-type: circle"><p><span><strong
class="command">Data</strong></span> - Described in
- <a
href="#messages_request_analysis_data">Data</a></p></li></ul></div></div><div
class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5
class="title"><a
id="messages_request_analysis_parameters"></a>4.3.2.2. Parameters</h5></div></div></div><pre
class="programlisting">
+ <a href="#messages_request_analysis_parameters"
title="4.3.2.2. Parameters">Parameters</a></p></li><li
style="list-style-type: circle"><p><span><strong
class="command">Metadata</strong></span> - Described in
+ <a href="#messages_request_analysis_metadata"
title="4.3.2.4. Metadata">Metadata</a></p></li><li style="list-style-type:
circle"><p><span><strong class="command">Data</strong></span> - Described in
+ <a href="#messages_request_analysis_data"
title="4.3.2.8. Data">Data</a></p></li></ul></div></div><div class="section"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h5 class="title"><a
id="messages_request_analysis_parameters"></a>4.3.2.2. Parameters</h5></div></div></div><pre
class="programlisting">

&lt;nmwg:parameters xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="parameters1"&gt;

@@ -323,9 +346,9 @@

</pre><div class="table"><a
id="table.messages_request_analysis_parameters"></a><p
class="title"><b>Table 3. Parameters Element Requirements</b></p><div
class="table-contents"><table summary="Parameters Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">parameters</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">no</td></tr></tbody></table></div></div><br class="table-break"
/><p>
The parameters element encloses a series of parameter elements
that
- can be used to adjust variable aspects of a request message.
This
- element serves merely as a container for the
- <a href="#messages_request_analysis_parameter">Parameter</a>
elements that
+ can be used to adjust variable aspects of many parts of this
+ schema. This element serves merely as a container for the
+ <a href="#messages_request_analysis_parameter"
title="4.3.2.3. Parameter">Parameter</a> elements that
will populate it. The single available attribute is described
first:
</p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">id</strong></span> - Identifying attribute that can be
@@ -333,7 +356,7 @@
There is only one available element, although it can be used
multiple times.
</p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">Parameter</strong></span> - Described in
- <a
href="#messages_request_analysis_parameter">Parameter</a></p></li></ul></div></div><div
class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5
class="title"><a
id="messages_request_analysis_parameter"></a>4.3.2.3. Parameter</h5></div></div></div><pre
class="programlisting">
+ <a href="#messages_request_analysis_parameter"
title="4.3.2.3. Parameter">Parameter</a></p></li></ul></div></div><div
class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5
class="title"><a
id="messages_request_analysis_parameter"></a>4.3.2.3. Parameter</h5></div></div></div><pre
class="programlisting">

&lt;nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
name="NAME"&gt;VALUE&lt;/nmwg:parameter&gt;
@@ -357,16 +380,35 @@
</p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="messages_request_analysis_metadata"></a>4.3.2.4. Metadata</h5></div></div></div><pre
class="programlisting">

&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
- id="metadata2" metadataIdRef="metadata1" /&gt;
+ id="metadata2" metadataIdRef="metadata1"&gt;
+
+ &lt;!-- Possible Values Include: --&gt;
+
+ &lt;nmwg:subject /&gt;
+
+ &lt;nmwg:key /&gt;
+
+ &lt;nmwg:eventType /&gt;
+
+ &lt;nmwg:parameters /&gt;
+
+&lt;/nmwg:metadata&gt;

- </pre><div class="table"><a
id="table.messages_request_analysis_metadata"></a><p
class="title"><b>Table 5. Metadata Element Requirements</b></p><div
class="table-contents"><table summary="Metadata Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">undefined</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ </pre><div class="table"><a
id="table.messages_request_analysis_metadata"></a><p
class="title"><b>Table 5. Metadata Element Requirements</b></p><div
class="table-contents"><table summary="Metadata Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">undefined, (subject, eventType, and parameters are
common)</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br cl
ass="table-break" /><p>
The metadata element normally contains the static parts of
measurements, and will no doubt differ from service
to service. Besides measurement data it is possible to send
other
- items such as service descriptions. We leave the description of
- what is possible inside of a metadata blank, and use vague schema
- language that allows for <span
class="emphasis"><em>any</em></span> reasonable XML
- to be contained within.
+ items such as service descriptions. The schema description
itself
+ of what is possible inside of this element uses vague language
that
+ allows for <span class="emphasis"><em>any</em></span> reasonable
XML to be contained
+ within. The most common elements that are included are
+ <a href="#messages_request_analysis_subject"
title="4.3.2.5. Subject">Subject</a>,
+ <a href="#messages_request_analysis_key"
title="4.3.2.6. Key">Key</a>,
+ <a href="#messages_request_analysis_eventType"
title="4.3.2.7. EventType">EventType</a>, and
+ <a href="#messages_request_analysis_parameters"
title="4.3.2.2. Parameters">Parameters</a>. We will
+ present only a brief discussion of these within this document; a
+ more exact definition may be found in specific measurement
+ documentation.
</p><p>
There are two attributes possible. These are used to both track
state and perform the various forms of chaining (e.g.
@@ -375,12 +417,57 @@
follows:
</p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">id</strong></span> - Identifying attribute that can be
used to track state.</p></li><li style="list-style-type:
circle"><p><span><strong class="command">metadataIdRef</strong></span> -
Identifying attribute
- that can be used to track state or be linked to
chaining.</p></li></ul></div></div><div class="section" lang="en"
xml:lang="en"><div class="titlepage"><div><div><h5 class="title"><a
id="messages_request_analysis_data"></a>4.3.2.5. Data</h5></div></div></div><pre
class="programlisting">
+ that can be used to track state or be linked to
chaining.</p></li></ul></div></div><div class="section" lang="en"
xml:lang="en"><div class="titlepage"><div><div><h5 class="title"><a
id="messages_request_analysis_subject"></a>4.3.2.5. Subject</h5></div></div></div><pre
class="programlisting">

+&lt;nmwg:subject xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ id="subject1" metadataIdRef="metadata1" /&gt;
+
+ </pre><div class="table"><a
id="table.messages_request_analysis_subject"></a><p
class="title"><b>Table 6. Subject Element Requirements</b></p><div
class="table-contents"><table summary="Subject Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">subject</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">undefined, (topology elements are common)</td></tr><tr><td
align="left"><span><strong class="command">required</strong></span></td><td
align="left">N/A</td></tr></tbody></table></div></div><br class="table-break"
/><
p>
+ The subject element normally contains topological information
that
+ relates directly to a measurement or may refer to a specific
+ service. We leave a full description of this element up to
+ individual implementations but mention it here due to its common
+ use. There are two attributes possible. These are used to both
+ track state and perform a specific type of chaining (e.g.
+ <span class="emphasis"><em>subject</em></span>) that may be
required in a request
+ message. A detailed description follows:
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">id</strong></span> - Identifying attribute that can be
+ used to track state.</p></li><li style="list-style-type:
circle"><p><span><strong class="command">metadataIdRef</strong></span> -
Identifying attribute
+ that can be used to track state or be linked to
chaining.</p></li></ul></div></div><div class="section" lang="en"
xml:lang="en"><div class="titlepage"><div><div><h5 class="title"><a
id="messages_request_analysis_key"></a>4.3.2.6. Key</h5></div></div></div><pre
class="programlisting">
+
+&lt;nmwg:key xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"&gt;
+
+ &lt;nmwg:parameters /&gt;
+
+&lt;/nmwg:key&gt;
+
+ </pre><div class="table"><a
id="table.messages_request_analysis_key"></a><p class="title"><b>Table 7. Key
Element Requirements</b></p><div class="table-contents"><table summary="Key
Element Requirements" border="1"><colgroup><col align="left"
/></colgroup><tbody><tr><td align="left"><span><strong
class="command">localname</strong></span></td><td
align="left">key</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">parameters</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">N/A</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ The key structure is normally used to convey sensitive or private
+ information to and from the service. For this reason the
contents
+ of the key should be viewed as opaque, and generally not be
+ disected. The key normally contains the
+ <a href="#messages_request_analysis_parameters"
title="4.3.2.2. Parameters">Parameters</a> element.
+ There is only one attributes possible: id. This is used to
+ track state. A detailed description follows:
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">id</strong></span> - Identifying attribute that can be
+ used to track state.</p></li></ul></div></div><div
class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5
class="title"><a
id="messages_request_analysis_eventType"></a>4.3.2.7. EventType</h5></div></div></div><pre
class="programlisting">
+
+&lt;nmwg:eventType
xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"&gt;TEXT&lt;/nmwg:eventType&gt;
+
+ </pre><div class="table"><a
id="table.messages_request_analysis_eventType"></a><p
class="title"><b>Table 8. EventType Element Requirements</b></p><div
class="table-contents"><table summary="EventType Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">eventType</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">N/A</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">N/A</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ The <span class="emphasis"><em>eventType</em></span> element is
commonly used to
+ describe a measurement's specific data type (e.g. corresponding
to
+ the characteristic document) or may be used to trigger an
internal
+ event within the service. This element contains no attributes,
and
+ can only contain text, normally in the form of a
+ <span class="emphasis"><em>URI</em></span>. There may be many
+ <span class="emphasis"><em>eventType</em></span> elements in a
single metadata.
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="messages_request_analysis_data"></a>4.3.2.8. Data</h5></div></div></div><pre
class="programlisting">
+
&lt;nmwg:data xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="data2" metadataIdRef="metadata2" /&gt;

- </pre><div class="table"><a
id="table.messages_request_analysis_data"></a><p
class="title"><b>Table 6. Data Element Requirements</b></p><div
class="table-contents"><table summary="Data Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">undefined</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ </pre><div class="table"><a
id="table.messages_request_analysis_data"></a><p
class="title"><b>Table 9. Data Element Requirements</b></p><div
class="table-contents"><table summary="Data Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">undefined</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
The data element normally contains the dynamic parts of
measurements, and will no doubt differ from service to service.
Besides collected measurements the data field may also be
populated
@@ -520,20 +607,20 @@

</pre></div></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
id="messages_response"></a>4.4. Response Message</h3></div></div></div><p>
The response message is a container filled with the results of a
- <a href="#messages_request">Request Message</a> from
+ <a href="#messages_request" title="4.3. Request Message">Request
Message</a> from
<span class="emphasis"><em>perfSONAR</em></span> capable services.
Enclosed in this
simple envelope will be a series of metadata and data
pairs containing the results of actions performed by a service. We
first
present a very simple schema in
- <a href="#messages_response_schema">Response Message Schema</a>
along with an analysis of
- the elements in <a href="#messages_response_analysis">Response
Message Analysis</a>. We
- conclude with examples in <a
href="#messages_response_example">Response Message Example</a>.
+ <a href="#messages_response_schema" title="4.4.1. Response Message
Schema">Response Message Schema</a> along with an analysis of
+ the elements in <a href="#messages_response_analysis"
title="4.4.2. Response Message Analysis">Response Message Analysis</a>. We
+ conclude with examples in <a href="#messages_response_example"
title="4.4.3. Response Message Example">Response Message Example</a>.
</p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="messages_response_schema"></a>4.4.1. Response Message
Schema</h4></div></div></div><p>
The following schema is a native description of the response
schema as
- in the <a href="#id2533392">RELAX-NG</a> language. Through the
use of
- tools such as <a href="#id2533411">Trang</a> and <a
href="#id2533430">Multi-Schema XML Validator</a>
+ in the [<a href="#id2546166"><span
class="citation">RELAX-NG</span></a>] language. Through the use of
+ tools such as [<a href="#id2546184"><span
class="citation">Trang</span></a>] and [<a href="#id2546203"><span
class="citation">MSV</span></a>]
it is possible to convert this to other widely accepted formats
such
- as <a href="#id2533448">XSD</a>.
+ as [<a href="#id2546222"><span class="citation">XSD</span></a>].
</p><pre class="programlisting">

<font color=red># Begin Schema</font>
@@ -627,9 +714,9 @@

&lt;/nmwg:message&gt;

- </pre><div class="table"><a
id="table.messages_response_analysis_message"></a><p
class="title"><b>Table 7. Message Element Requirements</b></p><div
class="table-contents"><table summary="Message Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">message</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, type</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">parameters, metadata, data</td></tr><tr><td
align="left"><span><strong class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ </pre><div class="table"><a
id="table.messages_response_analysis_message"></a><p
class="title"><b>Table 10. Message Element Requirements</b></p><div
class="table-contents"><table summary="Message Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">message</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, type</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">parameters, metadata, data</td></tr><tr><td
align="left"><span><strong class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
The message element, like it's counterpart seen in
- <a href="#messages_response_analysis_message">Message</a> serves
as a
+ <a href="#messages_response_analysis_message"
title="4.4.2.1. Message">Message</a> serves as a
container for transporting responses from
<span class="emphasis"><em>perfSONAR</em></span> capable
services. The message itself
is unremarkable, it features attributes to aid in the
identification
@@ -642,9 +729,9 @@
There are three major elements that may be contained in the
message
element:
</p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">Parameters</strong></span> - Described in
- <a
href="#messages_response_analysis_parameters">Parameters</a></p></li><li
style="list-style-type: circle"><p><span><strong
class="command">Metadata</strong></span> - Described in
- <a
href="#messages_response_analysis_metadata">Metadata</a></p></li><li
style="list-style-type: circle"><p><span><strong
class="command">Data</strong></span> - Described in
- <a
href="#messages_response_analysis_data">Data</a></p></li></ul></div></div><div
class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5
class="title"><a
id="messages_response_analysis_parameters"></a>4.4.2.2. Parameters</h5></div></div></div><pre
class="programlisting">
+ <a href="#messages_response_analysis_parameters"
title="4.4.2.2. Parameters">Parameters</a></p></li><li
style="list-style-type: circle"><p><span><strong
class="command">Metadata</strong></span> - Described in
+ <a href="#messages_response_analysis_metadata"
title="4.4.2.4. Metadata">Metadata</a></p></li><li style="list-style-type:
circle"><p><span><strong class="command">Data</strong></span> - Described in
+ <a href="#messages_response_analysis_data"
title="4.4.2.5. Data">Data</a></p></li></ul></div></div><div class="section"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h5 class="title"><a
id="messages_response_analysis_parameters"></a>4.4.2.2. Parameters</h5></div></div></div><pre
class="programlisting">

&lt;nmwg:parameters xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="parameters1"&gt;

@@ -652,15 +739,16 @@

&lt;/nmwg:parameters&gt;

- </pre><div class="table"><a
id="table.messages_response_analysis_parameters"></a><p
class="title"><b>Table 8. Parameters Element Requirements</b></p><div
class="table-contents"><table summary="Parameters Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">parameters</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">no</td></tr></tbody></table></div></div><br class="table-break"
/><p>
- The parameters element is normally only present if there was a
- corresponding element in
- <a href="#messages_response_analysis_message">Message</a>,
although it
- can be used by services to relay back other forms of information.
- As in <a
href="#messages_response_analysis_parameters">Parameters</a>, it
- encloses a series of parameter elements that. This element
serves
+ </pre><div class="table"><a
id="table.messages_response_analysis_parameters"></a><p
class="title"><b>Table 11. Parameters Element Requirements</b></p><div
class="table-contents"><table summary="Parameters Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">parameters</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">no</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ The parameters element is normally only present in the message
+ element, if there was a corresponding element in
+ <a href="#messages_response_analysis_message"
title="4.4.2.1. Message">Message</a>. It
+ can also be used by services to relay back other forms of
+ information. As in
+ <a href="#messages_response_analysis_parameters"
title="4.4.2.2. Parameters">Parameters</a>, it
+ encloses a series of parameter elements. This element serves
merely as a container for the
- <a href="#messages_response_analysis_parameter">Parameter</a>
elements
+ <a href="#messages_response_analysis_parameter"
title="4.4.2.3. Parameter">Parameter</a> elements
that will populate it. The single available attribute is
described
first:
</p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">id</strong></span> - Identifying attribute that can be
@@ -668,7 +756,7 @@
There is only one available element, although it can be used
multiple times.
</p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">Parameter</strong></span> - Described in
- <a
href="#messages_response_analysis_parameter">Parameter</a></p></li></ul></div></div><div
class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5
class="title"><a
id="messages_response_analysis_parameter"></a>4.4.2.3. Parameter</h5></div></div></div><pre
class="programlisting">
+ <a href="#messages_response_analysis_parameter"
title="4.4.2.3. Parameter">Parameter</a></p></li></ul></div></div><div
class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5
class="title"><a
id="messages_response_analysis_parameter"></a>4.4.2.3. Parameter</h5></div></div></div><pre
class="programlisting">

&lt;nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
name="NAME"&gt;VALUE&lt;/nmwg:parameter&gt;
@@ -678,7 +766,7 @@
&lt;nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
name="NAME" value="VALUE" /&gt;

- </pre><div class="table"><a
id="table.messages_response_analysis_parameter"></a><p
class="title"><b>Table 9. Parameter Element Requirements</b></p><div
class="table-contents"><table summary="Parameter Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">name, value</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ </pre><div class="table"><a
id="table.messages_response_analysis_parameter"></a><p
class="title"><b>Table 12. Parameter Element Requirements</b></p><div
class="table-contents"><table summary="Parameter Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">name, value</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
The parameter element features a generic structure that allows
it to
easily adapt to the needs of a particular schema. Possible names
and values will not be enumerated here, but will be done both at
the
@@ -692,30 +780,50 @@
</p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="messages_response_analysis_metadata"></a>4.4.2.4. Metadata</h5></div></div></div><pre
class="programlisting">

&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
- id="metadata2" metadataIdRef="metadata1" /&gt;
+ id="metadata2" metadataIdRef="metadata1"&gt;
+
+ &lt;!-- These elements are commonly used: --&gt;
+
+ &lt;nwmg:subject /&gt;
+
+ &lt;nmwg:key /&gt;
+
+ &lt;nmwg:eventType /&gt;
+
+ &lt;nmwg:parameters /&gt;
+
+&lt;/nmwg:metadata&gt;

- </pre><div class="table"><a
id="table.messages_response_analysis_metadata"></a><p
class="title"><b>Table 10. Metadata Element Requirements</b></p><div
class="table-contents"><table summary="Metadata Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">undefined</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ </pre><div class="table"><a
id="table.messages_response_analysis_metadata"></a><p
class="title"><b>Table 13. Metadata Element Requirements</b></p><div
class="table-contents"><table summary="Metadata Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">undefined, (subject, key, eventType, and parameters are
common)</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div
><br class="table-break" /><p>
The metadata element in the response is normally an exact copy of
- the sent <a
href="#messages_response_analysis_metadata">Metadata</a>.
+ the sent <a href="#messages_response_analysis_metadata"
title="4.4.2.4. Metadata">Metadata</a>.
We leave the description of what is possible inside of a metadata
blank, and use vague schema language that allows for
<span class="emphasis"><em>any</em></span> reasonable XML to be
contained within.
</p><p>
There are two attributes possible. These are used to both track
state, possibly back to the sent
- <a href="#messages_response_analysis_metadata">Metadata</a>. A
detailed
+ <a href="#messages_response_analysis_metadata"
title="4.4.2.4. Metadata">Metadata</a>. A detailed
description follows:
</p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">id</strong></span> - Identifying attribute that can be
used to track state.</p></li><li style="list-style-type:
circle"><p><span><strong class="command">metadataIdRef</strong></span> -
Identifying attribute
that can be used to track state.</p></li></ul></div></div><div
class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5
class="title"><a
id="messages_response_analysis_data"></a>4.4.2.5. Data</h5></div></div></div><pre
class="programlisting">

&lt;nmwg:data xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
- id="data2" metadataIdRef="metadata2" /&gt;
+ id="data2" metadataIdRef="metadata2"&gt;
+
+ &lt;nmwg:datum /&gt;
+
+ &lt;nmwg:key /&gt;
+
+ &lt;nmwg:metadata /&gt;
+
+&lt;/nmwg:data&gt;

- </pre><div class="table"><a
id="table.messages_response_analysis_data"></a><p
class="title"><b>Table 11. Data Element Requirements</b></p><div
class="table-contents"><table summary="Data Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">undefined</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ </pre><div class="table"><a
id="table.messages_response_analysis_data"></a><p
class="title"><b>Table 14. Data Element Requirements</b></p><div
class="table-contents"><table summary="Data Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">undefined, (datum, key, and metadata are
common)</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
The data element will contain results and is usually not not
empty
like the trigger that is used in
- <a href="#messages_response_analysis_data">Data</a>. We leave
the
+ <a href="#messages_response_analysis_data"
title="4.4.2.5. Data">Data</a>. We leave the
description of what is possible inside of a data blank, and use
vague schema language that allows for <span
class="emphasis"><em>any</em></span>
reasonable XML to be contained within.
@@ -804,7 +912,726 @@

&lt;!-- End XML --&gt;

- </pre></div></div></div><div class="section" lang="en"
xml:lang="en"><div class="titlepage"><div><div><h2 class="title"
style="clear: both"><a id="result_codes"></a>5. Result
Codes</h2></div></div></div><p>
+ </pre></div></div></div><div class="section" lang="en"
xml:lang="en"><div class="titlepage"><div><div><h2 class="title"
style="clear: both"><a
id="chaining_info"></a>5. Chaining</h2></div></div></div><p>
+ Since inception a key goal of the [<a href="#id2546093"><span
class="citation">NM-WG</span></a>]
+ [<a href="#id2546130"><span class="citation">XML</span></a>]
specification has been extension. The
+ authors of the original <a href="#schemata"
title="schemata">schemata</a> realized that not
+ every situation could easily be described though the basic constructs;
+ extending the basic building blocks to complex situations would be
+ paramount. Uncharted concepts could be represented with newly created
+ constructs each time a foreign abstraction came to light; but extension
+ and backwards compatibility must be favored over quick and easy
+ solutions. Therefore, basic extension mechanisms, known as
+ <a href="#chaining" title="chaining">chaining</a>, are the recognized
procedure to extend
+ [<a href="#id2546112"><span class="citation">perfSONAR</span></a>]
metadata constructs as well as express
+ other operations on the underlying data.
+ </p><p>
+ This section presents the major uses of chaining; note that individual
+ service implementations may choose to strictly or loosely interpret
these
+ guidelines for the sake of performance or protection. The protocol
itself
+ offers no specific guidance on these issues in favor of simply
describing
+ the structural composition of both the input data and the resulting
+ output.
+ </p><p>
+ Chaining itself has taken on two major forms: <a
href="#merge_chaining" title="merge chaining">merge chaining</a>
+ and <a href="#filter_chaining" title="filter chaining">filter
chaining</a>.
+ These two instances will be described first in broad
+ terms that explain the logic and reasoning of why each operation makes
+ sense, and in what context they should be employed. The specific
syntax
+ and transformation steps will be presented in the next section.
+ </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
id="merge_chaining_info"></a>5.1. Merge Chaining</h3></div></div></div><p>
+ As the name implies, we intend to <span
class="emphasis"><em>merge</em></span> or combine metadata elements
+ through this structure. There are many things we may consider when
+ describing this operation:
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p>Which elements are <span
class="emphasis"><em>mergeable</em></span>?</p></li><li
style="list-style-type: circle"><p>How much <span
class="emphasis"><em>recursion</em></span> is needed for mergeable
elements?</p></li><li style="list-style-type: circle"><p>When do we <span
class="emphasis"><em>duplicate</em></span> elements?</p></li><li
style="list-style-type: circle"><p>When should we <span
class="emphasis"><em>replace</em></span> elements in the course of
merging?</p></li></ul></div><p>
+ As stated previously, the schemata itself does not offer any
suggestions
+ as to what is a good merge vs. a bad merge. There are no rules
+ regarding which <span class="emphasis"><em>types</em></span> of data
should and should
+ not be merged. There is no guidance on when we can duplicate or
+ replace elements.
+ </p><p>
+ We present here some very simple and succinct guidelines that
services
+ may implement for this particular style of merging. There will
always
+ be exceptions to rules, therefore the reader is encouraged to think
+ carefully about what a specific service may need when implementing
this
+ recommendation.
+ </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="merge_chaining_recurse"></a>5.1.1. Mergeable Elements and
Recursion</h4></div></div></div><p>
+ In general when merging we first look at the <span
class="emphasis"><em>top-level</em></span> elements;
+ namely subject, eventType, and parameters. When faced with
+ two metadata blocks to be merged, we only wish to combine <span
class="emphasis"><em>like</em></span>
+ elements that share a common namespace. When this first criteria
is
+ met, we will of course recurse downward and keep trying until we
+ reach the bottom of the structure.
+ </p><p>
+ How far should we venture into the XML structure looking for
+ similarities or differences? This question does not have a
definite
+ answer such as <span class="emphasis"><em>stop at the grandchild
of the current element</em></span>. While
+ this may be frustrating, domain knowledge can help you make a
passable
+ decision especially with regards to topology based elements.
+ </p><p>
+ <span class="emphasis"><em>Like</em></span> elements that do not
share a common namespace will require
+ special rules that may differ from service to service. Depending
on
+ the level of protection or speed we wish to attain these rules will
+ vary. Service and protocol documentation will fill in details
beyond
+ the scope of this memo.
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="merge_chaining_rules"></a>5.1.2. Duplication, Augmentation, and
Replacement</h4></div></div></div><p>
+ When are faced with <span class="emphasis"><em>like</em></span>
elements that may not share a common
+ namespace we shouldn't really combine at all. We can try to find
the
+ <span class="emphasis"><em>least significant</em></span> namespace
and work from there. Additionally we
+ will sometimes run into items that may be exactly the same (such as
+ certain <span class="emphasis"><em>parameters</em></span>, or
<span class="emphasis"><em>eventTypes</em></span>). In some cases we should
take
+ care to <span class="emphasis"><em>add</em></span> all of these
together to make duplicates; other cases
+ may dictate total replacement. Specific rule such as these are
best
+ left to a service designer.
+ </p><p>
+ As an example of extreme cases, consider taking the very safe
approach
+ to the combining of elements (i.e. not merging <span
class="emphasis"><em>like</em></span> elements with
+ different namespaces). This approach will ensure that we protect
the
+ from schema differences but may result in many more <span
class="emphasis"><em>wrong</em></span> answers
+ when it comes to searching. The converse is a very dangerous
approach
+ we we do in fact merge items that could be different on the inside.
+ This will result in an approach similar to <span
class="emphasis"><em>I know what you meant</em></span> and
+ could yield a more robust query mechanism (providing intuitive
answers
+ when something may not completely match, rejecting outright things
+ that do not make sense).
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="merge_chaining_ex"></a>5.1.3. Merge Chaining
Examples</h4></div></div></div><p>
+ A classic example of merge chaining is to partially specify a
metadata
+ (leaving out perhaps one key element) and then constructing new
elements
+ from this original. This example does not feature any <span
class="emphasis"><em>overwriting</em></span> of
+ duplicate elements.
+ </p><p>
+ Take for example our SNMP Interface from above. If e wanted to
specify
+ the two common <span class="emphasis"><em>directions</em></span>
(<span class="emphasis"><em>in</em></span> and <span
class="emphasis"><em>out</em></span>) we could construct a chain
+ similar to the below example.
+ </p><pre class="programlisting">
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1"&gt;
+ &lt;netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:direction&gt;in&lt;/nmwgt:direction&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/netutil:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:eventType&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:parameter&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="m1"&gt;
+ &lt;netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s2"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:direction&gt;in&lt;/nmwgt:direction&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/netutil:subject&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m3"
metadataIdRef="m1"&gt;
+ &lt;netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s3"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:direction&gt;out&lt;/nmwgt:direction&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/netutil:subject&gt;
+&lt;/nmwg:metadata&gt;
+
+ </pre><p>
+ Note that the chaining is performed via the use of the <span
class="emphasis"><em>metadataIdRef</em></span>
+ tag in the metadata element. This is a signal for services
(specifically
+ the SNMP MA or RRD MA) to keep looking deeper in an effort to
+ resolve the chains. The figure below demonstrates the <span
class="emphasis"><em>linking</em></span> between
+ the metadata elements. The resulting XML structure after chaining
is also
+ listed below.
+ </p><p>
+ </p><div class="mediaobject"><img src="chain.png" /></div><p>
+ </p><pre class="programlisting">
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1"&gt;
+ &lt;netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;nmwgt:direction&gt;in&lt;/nmwgt:direction&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/netutil:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:eventType&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:parameter&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="m1"&gt;
+ &lt;netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;nmwgt:direction&gt;in&lt;/nmwgt:direction&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/netutil:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:eventType&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:parameter&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m3"
metadataIdRef="m1"&gt;
+ &lt;netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;nmwgt:direction&gt;out&lt;/nmwgt:direction&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/netutil:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:eventType&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:parameter&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+ </pre><p>
+ For continuity this example has not attempted to modify the
+ <span class="emphasis"><em>metadataIdRef</em></span> attribute.
Implementations may choose to do so if
+ they feel the need. Because eventTypes may be repeated (either as
the
+ <span class="emphasis"><em>eventType</em></span> element or as
parameters) we must take special care when
+ merging them. The next example features multiple eventType
merging.
+ This example also features a so called <span
class="emphasis"><em>double chain</em></span> where the results
+ of the first chaining operation will feed into the process for the
+ second. This is a common occurrence, and should be supported in
+ services.
+ </p><pre class="programlisting">
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1"&gt;
+ &lt;nmwg:subject id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;nmwgt:direction&gt;in&lt;/nmwgt:direction&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/nmwg:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="m1"&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m3"
metadataIdRef="m2"&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/errors/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/errors/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+ </pre><p>
+ The resulting output and cartoon are pictured below. We did take
two
+ major issues into consideration: multiple <span
class="emphasis"><em>parameters</em></span> and <span
class="emphasis"><em>eventType</em></span>
+ elements that did conflict, and the double chaining. Services
that do
+ no support multiple eventTypes (or simply wish to not implement a
+ naive form of chaining) will not need to worry about special cases
such
+ as this.
+ </p><p>
+ </p><div class="mediaobject"><img src="chain2.png" /></div><p>
+ </p><pre class="programlisting">
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1"&gt;
+ &lt;nmwg:subject id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;nmwgt:direction&gt;in&lt;/nmwgt:direction&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/nmwg:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="m1"&gt;
+ &lt;nmwg:subject id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;nmwgt:direction&gt;in&lt;/nmwgt:direction&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/nmwg:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:eventType&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:parameter&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m3"
metadataIdRef="m2"&gt;
+ &lt;nmwg:subject id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;nmwgt:direction&gt;in&lt;/nmwgt:direction&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/nmwg:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:eventType&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/errors/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:parameter&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/errors/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+ </pre><p>
+ Services such as the SNMP MA treat particular elements (such as
+ eventTypes and parameters with certain <span
class="emphasis"><em>name</em></span> attributes) in a special
+ way. The service is careful not to overwrite or lose any
information
+ and will only add these items together. This is not the case for
any
+ element though, consider the following example.
+ </p><pre class="programlisting">
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1"&gt;
+ &lt;nmwg:subject id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;nmwgt:direction&gt;in&lt;/nmwgt:direction&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/nmwg:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="m1"&gt;
+ &lt;nmwg:subject id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifName&gt;eth1&lt;/nmwgt:ifName&gt;
+ &lt;nmwgt:direction&gt;out&lt;/nmwgt:direction&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/nmwg:subject&gt;
+&lt;/nmwg:metadata&gt;
+
+ </pre><p>
+ Note that we probably wanted to change the direction for this
particular
+ interface, not necessarily the <span
class="emphasis"><em>ifName</em></span> element. The output of this
+ chain is shown below.
+ </p><pre class="programlisting">
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1"&gt;
+ &lt;nmwg:subject id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;nmwgt:direction&gt;in&lt;/nmwgt:direction&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/nmwg:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="m1"&gt;
+ &lt;nmwg:subject id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth1&lt;/nmwgt:ifName&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;nmwgt:direction&gt;out&lt;/nmwgt:direction&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/nmwg:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+ </pre><p>
+ This example shows that its pretty easy to accidental flub up when
+ designing a chain instance. It also shows that the service won't
+ necessarily do a whole lot to warn you of your actions. It is
possible
+ to build in different rules instead of <span
class="emphasis"><em>last seen value</em></span> such as
+ <span class="emphasis"><em>first seen</em></span>, <span
class="emphasis"><em>original</em></span>, or any other combination. It is
imperative
+ that services describe their own implementations of chaining,
+ particularly when interoperability becomes an issue.
+ </p><p>
+ A final example comes when we deal with items with the same local
+ name, but perhaps a different namespace. There are several
approaches
+ that can be taken to dealing with this type of situation. The SNMP
+ follows a safe approach of simply <span
class="emphasis"><em>adding</em></span> all of the elements in
+ question and not attempting to internally merge at all. This
causes
+ unreadable metadata in many cases, but does not permit data
pollution.
+ </p><pre class="programlisting">
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1"&gt;
+ &lt;nmwg:subject id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/nmwg:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="1"&gt;
+ &lt;netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s2"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:direction&gt;in&lt;/nmwgt:direction&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/netutil:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+ </pre><p>
+ There are three approaches that I will illustrate here:
+ <span class="emphasis"><em>safe yet stupid</em></span>, <span
class="emphasis"><em>dangerous yet intelligent</em></span>, and finally
+ <span class="emphasis"><em>slow and steady</em></span>. In the
case of services like the SNMP
+ MA the last approach is used, finding the proper balance will
require
+ some thought (depending on how sensing or accurate a service
wishes to
+ become. Approach one yields output similar to the below example.
+ </p><pre class="programlisting">
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1"&gt;
+ &lt;nmwg:subject id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/nmwg:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="1"&gt;
+ &lt;netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s2"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:direction&gt;in&lt;/nmwgt:direction&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/netutil:subject&gt;
+ &lt;nmwg:subject id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/nmwg:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+ </pre><p>
+ Note that this is not schema valid, and presumably would not return
+ results from the backend storage. This is rather ironic given
that we
+ are trying to preserve validity on the schema side of things yet
still
+ generate a clearly invalid result. The other end of the spectrum
gives
+ a result such as the example below.
+ </p><pre class="programlisting">
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1"&gt;
+ &lt;nmwg:subject id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/nmwg:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="1"&gt;
+ &lt;netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s2"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:direction&gt;in&lt;/nmwgt:direction&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/netutil:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+ </pre><p>
+ The <span class="emphasis"><em>stupid</em></span> part of this
comes from not necessarily caring about
+ namespaces, and only merging based on localname. Because the
<span class="emphasis"><em>source</em></span>
+ metadata featured the <span
class="emphasis"><em>netutil</em></span> namespace it remains and all other
+ items are added to it.
+ </p><p>
+ The approach taken by the SNMP MA is to have a little domain
knowledge
+ before making a quick judgement. Knowing full well that <span
class="emphasis"><em>nmwg</em></span> is
+ a more general namespace than <span
class="emphasis"><em>netutil</em></span> the service tries to <span
class="emphasis"><em>guess</em></span>
+ the intent and goes with the most general namespace in order to
support
+ a richer query set. Internally anything that utilizes the <span
class="emphasis"><em>nmwg</em></span>
+ namespace receives a <span class="emphasis"><em>wild
card</em></span> when performing searches, therefor when
+ we are faced with a choice between specific and general, the
service
+ errs on the side of general. An example of this merge is below.
+ </p><pre class="programlisting">
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1"&gt;
+ &lt;nmwg:subject id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/nmwg:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="1"&gt;
+ &lt;nmwg:subject id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:direction&gt;in&lt;/nmwgt:direction&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/nmwg:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+ </pre><p>
+ A final question remains: what happens if you are dealing with two
+ very specific namespaces such as this example.
+ </p><pre class="programlisting">
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1"&gt;
+ &lt;neterr:subject
xmlns:neterr="http://ggf.org/ns/nmwg/characteristic/errors/2.0/"; id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/neterr:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/errors/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/errors/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="1"&gt;
+ &lt;netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s2"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/netutil:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+ </pre><p>
+ In the case of the SNMP MA the service will still guess <span
class="emphasis"><em>general</em></span> and
+ convert to the <span class="emphasis"><em>nmwg</em></span>
namespace. The resulting data set
+ will of coursetake on an interesting look as in this result.
+ </p><pre class="programlisting">
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1"&gt;
+ &lt;neterr:subject
xmlns:neterr="http://ggf.org/ns/nmwg/characteristic/errors/2.0/"; id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/neterr:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/errors/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/errors/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="1"&gt;
+ &lt;nmwg:subject id="s2"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/nmwg:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/errors/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/errors/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+ </pre><p>
+ Clearly the two eventTypes (for utilization and errors) may not
appear
+ in the same metadata description, but again the SNMP MA tries to
help
+ out a bit. eventType descriptions are interpreted as <span
class="emphasis"><em>or</em></span> operations when
+ performing a query. Therefore even if our chain was constructed
poorly,
+ our final results will be rather robust (perhaps a bit more robust
+ than needed). The service designers will no doubt settle on an
+ approach that fits well for the data they are exposing.
+ </p></div></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
id="filter_chaining_info"></a>5.2. Operator (Filter)
Chaining</h3></div></div></div><p>
+ Filter chaining involves the application of a
+ <span class="emphasis"><em>filter</em></span> (or function) to the
underlying dataset
+ that a particular metadata describes. We can think of this much
like a
+ database operation, where the first metadata is used to select a
broad
+ range of data, and subsequent metadata elements that are chained in
+ this manner are used to slowly whittle down the dataset to very
+ specific range.
+ </p><p>
+ The figure illustrates the distinction between the various operators
+ of a filter chain. The circles themselves represent the actual
metadata
+ description of a dataset (taken from the universe of all data). The
+ intersection of these two metadata descriptions becomes the data set
+ that we are interested in.
+ </p><p>
+ </p><div class="mediaobject"><img src="ven.png" /></div><p>
+ </p><p>
+ It is important to note that even though we are manipulating the data
+ through this form of chaining, we shouldn't be harming it, or it the
+ related metadata elements. Chaining in general is a non-destructive
+ operation although it is very possible that when implemented poorly
+ data corruption may occur.
+ </p><p>
+ Filter operations themselves can vary from time range selection to
+ aggregations such as [<span class="citation">CDF</span>].
Describing all
+ possible operators is well beyond the scope of this work. Current
+ experience has named most statistical and database operations as
+ candidates for filtering, although new uses are always being
devised.
+ </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="filter_chaining_ex"></a>5.2.1. Operator Chaining
Examples</h4></div></div></div><p>
+ Filter chaining itself is an easier concept to manage than merge
+ chaining, partially because there are less rules and nuances to
grasp.
+ As stated above, it is easy to think of the dataset for the
+ source metadata to be <span class="emphasis"><em>input</em></span>
to a function that is named
+ by the metadata utilizing the filter chain. Consider the following
+ cartoon as an example of the internal process of resolving a filter
+ chain.
+ </p><p>
+ </p><div class="mediaobject"><img src="filter.png" /></div><p>
+ </p><p>
+ The syntax of filter chaining is similar to that of merge chaining
(by
+ using <span class="emphasis"><em>metadataIdRef</em></span>
attributes) but the placement is a bit different.
+ Consider this example.
+ </p><pre class="programlisting">
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1"&gt;
+ &lt;netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s1"&gt;
+ &lt;nmwgt:interface
xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/"&gt;
+ &lt;nmwgt:ifAddress type="ipv4"&gt;127.0.0.1&lt;/nmwgt:ifAddress&gt;
+ &lt;nmwgt:hostName&gt;localhost&lt;/nmwgt:hostName&gt;
+ &lt;nmwgt:ifName&gt;eth0&lt;/nmwgt:ifName&gt;
+ &lt;nmwgt:ifIndex&gt;2&lt;/nmwgt:ifIndex&gt;
+ &lt;nmwgt:direction&gt;in&lt;/nmwgt:direction&gt;
+ &lt;nmwgt:capacity&gt;1000000000&lt;/nmwgt:capacity&gt;
+ &lt;/nmwgt:interface&gt;
+ &lt;/netutil:subject&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:eventType&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:eventType&gt;
+ &lt;nmwg:parameters id="p1"&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/tools/snmp/2.0&lt;/nmwg:parameter&gt;
+ &lt;nmwg:parameter
name="supportedEventType"&gt;http://ggf.org/ns/nmwg/characteristic/utilization/2.0&lt;/nmwg:parameter&gt;
+ &lt;/nmwg:parameters&gt;
+&lt;/nmwg:metadata&gt;
+
+&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"&gt;
+ &lt;select:subject id="s2" metadataIdRef="m1"
xmlns:select="http://ggf.org/ns/nmwg/ops/select/2.0/"/&gt;
+ &lt;select:parameters id="param2c"
xmlns:select="http://ggf.org/ns/nmwg/ops/select/2.0/"&gt;
+ &lt;nmwg:parameter name="startTime"&gt;1121472000&lt;/nmwg:parameter&gt;
+ &lt;nmwg:parameter name="endTime"&gt;1121904000&lt;/nmwg:parameter&gt;
+ &lt;nmwg:parameter
name="consolidationFunction"&gt;AVERAGE&lt;/nmwg:parameter&gt;
+ &lt;nmwg:parameter name="resolution"&gt;60&lt;/nmwg:parameter&gt;
+ &lt;/select:parameters&gt;
+
&lt;nmwg:eventType&gt;http://ggf.org/ns/nmwg/ops/select/2.0&lt;/nmwg:eventType&gt;

+&lt;/nmwg:metadata&gt;
+
+ </pre><p>
+ The reference is placed in the <span
class="emphasis"><em>subject</em></span> element in this case, as in
+ merge chaining this is a signal to the service that filter
chaining will
+ be required. This indicates that the <span
class="emphasis"><em>input</em></span> is the data pointed to
+ by the first metadata and the output will be a subset of this. For
+ the sake of these examples we will be dealing with the <span
class="emphasis"><em>select</em></span>
+ namespace as our filter of choice due to an abundance of examples
and
+ its common goal of filtering based on time. Other filter examples
will
+ work in the same manner.
+ </p><p>
+ Because the operations of a filter chain are essentially <span
class="emphasis"><em>internal</em></span> we
+ do not present what resultant XML should look like. Currently
services
+ ignore many of the steps that may go into reforming the XML for
+ response messages in favor of simply returning the <span
class="emphasis"><em>backend</em></span>
+ representation of metadata. While quick and easy, this does lead
to
+ information loss (specifically when dealing with the various ways
to
+ implement merge chaining). Client applications may have no reason
to
+ see the original filter information, and therefore are built not
to
+ need it.
+ </p></div></div></div><div class="section" lang="en"
xml:lang="en"><div class="titlepage"><div><div><h2 class="title"
style="clear: both"><a id="result_codes"></a>6. Result
Codes</h2></div></div></div><p>
There are currently two hierarchical systems in use to return status
information about services. Each of these approaches takes into
account
the facts that there are many diverse services as well as different
@@ -816,7 +1643,7 @@
</p><p>
The original system, currently used by all
<span class="emphasis"><em>perfSONAR</em></span> services and
explained in
- <a href="#id2533485">Result Codes</a>, relies on a static tree of
status
+ [<a href="#id2546258"><span class="citation">Result Codes</span></a>],
relies on a static tree of status
information that is branched first by general features (i.e.
<span class="emphasis"><em>success</em></span>, <span
class="emphasis"><em>error</em></span>) and later
by more specific characteristics such as service and error type. This
@@ -865,22 +1692,22 @@
something_else/
1.0


- </pre></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
id="extension"></a>6. Extension</h2></div></div></div><p>
+ </pre></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
id="extension"></a>7. Extension</h2></div></div></div><p>
This document <span class="emphasis"><em>must</em></span> become the
basis for all extension
protocols in the perfSONAR framework. As a demonstration we include
two
protocols that should be implemented by all perfSONAR services:
- <a href="#extension_echo">Echo Protocol</a> and <a
href="#extension_aa">Authentication and Authorization Protocol</a>.
+ <a href="#extension_echo" title="7.1. Echo Protocol">Echo Protocol</a>
and <a href="#extension_aa" title="7.2. Authentication and Authorization
Protocol">Authentication and Authorization Protocol</a>.
These protocols will incorporate the preceding work to eliminate
duplication as much as possible, only specifying parts that are
necessary
for clarification. Each extension may be treated as a separate work,
and
will include the necessary schema, analysis, and example sections.
- </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
id="extension_echo"></a>6.1. Echo Protocol</h3></div></div></div><p>
+ </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
id="extension_echo"></a>7.1. Echo Protocol</h3></div></div></div><p>
The sole purpose of certain <span
class="emphasis"><em>perfSONAR</em></span> services is
to aid in the discovery and protection of the enterprise. The tasks
undertaken by these critical components also require sound
communication
- protocols based on the same <a href="#id2533357">XML</a> formats
used to
+ protocols based on the same [<a href="#id2546130"><span
class="citation">XML</span></a>] formats used to
exchange and store measurement data as defined by the
- <a href="#id2533320">NM-WG</a> in the <a href="#id2533375">OGF</a>.
+ [<a href="#id2546093"><span class="citation">NM-WG</span></a>] in
the [<a href="#id2546148"><span class="citation">OGF</span></a>].
</p><p>
The <span class="emphasis"><em>Echo Protocol</em></span> is
currently used by client
applications as well as other services to ascertain the
@@ -896,34 +1723,34 @@
provide a simple <span class="emphasis"><em>request</em></span> and
<span class="emphasis"><em>response</em></span> message set capable
of delivering
rudimentary status information. This protocol for exchange is
similar to
- other types of communication, notably <a href="#ping">ping</a>.
While this
+ other types of communication, notably <a href="#ping"
title="ping">ping</a>. While this
protocol may seem to be a reinvention of existing tooling, the
extension possibility far outweighs the duplication of functionality.
</p><p>
We present an overview of the messages used in this protocol,
including
both schematic designs and examples for the
- <a href="#extension_echo_request_message">Request Message</a> and
- <a href="#extension_echo_response_message">Response Message</a>.
+ <a href="#extension_echo_request_message" title="7.1.2. Request
Message">Request Message</a> and
+ <a href="#extension_echo_response_message" title="7.1.3. Response
Message">Response Message</a>.
We conclude with a brief description of where extensions are
possible followed by some current examples in
- <a href="#extension_echo_protocol_extension">Protocol Extension</a>.

+ <a href="#extension_echo_protocol_extension" title="7.1.5. Protocol
Extension">Protocol Extension</a>.
</p><p>
The remainder of this section will explain the origins of this
command
- protocol in <a href="#extension_echo_architecture">Architecture</a>,
detailed
+ protocol in <a href="#extension_echo_architecture"
title="7.1.1. Architecture">Architecture</a>, detailed
descriptions regarding syntax and semantics in
- <a href="#extension_echo_request_message">Request Message</a> and
- <a href="#extension_echo_response_message">Response Message</a>, an
overview of
+ <a href="#extension_echo_request_message" title="7.1.2. Request
Message">Request Message</a> and
+ <a href="#extension_echo_response_message" title="7.1.3. Response
Message">Response Message</a>, an overview of
status in
- <a href="#extension_echo_result_codes">Result Codes</a>, and finally
points of
+ <a href="#extension_echo_result_codes" title="7.1.4. Result
Codes">Result Codes</a>, and finally points of
extension will be discussed in
- <a href="#extension_echo_protocol_extension">Protocol Extension</a>.
- </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="extension_echo_architecture"></a>6.1.1. Architecture</h4></div></div></div><p>
+ <a href="#extension_echo_protocol_extension" title="7.1.5. Protocol
Extension">Protocol Extension</a>.
+ </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="extension_echo_architecture"></a>7.1.1. Architecture</h4></div></div></div><p>
To ensure availability, each <span
class="emphasis"><em>perfSONAR</em></span> service
<span><strong class="command">must</strong></span> be able to
respond to simple queries regarding
status. Services that fail to answer a direct question may be
experiencing difficulty, and therefore may not be able to complete
interaction with interested parties. Client applications,
services, or
- external monitoring tools (such as <a
href="#id2533466">SmokePing</a>) can
+ external monitoring tools (such as [<a href="#id2546240"><span
class="citation">SmokePing</span></a>]) can
use this simple method to quickly come to conclusions regarding
framework
availability.
</p><p>
@@ -937,7 +1764,7 @@
the service, receive statistics, or monitor erroneous behavior.
The
assignment of these other tasks within an <span><strong
class="command">EchoRequest</strong></span>
message is valid provided that the basic structure is not
compromised.
- </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="extension_echo_request_message"></a>6.1.2. Request
Message</h4></div></div></div><p>
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="extension_echo_request_message"></a>7.1.2. Request
Message</h4></div></div></div><p>
The <span><strong class="command">EchoRequest</strong></span>
message can be initiated by a
client application or service wanting to know the availability of
some
other service. The format of this message is minimal with respect
to
@@ -946,11 +1773,11 @@
All protocols used within <span
class="emphasis"><em>perfSONAR</em></span> are based on
recommendations from the <span
class="emphasis"><em>OGF</em></span>'s
<span class="emphasis"><em>NM-WG</em></span>, and have been
initially described
- in <a href="#id2533504">A Scalable Framework for Representation
and Exchange of Network Measurements</a>. The basic format described
+ in [<a href="#id2546278"><span
class="citation">Zurawski06Scalable</span></a>]. The basic format described
in this work for measurements has been adapted as a template for
use in
service communication as well, keeping the concept of
- <a href="#metadata">metadata</a> and <a href="#data">data</a>
intact.
- </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_request_schema"></a>6.1.2.1. Request Message
Schema</h5></div></div></div><p>
+ <a href="#metadata" title="metadata">metadata</a> and <a
href="#data" title="data">data</a> intact.
+ </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_request_schema"></a>7.1.2.1. Request Message
Schema</h5></div></div></div><p>
<span class="emphasis"><em>NM-WG</em></span> schemata is always
expressed in terms of
the RELAX-NG schema language. This tool, unlike similar XML
schema
languages, does not utilize XML markup. The syntax is similar
@@ -987,9 +1814,9 @@

<font color=red># End Schema</font>

- </pre></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_request_analysis"></a>6.1.2.2. Request Message
Analysis</h5></div></div></div><p>
+ </pre></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_request_analysis"></a>7.1.2.2. Request Message
Analysis</h5></div></div></div><p>
The following is a breakdown of the elements featured in the
schema.
- </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_request_analysis_message"></a>6.1.2.2.1. Message</h6></div></div></div><pre
class="programlisting">
+ </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_request_analysis_message"></a>7.1.2.2.1. Message</h6></div></div></div><pre
class="programlisting">

&lt;nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
type="EchoRequest"
@@ -1001,14 +1828,14 @@

&lt;/nmwg:message&gt;

- </pre><div class="table"><a
id="table.extension_echo_request_analysis_message"></a><p
class="title"><b>Table 12. Message Element Requirements</b></p><div
class="table-contents"><table summary="Message Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">message</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, type</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">metadata, data</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ </pre><div class="table"><a
id="table.extension_echo_request_analysis_message"></a><p
class="title"><b>Table 15. Message Element Requirements</b></p><div
class="table-contents"><table summary="Message Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">message</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, type</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">metadata, data</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
This appears the same was as it does in
- <a href="#messages_request_analysis_message">Message</a>, the
only
+ <a href="#messages_request_analysis_message"
title="4.3.2.1. Message">Message</a>, the only
notable exception is a requirement that
<span class="emphasis"><em>type</em></span> attribute contain
the values
<span><strong class="command">EchoRequest</strong></span> or
<span><strong
class="command">http://schemas.perfsonar.net/messages/EchoRequest/1.0</strong></span>.
- </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_request_analysis_metadata"></a>6.1.2.2.2. Metadata</h6></div></div></div><pre
class="programlisting">
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_request_analysis_metadata"></a>7.1.2.2.2. Metadata</h6></div></div></div><pre
class="programlisting">

&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="STRING"&gt;

@@ -1016,19 +1843,19 @@

&lt;/nmwg:metadata&gt;

- </pre><div class="table"><a
id="table.extension_echo_request_analysis_metadata"></a><p
class="title"><b>Table 13. Metadata Element Requirements</b></p><div
class="table-contents"><table summary="Metadata Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">eventType</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ </pre><div class="table"><a
id="table.extension_echo_request_analysis_metadata"></a><p
class="title"><b>Table 16. Metadata Element Requirements</b></p><div
class="table-contents"><table summary="Metadata Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">eventType</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
This appears the same was as it does in
- <a href="#messages_request_analysis_metadata">Metadata</a>,
the only
+ <a href="#messages_request_analysis_metadata"
title="4.3.2.4. Metadata">Metadata</a>, the only
notable exception is specifying that
- <a
href="#extension_echo_request_analysis_eventtype">EventType</a> can be
+ <a href="#extension_echo_request_analysis_eventtype"
title="7.1.2.2.3. EventType">EventType</a> can be
the only child.
- </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_request_analysis_eventtype"></a>6.1.2.2.3. EventType</h6></div></div></div><pre
class="programlisting">
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_request_analysis_eventtype"></a>7.1.2.2.3. EventType</h6></div></div></div><pre
class="programlisting">

&lt;nmwg:eventType xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"&gt;
http://schemas.perfsonar.net/tools/admin/echo/2.0
&lt;/nmwg:eventType&gt;

- </pre><div class="table"><a
id="table.extension_echo_request_analysis_eventtype"></a><p
class="title"><b>Table 14. EventType Element Requirements</b></p><div
class="table-contents"><table summary="EventType Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">eventType</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">N/A</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ </pre><div class="table"><a
id="table.extension_echo_request_analysis_eventtype"></a><p
class="title"><b>Table 17. EventType Element Requirements</b></p><div
class="table-contents"><table summary="EventType Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">eventType</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">N/A</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
The <span class="emphasis"><em>eventType</em></span> element
is normally used to
specify an action for a service or measurement. We utilize it
for
this role in the <span class="emphasis"><em>Echo
Protocol</em></span> by specifying
@@ -1040,19 +1867,19 @@
</p><p>
Because this element is currently well defined into a specific
role
and purpose, the eventType is non-negotiable. Extensions, as
- discussed in <a
href="#extension_echo_protocol_extension">Protocol Extension</a>,
+ discussed in <a href="#extension_echo_protocol_extension"
title="7.1.5. Protocol Extension">Protocol Extension</a>,
may be employed on a service by service basis to expand this
basic
specification, as long as the role is preserved.
- </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_request_analysis_data"></a>6.1.2.2.4. Data</h6></div></div></div><pre
class="programlisting">
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_request_analysis_data"></a>7.1.2.2.4. Data</h6></div></div></div><pre
class="programlisting">

&lt;nmwg:data xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="STRING"
metadataIdRef="STRING" /&gt;

- </pre><div class="table"><a
id="table.extension_echo_request_analysis_data"></a><p
class="title"><b>Table 15. Data Element Requirements</b></p><div
class="table-contents"><table summary="Data Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">N/A</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ </pre><div class="table"><a
id="table.extension_echo_request_analysis_data"></a><p
class="title"><b>Table 18. Data Element Requirements</b></p><div
class="table-contents"><table summary="Data Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">N/A</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
This appears the same was as it does in
- <a href="#messages_request_analysis_data">Data</a>.
- </p></div></div><div class="section" lang="en"
xml:lang="en"><div class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_request_example"></a>6.1.2.3. Request Message
Example</h5></div></div></div><p>
+ <a href="#messages_request_analysis_data"
title="4.3.2.8. Data">Data</a>.
+ </p></div></div><div class="section" lang="en"
xml:lang="en"><div class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_request_example"></a>7.1.2.3. Request Message
Example</h5></div></div></div><p>
The first example shows a correct configuration for an
<span class="emphasis"><em>EchoRequest</em></span> message.
</p><pre class="programlisting">
@@ -1097,7 +1924,7 @@

&lt;!-- End XML --&gt;

- </pre></div></div><div class="section" lang="en"
xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a
id="extension_echo_response_message"></a>6.1.3. Response
Message</h4></div></div></div><p>
+ </pre></div></div><div class="section" lang="en"
xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a
id="extension_echo_response_message"></a>7.1.3. Response
Message</h4></div></div></div><p>
The <span><strong class="command">EchoResponse</strong></span>
message is a reply to a given
<span><strong class="command">EchoRequest</strong></span> message
from a client application or
service. Like the <span><strong
class="command">EchoRequest</strong></span> the format is
@@ -1105,10 +1932,10 @@
<span class="emphasis"><em>NM-WG</em></span> work with respect to
other
<span class="emphasis"><em>perfSONAR</em></span> services. This
simplicity does however
allow for limited extension, as discussed in
- <a href="#extension_echo_protocol_extension">Protocol
Extension</a>. As discussed in
- <a href="#extension_echo_request_message">Request Message</a>,
this response message is also
+ <a href="#extension_echo_protocol_extension"
title="7.1.5. Protocol Extension">Protocol Extension</a>. As discussed in
+ <a href="#extension_echo_request_message" title="7.1.2. Request
Message">Request Message</a>, this response message is also
based on recommendations from the <span
class="emphasis"><em>NM-WG</em></span>.
- </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_response_schema"></a>6.1.3.1. Response Message
Schema</h5></div></div></div><p>
+ </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_response_schema"></a>7.1.3.1. Response Message
Schema</h5></div></div></div><p>
<span class="emphasis"><em>NM-WG</em></span> schemata is always
expressed in terms of
the RELAX-NG schema language. This tool, unlike similar XML
schema
languages, does not utilize XML markup. The syntax is similar
@@ -1153,9 +1980,9 @@

<font color=red># End Schema</font>

- </pre></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_response_analysis"></a>6.1.3.2. Response Message
Analysis</h5></div></div></div><p>
+ </pre></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_response_analysis"></a>7.1.3.2. Response Message
Analysis</h5></div></div></div><p>
The following is a breakdown of the elements featured in the
schema.
- </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_response_analysis_message"></a>6.1.3.2.1. Message</h6></div></div></div><pre
class="programlisting">
+ </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_response_analysis_message"></a>7.1.3.2.1. Message</h6></div></div></div><pre
class="programlisting">

&lt;nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
type="EchoResponse"
@@ -1167,14 +1994,14 @@

&lt;/nmwg:message&gt;

- </pre><div class="table"><a
id="table.extension_echo_response_analysis_message"></a><p
class="title"><b>Table 16. Message Element Requirements</b></p><div
class="table-contents"><table summary="Message Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">message</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, type</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">metadata, data</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ </pre><div class="table"><a
id="table.extension_echo_response_analysis_message"></a><p
class="title"><b>Table 19. Message Element Requirements</b></p><div
class="table-contents"><table summary="Message Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">message</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, type</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">metadata, data</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
This appears the same was as it does in
- <a href="#messages_response_analysis_message">Message</a>, the
only
+ <a href="#messages_response_analysis_message"
title="4.4.2.1. Message">Message</a>, the only
notable exception is a requirement that
<span class="emphasis"><em>type</em></span> attribute contain
the values
<span><strong class="command">EchoResponse</strong></span> or
<span><strong
class="command">http://schemas.perfsonar.net/messages/EchoResponse/1.0</strong></span>.
- </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_response_analysis_metadata"></a>6.1.3.2.2. Metadata</h6></div></div></div><pre
class="programlisting">
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_response_analysis_metadata"></a>7.1.3.2.2. Metadata</h6></div></div></div><pre
class="programlisting">

&lt;nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="STRING"&gt;

@@ -1182,19 +2009,19 @@

&lt;/nmwg:metadata&gt;

- </pre><div class="table"><a
id="table.extension_echo_response_analysis_metadata"></a><p
class="title"><b>Table 17. Metadata Element Requirements</b></p><div
class="table-contents"><table summary="Metadata Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">eventType</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ </pre><div class="table"><a
id="table.extension_echo_response_analysis_metadata"></a><p
class="title"><b>Table 20. Metadata Element Requirements</b></p><div
class="table-contents"><table summary="Metadata Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">eventType</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
This appears the same was as it does in
- <a href="#messages_response_analysis_metadata">Metadata</a>,
the only
+ <a href="#messages_response_analysis_metadata"
title="4.4.2.4. Metadata">Metadata</a>, the only
notable exception is specifying that
- <a
href="#extension_echo_response_analysis_eventtype">EventType</a> can be
+ <a href="#extension_echo_response_analysis_eventtype"
title="7.1.3.2.3. EventType">EventType</a> can be
the only child.
- </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_response_analysis_eventtype"></a>6.1.3.2.3. EventType</h6></div></div></div><pre
class="programlisting">
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_response_analysis_eventtype"></a>7.1.3.2.3. EventType</h6></div></div></div><pre
class="programlisting">

&lt;nmwg:eventType xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"&gt;
http://schemas.perfsonar.net/tools/admin/echo/2.0
&lt;/nmwg:eventType&gt;

- </pre><div class="table"><a
id="table.extension_echo_response_analysis_eventtype"></a><p
class="title"><b>Table 18. EventType Element Requirements</b></p><div
class="table-contents"><table summary="EventType Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">eventType</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">N/A</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ </pre><div class="table"><a
id="table.extension_echo_response_analysis_eventtype"></a><p
class="title"><b>Table 21. EventType Element Requirements</b></p><div
class="table-contents"><table summary="EventType Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">eventType</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">N/A</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
The <span class="emphasis"><em>eventType</em></span> element
is normally used to
specify an action for a service or measurement. We utilize it
for
this role in the <span class="emphasis"><em>Echo
Protocol</em></span> by specifying
@@ -1203,20 +2030,20 @@
for this element, and only text can be used as a child,
specifically
text reporting the status of the transaction. A complete list
of
<span class="emphasis"><em>available</em></span> status
strings is availble in
- <a href="#extension_echo_result_codes">Result Codes</a>.
- </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_response_analysis_data"></a>6.1.3.2.4. Data</h6></div></div></div><pre
class="programlisting">
+ <a href="#extension_echo_result_codes" title="7.1.4. Result
Codes">Result Codes</a>.
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_response_analysis_data"></a>7.1.3.2.4. Data</h6></div></div></div><pre
class="programlisting">

&lt;nmwg:data xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="STRING"
metadataIdRef="STRING" /&gt;

- </pre><div class="table"><a
id="table.extension_echo_response_analysis_data"></a><p
class="title"><b>Table 19. Data Element Requirements</b></p><div
class="table-contents"><table summary="Data Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">datum</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ </pre><div class="table"><a
id="table.extension_echo_response_analysis_data"></a><p
class="title"><b>Table 22. Data Element Requirements</b></p><div
class="table-contents"><table summary="Data Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">datum</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
This appears the same was as it does in
- <a href="#messages_response_analysis_data">Data</a> with the
+ <a href="#messages_response_analysis_data"
title="4.4.2.5. Data">Data</a> with the
exception of allowing
- <a href="#extension_echo_response_analysis_datum">Datum</a> as
a child
+ <a href="#extension_echo_response_analysis_datum"
title="7.1.3.2.5. Datum">Datum</a> as a child
element.
- </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_response_analysis_datum"></a>6.1.3.2.5. Datum</h6></div></div></div><pre
class="programlisting">
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h6 class="title"><a
id="extension_echo_response_analysis_datum"></a>7.1.3.2.5. Datum</h6></div></div></div><pre
class="programlisting">

&lt;nmwgr:datum xmlns:nmwgr="http://ggf.org/ns/nmwg/result/2.0"&gt;
TEXT
@@ -1228,7 +2055,7 @@
TEXT
&lt;/nmwg:datum&gt;

- </pre><div class="table"><a
id="table.extension_echo_response_analysis_datum"></a><p
class="title"><b>Table 20. Datum Element Requirements</b></p><div
class="table-contents"><table summary="Datum Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">datum</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/result/2.0/,
http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td align="left"><span><strong
class="command">attributes</strong></span></td><td
align="left">value</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ </pre><div class="table"><a
id="table.extension_echo_response_analysis_datum"></a><p
class="title"><b>Table 23. Datum Element Requirements</b></p><div
class="table-contents"><table summary="Datum Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span><strong class="command">localname</strong></span></td><td
align="left">datum</td></tr><tr><td align="left"><span><strong
class="command">namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/result/2.0/,
http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td align="left"><span><strong
class="command">attributes</strong></span></td><td
align="left">value</td></tr><tr><td align="left"><span><strong
class="command">nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
The <span class="emphasis"><em>datum</em></span> element
describes measurements in
most circumstances; the intent in the
<span class="emphasis"><em>Echo Protocol</em></span> is to
report back a human
@@ -1236,7 +2063,7 @@
accepted for this element, <span
class="emphasis"><em>value</em></span>, and it may be
used in place of an enclosed text element. The text could be
any message the service wishes to return.
- </p></div></div><div class="section" lang="en"
xml:lang="en"><div class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_response_example"></a>6.1.3.3. Response Message
Example</h5></div></div></div><p>
+ </p></div></div><div class="section" lang="en"
xml:lang="en"><div class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_response_example"></a>7.1.3.3. Response Message
Example</h5></div></div></div><p>
The first example shows a correct configuration for an
<span class="emphasis"><em>EchoResponse</em></span> message.
</p><pre class="programlisting">
@@ -1283,9 +2110,9 @@

&lt;!-- End XML --&gt;

- </pre></div></div><div class="section" lang="en"
xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a
id="extension_echo_result_codes"></a>6.1.4. Result
Codes</h4></div></div></div><p>
+ </pre></div></div><div class="section" lang="en"
xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a
id="extension_echo_result_codes"></a>7.1.4. Result
Codes</h4></div></div></div><p>
The following new result codes can be incorporated into the echo
- protocol based on <a href="#result_codes">Result Codes</a>. We
will introduce
+ protocol based on <a href="#result_codes" title="6. Result
Codes">Result Codes</a>. We will introduce
these into both styles to allow for backwards compatibility. The
original style is presented first:
</p><pre class="programlisting">
@@ -1307,7 +2134,7 @@
echo/
1.0


- </pre></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="extension_echo_protocol_extension"></a>6.1.5. Protocol
Extension</h4></div></div></div><p>
+ </pre></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="extension_echo_protocol_extension"></a>7.1.5. Protocol
Extension</h4></div></div></div><p>
There are two avenues for extension within the
<span class="emphasis"><em>Echo Protocol</em></span> as described
in this document. It
is possible to manipulate the values contained within the
@@ -1317,7 +2144,7 @@
for a given service should be careful to not change the themes
presented
in this protocol specification. It is imperative that all services
respect the basic functionality in their quest to add new features.
- </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_protocol_extension_eventType"></a>6.1.5.1. eventType
Extension</h5></div></div></div><p>
+ </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_protocol_extension_eventType"></a>7.1.5.1. eventType
Extension</h5></div></div></div><p>
The current accepted <span
class="emphasis"><em>eventType</em></span> for the
<span class="emphasis"><em>Echo Protocol</em></span>'s
<span><strong class="command">EchoRequest</strong></span>
message is
@@ -1351,7 +2178,7 @@
By simply allow some additional string matching to occur in the
<span class="emphasis"><em>eventType</em></span> it is now
possible to receive additional
data to check the health of the system.
- </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_protocol_extension_other"></a>6.1.5.2. Other
Extensions</h5></div></div></div><p>
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="extension_echo_protocol_extension_other"></a>7.1.5.2. Other
Extensions</h5></div></div></div><p>
Similar to the above approach, it is possible to extend the
schema
by adding additional elements to increase functionality.
Individuals
pursuing this route should be comfortable with schema design in
@@ -1360,7 +2187,7 @@
</p><p>
A simple extension involves allowing the commonly used
<span class="emphasis"><em>parameters</em></span> structure to
reside in the
- <a href="#extension_echo_request_analysis_message">Message</a>
of the
+ <a href="#extension_echo_request_analysis_message"
title="7.1.2.2.1. Message">Message</a> of the
<span><strong class="command">EchoRequest</strong></span>
message. This modification is
presented below.
</p><pre class="programlisting">
@@ -1398,7 +2225,7 @@

</pre><p>
Building on the example in
- <a href="#extension_echo_protocol_extension_eventType">eventType
Extension</a>, the following example
+ <a href="#extension_echo_protocol_extension_eventType"
title="7.1.5.1. eventType Extension">eventType Extension</a>, the following
example
message shows how to ask for similar information as previously
described.
</p><pre class="programlisting">
@@ -1423,7 +2250,7 @@
</pre><p>
While this method does require some additional schema
modification,
the result produced is the same as described in
- <a href="#extension_echo_protocol_extension_eventType">eventType
Extension</a>. An important
+ <a href="#extension_echo_protocol_extension_eventType"
title="7.1.5.1. eventType Extension">eventType Extension</a>. An important
consideration is the inclusion of <span
class="emphasis"><em>parameters</em></span>
in an <span><strong class="command">EchoRequest</strong></span>
</p></div><p>
@@ -1432,9 +2259,9 @@
that provide strict validation may reject messages that do not fit
this
standard explicitly, so be sure to design client applications
appropriately.
- </p></div></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
id="extension_aa"></a>6.2. Authentication and Authorization
Protocol</h3></div></div></div><p>
+ </p></div></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
id="extension_aa"></a>7.2. Authentication and Authorization
Protocol</h3></div></div></div><p>
TBD
- </p></div></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
id="conclusion"></a>7. Conclusion</h2></div></div></div><p>
+ </p></div></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
id="conclusion"></a>8. Conclusion</h2></div></div></div><p>
Using the protocol and schema presented in this work, perfSONAR
services
now have a clear wary forward with regards to documentation. Services
documentation is now able to:
@@ -1442,51 +2269,55 @@
based on this document
</p></li><li style="list-style-type: circle"><p>Choose at least one
(or create one)
<span class="emphasis"><em>schema profile</em></span>, based on
- <a href="#id2533300">Measurement Schema</a></p></li></ul></div><p>
+ [<a href="#id2546074"><span class="citation">Measurement
Schema</span></a>]</p></li></ul></div><p>
Using these as building blocks, a truly unified communication protocol
is possible.
- </p></div><div class="glossary"><div class="titlepage"><div><div><h2
class="title"><a id="glossary"></a>Terms</h2></div></div></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><h3 class="title">C</h3><dl><dt><a
id="characteristic"></a>characteristic</dt><dd><p>Taken on the context of
networking, these describe the
+ </p></div><div class="glossary"><div class="titlepage"><div><div><h2
class="title"><a id="glossary"></a>Terms</h2></div></div></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><h3 class="title">C</h3><dl><dt><a
id="chaining"></a>chaining</dt><dd><p>The process of linking together
elements in the NM-WG
+ XML specification.</p></dd><dt><a
id="characteristic"></a>characteristic</dt><dd><p>Taken on the context of
networking, these describe the
intrinsic properties of a portion of the network that are related
to the performance and reliability of the network. See
<a href="http://www.ggf.org/documents/GFD.23.pdf";
target="_top">http://www.ggf.org/documents/GFD.23.pdf</a>
- for more information.</p></dd></dl></div><div class="glossdiv"><h3
class="title">D</h3><dl><dt><a id="data"></a>data</dt><dd><p>An <a
href="#NMWG">NM-WG</a> XML block used
- to store dynamic information, such as the results of a
measurement.</p></dd></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><h3
class="title">I</h3><dl><dt><a id="ICMP"></a>ICMP</dt><dd><p>
+ for more information.</p></dd></dl></div><div class="glossdiv"><h3
class="title">D</h3><dl><dt><a id="data"></a>data</dt><dd><p>An <a
href="#NMWG" title="NM-WG">NM-WG</a> XML block used
+ to store dynamic information, such as the results of a
measurement.</p></dd></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><h3 class="title">F</h3><dl><dt><a
id="filter_chaining"></a>filter chaining</dt><dd><p>Chaining operation that
is akin to performing advanced
+ selection or aggregation on a
dataset.</p></dd></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><h3
class="title">I</h3><dl><dt><a id="ICMP"></a>ICMP</dt><dd><p>
The Internet Control Message Protocol (ICMP) is a communications
protocol used in computer networking. The main use of this format
is by networked devices to send error and status messages.
- </p></dd></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><h3 class="title">M</h3><dl><dt><a
id="metadata"></a>metadata</dt><dd><p>An <a href="#NMWG">NM-WG</a> XML block
used
+ </p></dd></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><h3 class="title">M</h3><dl><dt><a
id="merge_chaining"></a>merge chaining</dt><dd><p>Chaining that combines
linked metadata items into a new
+ representation.</p></dd><dt><a
id="metadata"></a>metadata</dt><dd><p>An <a href="#NMWG"
title="NM-WG">NM-WG</a> XML block used
to store static information, such as the specific parameters of a
- measurement.</p></dd></dl></div><div class="glossdiv"><h3
class="title">N</h3><dl><dt><a id="NMWG"></a>NM-WG</dt><dd><p>The performance
of most grid applications is dependent on the
+ measurement.</p></dd></dl></div><div class="glossdiv"><h3
class="title">N</h3><dl><dt><a id="namespace"></a>namespace</dt><dd><p>A
simple method of qualifying names (element or attribute)
+ in XML by associating them with URI
references.</p></dd><dt><a id="NMWG"></a>NM-WG</dt><dd><p>The performance of
most grid applications is dependent on the
performance of the networks forming the grid. The Network
Measurements Working Group (NMWG) identifies network metrics
- (aka <a href="#characteristic">characteristics</a>) useful to grid
applications
+ (aka <a href="#characteristic"
title="characteristic">characteristics</a>) useful to grid applications
and middleware, and develops standard mechanisms to describe and
- publish these characteristics to the Grid.</p></dd></dl></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><h3
class="title">P</h3><dl><dt><a id="ping"></a>ping</dt><dd><p>
+ publish these characteristics to the Grid.</p></dd></dl></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><h3
class="title">P</h3><dl><dt><a
id="perfSONAR"></a>perfSONAR</dt><dd><p>Network performance monitoring
framework.</p></dd><dt><a id="ping"></a>ping</dt><dd><p>
Computer network tool used to test whether a particular host is
reachable across an IP network. It works by sending
- <a href="#ICMP">ICMP</a> "echo request" packets to the target
- host and listening for <a href="#ICMP">ICMP</a> "echo response"
+ <a href="#ICMP" title="ICMP">ICMP</a> "echo request" packets to
the target
+ host and listening for <a href="#ICMP" title="ICMP">ICMP</a>
"echo response"
replies.
- </p></dd></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><dl></dl></div></div><div class="bibliography"><div
class="titlepage"><div><div><h2 class="title"><a
id="bibliography"></a>References</h2></div></div></div><div
class="biblioentry"><a id="id2533300"></a><p>[<abbr
class="abbrev">Measurement Schema</abbr>] <span class="title"><i>
+ </p></dd></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><h3
class="title">S</h3><dl><dt><a id="schema"></a>schema</dt><dd><p>XML
specification, normally written in XML.</p></dd><dt><a
id="schemata"></a>schemata</dt><dd><p>Plural of
schema.</p></dd></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><dl></dl></div><div class="glossdiv"><dl></dl></div><div
class="glossdiv"><dl></dl></div><div
class="glossdiv"><dl></dl></div></div><div class="bibliography"><div
class="titlepage"><div><div><h2 class="title"><a
id="bibliography"></a>References</h2></div></div></div><div
class="biblioentry"><a id="id2546074"></a><p>[<abbr
class="abbrev">Measurement Schema</abbr>] <span class="title"><i>
<a
href="https://forge.gridforum.org/sf/docman/do/downloadDocument/projects.nm-wg/docman.root.working_drafts/doc15119";
target="_top">Measurement Schema</a>
- </i>. </span></p></div><div class="biblioentry"><a
id="id2533320"></a><p>[<abbr class="abbrev">NM-WG</abbr>] <span
class="title"><i>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2546093"></a><p>[<abbr class="abbrev">NM-WG</abbr>] <span
class="title"><i>
<a href="http://nmwg.internet2.edu"; target="_top">Network
Measurements Working Group</a>
- </i>. </span></p></div><div class="biblioentry"><a
id="id2533338"></a><p>[<abbr class="abbrev">perfSONAR</abbr>] <span
class="title"><i>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2546112"></a><p>[<abbr class="abbrev">perfSONAR</abbr>] <span
class="title"><i>
<a href="http://www.perfsonar.net"; target="_top">perfSONAR</a>
- </i>. </span></p></div><div class="biblioentry"><a
id="id2533357"></a><p>[<abbr class="abbrev">XML</abbr>] <span
class="title"><i>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2546130"></a><p>[<abbr class="abbrev">XML</abbr>] <span
class="title"><i>
<a href="http://www.w3.org/XML"; target="_top">Extensible Markup
Language (XML)</a>
- </i>. </span></p></div><div class="biblioentry"><a
id="id2533375"></a><p>[<abbr class="abbrev">OGF</abbr>] <span
class="title"><i>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2546148"></a><p>[<abbr class="abbrev">OGF</abbr>] <span
class="title"><i>
<a href="http://www.ogf.org/"; target="_top">(Global|Open) Grid
Forum</a>
- </i>. </span></p></div><div class="biblioentry"><a
id="id2533392"></a><p>[<abbr class="abbrev">RELAX-NG</abbr>] <span
class="title"><i>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2546166"></a><p>[<abbr class="abbrev">RELAX-NG</abbr>] <span
class="title"><i>
<a href="http://relaxng.org/"; target="_top">RELAX-NG Schema
Language</a>
- </i>. </span></p></div><div class="biblioentry"><a
id="id2533411"></a><p>[<abbr class="abbrev">Trang</abbr>] <span
class="title"><i>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2546184"></a><p>[<abbr class="abbrev">Trang</abbr>] <span
class="title"><i>
<a href="http://www.thaiopensource.com/relaxng/trang.html";
target="_top">Multi-format schema converter based on RELAX NG</a>
- </i>. </span></p></div><div class="biblioentry"><a
id="id2533430"></a><p>[<abbr class="abbrev">MSV</abbr>] <span
class="title"><i>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2546203"></a><p>[<abbr class="abbrev">MSV</abbr>] <span
class="title"><i>
<a href="https://msv.dev.java.net/"; target="_top">Sun Multi-Schema
XML Validator (MSV)</a>
- </i>. </span></p></div><div class="biblioentry"><a
id="id2533448"></a><p>[<abbr class="abbrev">XSD</abbr>] <span
class="title"><i>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2546222"></a><p>[<abbr class="abbrev">XSD</abbr>] <span
class="title"><i>
<a href="http://www.w3.org/XML/Schema"; target="_top">XML Schema</a>
- </i>. </span></p></div><div class="biblioentry"><a
id="id2533466"></a><p>[<abbr class="abbrev">SmokePing</abbr>] <span
class="title"><i>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2546240"></a><p>[<abbr class="abbrev">SmokePing</abbr>] <span
class="title"><i>
<a href="http://oss.oetiker.ch/smokeping/"; target="_top">SmokePing
latency measurement tool</a>
- </i>. </span></p></div><div class="biblioentry"><a
id="id2533485"></a><p>[<abbr class="abbrev">Result Codes</abbr>] <span
class="title"><i>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2546258"></a><p>[<abbr class="abbrev">Result Codes</abbr>] <span
class="title"><i>
<a href="http://wiki.perfsonar.net/jra1-wiki/index.php/Result_codes";
target="_top">Result Codes</a>
- </i>. </span></p></div><div class="biblioentry"><a
id="id2533504"></a><p>[<abbr class="abbrev">Zurawski06Scalable</abbr>] <span
class="title"><i>A Scalable Framework for Representation and Exchange of
Network Measurements</i>. </span><span class="authorgroup"><span
class="firstname">J.</span> <span class="surname">Zurawski</span>, <span
class="firstname">M.</span> <span class="surname">Swany</span>, and <span
class="firstname">D.</span> <span class="surname">Gunter</span>. </span><span
class="confgroup"><span class="confdates">March, 2006. </span><span
class="conftitle">2nd International IEEE/Create-Net Conference on Testbeds
and Research Infrastructures for the Development of Networks and Communities.
</span><span class="address">Barcelona, Spain. </span><span
class="confsponsor">IEEE/Create-Net. </span>.
</span></p></div></div></div></body></html>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2546278"></a><p>[<abbr class="abbrev">Zurawski06Scalable</abbr>] <span
class="title"><i>A Scalable Framework for Representation and Exchange of
Network Measurements</i>. </span><span class="authorgroup"><span
class="firstname">J.</span> <span class="surname">Zurawski</span>, <span
class="firstname">M.</span> <span class="surname">Swany</span>, and <span
class="firstname">D.</span> <span class="surname">Gunter</span>. </span><span
class="confgroup"><span class="confdates">March, 2006. </span><span
class="conftitle">2nd International IEEE/Create-Net Conference on Testbeds
and Research Infrastructures for the Development of Networks and Communities.
</span><span class="address">Barcelona, Spain. </span><span
class="confsponsor">IEEE/Create-Net. </span>.
</span></p></div></div></div></body></html>

Modified: trunk/perfsonar-doc/protocol/base/base_protocol.xml
===================================================================
--- trunk/perfsonar-doc/protocol/base/base_protocol.xml 2008-06-02 10:18:00
UTC (rev 3935)
+++ trunk/perfsonar-doc/protocol/base/base_protocol.xml 2008-06-02 12:03:53
UTC (rev 3936)
@@ -51,19 +51,23 @@
</thead>
<tbody>
<row>
- <entry>1.0</entry>
- <entry>4/3/2008</entry>
+ <entry>1.00</entry>
+ <entry>04/03/2008</entry>
<entry>Initial Preparation</entry>
<entry>J. Zurawski</entry>
</row>
- </tbody>
- <tbody>
<row>
<entry>1.01</entry>
- <entry>4/7/2008</entry>
+ <entry>04/07/2008</entry>
<entry>Wording Edits</entry>
<entry>M. Swany</entry>
</row>
+ <row>
+ <entry>1.02</entry>
+ <entry>05/30/2008</entry>
+ <entry>Pre-OGF Cleanup</entry>
+ <entry>J. Zurawski</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -76,32 +80,37 @@
<para>
<citation>perfSONAR</citation> is an infrastructure for network
performance monitoring and data exchange. It consists of a set of
services
- delivering performance measurements in a federated environment. These
- services act as an intermediate layer, between the performance
measurement
- tools and the diagnostic or visualization applications.
+ capable of performing, storing, and exchanging performance measurements
+ in a federated environment. These services act as an intermediate
layer,
+ between the performance measurement tools and the diagnostic or
+ visualization applications.
</para>

<para>
This framework is designed in the <emphasis>service-oriented</emphasis>
style, implying that a set of elementary functions has been isolated
and
- can be provided by different software entities. In this model, all
- services must communicate using well-defined protocols. This document
- describes the base communication protocol to be used by all services
and
- clients in the
- <emphasis>perfSONAR</emphasis> framework. These communication
protocols
- are based on and utilize the same <citation>XML</citation> structure
used
- to exchange and store measurement data as defined by
- the <citation>NM-WG</citation> in the <citation>OGF</citation>.
+ can be delivered by potentially different software entities. In this
+ model, all services must communicate using well-defined protocols.
+ This document describes the base communication protocol to be used by
+ all services and clients in the <emphasis>perfSONAR</emphasis>
+ framework. These communication protocols are based on and utilize the
+ same <citation>XML</citation> structure used to exchange and store
+ measurement data as defined by the <citation>NM-WG</citation> in the
+ <citation>OGF</citation>.
</para>

<para>
- This document will proceed as follows: we first examine why this
document
- is necessary and what it will achieve. We follow with a discussion of
the
- syntactic details and a semantic description of the major message
types.
- After, we introduce two common protocols used by every service in the
- <emphasis>perfSONAR</emphasis> infrastructure: the Echo and
Authentication
- protocols. Finally we conclude with some description of other protocol
- documents.
+ This document will proceed as follows: in <xref linkend="motivation"
/> we
+ examine why this document is necessary and what it will achieve. In
+ <xref linkend="messages" /> a discussion of the syntactic details and a
+ semantic description of the major message types is discussed. To
motivate
+ some future work, a discussion of <xref linkend="chaining_info" /> is
+ included next. A discussion of some of the common error and status
codes
+ is brought up in <xref linkend="result_codes" />. After this we
introduce
+ two common protocols in <xref linkend="extension" /> used by every
+ service in the <emphasis>perfSONAR</emphasis> infrastructure: the Echo
and
+ Authentication protocols. Finally we conclude with some description of
+ other protocol documents in <xref linkend="conclusion" />.
</para>

</section>
@@ -109,30 +118,20 @@
<section id="motivation" xreflabel="Motivation">
<title>Motivation</title>

- <!--
+ <para>
+ A common message exchange pattern in
<emphasis>perfSONAR</emphasis> is
+ a <emphasis>Request</emphasis> followed by
+ a <emphasis>Response</emphasis>. As this pattern is important,
we will
+ show a basic interaction and build on it. Consider this example
of a
+ client application interacting with some
<emphasis>perfSONAR</emphasis>
+ service in search of data.
+ </para>
+
<para>
- All services feature communication mechanisms derived from the same
- source and function in a particularly similar manner utilizing a
- <emphasis>Request</emphasis> and <emphasis>Response</emphasis>
paradigm.
- Due to this similarity, documenting the detailed aspects of this
behavior
- in repeated descriptions is absurd. Consider this example of a client
- application interacting with some <emphasis>perfSONAR</emphasis>
service
- in search of data.
+ Consider the following exchange diagram demonstrating the exchange
pattern
+ between two <emphasis>perfSONAR</emphasis> entities.
</para>
- -->

- <para>
- A common message exchange pattern in <emphasis>perfSONAR</emphasis>
is
- a <emphasis>Request</emphasis> followed by
- a <emphasis>Response</emphasis>. As this pattern is important, we
will
- show a basic interaction and build on it. Consider this example of
a
- client application interacting with some
<emphasis>perfSONAR</emphasis>
- service in search of data.
- </para>
-
- <!--TODO: While one-sided messaging is not precluded, it is not
completely
- defined yet -->
-
<para>
<mediaobject>
<imageobject>
@@ -157,6 +156,23 @@
</para>

<para>
+ A less common interaction is the notion of a
+ <command>subscription</command>, <command>notification</command> or
+ other form of <emphasis>one-sided</emphasis> exchange.
+ <emphasis>perfSONAR</emphasis> currently uses this to perform tasks
such
+ as <emphasis>subscribing</emphasis> to a service, or otherwise
notifying
+ a service or client about the existence of some key piece of
information.
+ </para>
+
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="exchange3.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+
+ <para>
Essentially, the acts of sending messages, receiving responses, and
being
able to discern success or failure are common across many specific
interactions. One aim of this document is to prevent the following
@@ -171,6 +187,12 @@
exchange and describe how extension is possible.</para>
</listitem>
<listitem>
+ <para><command>Duplicate Semantic Principals</command> - Concepts
used
+ in services designed in the past will more than likely carryover into
+ future releases. Identifying and describing common practices will
+ save time in the documentation of common features.</para>
+ </listitem>
+ <listitem>
<para><command>Duplicate Error Conditions</command> - Some errors
will
occur across services and do not need to be defined repeatedly
(e.g. Unknown Message Type).</para>
@@ -185,9 +207,10 @@
</itemizedlist>

<para>
- With this base, it will be possible to define protocol extensions on
- a <emphasis>type-by-type</emphasis> basis instead of
- <emphasis>service by service</emphasis>. This also allows for a
+ With a set design and format to this base functionality, it is
+ possible to define protocol extensions on a
+ <emphasis>type-by-type</emphasis> basis instead of through the current
+ <emphasis>service by service</emphasis> approach. This also allows
for a
sufficient reduction in documentation due to service types implementing
the same underlying format of messages (e.g. Measurement Archives
mostly
implement the same message types with notable exceptions and data
@@ -247,13 +270,15 @@
<para><command>Message Structure</command> - There may be many
metadata and data elements in each message, and there does not
need to
be a matching data for <emphasis>every</emphasis> metadata (e.g.
- chaining)
+ <xref linkend="chaining_info" />)
</para>
</listitem>
<listitem>
- <para><command>Metadata</command> - Can contain measurement data,
or
- perhaps identifying information about a service, note that we
still
- loosely observe the <emphasis>static</emphasis> rule of
thumb</para>
+ <para><command>Metadata</command> - Can contain measurement data,
+ identifying information about a service, or even information meant
to
+ serve as a modifier (see <xref linkend="chaining_info" />). Note
that
+ we still loosely observe the <emphasis>static</emphasis> rule of
+ thumb</para>
</listitem>
<listitem>
<para><command>Data</command> - Serves a dual role: in request
@@ -273,7 +298,8 @@

<itemizedlist mark='opencircle'>
<listitem>
- <para><command>Syntax</command> - Does the XML parse</para>
+ <para><command>Syntax</command> - Does the request parse
+ correctly</para>
</listitem>
<listitem>
<para><command>Message Type</command> - Can this service accept and
@@ -281,17 +307,16 @@
</listitem>
<listitem>
<para><command>Structure</command> - Is there at least a single
- metadata and data pair that is capable of being acted on; do any
- chains resolve properly</para>
+ metadata and data pair that is capable of being acted on</para>
</listitem>
<listitem>
<para><command>Semantics</command> - Does the request make sense,
can
- the metadata be acted upon</para>
+ the metadata be acted upon; are the chains resolved properly</para>
</listitem>
</itemizedlist>

<para>
- The service has two options at this point: acting on the message and
+ The service has two options at this point: acting on the message
returning data or reporting some other form of status. We will
explore
the first option initially:
</para>
@@ -377,7 +402,7 @@
<message type="response">

<metadata id="m1">
- <!-- some error code -->
+ <!-- some error information -->
</metadata>

<data id="d1" metadatIdRef="m1">
@@ -601,8 +626,8 @@

<para>
The parameters element encloses a series of parameter elements
that
- can be used to adjust variable aspects of a request message.
This
- element serves merely as a container for the
+ can be used to adjust variable aspects of many parts of this
+ schema. This element serves merely as a container for the
<xref linkend="messages_request_analysis_parameter" /> elements
that
will populate it. The single available attribute is described
first:
@@ -706,7 +731,19 @@
<programlisting>
<![CDATA[
<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
- id="metadata2" metadataIdRef="metadata1" />
+ id="metadata2" metadataIdRef="metadata1">
+
+ <!-- Possible Values Include: -->
+
+ <nmwg:subject />
+
+ <nmwg:key />
+
+ <nmwg:eventType />
+
+ <nmwg:parameters />
+
+</nmwg:metadata>
]]>
</programlisting>

@@ -730,7 +767,7 @@
</row>
<row>
<entry><command>nested elements</command></entry>
- <entry>undefined</entry>
+ <entry>undefined, (subject, eventType, and parameters are
common)</entry>
</row>
<row>
<entry><command>required</command></entry>
@@ -744,10 +781,17 @@
The metadata element normally contains the static parts of
measurements, and will no doubt differ from service
to service. Besides measurement data it is possible to send
other
- items such as service descriptions. We leave the description of
- what is possible inside of a metadata blank, and use vague schema
- language that allows for <emphasis>any</emphasis> reasonable XML
- to be contained within.
+ items such as service descriptions. The schema description
itself
+ of what is possible inside of this element uses vague language
that
+ allows for <emphasis>any</emphasis> reasonable XML to be
contained
+ within. The most common elements that are included are
+ <xref linkend="messages_request_analysis_subject" />,
+ <xref linkend="messages_request_analysis_key" />,
+ <xref linkend="messages_request_analysis_eventType" />, and
+ <xref linkend="messages_request_analysis_parameters" />. We will
+ present only a brief discussion of these within this document; a
+ more exact definition may be found in specific measurement
+ documentation.
</para>

<para>
@@ -771,6 +815,183 @@

</section>

+ <section id="messages_request_analysis_subject" xreflabel="Subject">
+ <title>Subject</title>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:subject xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ id="subject1" metadataIdRef="metadata1" />
+ ]]>
+ </programlisting>
+
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_request_analysis_subject">
+ <title>Subject Element Requirements</title>
+ <tgroup cols="1" align="left" colsep="1" rowsep="1">
+ <colspec colnum="1" colname="c1" width="30%"/>
+ <colspec colnum="2" colname="c2" width="70%"/>
+ <tbody>
+ <row>
+ <entry><command>localname</command></entry>
+ <entry>subject</entry>
+ </row>
+ <row>
+ <entry><command>namespaces</command></entry>
+ <entry>http://ggf.org/ns/nmwg/base/2.0/</entry>
+ </row>
+ <row>
+ <entry><command>attributes</command></entry>
+ <entry>id, metadataIdRef</entry>
+ </row>
+ <row>
+ <entry><command>nested elements</command></entry>
+ <entry>undefined, (topology elements are common)</entry>
+ </row>
+ <row>
+ <entry><command>required</command></entry>
+ <entry>N/A</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ The subject element normally contains topological information
that
+ relates directly to a measurement or may refer to a specific
+ service. We leave a full description of this element up to
+ individual implementations but mention it here due to its common
+ use. There are two attributes possible. These are used to both
+ track state and perform a specific type of chaining (e.g.
+ <emphasis>subject</emphasis>) that may be required in a request
+ message. A detailed description follows:
+ </para>
+
+ <itemizedlist mark='opencircle'>
+ <listitem>
+ <para><command>id</command> - Identifying attribute that can be
+ used to track state.</para>
+ </listitem>
+ <listitem>
+ <para><command>metadataIdRef</command> - Identifying attribute
+ that can be used to track state or be linked to
chaining.</para>
+ </listitem>
+ </itemizedlist>
+
+ </section>
+
+ <section id="messages_request_analysis_key" xreflabel="Key">
+ <title>Key</title>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:key xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";>
+
+ <nmwg:parameters />
+
+</nmwg:key>
+ ]]>
+ </programlisting>
+
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_request_analysis_key">
+ <title>Key Element Requirements</title>
+ <tgroup cols="1" align="left" colsep="1" rowsep="1">
+ <colspec colnum="1" colname="c1" width="30%"/>
+ <colspec colnum="2" colname="c2" width="70%"/>
+ <tbody>
+ <row>
+ <entry><command>localname</command></entry>
+ <entry>key</entry>
+ </row>
+ <row>
+ <entry><command>namespaces</command></entry>
+ <entry>http://ggf.org/ns/nmwg/base/2.0/</entry>
+ </row>
+ <row>
+ <entry><command>attributes</command></entry>
+ <entry>id</entry>
+ </row>
+ <row>
+ <entry><command>nested elements</command></entry>
+ <entry>parameters</entry>
+ </row>
+ <row>
+ <entry><command>required</command></entry>
+ <entry>N/A</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ The key structure is normally used to convey sensitive or private
+ information to and from the service. For this reason the
contents
+ of the key should be viewed as opaque, and generally not be
+ disected. The key normally contains the
+ <xref linkend="messages_request_analysis_parameters" /> element.
+ There is only one attributes possible: id. This is used to
+ track state. A detailed description follows:
+ </para>
+
+ <itemizedlist mark='opencircle'>
+ <listitem>
+ <para><command>id</command> - Identifying attribute that can be
+ used to track state.</para>
+ </listitem>
+ </itemizedlist>
+
+ </section>
+
+ <section id="messages_request_analysis_eventType"
xreflabel="EventType">
+ <title>EventType</title>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:eventType
xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";>TEXT</nmwg:eventType>
+ ]]>
+ </programlisting>
+
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_request_analysis_eventType">
+ <title>EventType Element Requirements</title>
+ <tgroup cols="1" align="left" colsep="1" rowsep="1">
+ <colspec colnum="1" colname="c1" width="30%"/>
+ <colspec colnum="2" colname="c2" width="70%"/>
+ <tbody>
+ <row>
+ <entry><command>localname</command></entry>
+ <entry>eventType</entry>
+ </row>
+ <row>
+ <entry><command>namespaces</command></entry>
+ <entry>http://ggf.org/ns/nmwg/base/2.0/</entry>
+ </row>
+ <row>
+ <entry><command>attributes</command></entry>
+ <entry>N/A</entry>
+ </row>
+ <row>
+ <entry><command>nested elements</command></entry>
+ <entry>text</entry>
+ </row>
+ <row>
+ <entry><command>required</command></entry>
+ <entry>N/A</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ The <emphasis>eventType</emphasis> element is commonly used to
+ describe a measurement's specific data type (e.g. corresponding
to
+ the characteristic document) or may be used to trigger an
internal
+ event within the service. This element contains no attributes,
and
+ can only contain text, normally in the form of a
+ <emphasis>URI</emphasis>. There may be many
+ <emphasis>eventType</emphasis> elements in a single metadata.
+ </para>
+
+ </section>
+
<section id="messages_request_analysis_data" xreflabel="Data">
<title>Data</title>

@@ -1097,12 +1318,13 @@
</table>

<para>
- The parameters element is normally only present if there was a
- corresponding element in
- <xref linkend="messages_response_analysis_message" />, although
it
- can be used by services to relay back other forms of information.
- As in <xref linkend="messages_response_analysis_parameters" />,
it
- encloses a series of parameter elements that. This element
serves
+ The parameters element is normally only present in the message
+ element, if there was a corresponding element in
+ <xref linkend="messages_response_analysis_message" />. It
+ can also be used by services to relay back other forms of
+ information. As in
+ <xref linkend="messages_response_analysis_parameters" />, it
+ encloses a series of parameter elements. This element serves
merely as a container for the
<xref linkend="messages_response_analysis_parameter" /> elements
that will populate it. The single available attribute is
described
@@ -1207,7 +1429,19 @@
<programlisting>
<![CDATA[
<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
- id="metadata2" metadataIdRef="metadata1" />
+ id="metadata2" metadataIdRef="metadata1">
+
+ <!-- These elements are commonly used: -->
+
+ <nwmg:subject />
+
+ <nmwg:key />
+
+ <nmwg:eventType />
+
+ <nmwg:parameters />
+
+</nmwg:metadata>
]]>
</programlisting>

@@ -1231,7 +1465,7 @@
</row>
<row>
<entry><command>nested elements</command></entry>
- <entry>undefined</entry>
+ <entry>undefined, (subject, key, eventType, and parameters
are common)</entry>
</row>
<row>
<entry><command>required</command></entry>
@@ -1269,13 +1503,27 @@

</section>

+
+
+<!-- insert subject/eventType/key from above -->
+
+
+
<section id="messages_response_analysis_data" xreflabel="Data">
<title>Data</title>

<programlisting>
<![CDATA[
<nmwg:data xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
- id="data2" metadataIdRef="metadata2" />
+ id="data2" metadataIdRef="metadata2">
+
+ <nmwg:datum />
+
+ <nmwg:key />
+
+ <nmwg:metadata />
+
+</nmwg:data>
]]>
</programlisting>

@@ -1299,7 +1547,7 @@
</row>
<row>
<entry><command>nested elements</command></entry>
- <entry>undefined</entry>
+ <entry>undefined, (datum, key, and metadata are
common)</entry>
</row>
<row>
<entry><command>required</command></entry>
@@ -1336,6 +1584,10 @@

</section>

+
+<!-- insert datum stuff here... -->
+
+
</section>

<section id="messages_response_example" xreflabel="Response Message
Example">
@@ -1388,6 +1640,902 @@

</section>

+
+
+
+
+
+
+
+ <section id="chaining_info" xreflabel="Chaining">
+ <title>Chaining</title>
+
+ <para>
+ Since inception a key goal of the <citation>NM-WG</citation>
+ <citation>XML</citation> specification has been extension. The
+ authors of the original <xref linkend="schemata"/> realized that not
+ every situation could easily be described though the basic constructs;
+ extending the basic building blocks to complex situations would be
+ paramount. Uncharted concepts could be represented with newly created
+ constructs each time a foreign abstraction came to light; but extension
+ and backwards compatibility must be favored over quick and easy
+ solutions. Therefore, basic extension mechanisms, known as
+ <xref linkend="chaining"/>, are the recognized procedure to extend
+ <citation>perfSONAR</citation> metadata constructs as well as express
+ other operations on the underlying data.
+ </para>
+
+ <para>
+ This section presents the major uses of chaining; note that individual
+ service implementations may choose to strictly or loosely interpret
these
+ guidelines for the sake of performance or protection. The protocol
itself
+ offers no specific guidance on these issues in favor of simply
describing
+ the structural composition of both the input data and the resulting
+ output.
+ </para>
+
+ <para>
+ Chaining itself has taken on two major forms: <xref
linkend="merge_chaining"/>
+ and <xref linkend="filter_chaining"/>.
+ These two instances will be described first in broad
+ terms that explain the logic and reasoning of why each operation makes
+ sense, and in what context they should be employed. The specific
syntax
+ and transformation steps will be presented in the next section.
+ </para>
+
+ <section id="merge_chaining_info" xreflabel="Merge Chaining">
+ <title>Merge Chaining</title>
+
+ <para>
+ As the name implies, we intend to <emphasis>merge</emphasis> or
combine metadata elements
+ through this structure. There are many things we may consider when
+ describing this operation:
+ </para>
+
+ <itemizedlist mark='opencircle'>
+ <listitem>
+ <para>Which elements are <emphasis>mergeable</emphasis>?</para>
+ </listitem>
+ <listitem>
+ <para>How much <emphasis>recursion</emphasis> is needed for
mergeable elements?</para>
+ </listitem>
+ <listitem>
+ <para>When do we <emphasis>duplicate</emphasis> elements?</para>
+ </listitem>
+ <listitem>
+ <para>When should we <emphasis>replace</emphasis> elements in the
course of merging?</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ As stated previously, the schemata itself does not offer any
suggestions
+ as to what is a good merge vs. a bad merge. There are no rules
+ regarding which <emphasis>types</emphasis> of data should and should
+ not be merged. There is no guidance on when we can duplicate or
+ replace elements.
+ </para>
+
+ <para>
+ We present here some very simple and succinct guidelines that
services
+ may implement for this particular style of merging. There will
always
+ be exceptions to rules, therefore the reader is encouraged to think
+ carefully about what a specific service may need when implementing
this
+ recommendation.
+ </para>
+
+ <section id="merge_chaining_recurse" xreflabel="Mergeable Elements and
Recursion">
+ <title>Mergeable Elements and Recursion</title>
+
+ <para>
+ In general when merging we first look at the
<emphasis>top-level</emphasis> elements;
+ namely subject, eventType, and parameters. When faced with
+ two metadata blocks to be merged, we only wish to combine
<emphasis>like</emphasis>
+ elements that share a common namespace. When this first criteria
is
+ met, we will of course recurse downward and keep trying until we
+ reach the bottom of the structure.
+ </para>
+
+ <para>
+ How far should we venture into the XML structure looking for
+ similarities or differences? This question does not have a
definite
+ answer such as <emphasis>stop at the grandchild of the current
element</emphasis>. While
+ this may be frustrating, domain knowledge can help you make a
passable
+ decision especially with regards to topology based elements.
+ </para>
+
+ <para>
+ <emphasis>Like</emphasis> elements that do not share a common
namespace will require
+ special rules that may differ from service to service. Depending
on
+ the level of protection or speed we wish to attain these rules will
+ vary. Service and protocol documentation will fill in details
beyond
+ the scope of this memo.
+ </para>
+
+ </section>
+
+ <section id="merge_chaining_rules" xreflabel="Duplication,
Augmentation, and Replacement">
+ <title>Duplication, Augmentation, and Replacement</title>
+
+ <para>
+ When are faced with <emphasis>like</emphasis> elements that may
not share a common
+ namespace we shouldn't really combine at all. We can try to find
the
+ <emphasis>least significant</emphasis> namespace and work from
there. Additionally we
+ will sometimes run into items that may be exactly the same (such as
+ certain <emphasis>parameters</emphasis>, or
<emphasis>eventTypes</emphasis>). In some cases we should take
+ care to <emphasis>add</emphasis> all of these together to make
duplicates; other cases
+ may dictate total replacement. Specific rule such as these are
best
+ left to a service designer.
+ </para>
+
+ <para>
+ As an example of extreme cases, consider taking the very safe
approach
+ to the combining of elements (i.e. not merging
<emphasis>like</emphasis> elements with
+ different namespaces). This approach will ensure that we protect
the
+ from schema differences but may result in many more
<emphasis>wrong</emphasis> answers
+ when it comes to searching. The converse is a very dangerous
approach
+ we we do in fact merge items that could be different on the inside.
+ This will result in an approach similar to <emphasis>I know what
you meant</emphasis> and
+ could yield a more robust query mechanism (providing intuitive
answers
+ when something may not completely match, rejecting outright things
+ that do not make sense).
+ </para>
+
+ </section>
+
+ <section id="merge_chaining_ex" xreflabel="Merge Chaining Examples">
+ <title>Merge Chaining Examples</title>
+
+ <para>
+ A classic example of merge chaining is to partially specify a
metadata
+ (leaving out perhaps one key element) and then constructing new
elements
+ from this original. This example does not feature any
<emphasis>overwriting</emphasis> of
+ duplicate elements.
+ </para>
+
+ <para>
+ Take for example our SNMP Interface from above. If e wanted to
specify
+ the two common <emphasis>directions</emphasis>
(<emphasis>in</emphasis> and <emphasis>out</emphasis>) we could construct a
chain
+ similar to the below example.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1">
+ <netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:direction>in</nmwgt:direction>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ </nmwgt:interface>
+ </netutil:subject>
+ <nmwg:eventType>http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:eventType>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:parameter>
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="m1">
+ <netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s2">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:direction>in</nmwgt:direction>
+ </nmwgt:interface>
+ </netutil:subject>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m3"
metadataIdRef="m1">
+ <netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s3">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:direction>out</nmwgt:direction>
+ </nmwgt:interface>
+ </netutil:subject>
+</nmwg:metadata>
+ ]]>
+ </programlisting>
+
+ <para>
+ Note that the chaining is performed via the use of the
<emphasis>metadataIdRef</emphasis>
+ tag in the metadata element. This is a signal for services
(specifically
+ the SNMP MA or RRD MA) to keep looking deeper in an effort to
+ resolve the chains. The figure below demonstrates the
<emphasis>linking</emphasis> between
+ the metadata elements. The resulting XML structure after chaining
is also
+ listed below.
+ </para>
+
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="chain.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1">
+ <netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ <nmwgt:direction>in</nmwgt:direction>
+ </nmwgt:interface>
+ </netutil:subject>
+ <nmwg:eventType>http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:eventType>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:parameter>
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="m1">
+ <netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ <nmwgt:direction>in</nmwgt:direction>
+ </nmwgt:interface>
+ </netutil:subject>
+ <nmwg:eventType>http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:eventType>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:parameter>
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m3"
metadataIdRef="m1">
+ <netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ <nmwgt:direction>out</nmwgt:direction>
+ </nmwgt:interface>
+ </netutil:subject>
+ <nmwg:eventType>http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:eventType>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:parameter>
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+ ]]>
+ </programlisting>
+
+ <para>
+ For continuity this example has not attempted to modify the
+ <emphasis>metadataIdRef</emphasis> attribute. Implementations may
choose to do so if
+ they feel the need. Because eventTypes may be repeated (either as
the
+ <emphasis>eventType</emphasis> element or as parameters) we must
take special care when
+ merging them. The next example features multiple eventType
merging.
+ This example also features a so called <emphasis>double
chain</emphasis> where the results
+ of the first chaining operation will feed into the process for the
+ second. This is a common occurrence, and should be supported in
+ services.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1">
+ <nmwg:subject id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ <nmwgt:direction>in</nmwgt:direction>
+ </nmwgt:interface>
+ </nmwg:subject>
+ <nmwg:eventType>http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="m1">
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m3"
metadataIdRef="m2">
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/errors/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/errors/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+ ]]>
+ </programlisting>
+
+ <para>
+ The resulting output and cartoon are pictured below. We did take
two
+ major issues into consideration: multiple
<emphasis>parameters</emphasis> and <emphasis>eventType</emphasis>
+ elements that did conflict, and the double chaining. Services
that do
+ no support multiple eventTypes (or simply wish to not implement a
+ naive form of chaining) will not need to worry about special cases
such
+ as this.
+ </para>
+
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="chain2.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1">
+ <nmwg:subject id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ <nmwgt:direction>in</nmwgt:direction>
+ </nmwgt:interface>
+ </nmwg:subject>
+ <nmwg:eventType>http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="m1">
+ <nmwg:subject id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ <nmwgt:direction>in</nmwgt:direction>
+ </nmwgt:interface>
+ </nmwg:subject>
+ <nmwg:eventType>http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:eventType>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:parameter>
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m3"
metadataIdRef="m2">
+ <nmwg:subject id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ <nmwgt:direction>in</nmwgt:direction>
+ </nmwgt:interface>
+ </nmwg:subject>
+ <nmwg:eventType>http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:eventType>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/errors/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:parameter>
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/errors/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+ ]]>
+ </programlisting>
+
+ <para>
+ Services such as the SNMP MA treat particular elements (such as
+ eventTypes and parameters with certain <emphasis>name</emphasis>
attributes) in a special
+ way. The service is careful not to overwrite or lose any
information
+ and will only add these items together. This is not the case for
any
+ element though, consider the following example.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1">
+ <nmwg:subject id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ <nmwgt:direction>in</nmwgt:direction>
+ </nmwgt:interface>
+ </nmwg:subject>
+ <nmwg:eventType>http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="m1">
+ <nmwg:subject id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifName>eth1</nmwgt:ifName>
+ <nmwgt:direction>out</nmwgt:direction>
+ </nmwgt:interface>
+ </nmwg:subject>
+</nmwg:metadata>
+ ]]>
+ </programlisting>
+
+ <para>
+ Note that we probably wanted to change the direction for this
particular
+ interface, not necessarily the <emphasis>ifName</emphasis>
element. The output of this
+ chain is shown below.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1">
+ <nmwg:subject id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ <nmwgt:direction>in</nmwgt:direction>
+ </nmwgt:interface>
+ </nmwg:subject>
+ <nmwg:eventType>http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="m1">
+ <nmwg:subject id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth1</nmwgt:ifName>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ <nmwgt:direction>out</nmwgt:direction>
+ </nmwgt:interface>
+ </nmwg:subject>
+ <nmwg:eventType>http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+ ]]>
+ </programlisting>
+
+ <para>
+ This example shows that its pretty easy to accidental flub up when
+ designing a chain instance. It also shows that the service won't
+ necessarily do a whole lot to warn you of your actions. It is
possible
+ to build in different rules instead of <emphasis>last seen
value</emphasis> such as
+ <emphasis>first seen</emphasis>, <emphasis>original</emphasis>, or
any other combination. It is imperative
+ that services describe their own implementations of chaining,
+ particularly when interoperability becomes an issue.
+ </para>
+
+ <para>
+ A final example comes when we deal with items with the same local
+ name, but perhaps a different namespace. There are several
approaches
+ that can be taken to dealing with this type of situation. The SNMP
+ follows a safe approach of simply <emphasis>adding</emphasis> all
of the elements in
+ question and not attempting to internally merge at all. This
causes
+ unreadable metadata in many cases, but does not permit data
pollution.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1">
+ <nmwg:subject id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ </nmwgt:interface>
+ </nmwg:subject>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="1">
+ <netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s2">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:direction>in</nmwgt:direction>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ </nmwgt:interface>
+ </netutil:subject>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+ ]]>
+ </programlisting>
+
+ <para>
+ There are three approaches that I will illustrate here:
+ <emphasis>safe yet stupid</emphasis>, <emphasis>dangerous yet
intelligent</emphasis>, and finally
+ <emphasis>slow and steady</emphasis>. In the case of services
like the SNMP
+ MA the last approach is used, finding the proper balance will
require
+ some thought (depending on how sensing or accurate a service
wishes to
+ become. Approach one yields output similar to the below example.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1">
+ <nmwg:subject id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ </nmwgt:interface>
+ </nmwg:subject>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="1">
+ <netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s2">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:direction>in</nmwgt:direction>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ </nmwgt:interface>
+ </netutil:subject>
+ <nmwg:subject id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ </nmwgt:interface>
+ </nmwg:subject>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+ ]]>
+ </programlisting>
+
+ <para>
+ Note that this is not schema valid, and presumably would not return
+ results from the backend storage. This is rather ironic given
that we
+ are trying to preserve validity on the schema side of things yet
still
+ generate a clearly invalid result. The other end of the spectrum
gives
+ a result such as the example below.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1">
+ <nmwg:subject id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ </nmwgt:interface>
+ </nmwg:subject>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="1">
+ <netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s2">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:direction>in</nmwgt:direction>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ </nmwgt:interface>
+ </netutil:subject>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+ ]]>
+ </programlisting>
+
+ <para>
+ The <emphasis>stupid</emphasis> part of this comes from not
necessarily caring about
+ namespaces, and only merging based on localname. Because the
<emphasis>source</emphasis>
+ metadata featured the <emphasis>netutil</emphasis> namespace it
remains and all other
+ items are added to it.
+ </para>
+
+ <para>
+ The approach taken by the SNMP MA is to have a little domain
knowledge
+ before making a quick judgement. Knowing full well that
<emphasis>nmwg</emphasis> is
+ a more general namespace than <emphasis>netutil</emphasis> the
service tries to <emphasis>guess</emphasis>
+ the intent and goes with the most general namespace in order to
support
+ a richer query set. Internally anything that utilizes the
<emphasis>nmwg</emphasis>
+ namespace receives a <emphasis>wild card</emphasis> when
performing searches, therefor when
+ we are faced with a choice between specific and general, the
service
+ errs on the side of general. An example of this merge is below.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1">
+ <nmwg:subject id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ </nmwgt:interface>
+ </nmwg:subject>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="1">
+ <nmwg:subject id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:direction>in</nmwgt:direction>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ </nmwgt:interface>
+ </nmwg:subject>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+ ]]>
+ </programlisting>
+
+ <para>
+ A final question remains: what happens if you are dealing with two
+ very specific namespaces such as this example.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1">
+ <neterr:subject
xmlns:neterr="http://ggf.org/ns/nmwg/characteristic/errors/2.0/"; id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ </nmwgt:interface>
+ </neterr:subject>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/errors/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/errors/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="1">
+ <netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s2">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ </nmwgt:interface>
+ </netutil:subject>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+ ]]>
+ </programlisting>
+
+ <para>
+ In the case of the SNMP MA the service will still guess
<emphasis>general</emphasis> and
+ convert to the <emphasis>nmwg</emphasis> namespace. The resulting
data set
+ will of coursetake on an interesting look as in this result.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1">
+ <neterr:subject
xmlns:neterr="http://ggf.org/ns/nmwg/characteristic/errors/2.0/"; id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ </nmwgt:interface>
+ </neterr:subject>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/errors/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/errors/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2"
metadataIdRef="1">
+ <nmwg:subject id="s2">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ </nmwgt:interface>
+ </nmwg:subject>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/errors/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/errors/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+ ]]>
+ </programlisting>
+
+ <para>
+ Clearly the two eventTypes (for utilization and errors) may not
appear
+ in the same metadata description, but again the SNMP MA tries to
help
+ out a bit. eventType descriptions are interpreted as
<emphasis>or</emphasis> operations when
+ performing a query. Therefore even if our chain was constructed
poorly,
+ our final results will be rather robust (perhaps a bit more robust
+ than needed). The service designers will no doubt settle on an
+ approach that fits well for the data they are exposing.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section id="filter_chaining_info" xreflabel="Filter Chaining">
+ <title>Operator (Filter) Chaining</title>
+
+ <para>
+ Filter chaining involves the application of a
+ <emphasis>filter</emphasis> (or function) to the underlying dataset
+ that a particular metadata describes. We can think of this much
like a
+ database operation, where the first metadata is used to select a
broad
+ range of data, and subsequent metadata elements that are chained in
+ this manner are used to slowly whittle down the dataset to very
+ specific range.
+ </para>
+
+ <para>
+ The figure illustrates the distinction between the various operators
+ of a filter chain. The circles themselves represent the actual
metadata
+ description of a dataset (taken from the universe of all data). The
+ intersection of these two metadata descriptions becomes the data set
+ that we are interested in.
+ </para>
+
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="ven.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+
+ <para>
+ It is important to note that even though we are manipulating the data
+ through this form of chaining, we shouldn't be harming it, or it the
+ related metadata elements. Chaining in general is a non-destructive
+ operation although it is very possible that when implemented poorly
+ data corruption may occur.
+ </para>
+
+ <para>
+ Filter operations themselves can vary from time range selection to
+ aggregations such as <citation>CDF</citation>. Describing all
+ possible operators is well beyond the scope of this work. Current
+ experience has named most statistical and database operations as
+ candidates for filtering, although new uses are always being
devised.
+ </para>
+
+ <section id="filter_chaining_ex" xreflabel="Filter Chaining Examples">
+ <title>Operator Chaining Examples</title>
+
+ <para>
+ Filter chaining itself is an easier concept to manage than merge
+ chaining, partially because there are less rules and nuances to
grasp.
+ As stated above, it is easy to think of the dataset for the
+ source metadata to be <emphasis>input</emphasis> to a function
that is named
+ by the metadata utilizing the filter chain. Consider the following
+ cartoon as an example of the internal process of resolving a filter
+ chain.
+ </para>
+
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="filter.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+
+ <para>
+ The syntax of filter chaining is similar to that of merge chaining
(by
+ using <emphasis>metadataIdRef</emphasis> attributes) but the
placement is a bit different.
+ Consider this example.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m1">
+ <netutil:subject
xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/";
id="s1">
+ <nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/";>
+ <nmwgt:ifAddress type="ipv4">127.0.0.1</nmwgt:ifAddress>
+ <nmwgt:hostName>localhost</nmwgt:hostName>
+ <nmwgt:ifName>eth0</nmwgt:ifName>
+ <nmwgt:ifIndex>2</nmwgt:ifIndex>
+ <nmwgt:direction>in</nmwgt:direction>
+ <nmwgt:capacity>1000000000</nmwgt:capacity>
+ </nmwgt:interface>
+ </netutil:subject>
+ <nmwg:eventType>http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:eventType>
+
<nmwg:eventType>http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:eventType>
+ <nmwg:parameters id="p1">
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:parameter>
+ <nmwg:parameter
name="supportedEventType">http://ggf.org/ns/nmwg/characteristic/utilization/2.0</nmwg:parameter>
+ </nmwg:parameters>
+</nmwg:metadata>
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="m2">
+ <select:subject id="s2" metadataIdRef="m1"
xmlns:select="http://ggf.org/ns/nmwg/ops/select/2.0/"/>
+ <select:parameters id="param2c"
xmlns:select="http://ggf.org/ns/nmwg/ops/select/2.0/";>
+ <nmwg:parameter name="startTime">1121472000</nmwg:parameter>
+ <nmwg:parameter name="endTime">1121904000</nmwg:parameter>
+ <nmwg:parameter name="consolidationFunction">AVERAGE</nmwg:parameter>
+ <nmwg:parameter name="resolution">60</nmwg:parameter>
+ </select:parameters>
+ <nmwg:eventType>http://ggf.org/ns/nmwg/ops/select/2.0</nmwg:eventType>
+</nmwg:metadata>
+ ]]>
+ </programlisting>
+
+ <para>
+ The reference is placed in the <emphasis>subject</emphasis>
element in this case, as in
+ merge chaining this is a signal to the service that filter
chaining will
+ be required. This indicates that the <emphasis>input</emphasis>
is the data pointed to
+ by the first metadata and the output will be a subset of this. For
+ the sake of these examples we will be dealing with the
<emphasis>select</emphasis>
+ namespace as our filter of choice due to an abundance of examples
and
+ its common goal of filtering based on time. Other filter examples
will
+ work in the same manner.
+ </para>
+
+ <para>
+ Because the operations of a filter chain are essentially
<emphasis>internal</emphasis> we
+ do not present what resultant XML should look like. Currently
services
+ ignore many of the steps that may go into reforming the XML for
+ response messages in favor of simply returning the
<emphasis>backend</emphasis>
+ representation of metadata. While quick and easy, this does lead
to
+ information loss (specifically when dealing with the various ways
to
+ implement merge chaining). Client applications may have no reason
to
+ see the original filter information, and therefore are built not
to
+ need it.
+ </para>
+
+ </section>
+
+ </section>
+
+ </section>
+
<section id="result_codes" xreflabel="Result Codes">
<title>Result Codes</title>

@@ -2450,7 +3598,15 @@
</glossdiv>

<glossdiv id="C">
- <title>C</title>
+ <title>C</title>
+ <glossentry id="chaining"><glossterm>chaining</glossterm>
+ <glossdef>
+ <para>The process of linking together elements in the NM-WG
+ XML specification.</para>
+ </glossdef>
+ <glossseealso otherterm="filter_chaining">filter
chaining</glossseealso>
+ <glossseealso otherterm="merge_chaining">merge
chaining</glossseealso>
+ </glossentry>
<glossentry id="characteristic"
xreflabel="characteristics"><glossterm>characteristic</glossterm>
<glossdef>
<para>Taken on the context of networking, these describe the
@@ -2477,7 +3633,15 @@
</glossdiv>

<glossdiv id="F">
- <title>F</title>
+ <title>F</title>
+ <glossentry id="filter_chaining" xreflabel="filter
chaining"><glossterm>filter chaining</glossterm>
+ <glossdef>
+ <para>Chaining operation that is akin to performing advanced
+ selection or aggregation on a dataset.</para>
+ </glossdef>
+ <glossseealso otherterm="chaining">chaining</glossseealso>
+ <glossseealso otherterm="merge_chaining">merge
chaining</glossseealso>
+ </glossentry>
</glossdiv>

<glossdiv id="G">
@@ -2514,7 +3678,15 @@
</glossdiv>

<glossdiv id="M">
- <title>M</title>
+ <title>M</title>
+ <glossentry id="merge_chaining" xreflabel="merge
chaining"><glossterm>merge chaining</glossterm>
+ <glossdef>
+ <para>Chaining that combines linked metadata items into a new
+ representation.</para>
+ </glossdef>
+ <glossseealso otherterm="filter_chaining">filter
chaining</glossseealso>
+ <glossseealso otherterm="chaining">chaining</glossseealso>
+ </glossentry>
<glossentry id="metadata"><glossterm>metadata</glossterm>
<glossdef>
<para>An <xref linkend="NMWG" /> XML block used
@@ -2526,6 +3698,12 @@

<glossdiv id="N">
<title>N</title>
+ <glossentry id="namespace"><glossterm>namespace</glossterm>
+ <glossdef>
+ <para>A simple method of qualifying names (element or attribute)
+ in XML by associating them with URI references.</para>
+ </glossdef>
+ </glossentry>
<glossentry id="NMWG"><glossterm>NM-WG</glossterm>
<glossdef>
<para>The performance of most grid applications is dependent on
the
@@ -2543,7 +3721,12 @@
</glossdiv>

<glossdiv id="P">
- <title>P</title>
+ <title>P</title>
+ <glossentry id="perfSONAR"><glossterm>perfSONAR</glossterm>
+ <glossdef>
+ <para>Network performance monitoring framework.</para>
+ </glossdef>
+ </glossentry>
<glossentry id="ping"><glossterm>ping</glossterm>
<glossdef>
<para>
@@ -2566,7 +3749,19 @@
</glossdiv>

<glossdiv id="S">
- <title>S</title>
+ <title>S</title>
+ <glossentry id="schema"><glossterm>schema</glossterm>
+ <glossdef>
+ <para>XML specification, normally written in XML.</para>
+ </glossdef>
+ <glossseealso otherterm="schemata">schemata</glossseealso>
+ </glossentry>
+ <glossentry id="schemata"><glossterm>schemata</glossterm>
+ <glossdef>
+ <para>Plural of schema.</para>
+ </glossdef>
+ <glossseealso otherterm="schema">schema</glossseealso>
+ </glossentry>
</glossdiv>

<glossdiv id="T">

Added: trunk/perfsonar-doc/protocol/base/chain.dia


Property changes on: trunk/perfsonar-doc/protocol/base/chain.dia
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream

Added: trunk/perfsonar-doc/protocol/base/chain.png


Property changes on: trunk/perfsonar-doc/protocol/base/chain.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream

Added: trunk/perfsonar-doc/protocol/base/chain2.dia


Property changes on: trunk/perfsonar-doc/protocol/base/chain2.dia
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream

Added: trunk/perfsonar-doc/protocol/base/chain2.png


Property changes on: trunk/perfsonar-doc/protocol/base/chain2.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream

Added: trunk/perfsonar-doc/protocol/base/exchange3.dia


Property changes on: trunk/perfsonar-doc/protocol/base/exchange3.dia
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream

Added: trunk/perfsonar-doc/protocol/base/exchange3.png


Property changes on: trunk/perfsonar-doc/protocol/base/exchange3.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream

Added: trunk/perfsonar-doc/protocol/base/filter.dia


Property changes on: trunk/perfsonar-doc/protocol/base/filter.dia
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream

Added: trunk/perfsonar-doc/protocol/base/filter.png


Property changes on: trunk/perfsonar-doc/protocol/base/filter.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream

Added: trunk/perfsonar-doc/protocol/base/ven.dia


Property changes on: trunk/perfsonar-doc/protocol/base/ven.dia
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream

Added: trunk/perfsonar-doc/protocol/base/ven.png


Property changes on: trunk/perfsonar-doc/protocol/base/ven.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream


  • perfsonar: r3936 - trunk/perfsonar-doc/protocol/base, svnlog, 06/02/2008

Archive powered by MHonArc 2.6.16.

Top of Page