perfsonar-dev - perfsonar: r5107 - in trunk/perfsonar-doc/protocol: . Echo Echo/examples Echo/schema MA MA/examples MA/schema base

Subject: perfsonar development work

List archive

perfsonar: r5107 - in trunk/perfsonar-doc/protocol: . Echo Echo/examples Echo/schema MA MA/examples MA/schema base

From:
To:
Subject: perfsonar: r5107 - in trunk/perfsonar-doc/protocol: . Echo Echo/examples Echo/schema MA MA/examples MA/schema base
Date: Thu, 23 Apr 2009 22:30:11 -0400

Author: zurawski
Date: 2009-04-23 22:30:10 -0400 (Thu, 23 Apr 2009)
New Revision: 5107

Added:
trunk/perfsonar-doc/protocol/Echo/
trunk/perfsonar-doc/protocol/Echo/Makefile
trunk/perfsonar-doc/protocol/Echo/echo_extension.html
trunk/perfsonar-doc/protocol/Echo/echo_extension.xml
trunk/perfsonar-doc/protocol/Echo/examples/
trunk/perfsonar-doc/protocol/Echo/examples/request_extension.xml
trunk/perfsonar-doc/protocol/Echo/examples/response_extension.xml
trunk/perfsonar-doc/protocol/Echo/schema/
trunk/perfsonar-doc/protocol/Echo/schema/echo_request_extension.rnc
trunk/perfsonar-doc/protocol/Echo/schema/echo_response_extension.rnc
trunk/perfsonar-doc/protocol/LS/
trunk/perfsonar-doc/protocol/MA/examples/sd_request1.xml
trunk/perfsonar-doc/protocol/MA/examples/sd_request2.xml
trunk/perfsonar-doc/protocol/MA/examples/sd_request3.xml
trunk/perfsonar-doc/protocol/MA/examples/sd_request4.xml
trunk/perfsonar-doc/protocol/MA/examples/sd_request5.xml
trunk/perfsonar-doc/protocol/MA/examples/sd_response1.xml
trunk/perfsonar-doc/protocol/MA/examples/sd_response2.xml
trunk/perfsonar-doc/protocol/MA/examples/sd_response3.xml
trunk/perfsonar-doc/protocol/MA/schema/setupdata_request.rnc
trunk/perfsonar-doc/protocol/MA/schema/setupdata_response.rnc
Modified:
trunk/perfsonar-doc/protocol/MA/ma.html
trunk/perfsonar-doc/protocol/MA/ma.xml
trunk/perfsonar-doc/protocol/base/base_protocol.html
trunk/perfsonar-doc/protocol/base/base_protocol.xml
Log:
Some long overdue updates to the various protocol documents.

-jason

Added: trunk/perfsonar-doc/protocol/Echo/Makefile

Property changes on: trunk/perfsonar-doc/protocol/Echo/Makefile
___________________________________________________________________
Name: svn:mime-type
+ text/plain
Name: svn:keywords
+ "Author Date Id Rev URL"
Name: svn:eol-style
+ native

Added: trunk/perfsonar-doc/protocol/Echo/echo_extension.html

Property changes on: trunk/perfsonar-doc/protocol/Echo/echo_extension.html
___________________________________________________________________
Name: svn:mime-type
+ text/html
Name: svn:keywords
+ "Author Date Id Rev URL"
Name: svn:eol-style
+ native

Copied: trunk/perfsonar-doc/protocol/Echo/echo_extension.xml (from rev 5101,
trunk/perfsonar-doc/protocol/base/echo_extension.xml)

Property changes on: trunk/perfsonar-doc/protocol/Echo/echo_extension.xml
___________________________________________________________________
Name: svn:mergeinfo
+

Copied: trunk/perfsonar-doc/protocol/Echo/examples/request_extension.xml
(from rev 5101,
trunk/perfsonar-doc/protocol/base/examples/request_extension.xml)

Property changes on:
trunk/perfsonar-doc/protocol/Echo/examples/request_extension.xml
___________________________________________________________________
Name: svn:mergeinfo
+

Copied: trunk/perfsonar-doc/protocol/Echo/examples/response_extension.xml
(from rev 5101,
trunk/perfsonar-doc/protocol/base/examples/response_extension.xml)

Property changes on:
trunk/perfsonar-doc/protocol/Echo/examples/response_extension.xml
___________________________________________________________________
Name: svn:mergeinfo
+

Copied: trunk/perfsonar-doc/protocol/Echo/schema/echo_request_extension.rnc
(from rev 5101,
trunk/perfsonar-doc/protocol/base/schema/echo_request_extension.rnc)

Property changes on:
trunk/perfsonar-doc/protocol/Echo/schema/echo_request_extension.rnc
___________________________________________________________________
Name: svn:mergeinfo
+

Copied: trunk/perfsonar-doc/protocol/Echo/schema/echo_response_extension.rnc
(from rev 5101,
trunk/perfsonar-doc/protocol/base/schema/echo_response_extension.rnc)

Property changes on:
trunk/perfsonar-doc/protocol/Echo/schema/echo_response_extension.rnc
___________________________________________________________________
Name: svn:mergeinfo
+

Added: trunk/perfsonar-doc/protocol/MA/examples/sd_request1.xml

Property changes on: trunk/perfsonar-doc/protocol/MA/examples/sd_request1.xml
___________________________________________________________________
Name: svn:mime-type
+ text/xml
Name: svn:keywords
+ "Author Date Id Rev URL"
Name: svn:eol-style
+ native

Added: trunk/perfsonar-doc/protocol/MA/examples/sd_request2.xml

Property changes on: trunk/perfsonar-doc/protocol/MA/examples/sd_request2.xml
___________________________________________________________________
Name: svn:mime-type
+ text/xml
Name: svn:keywords
+ "Author Date Id Rev URL"
Name: svn:eol-style
+ native

Added: trunk/perfsonar-doc/protocol/MA/examples/sd_request3.xml

Property changes on: trunk/perfsonar-doc/protocol/MA/examples/sd_request3.xml
___________________________________________________________________
Name: svn:mime-type
+ text/xml
Name: svn:keywords
+ "Author Date Id Rev URL"
Name: svn:eol-style
+ native

Added: trunk/perfsonar-doc/protocol/MA/examples/sd_request4.xml

Property changes on: trunk/perfsonar-doc/protocol/MA/examples/sd_request4.xml
___________________________________________________________________
Name: svn:mime-type
+ text/xml
Name: svn:keywords
+ "Author Date Id Rev URL"
Name: svn:eol-style
+ native

Added: trunk/perfsonar-doc/protocol/MA/examples/sd_request5.xml

Property changes on: trunk/perfsonar-doc/protocol/MA/examples/sd_request5.xml
___________________________________________________________________
Name: svn:mime-type
+ text/xml
Name: svn:keywords
+ "Author Date Id Rev URL"
Name: svn:eol-style
+ native

Added: trunk/perfsonar-doc/protocol/MA/examples/sd_response1.xml

Property changes on: trunk/perfsonar-doc/protocol/MA/examples/sd_response1.xml
___________________________________________________________________
Name: svn:mime-type
+ text/xml
Name: svn:keywords
+ "Author Date Id Rev URL"
Name: svn:eol-style
+ native

Added: trunk/perfsonar-doc/protocol/MA/examples/sd_response2.xml

Property changes on: trunk/perfsonar-doc/protocol/MA/examples/sd_response2.xml
___________________________________________________________________
Name: svn:mime-type
+ text/xml
Name: svn:keywords
+ "Author Date Id Rev URL"
Name: svn:eol-style
+ native

Added: trunk/perfsonar-doc/protocol/MA/examples/sd_response3.xml

Property changes on: trunk/perfsonar-doc/protocol/MA/examples/sd_response3.xml
___________________________________________________________________
Name: svn:mime-type
+ text/xml
Name: svn:keywords
+ "Author Date Id Rev URL"
Name: svn:eol-style
+ native

Modified: trunk/perfsonar-doc/protocol/MA/ma.html
===================================================================
--- trunk/perfsonar-doc/protocol/MA/ma.html 2009-04-23 11:23:39 UTC (rev
5106)
+++ trunk/perfsonar-doc/protocol/MA/ma.html 2009-04-24 02:30:10 UTC (rev
5107)
@@ -1,11 +1,10 @@
-<?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 Measurement Archive (MA) Protocol Extension</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="id2479489"></a>perfSONAR
Measurement Archive (MA) Protocol Extension</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"><<a
href="mailto:"></a>></code><br
/>
+<html xmlns="http://www.w3.org/1999/xhtml";><head><meta
http-equiv="Content-Type" content="text/html; charset=UTF-8"
/><title>perfSONAR Measurement Archive (MA) Protocol Extension</title><meta
name="generator" content="DocBook XSL Stylesheets V1.73.2"
/></head><body><div class="article" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h2 class="title"><a id="id2476818"></a>perfSONAR
Measurement Archive (MA) Protocol Extension</h2></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"><<a class="email"
href="mailto:"></a>></code><br
/>
          </p></div></div></div><div class="editor"><h4
class="editedby">Edited by</h4><h3 class="editor"><span
class="firstname">M.</span> <span class="surname">Swany</span></h3><div
class="affiliation"><span class="orgname">Universtity of Delaware<br
/></span><div class="address"><p>   <br />
-            <code class="email"><<a
href="mailto:"></a>></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="#metadata_key">3. MetadataKey</a></span></dt><dd><dl><dt><span
class="section"><a href="#metadata_key_request">3.1. MetadataKeyRequest
Message</a></span></dt><dd><dl><dt><span class="section"><a
href="#metadata_key_request_schema">3.1.1. MetadataKeyRequest Message
Schema</a></span></dt><dt><span class="section"><a
href="#metadata_key_request_analysis">3.1.2. MetadataKeyRequest Message
Analysis</a></span></dt><dd><dl><dt><span class="section"><a
href="#metadata_key_request_analysis_message">3.1.2.1.
Message</a></span></dt><dt><span class="section"><a
href="#metadata_key_request_analysis_parameters">3.1.2.2.
Parameters</a></span></dt><dt><span class="section"><a
href="#metadata_key_request_analysis_parameter">3.1.2.3.
Parameter</a></span></dt><dt><span class="section"><a
href="#metadata_key_request_analysis_metadata">3.1.2.4.
Metadata</a></span></dt><dt><span class="section"><a
href="#metadata_key_request_analysis_data">3.1.2.5.
Data</a></span></dt></dl></dd><dt><span class="section"><a
href="#metadata_key_request_example">3.1.3. MetadataKeyRequest Message
Example</a></span></dt></dl></dd><dt><span class="section"><a
href="#metadata_key_response">3.2. MetadataKeyResponse
Message</a></span></dt><dd><dl><dt><span class="section"><a
href="#metadata_key_response_schema">3.2.1. MetadataKeyResponse Message
Schema</a></span></dt><dt><span class="section"><a
href="#metadata_key_response_analysis">3.2.2. MetadataKeyResponse Message
Analysis</a></span></dt><dd><dl><dt><span class="section"><a
href="#metadata_key_response_analysis_message">3.2.2.1.
Message</a></span></dt><dt><span class="section"><a
href="#metadata_key_response_analysis_parame
ters">3.2.2.2. Parameters</a></span></dt><dt><span class="se!
ction"><
a href="#metadata_key_response_analysis_parameter">3.2.2.3.
Parameter</a></span></dt><dt><span class="section"><a
href="#metadata_key_response_analysis_metadata">3.2.2.4.
Metadata</a></span></dt><dt><span class="section"><a
href="#metadata_key_response_analysis_data">3.2.2.5.
Data</a></span></dt><dt><span class="section"><a
href="#metadata_key_response_analysis_key">3.2.2.6.
Key</a></span></dt><dt><span class="section"><a
href="#metadata_key_response_analysis_datum">3.2.2.7.
Datum</a></span></dt></dl></dd><dt><span class="section"><a
href="#metadata_key_response_example">3.2.3. MetadataKeyResponse Message
Example</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a
href="#setup_data">4. SetupData</a></span></dt><dt><span class="section"><a
href="#measurement_archive_store">5.
MeasurementArchiveStore</a></span></dt><dt><span class="section"><a
href="#result_codes">6. Result Codes</a></span></dt><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-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.0</td><td align="left">4/4/2008</td><td align="left">Initial
Preparation</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>
- Extensions to the <a href="#id2529527">perfSONAR Base Protocol</a>
have the
+            <code class="email"><<a class="email"
href="mailto:"></a>></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="#metadata_key">3. MetadataKey</a></span></dt><dd><dl><dt><span
class="section"><a href="#metadata_key_request">3.1. MetadataKeyRequest
Message</a></span></dt><dd><dl><dt><span class="section"><a
href="#metadata_key_request_schema">3.1.1. MetadataKeyRequest Message
Schema</a></span></dt><dt><span class="section"><a
href="#metadata_key_request_analysis">3.1.2. MetadataKeyRequest Message
Analysis</a></span></dt><dd><dl><dt><span class="section"><a
href="#metadata_key_request_analysis_message">3.1.2.1.
Message</a></span></dt><dt><span class="section"><a
href="#metadata_key_request_analysis_parameters">3.1.2.2.
Parameters</a></span></dt><dt><span class="section"><a
href="#metadata_key_request_analysis_parameter">3.1.2.3.
Parameter</a></span></dt><dt><span class="section"><a
href="#metadata_key_request_analysis_metadata">3.1.2.4.
Metadata</a></span></dt><dt><span class="section"><a
href="#metadata_key_request_analysis_data">3.1.2.5.
Data</a></span></dt></dl></dd><dt><span class="section"><a
href="#metadata_key_request_example">3.1.3. MetadataKeyRequest Message
Example</a></span></dt></dl></dd><dt><span class="section"><a
href="#metadata_key_response">3.2. MetadataKeyResponse
Message</a></span></dt><dd><dl><dt><span class="section"><a
href="#metadata_key_response_schema">3.2.1. MetadataKeyResponse Message
Schema</a></span></dt><dt><span class="section"><a
href="#metadata_key_response_analysis">3.2.2. MetadataKeyResponse Message
Analysis</a></span></dt><dd><dl><dt><span class="section"><a
href="#metadata_key_response_analysis_message">3.2.2.1.
Message</a></span></dt><dt><span class="section"><a
href="#metadata_key_response_analysis_parame
ters">3.2.2.2. Parameters</a></span></dt><dt><span class="se!
ction"><
a href="#metadata_key_response_analysis_parameter">3.2.2.3.
Parameter</a></span></dt><dt><span class="section"><a
href="#metadata_key_response_analysis_metadata">3.2.2.4.
Metadata</a></span></dt><dt><span class="section"><a
href="#metadata_key_response_analysis_data">3.2.2.5.
Data</a></span></dt><dt><span class="section"><a
href="#metadata_key_response_analysis_key">3.2.2.6.
Key</a></span></dt><dt><span class="section"><a
href="#metadata_key_response_analysis_datum">3.2.2.7.
Datum</a></span></dt></dl></dd><dt><span class="section"><a
href="#metadata_key_response_example">3.2.3. MetadataKeyResponse Message
Example</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a
href="#setup_data">4. SetupData</a></span></dt><dd><dl><dt><span
class="section"><a href="#setup_data_request">4.1. SetupDataRequest
Message</a></span></dt><dd><dl><dt><span class="section"><a
href="#setup_data_request_schema">4.1.1. SetupDataRequest Message
Schema</a></span></dt><dt><span class="section
"><a href="#setup_data_request_analysis">4.1.2. SetupDataRequest Message
Analysis</a></span></dt><dd><dl><dt><span class="section"><a
href="#setup_data_request_analysis_message">4.1.2.1.
Message</a></span></dt><dt><span class="section"><a
href="#setup_data_request_analysis_parameters">4.1.2.2.
Parameters</a></span></dt><dt><span class="section"><a
href="#setup_data_request_analysis_parameter">4.1.2.3.
Parameter</a></span></dt><dt><span class="section"><a
href="#setup_data_request_analysis_metadata">4.1.2.4.
Metadata</a></span></dt><dt><span class="section"><a
href="#setup_data_request_analysis_data">4.1.2.5.
Data</a></span></dt></dl></dd><dt><span class="section"><a
href="#setup_data_request_example">4.1.3. SetupDataRequest Message
Example</a></span></dt></dl></dd><dt><span class="section"><a
href="#setup_data_response">4.2. SetupDataResponse
Message</a></span></dt><dd><dl><dt><span class="section"><a
href="#setup_data_response_schema">4.2.1. SetupDataResponse Message Schema
</a></span></dt><dt><span class="section"><a href="#setup_da!
ta_respo
nse_analysis">4.2.2. SetupDataResponse Message
Analysis</a></span></dt><dd><dl><dt><span class="section"><a
href="#setup_data_response_analysis_message">4.2.2.1.
Message</a></span></dt><dt><span class="section"><a
href="#setup_data_response_analysis_parameters">4.2.2.2.
Parameters</a></span></dt><dt><span class="section"><a
href="#setup_data_response_analysis_parameter">4.2.2.3.
Parameter</a></span></dt><dt><span class="section"><a
href="#setup_data_response_analysis_metadata">4.2.2.4.
Metadata</a></span></dt><dt><span class="section"><a
href="#setup_data_response_analysis_data">4.2.2.5.
Data</a></span></dt><dt><span class="section"><a
href="#setup_data_response_analysis_datum">4.2.2.6.
Datum</a></span></dt></dl></dd><dt><span class="section"><a
href="#setup_data_response_example">4.2.3. SetupDataResponse Message
Example</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a
href="#data_info">5. DataInfo</a></span></dt><dt><span class="section"><a
href="#measurement_
archive_store">6. MeasurementArchiveStore</a></span></dt><dt><span
class="section"><a href="#result_codes">7. Result
Codes</a></span></dt><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">4/4/2008</td><td align="left">Initial
Prep
aration</td><td align="left">J. Zurawski</td></tr><tr><td al!
ign="lef
t">1.01</td><td align="left">4/22/2009</td><td align="left">OGF 26
Preparation</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>
+ Extensions to the [<a class="citation" href="#id2531472"><span
class="citation">perfSONAR Base Protocol</span></a>] have the
advantage of further specifying interactions on a message by message
basis for use in multiple service types. This eliminates the need to
exhaustively document key exchanges for each service, and allows the
@@ -14,13 +13,15 @@
The <span class="emphasis"><em>Measurement Archive</em></span>
protocol features three
messages used to query services identifying themselves as locations
of measurement data:
- </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">MetadataKey</strong></span> - Message set that supplies
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>MetadataKey</strong></span> - Message set that
supplies
metadata information in return for a re-playable key, see
- <a href="#metadata_key">MetadataKey</a></p></li><li
style="list-style-type: circle"><p><span><strong
class="command">SetupData</strong></span> - Message set that supplies
- metadata information in return for a re-playable key, see
- <a href="#setup_data">SetupData</a></p></li><li
style="list-style-type: circle"><p><span><strong
class="command">MeasurementArchiveStore</strong></span> - Message set that
supplies
- metadata information in return for a re-playable key, see
- <a
href="#measurement_archive_store">MeasurementArchiveStore</a></p></li></ul></div><p>
+ <a class="xref" href="#metadata_key"
title="3. MetadataKey">MetadataKey</a></p></li><li style="list-style-type:
circle"><p><span class="command"><strong>SetupData</strong></span> - Message
set that supplies
+ metadata information or a key in return for a measurement data, see
+ <a class="xref" href="#setup_data"
title="4. SetupData">SetupData</a></p></li><li style="list-style-type:
circle"><p><span class="command"><strong>DataInfo</strong></span> - Message
set that supplies
+ metadata information in return for a well defined key, see
+ <a class="xref" href="#data_info"
title="5. DataInfo">DataInfo</a></p></li><li style="list-style-type:
circle"><p><span
class="command"><strong>MeasurementArchiveStore</strong></span> - Message set
that
+ attempts to store information into the database, see
+ <a class="xref" href="#measurement_archive_store"
title="6. MeasurementArchiveStore">MeasurementArchiveStore</a></p></li></ul></div><p>
The rest of this document will proceed as follows: We will introduce
each
message along with a schema description, analysis, and example usage
scenario. After this, we will briefly discuss some of the common
@@ -31,15 +32,15 @@
exchange the often complex <span
class="emphasis"><em>metadata</em></span> description
of a measurement set for more easily consumed and exchange
<span class="emphasis"><em>key</em></span>. The <span
class="emphasis"><em>key structure</em></span>
- was first introduced in <a href="#id2529508">Measurement Schema</a>,
and can
+ was first introduced in [<a class="citation" href="#id2531454"><span
class="citation">Measurement Schema</span></a>], and can
be customized for any particular service implementation; the overall
goal
being a <span class="emphasis"><em>shortcut</em></span> to an
underlying data set, similar
to keys used in relational databases.
</p><p>
- Based on initial work in <a href="#id2529527">perfSONAR Base
Protocol</a>,
+ Based on initial work in [<a class="citation" href="#id2531472"><span
class="citation">perfSONAR Base Protocol</span></a>],
this exchange will be described in terms of both the
- <a href="#metadata_key_request">MetadataKeyRequest Message</a> and
- <a href="#metadata_key_response">MetadataKeyResponse Message</a>.
Each explanation will include
+ <a class="xref" href="#metadata_key_request"
title="3.1. MetadataKeyRequest Message">MetadataKeyRequest Message</a> and
+ <a class="xref" href="#metadata_key_response"
title="3.2. MetadataKeyResponse Message">MetadataKeyResponse Message</a>.
Each explanation will include
a schematic definition and analysis, followed by example instances.
Note
that no one service will implement this protocol exactly as written;
services are expected to offer an explanation of how they implement the
@@ -50,10 +51,10 @@
<span class="emphasis"><em>Measurement Archive</em></span>.
Enclosed in this 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="#metadata_key_request_schema">MetadataKeyRequest Message Schema</a>
+ a very simple schema in <a class="xref"
href="#metadata_key_request_schema" title="3.1.1. MetadataKeyRequest Message
Schema">MetadataKeyRequest Message Schema</a>
along with an analysis of the elements in
- <a href="#metadata_key_request_analysis">Request Message
Analysis</a>. We conclude with
- examples in <a
href="#metadata_key_request_example">MetadataKeyRequest Message Example</a>.
+ <a class="xref" href="#metadata_key_request_analysis"
title="3.1.2. MetadataKeyRequest Message Analysis">Request Message
Analysis</a>. We conclude with
+ examples in <a class="xref" href="#metadata_key_request_example"
title="3.1.3. MetadataKeyRequest Message Example">MetadataKeyRequest Message
Example</a>.
</p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="metadata_key_request_schema"></a>3.1.1. MetadataKeyRequest Message
Schema</h4></div></div></div><p>
The following schema is a native description of the request schema
as
in the [<span class="citation">RELAX-NG</span>] language. Through
the use of
@@ -134,7 +135,7 @@

</pre></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="metadata_key_request_analysis"></a>3.1.2. MetadataKeyRequest Message
Analysis</h4></div></div></div><p>
There are view deviations from the
- <a href="#id2529527">perfSONAR Base Protocol</a> for this
particular
+ [<a class="citation" href="#id2531472"><span
class="citation">perfSONAR Base Protocol</span></a>] for this particular
message type. The following analysis will describe each element,
noting when there are changes.
</p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="metadata_key_request_analysis_message"></a>3.1.2.1. Message</h5></div></div></div><pre
class="programlisting">
@@ -151,7 +152,7 @@

</nmwg:message>

- </pre><div class="table"><a
id="table.messages_request_analysis_message"></a><p
class="title"><b>Table 2. 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_mdk_request_analysis_message"></a><p
class="title"><b>Table 2. MDK Request Message Element
Requirements</b></p><div class="table-contents"><table summary="MDK Request
Message Element Requirements" border="1"><colgroup><col align="left"
/></colgroup><tbody><tr><td align="left"><span
class="command"><strong>localname</strong></span></td><td
align="left">message</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, type</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">parameters, metadata, data</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
There is no difference in the structure of this element. The
only
notable difference is the value of <span
class="emphasis"><em>type</em></span> is
restricted to be <span
class="emphasis"><em>MetadataKeyRequest</em></span>.
@@ -163,7 +164,7 @@

</nmwg:parameters>

- </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>
+ </pre><div class="table"><a
id="table.messages_mdk_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 class="command"><strong>localname</strong></span></td><td
align="left">parameters</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">no</td></tr></tbody></table></div></div><br class="table-break"
/><p>
There is no difference in the structure of this element.
</p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="metadata_key_request_analysis_parameter"></a>3.1.2.3. Parameter</h5></div></div></div><pre
class="programlisting">

@@ -175,21 +176,21 @@
<nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
name="NAME" value="VALUE" />

- </pre><div class="table"><a
id="table.messages_request_analysis_parameter"></a><p
class="title"><b>Table 4. 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_mdk_request_analysis_parameter"></a><p
class="title"><b>Table 4. 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 class="command"><strong>localname</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">name, value</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
There is no difference in the structure of this element.
</p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="metadata_key_request_analysis_metadata"></a>3.1.2.4. Metadata</h5></div></div></div><pre
class="programlisting">

<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="metadata2" metadataIdRef="metadata1" />

- </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_mdk_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 class="command"><strong>localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">undefined</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
There is no difference in the structure of this element.
</p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="metadata_key_request_analysis_data"></a>3.1.2.5. Data</h5></div></div></div><pre
class="programlisting">

<nmwg:data xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="data2" metadataIdRef="metadata2" />

- </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">N/A</td></tr><tr><td align="left"><span><strong
class="command">required</strong></span></td><td
align="left">varies</td></tr></tbody></table></div></div><br
class="table-break" /><p>
+ </pre><div class="table"><a
id="table.messages_mdk_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 class="command"><strong>localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">N/A</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">varies</td></tr></tbody></table></div></div><br
class="table-break" /><p>
There is no difference in the structure of this element. The
only
notable difference is that this element
<span class="emphasis"><em>should not</em></span> contain any
nested elements. This
@@ -321,14 +322,14 @@

</pre></div></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
id="metadata_key_response"></a>3.2. MetadataKeyResponse
Message</h3></div></div></div><p>
The MetadataKeyResponse message is a container filled with the
results
- of a <a href="#metadata_key_request">MetadataKeyRequest Message</a>
from
+ of a <a class="xref" href="#metadata_key_request"
title="3.1. MetadataKeyRequest Message">MetadataKeyRequest Message</a> from
<span class="emphasis"><em>perfSONAR Measurement Archive</em></span>
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="#metadata_key_response_schema">MetadataKeyResponse Message
Schema</a> along with an analysis of
- the elements in <a href="#metadata_key_response_analysis">Response
Message Analysis</a>. We
- conclude with examples in <a
href="#metadata_key_response_example">MetadataKeyResponse Message Example</a>.
+ <a class="xref" href="#metadata_key_response_schema"
title="3.2.1. MetadataKeyResponse Message Schema">MetadataKeyResponse Message
Schema</a> along with an analysis of
+ the elements in <a class="xref"
href="#metadata_key_response_analysis" title="3.2.2. MetadataKeyResponse
Message Analysis">Response Message Analysis</a>. We
+ conclude with examples in <a class="xref"
href="#metadata_key_response_example" title="3.2.3. MetadataKeyResponse
Message Example">MetadataKeyResponse Message Example</a>.
</p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="metadata_key_response_schema"></a>3.2.1. MetadataKeyResponse Message
Schema</h4></div></div></div><p>
The following schema is a native description of the response
schema as
in the [<span class="citation">RELAX-NG</span>] language. Through
the use of
@@ -438,7 +439,8 @@

</nmwg:message>

- </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_mdk_response_analysis_message"></a><p
class="title"><b>Table 7. MDK Response Message Element
Requirements</b></p><div class="table-contents">s
+ <table summary="MDK Response Message Element Requirements"
border="1"><colgroup><col align="left" /></colgroup><tbody><tr><td
align="left"><span class="command"><strong>localname</strong></span></td><td
align="left">message</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, type</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">parameters, metadata, data</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
There is no difference in the structure of this element. The
only
notable difference is the value of <span
class="emphasis"><em>type</em></span> is
restricted to be <span
class="emphasis"><em>MetadataKeyResponse</em></span>.
@@ -450,7 +452,7 @@

</nmwg:parameters>

- </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>
+ </pre><div class="table"><a
id="table.messages_mdk_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 class="command"><strong>localname</strong></span></td><td
align="left">parameters</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">no</td></tr></tbody></table></div></div><br class="table-break"
/><p>
There is no difference in the structure of this element.
</p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="metadata_key_response_analysis_parameter"></a>3.2.2.3. Parameter</h5></div></div></div><pre
class="programlisting">

@@ -462,28 +464,28 @@
<nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
name="NAME" value="VALUE" />

- </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_mdk_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 class="command"><strong>localname</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">name, value</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
There is no difference in the structure of this element.
</p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="metadata_key_response_analysis_metadata"></a>3.2.2.4. Metadata</h5></div></div></div><pre
class="programlisting">

<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="metadata2" metadataIdRef="metadata1" />

- </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_mdk_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 class="command"><strong>localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">undefined</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
There is no difference in the structure of this element.
</p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="metadata_key_response_analysis_data"></a>3.2.2.5. Data</h5></div></div></div><pre
class="programlisting">

<nmwg:data xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="data2" metadataIdRef="metadata2" />

- </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">key,
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.messages_mdk_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 class="command"><strong>localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">key, datum</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
This element features only one deviation from that of the
- <a href="#id2529527">perfSONAR Base Protocol</a>: the key element
+ [<a class="citation" href="#id2531472"><span
class="citation">perfSONAR Base Protocol</span></a>]: the key element
or a datum element must exist inside. The key element
will be explained in
- <a href="#metadata_key_response_analysis_key">Key</a> and the
datum
+ <a class="xref" href="#metadata_key_response_analysis_key"
title="3.2.2.6. Key">Key</a> and the datum
element will be explained in
- <a href="#metadata_key_response_analysis_datum">Datum</a>.
+ <a class="xref" href="#metadata_key_response_analysis_datum"
title="3.2.2.7. Datum">Datum</a>.
</p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="metadata_key_response_analysis_key"></a>3.2.2.6. Key</h5></div></div></div><pre
class="programlisting">

<nmwg:key xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; id="key1">
@@ -492,22 +494,22 @@

</nmwg:key>

- </pre><div class="table"><a
id="table.messages_response_analysis_key"></a><p
class="title"><b>Table 12. 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">varies</td></tr></tbody></table></div></div><br
class="table-break" /><p>
+ </pre><div class="table"><a
id="table.messages_response_analysis_key"></a><p
class="title"><b>Table 12. 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 class="command"><strong>localname</strong></span></td><td
align="left">key</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">parameters</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">varies</td></tr></tbody></table></div></div><br
class="table-break" /><p>
The key element is used to specify particular nuances of a
dataset
linked to a metadata description. The key element was first
- described in <a href="#id2529508">Measurement Schema</a>. This
element
+ described in [<a class="citation" href="#id2531454"><span
class="citation">Measurement Schema</span></a>]. This element
can contain the following attributes:
- </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
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>id</strong></span> - Identifying attribute that can be
used to track state.</p></li></ul></div><p>
There is only one element allowed within the key:
- </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="#metadata_key_response_analysis_parameters">Parameters</a></p></li></ul></div></div><div
class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5
class="title"><a
id="metadata_key_response_analysis_datum"></a>3.2.2.7. Datum</h5></div></div></div><pre
class="programlisting">
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>Parameters</strong></span> - Described in
+ <a class="xref"
href="#metadata_key_response_analysis_parameters"
title="3.2.2.2. Parameters">Parameters</a></p></li></ul></div></div><div
class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h5
class="title"><a
id="metadata_key_response_analysis_datum"></a>3.2.2.7. Datum</h5></div></div></div><pre
class="programlisting">

<nmwg:datum xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; >

- </pre><div class="table"><a
id="table.messages_response_analysis_datum"></a><p
class="title"><b>Table 13. 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/base/2.0/</td></tr><tr><td
align="left"><span><strong class="command">attributes</strong></span></td><td
align="left">undefined</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">varies</td></tr></tbody></table></div></div><br
class="table-break" /><p>
+ </pre><div class="table"><a
id="table.messages_mdk_response_analysis_datum"></a><p
class="title"><b>Table 13. 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 class="command"><strong>localname</strong></span></td><td
align="left">datum</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">undefined</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">undefined</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">varies</td></tr></tbody></table></div></div><br
class="table-break" /><p>
The datum element may appear instead of the
- <a href="#metadata_key_response_analysis_key">Key</a> when
anomalous
+ <a class="xref" href="#metadata_key_response_analysis_key"
title="3.2.2.6. Key">Key</a> when anomalous
behaviour in the service prevents the return of a key. Legacy or
alternate services may also choose to issue the key inside
of a datum element (see individual service documentation for
@@ -614,13 +616,568 @@


</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="setup_data"></a>4. SetupData</h2></div></div></div><p>
+ The <span class="emphasis"><em>SetupData</em></span> message exchange
offers a way to
+ retrieve measurement data for a given <span
class="emphasis"><em>metadata</em></span>
+ description or <span class="emphasis"><em>key</em></span> (collected
via the
+ <a class="xref" href="#setup_data" title="4. SetupData">SetupData</a>
message exchange). This message
+ represents the true crux of measurement archive services and allows the
+ retrieval of actual measurement data.
+ </p><p>
+ Based on initial work in [<a class="citation" href="#id2531472"><span
class="citation">perfSONAR Base Protocol</span></a>],
+ this exchange will be described in terms of both the
+ <a class="xref" href="#setup_data_request"
title="4.1. SetupDataRequest Message">SetupDataRequest Message</a> and
+ <a class="xref" href="#setup_data_response"
title="4.2. SetupDataResponse Message">SetupDataResponse Message</a>. Each
explanation will include
+ a schematic definition and analysis followed by example instances.
Note
+ that no one service will implement this protocol
+ <span class="emphasis"><em>exactly</em></span> as presented; services
are expected to offer
+ an explanation of how they implement the protocol as well as any
+ divergence in the service documentation.
+ </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
id="setup_data_request"></a>4.1. SetupDataRequest
Message</h3></div></div></div><p>
+ The SetupDataRequest message is a container for submitting metadata
+ of a given type to a perfSONAR based
+ <span class="emphasis"><em>Measurement Archive</em></span>.
Enclosed in this 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 class="xref"
href="#setup_data_request_schema" title="4.1.1. SetupDataRequest Message
Schema">SetupDataRequest Message Schema</a>
+ along with an analysis of the elements in
+ <a class="xref" href="#setup_data_request_analysis"
title="4.1.2. SetupDataRequest Message Analysis">Request Message
Analysis</a>. We conclude with
+ examples in <a class="xref" href="#setup_data_request_example"
title="4.1.3. SetupDataRequest Message Example">SetupDataRequest Message
Example</a>.
+ </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="setup_data_request_schema"></a>4.1.1. SetupDataRequest Message
Schema</h4></div></div></div><p>
+ The following schema is a native description of the request schema
as
+ in the [<span class="citation">RELAX-NG</span>] language. Through
the use of
+ tools such as [<span class="citation">Trang</span>] and [<span
class="citation">MSV</span>]
+ it is possible to convert this to other widely accepted formats
such
+ as [<span class="citation">XSD</span>].
+ </p><pre class="programlisting">
+
+<font color=red># Begin Schema</font>
+
+<font color=orange>namespace nmwg = "http://ggf.org/ns/nmwg/base/2.0/";</font>
+
+<font color=orange>start =</font>
+ <font color=green>element</font> <font color=blue>nmwg:message</font> {
+ Identifier? &
+ attribute type { "SetupDataRequest" } &
+ Parameters? &
+ (
+ Metadata |
+ Data
+ )+
+ }
+
+<font color=orange>Parameters = </font>
+ <font color=green>element</font> <font color=blue>nmwg:parameters</font> {
+ Identifier &
+ Parameter+
+ }
+
+<font color=orange>Parameter = </font>
+ <font color=green>element</font> <font color=blue>nmwg:parameter</font> {
+ attribute name { xsd:string } &
+ (
+ attribute value { xsd:string } |
+ (
+ anyElement |
+ text
+ )
+ )
+ }
+
+<font color=orange>Metadata =</font>
+ <font color=green>element</font> <font color=blue>nmwg:metadata</font> {
+ Identifier &
+ MetadataIdentifierRef? &
+ anyElement*
+ }
+
+<font color=orange>Data =</font>
+ <font color=green>element</font> <font color=blue>nmwg:data</font> {
+ Identifier &
+ MetadataIdentifierRef &
+ }
+
+<font color=orange>Identifier =</font>
+ attribute id { xsd:string }
+
+<font color=orange>MetadataIdentifierRef =</font>
+ attribute metadataIdRef { xsd:string }
+
+<font color=orange>anyElement = </font>
+ <font color=green>element</font> <font color=blue>*</font> {
+ anyThing
+ }
+
+<font color=orange>anyAttribute = </font>
+ attribute * { text }
+
+<font color=orange>anyThing = </font>
+ (
+ anyElement |
+ anyAttribute |
+ text
+ )*
+
+
+<font color=red># End Schema</font>
+
+ </pre></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="setup_data_request_analysis"></a>4.1.2. SetupDataRequest Message
Analysis</h4></div></div></div><p>
+ There are view deviations from the
+ [<a class="citation" href="#id2531472"><span
class="citation">perfSONAR Base Protocol</span></a>] for this particular
+ message type. The following analysis will describe each element,
+ noting when there are changes.
+ </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="setup_data_request_analysis_message"></a>4.1.2.1. Message</h5></div></div></div><pre
class="programlisting">
+
+<nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ id="message1"
+ type="Request">
+
+ <nmwg:parameters />
+
+ <nmwg:metadata />
+
+ <nmwg:data />
+
+</nmwg:message>
+
+ </pre><div class="table"><a
id="table.messages_sd_request_analysis_message"></a><p
class="title"><b>Table 14. SD Request Message Element
Requirements</b></p><div class="table-contents"><table summary="SD Request
Message Element Requirements" border="1"><colgroup><col align="left"
/></colgroup><tbody><tr><td align="left"><span
class="command"><strong>localname</strong></span></td><td
align="left">message</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, type</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">parameters, metadata, data</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/
><p>
+ There is no difference in the structure of this element. The
only
+ notable difference is the value of <span
class="emphasis"><em>type</em></span> is
+ restricted to be <span
class="emphasis"><em>SetupDataRequest</em></span>.
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="setup_data_request_analysis_parameters"></a>4.1.2.2. Parameters</h5></div></div></div><pre
class="programlisting">
+
+<nmwg:parameters xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="parameters1">
+
+ <nmwg:parameter />
+
+</nmwg:parameters>
+
+ </pre><div class="table"><a
id="table.messages_sd_request_analysis_parameters"></a><p
class="title"><b>Table 15. 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 class="command"><strong>localname</strong></span></td><td
align="left">parameters</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">no</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ There is no difference in the structure of this element.
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="setup_data_request_analysis_parameter"></a>4.1.2.3. Parameter</h5></div></div></div><pre
class="programlisting">
+
+<nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ name="NAME">VALUE</nmwg:parameter>
+
+
+
+<nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ name="NAME" value="VALUE" />
+
+ </pre><div class="table"><a
id="table.messages_sd_request_analysis_parameter"></a><p
class="title"><b>Table 16. 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 class="command"><strong>localname</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">name, value</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ There is no difference in the structure of this element.
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="setup_data_request_analysis_metadata"></a>4.1.2.4. Metadata</h5></div></div></div><pre
class="programlisting">
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ id="metadata2" metadataIdRef="metadata1" />
+
+ </pre><div class="table"><a
id="table.messages_sd_request_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 class="command"><strong>localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">undefined</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ There is no difference in the structure of this element. Note
that
+ the contents will vary from service to service.
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="setup_data_request_analysis_data"></a>4.1.2.5. Data</h5></div></div></div><pre
class="programlisting">
+
+<nmwg:data xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ id="data2" metadataIdRef="metadata2" />
+
+ </pre><div class="table"><a
id="table.messages_sd_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 class="command"><strong>localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">N/A</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">varies</td></tr></tbody></table></div></div><br
class="table-break" /><p>
+ There is no difference in the structure of this element. The
only
+ notable difference is that this element
+ <span class="emphasis"><em>should not</em></span> contain any
nested elements. This
+ element should only be used as a <span class="emphasis"><em>data
trigger</em></span>
+ for services to act on particular metadata elements.
+ </p></div></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="setup_data_request_example"></a>4.1.3. SetupDataRequest Message
Example</h4></div></div></div><p>
+ The following examples demonstrate some of the possible uses and
+ layouts of request messages in the MA Protocol. These examples are
+ not an attempt to be exhaustive, but rather some examples of ways
to
+ perform common tasks. Note that these messages are
+ <span class="emphasis"><em>NOT</em></span> indicative of a
particular service.
+ </p><p>
+ The first example demonstrates the most common use case: a single
+ metadata and data pair.
+ </p><pre class="programlisting">
+
+
+
+<nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ type="SetupDataRequest" id="message1">
+
+ <nmwg:metadata id="m1">
+ 
+ </nmwg:metadata>
+
+ <nmwg:data id="d1" metadatIdRef="m1" />
+
+</nmwg:message>
+
+
+
+ </pre><p>
+ The second example is similar, but incorporates a parameters block
+ that may be populated with optional behaviors for a service.
+ </p><pre class="programlisting">
+
+
+
+<nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ type="SetupDataRequest" id="message1">
+
+ <nmwg:parameters id="paraemters1">
+ <nmwg:parameter name="something">something
else</nmwg:parameter>
+ </nmwg:parameters>
+
+ <nmwg:metadata id="m1">
+ 
+ </nmwg:metadata>
+
+ <nmwg:data id="d1" metadatIdRef="m1" />
+
+</nmwg:message>
+
+
+
+ </pre><p>
+ The third example is also similar to the first, but shows it is
+ possible to ask for multiple pairs of metadata and data in a single
+ message. Note that there are two empty data triggers to signify
that
+ each message be acted upon.
+ </p><pre class="programlisting">
+
+
+
+<nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ type="SetupDataRequest" id="message1">
+
+ <nmwg:metadata id="m1">
+ 
+ </nmwg:metadata>
+
+ <nmwg:data id="d1" metadatIdRef="m1" />
+
+ <nmwg:metadata id="m2">
+ 
+ </nmwg:metadata>
+
+ <nmwg:data id="d2" metadatIdRef="m2" />
+
+</nmwg:message>
+
+
+
+ </pre><p>
+ This example features merge chaining. Note there is only one data
+ trigger, and it is at the <span
class="emphasis"><em>tail</em></span> of the chain. A
+ service would perform the necessary chaining first, then act on the
+ result of this operation.
+ </p><pre class="programlisting">
+
+
+
+<nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ type="SetupDataRequest" id="message1">
+
+ <nmwg:metadata id="m1">
+ 
+ </nmwg:metadata>
+
+ <nmwg:metadata id="m2" metadataIdRef="m1">
+ 
+ </nmwg:metadata>
+
+ <nmwg:data id="d1" metadatIdRef="m2" />
+
+</nmwg:message>
+
+
+
+ </pre><p>
+ The final example is an invalid case where the metadata does not
+ have an appropriate data trigger.
+ </p><pre class="programlisting">
+
+
+
+<nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ type="SetupDataRequest" id="message1">
+
+ <nmwg:metadata id="m1">
+ 
+ </nmwg:metadata>
+
+ <nmwg:data id="d1" metadatIdRef="m2" />
+
+</nmwg:message>
+
+
+
+ </pre></div></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
id="setup_data_response"></a>4.2. SetupDataResponse
Message</h3></div></div></div><p>
+ The SetupDataResponse message is a container filled with the results
+ of a <a class="xref" href="#setup_data_request"
title="4.1. SetupDataRequest Message">SetupDataRequest Message</a> from
+ <span class="emphasis"><em>perfSONAR Measurement Archive</em></span>
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 class="xref" href="#setup_data_response_schema"
title="4.2.1. SetupDataResponse Message Schema">SetupDataResponse Message
Schema</a> along with an analysis of
+ the elements in <a class="xref" href="#setup_data_response_analysis"
title="4.2.2. SetupDataResponse Message Analysis">Response Message
Analysis</a>. We
+ conclude with examples in <a class="xref"
href="#setup_data_response_example" title="4.2.3. SetupDataResponse Message
Example">SetupDataResponse Message Example</a>.
+ </p><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="setup_data_response_schema"></a>4.2.1. SetupDataResponse Message
Schema</h4></div></div></div><p>
+ The following schema is a native description of the response
schema as
+ in the [<span class="citation">RELAX-NG</span>] language. Through
the use of
+ tools such as [<span class="citation">Trang</span>] and [<span
class="citation">MSV</span>]
+ it is possible to convert this to other widely accepted formats
such
+ as [<span class="citation">XSD</span>].
+ </p><pre class="programlisting">
+
+<font color=red># Begin Schema</font>
+
+<font color=orange>namespace nmwg = "http://ggf.org/ns/nmwg/base/2.0/";</font>
+
+<font color=orange>start =</font>
+ <font color=green>element</font> <font color=blue>nmwg:message</font> {
+ Identifier? &
+ attribute messageIdRef { xsd:string }? &
+ attribute type { "SetupDataResponse" } &
+ Parameters? &
+ (
+ Metadata |
+ Data
+ )+
+ }
+
+<font color=orange>Parameters = </font>
+ <font color=green>element</font> <font color=blue>nmwg:parameters</font> {
+ Identifier &
+ Parameter+
+ }
+
+<font color=orange>Parameter = </font>
+ <font color=green>element</font> <font color=blue>nmwg:parameter</font> {
+ attribute name { xsd:string } &
+ (
+ attribute value { xsd:string } |
+ (
+ anyElement |
+ text
+ )
+ )
+ }
+
+<font color=orange>Metadata =</font>
+ <font color=green>element</font> <font color=blue>nmwg:metadata</font> {
+ Identifier &
+ MetadataIdentifierRef? &
+ anyElement*
+ }
+
+<font color=orange>Data =</font>
+ <font color=green>element</font> <font color=blue>nmwg:data</font> {
+ Identifier &
+ MetadataIdentifierRef &
+ (
+ Datum*
+ )
+ }
+
+<font color=orange>Identifier =</font>
+ attribute id { xsd:string }
+
+<font color=orange>MetadataIdentifierRef =</font>
+ attribute metadataIdRef { xsd:string }
+
+<font color=orange>anyElement = </font>
+ <font color=green>element</font> <font color=blue>*</font> {
+ anyThing
+ }
+
+<font color=orange>anyAttribute = </font>
+ attribute * { text }
+
+<font color=orange>anyThing = </font>
+ (
+ anyElement |
+ anyAttribute |
+ text
+ )*
+
+<font color=orange>Datum = </font>
+ <font color=green>element</font> <font color=blue>nmwg:datum</font> {
+ anyThing*
+ }
+
+<font color=red># End Schema</font>
+
+ </pre></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="setup_data_response_analysis"></a>4.2.2. SetupDataResponse Message
Analysis</h4></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><h5 class="title"><a
id="setup_data_response_analysis_message"></a>4.2.2.1. Message</h5></div></div></div><pre
class="programlisting">
+
+<nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ id="message1"
+ type="SetupDataResponse">
+
+ <nmwg:parameters />
+
+ <nmwg:metadata />
+
+ <nmwg:data />
+
+</nmwg:message>
+
+ </pre><div class="table"><a
id="table.messages_sd_response_analysis_message"></a><p
class="title"><b>Table 19. SD Response Message Element
Requirements</b></p><div class="table-contents"><table summary="SD Response
Message Element Requirements" border="1"><colgroup><col align="left"
/></colgroup><tbody><tr><td align="left"><span
class="command"><strong>localname</strong></span></td><td
align="left">message</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, type</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">parameters, metadata, data</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break
" /><p>
+ There is no difference in the structure of this element. The
only
+ notable difference is the value of <span
class="emphasis"><em>type</em></span> is
+ restricted to be <span
class="emphasis"><em>SetupDataResponse</em></span>.
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="setup_data_response_analysis_parameters"></a>4.2.2.2. Parameters</h5></div></div></div><pre
class="programlisting">
+
+<nmwg:parameters xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="parameters1">
+
+ <nmwg:parameter />
+
+</nmwg:parameters>
+
+ </pre><div class="table"><a
id="table.messages_sd_response_analysis_parameters"></a><p
class="title"><b>Table 20. 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 class="command"><strong>localname</strong></span></td><td
align="left">parameters</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">no</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ There is no difference in the structure of this element.
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="setup_data_response_analysis_parameter"></a>4.2.2.3. Parameter</h5></div></div></div><pre
class="programlisting">
+
+<nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ name="NAME">VALUE</nmwg:parameter>
+
+
+
+<nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ name="NAME" value="VALUE" />
+
+ </pre><div class="table"><a
id="table.messages_sd_response_analysis_parameter"></a><p
class="title"><b>Table 21. 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 class="command"><strong>localname</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">name, value</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ There is no difference in the structure of this element.
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="setup_data_response_analysis_metadata"></a>4.2.2.4. Metadata</h5></div></div></div><pre
class="programlisting">
+
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ id="metadata2" metadataIdRef="metadata1" />
+
+ </pre><div class="table"><a
id="table.messages_sd_response_analysis_metadata"></a><p
class="title"><b>Table 22. 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 class="command"><strong>localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">undefined</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ There is no difference in the structure of this element. As in
the
+ <a class="xref" href="#setup_data_request"
title="4.1. SetupDataRequest Message">SetupDataRequest Message</a> the
contents of this element
+ will vary by service.
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="setup_data_response_analysis_data"></a>4.2.2.5. Data</h5></div></div></div><pre
class="programlisting">
+
+<nmwg:data xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ id="data2" metadataIdRef="metadata2" />
+
+ </pre><div class="table"><a
id="table.messages_sd_response_analysis_data"></a><p
class="title"><b>Table 23. 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 class="command"><strong>localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">datum</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
+ This element features only one deviation from that of the
+ [<a class="citation" href="#id2531472"><span
class="citation">perfSONAR Base Protocol</span></a>]: datum elements are
+ expected to reside in the data element, it will be explained in
+ <a class="xref" href="#setup_data_response_analysis_datum"
title="4.2.2.6. Datum">Datum</a>.
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
id="setup_data_response_analysis_datum"></a>4.2.2.6. Datum</h5></div></div></div><pre
class="programlisting">
+
+<nmwg:datum xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; >
+
+ </pre><div class="table"><a
id="table.messages_sd_response_analysis_datum"></a><p
class="title"><b>Table 24. 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 class="command"><strong>localname</strong></span></td><td
align="left">datum</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">undefined</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">undefined</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">varies</td></tr></tbody></table></div></div><br
class="table-break" /><p>
+ The datum element is the only element that should appear here.
This
+ document will not specific attributes or elements for the datum
+ element.
+ </p></div></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
id="setup_data_response_example"></a>4.2.3. SetupDataResponse Message
Example</h4></div></div></div><p>
+ The following examples demonstrate some of the possible uses and
+ layouts of response messages in the MA Protocol.
+ </p><p>
+ The first example is the most common form of SetupDataResponse
+ message containing a single metadata and data pair. This would be
+ indicitive of success due to the presence of the key.
+ </p><pre class="programlisting">
+
+
+
+<nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ type="SetupDataResponse" id="message1">
+
+ <nmwg:metadata id="m1">
+ 
+ </nmwg:metadata>
+
+ <nmwg:data id="d1" metadatIdRef="m1">
+
+ <nmwg:datum />
+ <nmwg:datum />
+ 
+ <nmwg:datum />
+
+ </nmwg:data>
+
+</nmwg:message>
+
+
+
+ </pre><p>
+ The second example is similar, although it features two pairs.
+ </p><pre class="programlisting">
+
+
+
+<nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ type="SetupDataResponse" id="message1">
+
+ <nmwg:metadata id="m1">
+ 
+ </nmwg:metadata>
+
+ <nmwg:data id="d1" metadatIdRef="m1">
+
+ <nmwg:datum />
+ <nmwg:datum />
+ 
+ <nmwg:datum />
+
+ </nmwg:data>
+
+ <nmwg:metadata id="m2">
+ 
+ </nmwg:metadata>
+
+ <nmwg:data id="d2" metadatIdRef="m2">
+
+ <nmwg:datum />
+ <nmwg:datum />
+ 
+ <nmwg:datum />
+
+ </nmwg:data>
+
+</nmwg:message>
+
+
+
+ </pre><p>
+ The final example demonstrates an error condition. Note that this
+ may contain multiple pairs if sent, and it may be possible to have
+ sucess for some, and errors for others.
+ </p><pre class="programlisting">
+
+
+
+<nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ type="SetupDataResponse" id="message1">
+
+ <nmwg:metadata id="m1">
+ 
+ </nmwg:metadata>
+
+ <nmwg:data id="d1" metadatIdRef="m1">
+
+ <nmwg:datum>
+ 
+ </nmwg:datum>
+
+ </nmwg:data>
+
+</nmwg:message>
+
+
+
+ </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="data_info"></a>5. DataInfo</h2></div></div></div><p>
TBD
- </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
id="measurement_archive_store"></a>5. MeasurementArchiveStore</h2></div></div></div><p>
+ </p></div><div class="section" lang="en" xml:lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
id="measurement_archive_store"></a>6. MeasurementArchiveStore</h2></div></div></div><p>
TBD
- </p></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>
+ </p></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>7. Result Codes</h2></div></div></div><p>
The following new result codes can be incorporated into the MA
Protocol based on the work in the
- <a href="#id2529527">perfSONAR Base Protocol</a>. We will introduce
+ [<a class="citation" href="#id2531472"><span
class="citation">perfSONAR Base Protocol</span></a>]. We will introduce
these into both styles to allow for backwards compatibility. The
original style is presented first:
</p><pre class="programlisting">
@@ -640,9 +1197,9 @@
error/
ma/

- </pre></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 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"><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
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
class="glossdiv"><dl></dl></div><d
iv 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="id2529508"></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="id2529527"></a><p>[<abbr class="abbrev">perfSONAR Base Protocol</abbr>]
<span class="title"><i>
- <a
href="http://anonsvn.internet2.edu/svn/perfSONAR-PS/branches/merge/doc/strawman/protocol/base/base_protocol.html";
target="_top">perfSONAR Base Protocol</a>
+ </pre></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>
+ </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"><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
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
class="glossdiv"><dl></dl></div><d
iv 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="id2531454"></a><p>[<abbr
class="abbrev">Measurement Schema</abbr>] <span class="title"><i>
+ <a class="ulink"
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="id2531472"></a><p>[<abbr class="abbrev">perfSONAR Base Protocol</abbr>]
<span class="title"><i>
+ <a class="ulink"
href="http://anonsvn.internet2.edu/svn/perfSONAR-PS/branches/merge/doc/strawman/protocol/base/base_protocol.html";
target="_top">perfSONAR Base Protocol</a>
</i>. </span></p></div></div></div></body></html>

Property changes on: trunk/perfsonar-doc/protocol/MA/ma.html
___________________________________________________________________
Name: svn:mime-type
+ text/html

Modified: trunk/perfsonar-doc/protocol/MA/ma.xml
===================================================================
--- trunk/perfsonar-doc/protocol/MA/ma.xml 2009-04-23 11:23:39 UTC (rev
5106)
+++ trunk/perfsonar-doc/protocol/MA/ma.xml 2009-04-24 02:30:10 UTC (rev
5107)
@@ -51,11 +51,17 @@
</thead>
<tbody>
<row>
- <entry>1.0</entry>
+ <entry>1.00</entry>
<entry>4/4/2008</entry>
<entry>Initial Preparation</entry>
<entry>J. Zurawski</entry>
</row>
+ <row>
+ <entry>1.01</entry>
+ <entry>4/22/2009</entry>
+ <entry>OGF 26 Preparation</entry>
+ <entry>J. Zurawski</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -87,12 +93,17 @@
</listitem>
<listitem>
<para><command>SetupData</command> - Message set that supplies
- metadata information in return for a re-playable key, see
+ metadata information or a key in return for a measurement data, see
<xref linkend="setup_data" /></para>
</listitem>
<listitem>
- <para><command>MeasurementArchiveStore</command> - Message set that
supplies
- metadata information in return for a re-playable key, see
+ <para><command>DataInfo</command> - Message set that supplies
+ metadata information in return for a well defined key, see
+ <xref linkend="data_info" /></para>
+ </listitem>
+ <listitem>
+ <para><command>MeasurementArchiveStore</command> - Message set that
+ attempts to store information into the database, see
<xref linkend="measurement_archive_store" /></para>
</listitem>
</itemizedlist>
@@ -195,8 +206,8 @@
]]>
</programlisting>

- <table frame="all" align="center" halign="center" width="80%"
id="table.messages_request_analysis_message">
- <title>Message Element Requirements</title>
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_mdk_request_analysis_message">
+ <title>MDK Request Message 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%"/>
@@ -246,7 +257,7 @@
]]>
</programlisting>

- <table frame="all" align="center" halign="center" width="80%"
id="table.messages_request_analysis_parameters">
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_mdk_request_analysis_parameters">
<title>Parameters Element Requirements</title>
<tgroup cols="1" align="left" colsep="1" rowsep="1">
<colspec colnum="1" colname="c1" width="30%"/>
@@ -297,7 +308,7 @@
]]>
</programlisting>

- <table frame="all" align="center" halign="center" width="80%"
id="table.messages_request_analysis_parameter">
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_mdk_request_analysis_parameter">
<title>Parameter Element Requirements</title>
<tgroup cols="1" align="left" colsep="1" rowsep="1">
<colspec colnum="1" colname="c1" width="30%"/>
@@ -343,7 +354,7 @@
]]>
</programlisting>

- <table frame="all" align="center" halign="center" width="80%"
id="table.messages_request_analysis_metadata">
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_mdk_request_analysis_metadata">
<title>Metadata Element Requirements</title>
<tgroup cols="1" align="left" colsep="1" rowsep="1">
<colspec colnum="1" colname="c1" width="30%"/>
@@ -389,7 +400,7 @@
]]>
</programlisting>

- <table frame="all" align="center" halign="center" width="80%"
id="table.messages_request_analysis_data">
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_mdk_request_analysis_data">
<title>Data Element Requirements</title>
<tgroup cols="1" align="left" colsep="1" rowsep="1">
<colspec colnum="1" colname="c1" width="30%"/>
@@ -566,8 +577,8 @@
]]>
</programlisting>

- <table frame="all" align="center" halign="center" width="80%"
id="table.messages_response_analysis_message">
- <title>Message Element Requirements</title>
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_mdk_response_analysis_message">
+ <title>MDK Response Message Element Requirements</title>s
<tgroup cols="1" align="left" colsep="1" rowsep="1">
<colspec colnum="1" colname="c1" width="30%"/>
<colspec colnum="2" colname="c2" width="70%"/>
@@ -617,7 +628,7 @@
]]>
</programlisting>

- <table frame="all" align="center" halign="center" width="80%"
id="table.messages_response_analysis_parameters">
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_mdk_response_analysis_parameters">
<title>Parameters Element Requirements</title>
<tgroup cols="1" align="left" colsep="1" rowsep="1">
<colspec colnum="1" colname="c1" width="30%"/>
@@ -668,7 +679,7 @@
]]>
</programlisting>

- <table frame="all" align="center" halign="center" width="80%"
id="table.messages_response_analysis_parameter">
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_mdk_response_analysis_parameter">
<title>Parameter Element Requirements</title>
<tgroup cols="1" align="left" colsep="1" rowsep="1">
<colspec colnum="1" colname="c1" width="30%"/>
@@ -714,7 +725,7 @@
]]>
</programlisting>

- <table frame="all" align="center" halign="center" width="80%"
id="table.messages_response_analysis_metadata">
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_mdk_response_analysis_metadata">
<title>Metadata Element Requirements</title>
<tgroup cols="1" align="left" colsep="1" rowsep="1">
<colspec colnum="1" colname="c1" width="30%"/>
@@ -760,7 +771,7 @@
]]>
</programlisting>

- <table frame="all" align="center" halign="center" width="80%"
id="table.messages_response_analysis_data">
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_mdk_response_analysis_data">
<title>Data Element Requirements</title>
<tgroup cols="1" align="left" colsep="1" rowsep="1">
<colspec colnum="1" colname="c1" width="30%"/>
@@ -881,7 +892,7 @@
]]>
</programlisting>

- <table frame="all" align="center" halign="center" width="80%"
id="table.messages_response_analysis_datum">
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_mdk_response_analysis_datum">
<title>Datum Element Requirements</title>
<tgroup cols="1" align="left" colsep="1" rowsep="1">
<colspec colnum="1" colname="c1" width="30%"/>
@@ -978,11 +989,820 @@
<title>SetupData</title>

<para>
+ The <emphasis>SetupData</emphasis> message exchange offers a way to
+ retrieve measurement data for a given <emphasis>metadata</emphasis>
+ description or <emphasis>key</emphasis> (collected via the
+ <xref linkend="setup_data" /> message exchange). This message
+ represents the true crux of measurement archive services and allows the
+ retrieval of actual measurement data.
+ </para>
+
+ <para>
+ Based on initial work in <citation>perfSONAR Base Protocol</citation>,
+ this exchange will be described in terms of both the
+ <xref linkend="setup_data_request" /> and
+ <xref linkend="setup_data_response" />. Each explanation will include
+ a schematic definition and analysis followed by example instances.
Note
+ that no one service will implement this protocol
+ <emphasis>exactly</emphasis> as presented; services are expected to
offer
+ an explanation of how they implement the protocol as well as any
+ divergence in the service documentation.
+ </para>
+
+ <section id="setup_data_request" xreflabel="SetupDataRequest Message">
+ <title>SetupDataRequest Message</title>
+
+ <para>
+ The SetupDataRequest message is a container for submitting metadata
+ of a given type to a perfSONAR based
+ <emphasis>Measurement Archive</emphasis>. Enclosed in this envelope
+ will be a series of metadata and data pairs containing various
+ instructions to act on. We first present
+ a very simple schema in <xref linkend="setup_data_request_schema" />
+ along with an analysis of the elements in
+ <xref linkend="setup_data_request_analysis" />. We conclude with
+ examples in <xref linkend="setup_data_request_example" />.
+ </para>
+
+ <section id="setup_data_request_schema" xreflabel="SetupDataRequest
Message Schema">
+ <title>SetupDataRequest Message Schema</title>
+
+ <para>
+ The following schema is a native description of the request schema
as
+ in the <citation>RELAX-NG</citation> language. Through the use of
+ tools such as <citation>Trang</citation> and
<citation>MSV</citation>
+ it is possible to convert this to other widely accepted formats
such
+ as <citation>XSD</citation>.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <inlineschema file="schema/setupdata_request.rnc"/>
+ ]]>
+ </programlisting>
+
+ </section>
+
+ <section id="setup_data_request_analysis" xreflabel="Request Message
Analysis">
+ <title>SetupDataRequest Message Analysis</title>
+
+ <para>
+ There are view deviations from the
+ <citation>perfSONAR Base Protocol</citation> for this particular
+ message type. The following analysis will describe each element,
+ noting when there are changes.
+ </para>
+
+ <section id="setup_data_request_analysis_message"
xreflabel="Message">
+ <title>Message</title>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ id="message1"
+ type="Request">
+
+ <nmwg:parameters />
+
+ <nmwg:metadata />
+
+ <nmwg:data />
+
+</nmwg:message>
+ ]]>
+ </programlisting>
+
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_sd_request_analysis_message">
+ <title>SD Request Message 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>message</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, type</entry>
+ </row>
+ <row>
+ <entry><command>nested elements</command></entry>
+ <entry>parameters, metadata, data</entry>
+ </row>
+ <row>
+ <entry><command>required</command></entry>
+ <entry>yes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ There is no difference in the structure of this element. The
only
+ notable difference is the value of <emphasis>type</emphasis> is
+ restricted to be <emphasis>SetupDataRequest</emphasis>.
+ </para>
+
+ </section>
+
+ <section id="setup_data_request_analysis_parameters"
xreflabel="Parameters">
+ <title>Parameters</title>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:parameters xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="parameters1">
+
+ <nmwg:parameter />
+
+</nmwg:parameters>
+ ]]>
+ </programlisting>
+
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_sd_request_analysis_parameters">
+ <title>Parameters 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>parameters</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>parameter</entry>
+ </row>
+ <row>
+ <entry><command>required</command></entry>
+ <entry>no</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ There is no difference in the structure of this element.
+ </para>
+
+ </section>
+
+ <section id="setup_data_request_analysis_parameter"
xreflabel="Parameter">
+ <title>Parameter</title>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ name="NAME">VALUE</nmwg:parameter>
+
+
+
+<nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ name="NAME" value="VALUE" />
+ ]]>
+ </programlisting>
+
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_sd_request_analysis_parameter">
+ <title>Parameter 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>parameter</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>name, value</entry>
+ </row>
+ <row>
+ <entry><command>nested elements</command></entry>
+ <entry>text</entry>
+ </row>
+ <row>
+ <entry><command>required</command></entry>
+ <entry>yes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ There is no difference in the structure of this element.
+ </para>
+
+ </section>
+
+ <section id="setup_data_request_analysis_metadata"
xreflabel="Metadata">
+ <title>Metadata</title>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ id="metadata2" metadataIdRef="metadata1" />
+ ]]>
+ </programlisting>
+
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_sd_request_analysis_metadata">
+ <title>Metadata 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>metadata</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</entry>
+ </row>
+ <row>
+ <entry><command>required</command></entry>
+ <entry>yes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ There is no difference in the structure of this element. Note
that
+ the contents will vary from service to service.
+ </para>
+
+ </section>
+
+ <section id="setup_data_request_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" />
+ ]]>
+ </programlisting>
+
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_sd_request_analysis_data">
+ <title>Data 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>data</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>N/A</entry>
+ </row>
+ <row>
+ <entry><command>required</command></entry>
+ <entry>varies</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ There is no difference in the structure of this element. The
only
+ notable difference is that this element
+ <emphasis>should not</emphasis> contain any nested elements.
This
+ element should only be used as a <emphasis>data
trigger</emphasis>
+ for services to act on particular metadata elements.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section id="setup_data_request_example" xreflabel="SetupDataRequest
Message Example">
+ <title>SetupDataRequest Message Example</title>
+
+ <para>
+ The following examples demonstrate some of the possible uses and
+ layouts of request messages in the MA Protocol. These examples are
+ not an attempt to be exhaustive, but rather some examples of ways
to
+ perform common tasks. Note that these messages are
+ <emphasis>NOT</emphasis> indicative of a particular service.
+ </para>
+
+ <para>
+ The first example demonstrates the most common use case: a single
+ metadata and data pair.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <inlinexml file="examples/sd_request1.xml"/>
+ ]]>
+ </programlisting>
+
+ <para>
+ The second example is similar, but incorporates a parameters block
+ that may be populated with optional behaviors for a service.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <inlinexml file="examples/sd_request2.xml"/>
+ ]]>
+ </programlisting>
+
+ <para>
+ The third example is also similar to the first, but shows it is
+ possible to ask for multiple pairs of metadata and data in a single
+ message. Note that there are two empty data triggers to signify
that
+ each message be acted upon.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <inlinexml file="examples/sd_request3.xml"/>
+ ]]>
+ </programlisting>
+
+ <para>
+ This example features merge chaining. Note there is only one data
+ trigger, and it is at the <emphasis>tail</emphasis> of the chain.
A
+ service would perform the necessary chaining first, then act on the
+ result of this operation.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <inlinexml file="examples/sd_request4.xml"/>
+ ]]>
+ </programlisting>
+
+ <para>
+ The final example is an invalid case where the metadata does not
+ have an appropriate data trigger.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <inlinexml file="examples/sd_request5.xml"/>
+ ]]>
+ </programlisting>
+
+ </section>
+
+ </section>
+
+
+ <section id="setup_data_response" xreflabel="SetupDataResponse Message">
+ <title>SetupDataResponse Message</title>
+
+ <para>
+ The SetupDataResponse message is a container filled with the results
+ of a <xref linkend="setup_data_request" /> from
+ <emphasis>perfSONAR Measurement Archive</emphasis> 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
+ <xref linkend="setup_data_response_schema" /> along with an analysis
of
+ the elements in <xref linkend="setup_data_response_analysis" />. We
+ conclude with examples in <xref
linkend="setup_data_response_example" />.
+ </para>
+
+ <section id="setup_data_response_schema" xreflabel="SetupDataResponse
Message Schema">
+ <title>SetupDataResponse Message Schema</title>
+
+ <para>
+ The following schema is a native description of the response
schema as
+ in the <citation>RELAX-NG</citation> language. Through the use of
+ tools such as <citation>Trang</citation> and
<citation>MSV</citation>
+ it is possible to convert this to other widely accepted formats
such
+ as <citation>XSD</citation>.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <inlineschema file="schema/setupdata_response.rnc"/>
+ ]]>
+ </programlisting>
+
+ </section>
+
+ <section id="setup_data_response_analysis" xreflabel="Response Message
Analysis">
+ <title>SetupDataResponse Message Analysis</title>
+
+ <para>
+ The following is a breakdown of the elements featured in the
schema.
+ </para>
+
+ <section id="setup_data_response_analysis_message"
xreflabel="Message">
+ <title>Message</title>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:message xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ id="message1"
+ type="SetupDataResponse">
+
+ <nmwg:parameters />
+
+ <nmwg:metadata />
+
+ <nmwg:data />
+
+</nmwg:message>
+ ]]>
+ </programlisting>
+
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_sd_response_analysis_message">
+ <title>SD Response Message 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>message</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, type</entry>
+ </row>
+ <row>
+ <entry><command>nested elements</command></entry>
+ <entry>parameters, metadata, data</entry>
+ </row>
+ <row>
+ <entry><command>required</command></entry>
+ <entry>yes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ There is no difference in the structure of this element. The
only
+ notable difference is the value of <emphasis>type</emphasis> is
+ restricted to be <emphasis>SetupDataResponse</emphasis>.
+ </para>
+
+ </section>
+
+ <section id="setup_data_response_analysis_parameters"
xreflabel="Parameters">
+ <title>Parameters</title>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:parameters xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="parameters1">
+
+ <nmwg:parameter />
+
+</nmwg:parameters>
+ ]]>
+ </programlisting>
+
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_sd_response_analysis_parameters">
+ <title>Parameters 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>parameters</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>parameter</entry>
+ </row>
+ <row>
+ <entry><command>required</command></entry>
+ <entry>no</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ There is no difference in the structure of this element.
+ </para>
+
+ </section>
+
+ <section id="setup_data_response_analysis_parameter"
xreflabel="Parameter">
+ <title>Parameter</title>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ name="NAME">VALUE</nmwg:parameter>
+
+
+
+<nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ name="NAME" value="VALUE" />
+ ]]>
+ </programlisting>
+
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_sd_response_analysis_parameter">
+ <title>Parameter 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>parameter</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>name, value</entry>
+ </row>
+ <row>
+ <entry><command>nested elements</command></entry>
+ <entry>text</entry>
+ </row>
+ <row>
+ <entry><command>required</command></entry>
+ <entry>yes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ There is no difference in the structure of this element.
+ </para>
+
+ </section>
+
+ <section id="setup_data_response_analysis_metadata"
xreflabel="Metadata">
+ <title>Metadata</title>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
+ id="metadata2" metadataIdRef="metadata1" />
+ ]]>
+ </programlisting>
+
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_sd_response_analysis_metadata">
+ <title>Metadata 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>metadata</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</entry>
+ </row>
+ <row>
+ <entry><command>required</command></entry>
+ <entry>yes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ There is no difference in the structure of this element. As in
the
+ <xref linkend="setup_data_request" /> the contents of this
element
+ will vary by service.
+ </para>
+
+ </section>
+
+ <section id="setup_data_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" />
+ ]]>
+ </programlisting>
+
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_sd_response_analysis_data">
+ <title>Data 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>data</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>datum</entry>
+ </row>
+ <row>
+ <entry><command>required</command></entry>
+ <entry>yes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ This element features only one deviation from that of the
+ <citation>perfSONAR Base Protocol</citation>: datum elements are
+ expected to reside in the data element, it will be explained in
+ <xref linkend="setup_data_response_analysis_datum" />.
+ </para>
+
+ </section>
+
+ <section id="setup_data_response_analysis_datum" xreflabel="Datum">
+ <title>Datum</title>
+
+ <programlisting>
+ <![CDATA[
+<nmwg:datum xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/"; >
+ ]]>
+ </programlisting>
+
+ <table frame="all" align="center" halign="center" width="80%"
id="table.messages_sd_response_analysis_datum">
+ <title>Datum 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>datum</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>undefined</entry>
+ </row>
+ <row>
+ <entry><command>nested elements</command></entry>
+ <entry>undefined</entry>
+ </row>
+ <row>
+ <entry><command>required</command></entry>
+ <entry>varies</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ The datum element is the only element that should appear here.
This
+ document will not specific attributes or elements for the datum
+ element.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section id="setup_data_response_example" xreflabel="SetupDataResponse
Message Example">
+ <title>SetupDataResponse Message Example</title>
+
+ <para>
+ The following examples demonstrate some of the possible uses and
+ layouts of response messages in the MA Protocol.
+ </para>
+
+ <para>
+ The first example is the most common form of SetupDataResponse
+ message containing a single metadata and data pair. This would be
+ indicitive of success due to the presence of the key.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <inlinexml file="examples/sd_response1.xml"/>
+ ]]>
+ </programlisting>
+
+ <para>
+ The second example is similar, although it features two pairs.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <inlinexml file="examples/sd_response2.xml"/>
+ ]]>
+ </programlisting>
+
+ <para>
+ The final example demonstrates an error condition. Note that this
+ may contain multiple pairs if sent, and it may be possible to have
+ sucess for some, and errors for others.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <inlinexml file="examples/sd_response3.xml"/>
+ ]]>
+ </programlisting>
+
+
+ </section>
+
+ </section>
+
+ </section>
+
+
+
+
+
+
+
+
+
+ <section id="data_info" xreflabel="DataInfo">
+ <title>DataInfo</title>
+
+ <para>
TBD
</para>

</section>
-
+
+
+
+
+
+
+
+
+
+
<section id="measurement_archive_store"
xreflabel="MeasurementArchiveStore">
<title>MeasurementArchiveStore</title>

@@ -992,6 +1812,15 @@

</section>

+
+
+
+
+
+
+
+
+
<section id="result_codes" xreflabel="Result Codes">
<title>Result Codes</title>

Added: trunk/perfsonar-doc/protocol/MA/schema/setupdata_request.rnc

Added: trunk/perfsonar-doc/protocol/MA/schema/setupdata_response.rnc

Modified: trunk/perfsonar-doc/protocol/base/base_protocol.html
===================================================================
--- trunk/perfsonar-doc/protocol/base/base_protocol.html 2009-04-23
11:23:39 UTC (rev 5106)
+++ trunk/perfsonar-doc/protocol/base/base_protocol.html 2009-04-24
02:30:10 UTC (rev 5107)
@@ -1,11 +1,10 @@
-<?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.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"><<a
href="mailto:"></a>></code><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.73.2" /></head><body><div class="article"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a
id="id2476155"></a>perfSONAR Base Protocol</h2></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"><<a class="email"
href="mailto:"></a>></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"><<a
href="mailto:"></a>></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_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
+            <code class="email"><<a class="email"
href="mailto:"></a>></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_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><tr><td align="left">1.03</td><td
align="left">04/22/2009</td><td align="left">OGF 26 Preparation</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="int
roduction"></a>2. Introduction</h2></div></div></div><p>
+ [<a class="citation" href="#id2535356"><span
class="citation">perfSONAR</span></a>] is an infrastructure for network
performance monitoring and data exchange. It consists of a set of
services
capable of performing, storing, and exchanging performance measurements
in a federated environment. These services act as an intermediate
layer,
@@ -19,32 +18,28 @@
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>].
+ same [<a class="citation" href="#id2535373"><span
class="citation">XML</span></a>] structure used to exchange and store
+ measurement data as defined by the [<a class="citation"
href="#id2535338"><span class="citation">NM-WG</span></a>] in the
+ [<a class="citation" href="#id2535390"><span
class="citation">OGF</span></a>].
</p><p>
- This document will proceed as follows: in <a href="#motivation"
title="3. Motivation">Motivation</a> we
+ This document will proceed as follows: in <a class="xref"
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
+ <a class="xref" 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
+ some future work, a discussion of <a class="xref"
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
+ is brought up in <a class="xref" href="#result_codes" title="6. Result
Codes">Result Codes</a>. After this we introduce
+ two common protocols in <a class="xref" 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>.
+ other protocol documents in <a class="xref" 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>
- Consider the following exchange diagram demonstrating the exchange
pattern
- between two <span class="emphasis"><em>perfSONAR</em></span> entities.
- </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
+ upon 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>
</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
@@ -55,7 +50,7 @@
</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
+ <span class="command"><strong>subscription</strong></span>, <span
class="command"><strong>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
@@ -63,19 +58,18 @@
</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
- redundancies:
- </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
+ 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 redundancies:
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span class="command"><strong>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
Semantic Principals</strong></span> - Concepts used
+ exchange and describe how extension is possible.</p></li><li
style="list-style-type: circle"><p><span class="command"><strong>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
+ save time in the documentation of common features.</p></li><li
style="list-style-type: circle"><p><span class="command"><strong>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
+ (e.g. Unknown Message Type).</p></li><li style="list-style-type:
circle"><p><span class="command"><strong>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
@@ -114,31 +108,33 @@

</pre><p>
There are some important things to note about this query:
- </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong class="command">Message
Type</strong></span> - Every message in
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span class="command"><strong>Message
Type</strong></span> - Every message in
<span class="emphasis"><em>perfSONAR</em></span> contains a type,
these are necessary to
be able to identify the semantic intentions of the internal data
- </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.
- <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,
+ </p></li><li style="list-style-type: circle"><p><span
class="command"><strong>Message Structure</strong></span> - There may be many
+ metadata and data elements in each message, and there
+ <span class="command"><strong><span class="emphasis"><em>does
not</em></span></strong></span> need to be a matching
+ data for <span class="emphasis"><em>every</em></span> metadata
(e.g.
+ <a class="xref" href="#chaining_info"
title="5. Chaining">Chaining</a>)
+ </p></li><li style="list-style-type: circle"><p><span
class="command"><strong>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
+ serve as a modifier (see <a class="xref" 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
+ thumb</p></li><li style="list-style-type: circle"><p><span
class="command"><strong>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
metadata elements</p></li></ul></div><p>
Simply stated, we are sending some type of request that is
interested in
- 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 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</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>
+ getting back some data that matches the sent metadata. This returned
+ 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
class="command"><strong>Syntax</strong></span> - Does the request parse
+ correctly</p></li><li style="list-style-type: circle"><p><span
class="command"><strong>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 class="command"><strong>Structure</strong></span> - Is there
at least a single
+ metadata and data pair that is capable of being acted
on</p></li><li style="list-style-type: circle"><p><span
class="command"><strong>Semantics</strong></span> - Does the request make
sense
+ according to the schematic rules; 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:
@@ -159,25 +155,24 @@
</pre><p>
Note this message is similar to the response in many ways. The major
differences:
- </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong class="command">Message
Type</strong></span> - This becomes the foil
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span class="command"><strong>Message
Type</strong></span> - This becomes the foil
of the previous request; it is common to simply replace the word
- <span class="emphasis"><em>Request</em></span> with <span
class="emphasis"><em>Response</em></span></p></li><li style="list-style-type:
circle"><p><span><strong class="command">Message Structure</strong></span> -
All valid metadata and
- data pairings will be acted on, chained items may be
truncated</p></li><li style="list-style-type: circle"><p><span><strong
class="command">Metadata</strong></span> - May be
+ <span class="emphasis"><em>Request</em></span> with <span
class="emphasis"><em>Response</em></span></p></li><li style="list-style-type:
circle"><p><span class="command"><strong>Message Structure</strong></span> -
All valid metadata and
+ data pairings will be acted on, chained items may be
truncated</p></li><li style="list-style-type: circle"><p><span
class="command"><strong>Metadata</strong></span> - May be
<span class="emphasis"><em>completed</em></span> if it was not
this way in the request
- </p></li><li style="list-style-type: circle"><p><span><strong
class="command">Data</strong></span> - Should contain information, especially
+ </p></li><li style="list-style-type: circle"><p><span
class="command"><strong>Data</strong></span> - Should contain information,
especially
if it was empty in the initial request</p></li></ul></div><p>
The second situation is not very different, but is indicative of
something occurring that was not expected. We don't explicitly use
the
term <span class="emphasis"><em>error</em></span> to describe this
situation because many
- paths that lead to this are not <span
class="emphasis"><em>wrong</em></span>. Some
- examples of status may be:
- </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong class="command">Message
Syntax/Structure/Semantics</strong></span> - The
+ paths that lead to this are not wrong. Some examples of status may
be:
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span class="command"><strong>Message
Syntax/Structure/Semantics</strong></span> - The
service must be able to understand the request, if it cannot be
parsed
on either the syntactic or semantic levels the status should
reflect
- this</p></li><li style="list-style-type: circle"><p><span><strong
class="command">Metadata/Data Search</strong></span> - The backend storage
+ this</p></li><li style="list-style-type: circle"><p><span
class="command"><strong>Metadata/Data Search</strong></span> - The backend
storage
can simply be devoid of references to what a request is interested
in,
this can be expressed by returning nothing in the response or
having
- an explicit message to do so</p></li><li style="list-style-type:
circle"><p><span><strong class="command">Catastrophic Events</strong></span>
- Internal events may
+ an explicit message to do so</p></li><li style="list-style-type:
circle"><p><span class="command"><strong>Catastrophic Events</strong></span>
- Internal events may
trigger some sort of panic in the service; note that not all events
may be recovered from and are not the fault of the service itself
</p></li></ul></div><p>
@@ -198,7 +193,7 @@
</message>

</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" title="4.1. Preliminary
Example">Preliminary Example</a> characterizes many
+ The example from <a class="xref" 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
@@ -219,16 +214,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"
title="4.3.1. Request Message Schema">Request Message Schema</a> along
+ a very simple schema in <a class="xref"
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" 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>.
+ <a class="xref" href="#messages_request_analysis"
title="4.3.2. Request Message Analysis">Request Message Analysis</a>. We
conclude with examples
+ in <a class="xref" 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="#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>]
+ in the [<a class="citation" href="#id2535407"><span
class="citation">RELAX-NG</span></a>] language. Through the use of
+ tools such as [<a class="citation" href="#id2535442"><span
class="citation">Trang</span></a>] and [<a class="citation"
href="#id2535461"><span class="citation">MSV</span></a>]
it is possible to convert this to other widely accepted formats
such
- as [<a href="#id2546222"><span class="citation">XSD</span></a>].
+ as [<a class="citation" href="#id2535479"><span
class="citation">XSD</span></a>].
</p><pre class="programlisting">

<font color=red># Begin Schema</font>
@@ -321,22 +316,22 @@

</nmwg:message>

- </pre><div class="table"><a
id="table.messages_request_analysis_message"></a><p
class="title"><b>Table 2. 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_request_analysis_message"></a><p
class="title"><b>Table 2. 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 class="command"><strong>localname</strong></span></td><td
align="left">message</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, type</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">parameters, metadata, data</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><br class="table-break"
/><p>
The message element serves as a container for transporting
requests
to <span class="emphasis"><em>perfSONAR</em></span> capable
services. The message
itself is unremarkable, it features attributes to aid in the
identification of messages and contains elements with legitimate
content. We first examine the available attributes:
- </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">id</strong></span> - Identifier that can be used to track
- state between messages and services</p></li><li
style="list-style-type: circle"><p><span><strong
class="command">type</strong></span> - Designates the message to a
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>id</strong></span> - Identifier that can be used to
track
+ state between messages and services</p></li><li
style="list-style-type: circle"><p><span
class="command"><strong>type</strong></span> - Designates the message to a
particular type; fully enumerated in each protocol extension
</p></li></ul></div><p>
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"
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">
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>Parameters</strong></span> - Described in
+ <a class="xref" href="#messages_request_analysis_parameters"
title="4.3.2.2. Parameters">Parameters</a></p></li><li
style="list-style-type: circle"><p><span
class="command"><strong>Metadata</strong></span> - Described in
+ <a class="xref" href="#messages_request_analysis_metadata"
title="4.3.2.4. Metadata">Metadata</a></p></li><li style="list-style-type:
circle"><p><span class="command"><strong>Data</strong></span> - Described in
+ <a class="xref" 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">

<nmwg:parameters xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="parameters1">

@@ -344,19 +339,19 @@

</nmwg:parameters>

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">parameters</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span
class="command"><strong>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 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
+ <a class="xref" 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
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>id</strong></span> - Identifying attribute that can be
used to track state.</p></li></ul></div><p>
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"
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">
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>Parameter</strong></span> - Described in
+ <a class="xref" 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">

<nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
name="NAME">VALUE</nmwg:parameter>
@@ -366,13 +361,13 @@
<nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
name="NAME" value="VALUE" />

- </pre><div class="table"><a
id="table.messages_request_analysis_parameter"></a><p
class="title"><b>Table 4. 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_request_analysis_parameter"></a><p
class="title"><b>Table 4. 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 class="command"><strong>localname</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">name, value</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span
class="command"><strong>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
protocol extension and service level.
- </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">name</strong></span> - Generically specify the name
- of some variable value</p></li><li style="list-style-type:
circle"><p><span><strong class="command">value</strong></span> - Can be used
instead a text
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>name</strong></span> - Generically specify the name
+ of some variable value</p></li><li style="list-style-type:
circle"><p><span class="command"><strong>value</strong></span> - Can be used
instead a text
element to set the value of the <span
class="emphasis"><em>name</em></span></p></li></ul></div><p>
In lieu of the <span class="emphasis"><em>value</em></span>
attribute, a text element
may be used for the same purpose. This is the only element that
is
@@ -394,7 +389,7 @@

</nmwg:metadata>

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">undefined, (subject, key, eventType, and parameters are
common)</td></tr><tr><td align="left"><span
class="command"><strong>required</strong></span></td><td
align="left">yes</td></tr></tbody></table></div></div><
br class="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
@@ -402,10 +397,10 @@
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
+ <a class="xref" href="#messages_request_analysis_subject"
title="4.3.2.5. Subject">Subject</a>,
+ <a class="xref" href="#messages_request_analysis_key"
title="4.3.2.6. Key">Key</a>,
+ <a class="xref" href="#messages_request_analysis_eventType"
title="4.3.2.7. EventType">EventType</a>, and
+ <a class="xref" 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.
@@ -415,14 +410,14 @@
<span class="emphasis"><em>operator</em></span> or <span
class="emphasis"><em>merge</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
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>id</strong></span> - Identifying attribute that can be
+ used to track state.</p></li><li style="list-style-type:
circle"><p><span class="command"><strong>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_subject"></a>4.3.2.5. Subject</h5></div></div></div><pre
class="programlisting">

<nmwg:subject xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="subject1" metadataIdRef="metadata1" />

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">subject</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">undefined, (topology elements are common)</td></tr><tr><td
align="left"><span class="command"><strong>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
@@ -431,8 +426,8 @@
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
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>id</strong></span> - Identifying attribute that can be
+ used to track state.</p></li><li style="list-style-type:
circle"><p><span class="command"><strong>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">

<nmwg:key xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/">
@@ -441,20 +436,20 @@

</nmwg:key>

- </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>
+ </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
class="command"><strong>localname</strong></span></td><td
align="left">key</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">parameters</td></tr><tr><td align="left"><span
class="command"><strong>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.
+ dissected. The key normally contains the
+ <a class="xref" 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
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>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">

<nmwg:eventType
xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/">TEXT</nmwg:eventType>

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">eventType</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">N/A</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span
class="command"><strong>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
@@ -467,7 +462,7 @@
<nmwg:data xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="data2" metadataIdRef="metadata2" />

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">undefined</td></tr><tr><td align="left"><span
class="command"><strong>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
@@ -478,8 +473,8 @@
</p><p>
There are two attributes possible. These are used to both track
state inside of 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> - used
to link data to
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>id</strong></span> - Identifying attribute that can be
+ used to track state.</p></li><li style="list-style-type:
circle"><p><span class="command"><strong>metadataIdRef</strong></span> - used
to link data to
metadata.</p></li></ul></div></div></div><div class="section"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a
id="messages_request_example"></a>4.3.3. Request Message
Example</h4></div></div></div><p>
The following examples demonstrate some of the possible uses and
layouts of request messages in the base protocol. These examples
are
@@ -607,20 +602,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" title="4.3. Request Message">Request
Message</a> from
+ <a class="xref" 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" 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>.
+ <a class="xref" href="#messages_response_schema"
title="4.4.1. Response Message Schema">Response Message Schema</a> along with
an analysis of
+ the elements in <a class="xref" href="#messages_response_analysis"
title="4.4.2. Response Message Analysis">Response Message Analysis</a>. We
+ conclude with examples in <a class="xref"
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="#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>]
+ in the [<a class="citation" href="#id2535407"><span
class="citation">RELAX-NG</span></a>] language. Through the use of
+ tools such as [<a class="citation" href="#id2535442"><span
class="citation">Trang</span></a>] and [<a class="citation"
href="#id2535461"><span class="citation">MSV</span></a>]
it is possible to convert this to other widely accepted formats
such
- as [<a href="#id2546222"><span class="citation">XSD</span></a>].
+ as [<a class="citation" href="#id2535479"><span
class="citation">XSD</span></a>].
</p><pre class="programlisting">

<font color=red># Begin Schema</font>
@@ -714,24 +709,24 @@

</nmwg:message>

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">message</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, type</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">parameters, metadata, data</td></tr><tr><td align="left"><span
class="command"><strong>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"
title="4.4.2.1. Message">Message</a> serves as a
+ <a class="xref" 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
of messages and contains elements with legitimate content. We
first
examine the available attributes:
- </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">id</strong></span> - Identifier that can be used to track
- state between messages and services</p></li><li
style="list-style-type: circle"><p><span><strong
class="command">type</strong></span> - Designates the message to a
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>id</strong></span> - Identifier that can be used to
track
+ state between messages and services</p></li><li
style="list-style-type: circle"><p><span
class="command"><strong>type</strong></span> - Designates the message to a
particular type; fully enumerated in each protocol extension
</p></li></ul></div><p>
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"
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">
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>Parameters</strong></span> - Described in
+ <a class="xref" href="#messages_response_analysis_parameters"
title="4.4.2.2. Parameters">Parameters</a></p></li><li
style="list-style-type: circle"><p><span
class="command"><strong>Metadata</strong></span> - Described in
+ <a class="xref" href="#messages_response_analysis_metadata"
title="4.4.2.4. Metadata">Metadata</a></p></li><li style="list-style-type:
circle"><p><span class="command"><strong>Data</strong></span> - Described in
+ <a class="xref" 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">

<nmwg:parameters xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="parameters1">

@@ -739,24 +734,24 @@

</nmwg:parameters>

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">parameters</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span
class="command"><strong>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
+ <a class="xref" 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
+ <a class="xref" 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"
title="4.4.2.3. Parameter">Parameter</a> elements
+ <a class="xref" 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
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>id</strong></span> - Identifying attribute that can be
used to track state.</p></li></ul></div><p>
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"
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">
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>Parameter</strong></span> - Described in
+ <a class="xref" 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">

<nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
name="NAME">VALUE</nmwg:parameter>
@@ -766,13 +761,13 @@
<nmwg:parameter xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
name="NAME" value="VALUE" />

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">parameter</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">name, value</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span
class="command"><strong>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
protocol extension and service level.
- </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span><strong
class="command">name</strong></span> - Generically specify the name
- of some variable value</p></li><li style="list-style-type:
circle"><p><span><strong class="command">value</strong></span> - Can be used
instead a text
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>name</strong></span> - Generically specify the name
+ of some variable value</p></li><li style="list-style-type:
circle"><p><span class="command"><strong>value</strong></span> - Can be used
instead a text
element to set the value of the <span
class="emphasis"><em>name</em></span></p></li></ul></div><p>
In lieu of the <span class="emphasis"><em>value</em></span>
attribute, a text element
may be used for the same purpose. This is the only element that
is
@@ -794,19 +789,19 @@

</nmwg:metadata>

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">undefined, (subject, key, eventType, and parameters are
common)</td></tr><tr><td align="left"><span
class="command"><strong>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"
title="4.4.2.4. Metadata">Metadata</a>.
+ the sent <a class="xref"
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"
title="4.4.2.4. Metadata">Metadata</a>. A detailed
+ <a class="xref" 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
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>id</strong></span> - Identifying attribute that can be
+ used to track state.</p></li><li style="list-style-type:
circle"><p><span class="command"><strong>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">

<nmwg:data xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
@@ -820,18 +815,18 @@

</nmwg:data>

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">undefined, (datum, key, and metadata are
common)</td></tr><tr><td align="left"><span
class="command"><strong>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"
title="4.4.2.5. Data">Data</a>. We leave the
+ <a class="xref" 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.
</p><p>
There are two attributes possible. These are used to both track
state inside of a response 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> - used
to link data to
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="command"><strong>id</strong></span> - Identifying attribute that can be
+ used to track state.</p></li><li style="list-style-type:
circle"><p><span class="command"><strong>metadataIdRef</strong></span> - used
to link data to
metadata.</p></li></ul></div></div></div><div class="section"
lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a
id="messages_response_example"></a>4.4.3. Response Message
Example</h4></div></div></div><p>
The following examples demonstrate some of the possible uses and
layouts of response messages in the base protocol. These examples
are
@@ -892,7 +887,7 @@
</pre><p>
The final example demonstrates an error condition. Note that this
may contain multiple pairs if sent, and it may be possible to have
- sucess for some, and errors for others.
+ success for some, and errors for others.
</p><pre class="programlisting">


@@ -913,17 +908,17 @@


</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
+ Since inception a key goal of the [<a class="citation"
href="#id2535338"><span class="citation">NM-WG</span></a>]
+ [<a class="citation" href="#id2535373"><span
class="citation">XML</span></a>] specification has been extension. The
+ authors of the original <a class="xref" 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
+ <a class="xref" href="#chaining" title="chaining">chaining</a>, are
the recognized procedure to extend
+ [<a class="citation" href="#id2535356"><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
@@ -933,8 +928,8 @@
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>.
+ Chaining itself has taken on two major forms: <a class="xref"
href="#merge_chaining" title="merge chaining">merge chaining</a>
+ and <a class="xref" 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
@@ -943,7 +938,7 @@
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>
+ </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 merge-able
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
@@ -956,24 +951,23 @@
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.
+ Wwhen merging we should 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:
+ </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><span
class="emphasis"><em>Like</em></span> Elements (e.g. sharing the same
localname)</p></li><li style="list-style-type: circle"><p>Elements in the
same namespace</p></li></ul></div><p>
+ When this first criteria is met, we will of course recurse downward
+ and keep trying until we reach the bottom of the structure. 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>
- 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.
+ the scope of this work.
</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
@@ -996,11 +990,11 @@
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
+ (leaving out perhaps one unspecified 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
+ Take for example our SNMP Interface from above. If we 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">
@@ -1012,7 +1006,6 @@
<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>
@@ -1059,7 +1052,6 @@
<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>
@@ -1294,11 +1286,12 @@
</nmwg:metadata>

</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
+ This example shows that its pretty easy to introduce semantic
errors when
+ designing a chain instance. It also shows that the service may
not be
+ interested in protecting a poorly designed chain from being
accepted.
+ 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>
@@ -1559,10 +1552,10 @@
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.
+ response 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
+ aggregations such as [<a class="citation" href="#id2535424"><span
class="citation">CDF</span></a>]. 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.
@@ -1637,13 +1630,13 @@
the facts that there are many diverse services as well as different
status messages that may be returned, but the newer of the approaches
also allows for versioning and backwards compatibility that the
original
- attempt did not consider. The original system <span><strong
class="command">must</strong></span>
+ attempt did not consider. The original system <span
class="command"><strong>must</strong></span>
continue to be supported by all services for the foreseeable future,
while
a slow phase in of the latest eventTypes is attempted.
</p><p>
The original system, currently used by all
<span class="emphasis"><em>perfSONAR</em></span> services and
explained in
- [<a href="#id2546258"><span class="citation">Result Codes</span></a>],
relies on a static tree of status
+ [<a class="citation" href="#id2535514"><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
@@ -1696,7 +1689,7 @@
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" 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>.
+ <a class="xref" href="#extension_echo" title="7.1. Echo Protocol">Echo
Protocol</a> and <a class="xref" 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
@@ -1705,16 +1698,16 @@
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="#id2546130"><span
class="citation">XML</span></a>] formats used to
+ protocols based on the same [<a class="citation"
href="#id2535373"><span class="citation">XML</span></a>] formats 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>].
+ [<a class="citation" href="#id2535338"><span
class="citation">NM-WG</span></a>] in the [<a class="citation"
href="#id2535390"><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
<span class="emphasis"><em>liveness</em></span> of a given <span
class="emphasis"><em>perfSONAR</em></span>
- service instance. A well formatted <span><strong
class="command">EchoRequest</strong></span>
+ service instance. A well formatted <span
class="command"><strong>EchoRequest</strong></span>
message, when sent to any <span
class="emphasis"><em>perfSONAR</em></span> service, should
- trigger a similar <span><strong
class="command">EchoResponse</strong></span>. This interaction
+ trigger a similar <span
class="command"><strong>EchoResponse</strong></span>. This interaction
allows a client or service to gauge the responsiveness of a service;
the
potential to learn more information is also available for services
who
wish to provide it.
@@ -1723,34 +1716,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"
title="ping">ping</a>. While this
+ other types of communication, notably <a class="xref" 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" 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>.
+ <a class="xref" href="#extension_echo_request_message"
title="7.1.2. Request Message">Request Message</a> and
+ <a class="xref" 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" title="7.1.5. Protocol
Extension">Protocol Extension</a>.
+ <a class="xref" 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"
title="7.1.1. Architecture">Architecture</a>, detailed
+ protocol in <a class="xref" href="#extension_echo_architecture"
title="7.1.1. Architecture">Architecture</a>, detailed
descriptions regarding syntax and semantics in
- <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
+ <a class="xref" href="#extension_echo_request_message"
title="7.1.2. Request Message">Request Message</a> and
+ <a class="xref" 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" title="7.1.4. Result
Codes">Result Codes</a>, and finally points of
+ <a class="xref" 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" title="7.1.5. Protocol
Extension">Protocol Extension</a>.
+ <a class="xref" 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
+ <span class="command"><strong>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="#id2546240"><span
class="citation">SmokePing</span></a>]) can
+ external monitoring tools (such as [<a class="citation"
href="#id2535496"><span class="citation">SmokePing</span></a>]) can
use this simple method to quickly come to conclusions regarding
framework
availability.
</p><p>
@@ -1762,10 +1755,10 @@
may be built from this general protocol to elicit additional
functionality
on a service by service basis to do tasks such as test the
capabilities of
the service, receive statistics, or monitor erroneous behavior.
The
- assignment of these other tasks within an <span><strong
class="command">EchoRequest</strong></span>
+ assignment of these other tasks within an <span
class="command"><strong>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>7.1.2. Request
Message</h4></div></div></div><p>
- The <span><strong class="command">EchoRequest</strong></span>
message can be initiated by a
+ The <span class="command"><strong>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
other protocol messages as the input is rather simple.
@@ -1773,18 +1766,18 @@
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="#id2546278"><span
class="citation">Zurawski06Scalable</span></a>]. The basic format described
+ in [<a class="citation" href="#id2535532"><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" title="metadata">metadata</a> and <a
href="#data" title="data">data</a> intact.
+ <a class="xref" href="#metadata" title="metadata">metadata</a> and
<a class="xref" 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
to that of a regular language, and allows for a rather compact
description. The following describes the
- <span><strong class="command">EchoRequest</strong></span>
schema. Note that this
- <span><strong class="command">will</strong></span> only validate
+ <span class="command"><strong>EchoRequest</strong></span>
schema. Note that this
+ <span class="command"><strong>will</strong></span> only validate
<span class="emphasis"><em>EchoRequest</em></span> messages.
</p><pre class="programlisting">

@@ -1828,13 +1821,13 @@

</nmwg:message>

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">message</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, type</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">metadata, data</td></tr><tr><td align="left"><span
class="command"><strong>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"
title="4.3.2.1. Message">Message</a>, the only
+ <a class="xref" 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>.
+ <span class="command"><strong>EchoRequest</strong></span> or
+ <span
class="command"><strong>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>7.1.2.2.2. Metadata</h6></div></div></div><pre
class="programlisting">

<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="STRING">
@@ -1843,11 +1836,11 @@

</nmwg:metadata>

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">eventType</td></tr><tr><td align="left"><span
class="command"><strong>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"
title="4.3.2.4. Metadata">Metadata</a>, the only
+ <a class="xref" 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"
title="7.1.2.2.3. EventType">EventType</a> can be
+ <a class="xref"
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>7.1.2.2.3. EventType</h6></div></div></div><pre
class="programlisting">

@@ -1855,19 +1848,19 @@
http://schemas.perfsonar.net/tools/admin/echo/2.0
</nmwg:eventType>

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">eventType</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">N/A</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span
class="command"><strong>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
the <span class="emphasis"><em>action</em></span> of
responding to an
- <span><strong class="command">EchoRequest</strong></span>.
There are no attributes permitted
+ <span class="command"><strong>EchoRequest</strong></span>.
There are no attributes permitted
for this element, and only text can be used as a child,
specifically
text reporting
- <span><strong
class="command">http://schemas.perfsonar.net/tools/admin/echo/2.0</strong></span>.
+ <span
class="command"><strong>http://schemas.perfsonar.net/tools/admin/echo/2.0</strong></span>.
</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"
title="7.1.5. Protocol Extension">Protocol Extension</a>,
+ discussed in <a class="xref"
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>7.1.2.2.4. Data</h6></div></div></div><pre
class="programlisting">
@@ -1876,9 +1869,9 @@
id="STRING"
metadataIdRef="STRING" />

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">N/A</td></tr><tr><td align="left"><span
class="command"><strong>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"
title="4.3.2.8. Data">Data</a>.
+ <a class="xref" 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.
@@ -1925,22 +1918,22 @@


</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
+ The <span class="command"><strong>EchoResponse</strong></span>
message is a reply to a given
+ <span class="command"><strong>EchoRequest</strong></span> message
from a client application or
+ service. Like the <span
class="command"><strong>EchoRequest</strong></span> the format is
kept very simple, exposing only a selection of the
<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"
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
+ <a class="xref" href="#extension_echo_protocol_extension"
title="7.1.5. Protocol Extension">Protocol Extension</a>. As discussed in
+ <a class="xref" 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>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
to that of a regular language, and allows for a rather compact
- description. Similar to the <span><strong
class="command">EchoRequest</strong></span> RELAX-NG
+ description. Similar to the <span
class="command"><strong>EchoRequest</strong></span> RELAX-NG
description, this schema fragment offers only the bare essentials
for validating this message type.
</p><pre class="programlisting">
@@ -1994,13 +1987,13 @@

</nmwg:message>

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">message</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, type</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">metadata, data</td></tr><tr><td align="left"><span
class="command"><strong>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"
title="4.4.2.1. Message">Message</a>, the only
+ <a class="xref" 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>.
+ <span class="command"><strong>EchoResponse</strong></span> or
+ <span
class="command"><strong>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>7.1.3.2.2. Metadata</h6></div></div></div><pre
class="programlisting">

<nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="STRING">
@@ -2009,39 +2002,45 @@

</nmwg:metadata>

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">metadata</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">eventType</td></tr><tr><td align="left"><span
class="command"><strong>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"
title="4.4.2.4. Metadata">Metadata</a>, the only
+ <a class="xref" 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"
title="7.1.3.2.3. EventType">EventType</a> can be
+ <a class="xref"
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>7.1.3.2.3. EventType</h6></div></div></div><pre
class="programlisting">

<nmwg:eventType xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/">
http://schemas.perfsonar.net/tools/admin/echo/2.0
</nmwg:eventType>
+
+or
+
+<nmwg:eventType xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/">
+ http://schemas.perfsonar.net/status/success/echo/1.0
+</nmwg:eventType>

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">eventType</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">N/A</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span
class="command"><strong>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
the <span class="emphasis"><em>action</em></span> of a
response to an
- <span><strong class="command">EchoRequest</strong></span>.
There are no attributes permitted
+ <span class="command"><strong>EchoRequest</strong></span>.
There are no attributes permitted
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" title="7.1.4. Result
Codes">Result Codes</a>.
+ <span class="emphasis"><em>available</em></span> status
strings is available in
+ <a class="xref" 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">

<nmwg:data xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";
id="STRING"
metadataIdRef="STRING" />

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">data</td></tr><tr><td align="left"><span
class="command"><strong>namespaces</strong></span></td><td
align="left">http://ggf.org/ns/nmwg/base/2.0/</td></tr><tr><td
align="left"><span class="command"><strong>attributes</strong></span></td><td
align="left">id, metadataIdRef</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">datum</td></tr><tr><td align="left"><span
class="command"><strong>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"
title="4.4.2.5. Data">Data</a> with the
+ <a class="xref" 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"
title="7.1.3.2.5. Datum">Datum</a> as a child
+ <a class="xref" 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>7.1.3.2.5. Datum</h6></div></div></div><pre
class="programlisting">

@@ -2055,7 +2054,7 @@
TEXT
</nmwg:datum>

- </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>
+ </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 class="command"><strong>localname</strong></span></td><td
align="left">datum</td></tr><tr><td align="left"><span
class="command"><strong>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
class="command"><strong>attributes</strong></span></td><td
align="left">value</td></tr><tr><td align="left"><span
class="command"><strong>nested elements</strong></span></td><td
align="left">text</td></tr><tr><td align="left"><span
class="command"><strong>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
@@ -2112,7 +2111,7 @@

</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" title="6. Result
Codes">Result Codes</a>. We will introduce
+ protocol based on <a class="xref" 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">
@@ -2146,32 +2145,32 @@
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>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>
+ <span class="emphasis"><em>Echo Protocol</em></span>'s <span
class="command"><strong>EchoRequest</strong></span>
message is
- <span><strong
class="command">http://schemas.perfsonar.net/tools/admin/echo/2.0</strong></span>.
+ <span
class="command"><strong>http://schemas.perfsonar.net/tools/admin/echo/2.0</strong></span>.
This action must be accepted by all services. By adding
additional
<span class="emphasis"><em>eventType</em></span>s with the same
format it is possible to
extract additional information via a service.
</p><p>
- Consider simple service <span><strong
class="command">X</strong></span>. The designer of this
+ Consider simple service <span
class="command"><strong>X</strong></span>. The designer of this
service wishes to create a special behaviour for specific
<span class="emphasis"><em>eventType</em></span>s. The
following new
<span class="emphasis"><em>eventType</em></span>s are added to
his service code (and to
his implementation of the schema):
</p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p>
- <span><strong
class="command">http://schemas.perfsonar.net/tools/admin/echo/X/2.0</strong></span>
-
+ <span
class="command"><strong>http://schemas.perfsonar.net/tools/admin/echo/X/2.0</strong></span>
-
Allows service contact information to be returned via
<span class="emphasis"><em>nmwgr:datum</em></span>
</p><p>
- <span><strong
class="command">http://schemas.perfsonar.net/tools/admin/echo/X/contact/2.0</strong></span>
-
+ <span
class="command"><strong>http://schemas.perfsonar.net/tools/admin/echo/X/contact/2.0</strong></span>
-
Allows service contact information to be returned via
<span class="emphasis"><em>nmwgr:datum</em></span>
</p><p>
- <span><strong
class="command">http://schemas.perfsonar.net/tools/admin/echo/X/stats/2.0</strong></span>
-
+ <span
class="command"><strong>http://schemas.perfsonar.net/tools/admin/echo/X/stats/2.0</strong></span>
-
Allows service usage statistics to be returned via
<span class="emphasis"><em>nmwgr:datum</em></span>
</p><p>
- <span><strong
class="command">http://schemas.perfsonar.net/tools/admin/echo/X/db/2.0</strong></span>
-
+ <span
class="command"><strong>http://schemas.perfsonar.net/tools/admin/echo/X/db/2.0</strong></span>
-
Allows a basic database test to be performed, the results of
which
are returned via <span
class="emphasis"><em>nmwgr:datum</em></span>
</p></li></ul></div><p>
@@ -2187,8 +2186,8 @@
</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"
title="7.1.2.2.1. Message">Message</a> of the
- <span><strong class="command">EchoRequest</strong></span>
message. This modification is
+ <a class="xref" href="#extension_echo_request_analysis_message"
title="7.1.2.2.1. Message">Message</a> of the
+ <span class="command"><strong>EchoRequest</strong></span>
message. This modification is
presented below.
</p><pre class="programlisting">

@@ -2225,7 +2224,7 @@

</pre><p>
Building on the example in
- <a href="#extension_echo_protocol_extension_eventType"
title="7.1.5.1. eventType Extension">eventType Extension</a>, the following
example
+ <a class="xref"
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">
@@ -2250,9 +2249,9 @@
</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"
title="7.1.5.1. eventType Extension">eventType Extension</a>. An important
+ <a class="xref"
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>
+ in an <span class="command"><strong>EchoRequest</strong></span>
</p></div><p>
It is important to note that the extension methods proposed here
preserve the underlying base protocol completely. Existing
services
@@ -2269,55 +2268,57 @@
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="#id2546074"><span class="citation">Measurement
Schema</span></a>]</p></li></ul></div><p>
+ [<a class="citation" href="#id2535320"><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="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" title="NM-WG">NM-WG</a> XML block used
+ <a class="ulink" 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
class="xref" 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="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
+ representation.</p></dd><dt><a
id="metadata"></a>metadata</dt><dd><p>An <a class="xref" 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="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"
title="characteristic">characteristics</a>) useful to grid applications
+ (aka <a class="xref" 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="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" title="ICMP">ICMP</a> "echo request" packets to
the target
- host and listening for <a href="#ICMP" title="ICMP">ICMP</a>
"echo response"
+ <a class="xref" href="#ICMP" title="ICMP">ICMP</a> "echo
request" packets to the target
+ host and listening for <a class="xref" 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"><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="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="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="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="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="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="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="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="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="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="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="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>
+ </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="id2535320"></a><p>[<abbr
class="abbrev">Measurement Schema</abbr>] <span class="title"><i>
+ <a class="ulink"
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="id2535338"></a><p>[<abbr class="abbrev">NM-WG</abbr>] <span
class="title"><i>
+ <a class="ulink" href="http://nmwg.internet2.edu";
target="_top">Network Measurements Working Group</a>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2535356"></a><p>[<abbr class="abbrev">perfSONAR</abbr>] <span
class="title"><i>
+ <a class="ulink" href="http://www.perfsonar.net";
target="_top">perfSONAR</a>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2535373"></a><p>[<abbr class="abbrev">XML</abbr>] <span
class="title"><i>
+ <a class="ulink" href="http://www.w3.org/XML";
target="_top">Extensible Markup Language (XML)</a>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2535390"></a><p>[<abbr class="abbrev">OGF</abbr>] <span
class="title"><i>
+ <a class="ulink" href="http://www.ogf.org/";
target="_top">(Global|Open) Grid Forum</a>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2535407"></a><p>[<abbr class="abbrev">RELAX-NG</abbr>] <span
class="title"><i>
+ <a class="ulink" href="http://relaxng.org/"; target="_top">RELAX-NG
Schema Language</a>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2535424"></a><p>[<abbr class="abbrev">CDF</abbr>] <span
class="title"><i>
+ <a class="ulink"
href="http://en.wikipedia.org/wiki/Cumulative_distribution_function";
target="_top">Cumulative Distribution Function</a>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2535442"></a><p>[<abbr class="abbrev">Trang</abbr>] <span
class="title"><i>
+ <a class="ulink"
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="id2535461"></a><p>[<abbr class="abbrev">MSV</abbr>] <span
class="title"><i>
+ <a class="ulink" href="https://msv.dev.java.net/"; target="_top">Sun
Multi-Schema XML Validator (MSV)</a>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2535479"></a><p>[<abbr class="abbrev">XSD</abbr>] <span
class="title"><i>
+ <a class="ulink" href="http://www.w3.org/XML/Schema";
target="_top">XML Schema</a>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2535496"></a><p>[<abbr class="abbrev">SmokePing</abbr>] <span
class="title"><i>
+ <a class="ulink" href="http://oss.oetiker.ch/smokeping/";
target="_top">SmokePing latency measurement tool</a>
+ </i>. </span></p></div><div class="biblioentry"><a
id="id2535514"></a><p>[<abbr class="abbrev">Result Codes</abbr>] <span
class="title"><i>
+ <a class="ulink"
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="id2535532"></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>

Property changes on: trunk/perfsonar-doc/protocol/base/base_protocol.html
___________________________________________________________________
Name: svn:mime-type
+ text/html

Modified: trunk/perfsonar-doc/protocol/base/base_protocol.xml
===================================================================
--- trunk/perfsonar-doc/protocol/base/base_protocol.xml 2009-04-23 11:23:39
UTC (rev 5106)
+++ trunk/perfsonar-doc/protocol/base/base_protocol.xml 2009-04-24 02:30:10
UTC (rev 5107)
@@ -68,6 +68,12 @@
<entry>Pre-OGF Cleanup</entry>
<entry>J. Zurawski</entry>
</row>
+ <row>
+ <entry>1.03</entry>
+ <entry>04/22/2009</entry>
+ <entry>OGF 26 Preparation</entry>
+ <entry>J. Zurawski</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -118,21 +124,15 @@
<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>
+ 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
+ upon it. Consider this example of a client application interacting
with
+ some <emphasis>perfSONAR</emphasis> service in search of data.
+ </para>

<para>
- Consider the following exchange diagram demonstrating the exchange
pattern
- between two <emphasis>perfSONAR</emphasis> entities.
- </para>
-
- <para>
<mediaobject>
<imageobject>
<imagedata fileref="exchange.png"/>
@@ -173,10 +173,9 @@
</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
- redundancies:
+ 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 redundancies:
</para>

<itemizedlist mark='opencircle'>
@@ -268,8 +267,9 @@
</listitem>
<listitem>
<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.
+ metadata and data elements in each message, and there
+ <command><emphasis>does not</emphasis></command> need to be a
matching
+ data for <emphasis>every</emphasis> metadata (e.g.
<xref linkend="chaining_info" />)
</para>
</listitem>
@@ -291,9 +291,9 @@

<para>
Simply stated, we are sending some type of request that is
interested in
- 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:
+ getting back some data that matches the sent metadata. This returned
+ metadata may be partial or complete. When the service receives this
+ request it will check for several things:
</para>

<itemizedlist mark='opencircle'>
@@ -310,8 +310,9 @@
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; are the chains resolved properly</para>
+ <para><command>Semantics</command> - Does the request make sense
+ according to the schematic rules; can the metadata be acted upon;
are
+ the chains resolved properly</para>
</listitem>
</itemizedlist>

@@ -367,8 +368,7 @@
The second situation is not very different, but is indicative of
something occurring that was not expected. We don't explicitly use
the
term <emphasis>error</emphasis> to describe this situation because
many
- paths that lead to this are not <emphasis>wrong</emphasis>. Some
- examples of status may be:
+ paths that lead to this are not wrong. Some examples of status may
be:
</para>

<itemizedlist mark='opencircle'>
@@ -767,7 +767,7 @@
</row>
<row>
<entry><command>nested elements</command></entry>
- <entry>undefined, (subject, eventType, and parameters are
common)</entry>
+ <entry>undefined, (subject, key, eventType, and parameters
are common)</entry>
</row>
<row>
<entry><command>required</command></entry>
@@ -926,7 +926,7 @@
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
+ dissected. 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:
@@ -1625,7 +1625,7 @@
<para>
The final example demonstrates an error condition. Note that this
may contain multiple pairs if sent, and it may be possible to have
- sucess for some, and errors for others.
+ success for some, and errors for others.
</para>

<programlisting>
@@ -1697,7 +1697,7 @@
<para>Which elements are <emphasis>mergeable</emphasis>?</para>
</listitem>
<listitem>
- <para>How much <emphasis>recursion</emphasis> is needed for
mergeable elements?</para>
+ <para>How much <emphasis>recursion</emphasis> is needed for
merge-able elements?</para>
</listitem>
<listitem>
<para>When do we <emphasis>duplicate</emphasis> elements?</para>
@@ -1727,20 +1727,28 @@
<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.
+ Wwhen merging we should 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:
</para>
+
+ <itemizedlist mark='opencircle'>
+ <listitem>
+ <para><emphasis>Like</emphasis> Elements (e.g. sharing the same
localname)</para>
+ </listitem>
+ <listitem>
+ <para>Elements in the same namespace</para>
+ </listitem>
+ </itemizedlist>

<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.
+ When this first criteria is met, we will of course recurse downward
+ and keep trying until we reach the bottom of the structure. 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>
@@ -1748,7 +1756,7 @@
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.
+ the scope of this work.
</para>

</section>
@@ -1787,13 +1795,13 @@

<para>
A classic example of merge chaining is to partially specify a
metadata
- (leaving out perhaps one key element) and then constructing new
elements
+ (leaving out perhaps one unspecified 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
+ Take for example our SNMP Interface from above. If we 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>
@@ -1807,7 +1815,6 @@
<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>
@@ -1864,7 +1871,6 @@
<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>
@@ -2123,11 +2129,12 @@
</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
+ This example shows that its pretty easy to introduce semantic
errors when
+ designing a chain instance. It also shows that the service may
not be
+ interested in protecting a poorly designed chain from being
accepted.
+ 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>
@@ -2435,7 +2442,7 @@
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.
+ response data corruption may occur.
</para>

<para>
@@ -3177,6 +3184,12 @@
<nmwg:eventType xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";>
http://schemas.perfsonar.net/tools/admin/echo/2.0
</nmwg:eventType>
+
+or
+
+<nmwg:eventType xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/";>
+ http://schemas.perfsonar.net/status/success/echo/1.0
+</nmwg:eventType>
]]>
</programlisting>

@@ -3218,7 +3231,7 @@
<command>EchoRequest</command>. There are no attributes
permitted
for this element, and only text can be used as a child,
specifically
text reporting the status of the transaction. A complete list
of
- <emphasis>available</emphasis> status strings is availble in
+ <emphasis>available</emphasis> status strings is available in
<xref linkend="extension_echo_result_codes" />.
</para>

@@ -3839,6 +3852,13 @@
</title>
</biblioentry>

+ <biblioentry xreflabel="CDF">
+ <abbrev>CDF</abbrev>
+ <title>
+ <ulink
url="http://en.wikipedia.org/wiki/Cumulative_distribution_function";>Cumulative
Distribution Function</ulink>
+ </title>
+ </biblioentry>
+
<biblioentry xreflabel="Trang">
<abbrev>Trang</abbrev>
<title>

perfsonar: r5107 - in trunk/perfsonar-doc/protocol: . Echo Echo/examples Echo/schema MA MA/examples MA/schema base, svnlog, 04/23/2009

List archive

perfsonar: r5107 - in trunk/perfsonar-doc/protocol: . Echo Echo/examples Echo/schema MA MA/examples MA/schema base