perfsonar development work

Author: boote
Date: 2008-03-22 02:25:49 -0400 (Sat, 22 Mar 2008)
New Revision: 335

Modified:
   trunk/nmwg/doc/dLS/dLS_spec.xml
Log:
discovery phase documented as I understand it. Martin, please review
this and make sure it aligns with your vision.



Modified: trunk/nmwg/doc/dLS/dLS_spec.xml
===================================================================
--- trunk/nmwg/doc/dLS/dLS_spec.xml     2008-03-09 01:35:43 UTC (rev 334)
+++ trunk/nmwg/doc/dLS/dLS_spec.xml     2008-03-22 06:25:49 UTC (rev 335)
@@ -619,7 +619,7 @@
                 based upon continents or countries. This optimizations
                 can be added in after the fact, without changing
                 <command>Scope</command> specifications for already
-                deployed <command>LS</command> instances. (Already
+                deployed <command>LS</command> instances. Already
                 deployed <command>LS</command> instances would simply
                 jump over the geographic <emphasis>Scope</emphasis>
                 directly to the root <emphasis>Scope</emphasis>. This
@@ -1554,9 +1554,9 @@
             <orderedlist numeration="arabic">
               <listitem>
                 <para>
-                  A client locates an <command>LS</command> of some sort 
(this
-                  may be known beforehand via a configuration value, or from
-                       bootstrapping).  
+                    A client locates any <command>LS</command> instance. This
+                    SHOULD be one close to the client as possible for
+                    efficiency.
                 </para>
               </listitem>
               <listitem>
@@ -1564,95 +1564,115 @@
                   The client should start by making a discovery query (see 
                   <xref linkend="ls_discovery_message" />) to locate an
                   <command>LS</command> that contains the data it is 
interested
-                  in. The results of this query will be:
+                  in. This query is used to find the authoritative
+                  <command>LS</command> instances for a set of
+                  data (eventType) about a part of the network (topology).
                 </para>
                 <para>
+                  A successful result of this query will contain two parts:
+                </para>
+                <para>
                   <orderedlist numeration="arabic">
-                    <listitem>
-                      <para>  
-                        <command>Failure</command>:  Returned if there is no
-                        <command>LS</command> at a higher scope than the 
current
-                        one, and nothing was found in the summary info-set 
that
-                        matches the query.
-                      </para>
-                    </listitem>
-                    <listitem>
-                      <para>  
-                        <command>Referral</command>: This is returned when 
there
-                        is no match other than a 
-                        <emphasis>global wildcard</emphasis>.
-                      </para>
-                      <para>
-                        <orderedlist numeration="arabic">
-                          <listitem>
-                            <para>
-                              If this <command>LS</command> is not 
participating
-                              in the highest (<emphasis>upper</emphasis>) 
scope,
-                              then it returns the leader of its current scope
-                              (or a direct referral to an instance of the
-                              next-higher scope.)  This is effectively a
-                              wildcard match saying <emphasis>I don't know 
the
-                              answer, but I know who might.</emphasis> This 
is
-                              how the Metadata registered to an
-                              <command>LS</command> in another scope (domain)
-                              is found. 
-                            </para>
-                          </listitem>
-                        </orderedlist>
-                      </para>
-                    </listitem>
-                    <listitem>
-                      <para>  
-                        <command>Success</command>: We define success to 
mean at
-                        least one matching <command>LS</command> has been
-                        returned. The <command>LS</command> must return the
-                        following:
-                      </para>
-                      <para>
-                        <orderedlist numeration="arabic">
-                          <listitem>
-                            <para>
-                              If this <command>LS</command> is an
-                              <command>HLS</command> for the discovery 
query, it
-                                   returns itself.
-                            </para>
-                          </listitem>
-                          <listitem>
-                            <para>
-                              This <command>LS</command> also returns any 
other
-                              <command>HLS</command> instances it has found 
that
-                              match. An <command>LS</command> instance will 
have
-                              summary information from other domains when it 
is
-                                   participating in a higher-level scope 
(such as
-                                   upper).
-                            </para>
-                          </listitem>
-                          <listitem>
-                            <para>
-                              Note: this is where recursive searches would be
-                              added into the discovery phase. The trail up 
the
-                              scope hierarchy would be followed by the
-                              <command>LS</command> itself instead of 
returning
-                              the leader <command>LS</command>. Ideally, this
-                              list would be iterated on by the
-                              <command>LS</command> so that only leaf
-                              <command>LS</command> instances are returned.
-                            </para>
-                          </listitem>
-                        </orderedlist>
-                      </para>
-                    </listitem>
+                  <listitem>
+                    <para>
+                      <command>Referral:</command>
+                    </para>
+                    <para>
+                      This section
+                      is used to return the list of all
+                      <command>LS</command> instances
+                      that MUST be consulted in order to find the
+                      complete set of authoratitive
+                      <command>LS</command> instances for the
+                      given discovery request. This is not
+                      necessarily the complete set since querying
+                      these can lead to additional instances to check.
+                      A client can
+                      of course terminate this iteration earlier. For
+                      instance, some clients could only want to find
+                      a single source for a given set of data, and
+                      may not care that another source exists.
+                    </para>
+                    <para>
+                      If the <command>LS</command> is not at the
+                      root scope, it MUST return the parent scope
+                      in this list. (This is the only way to find
+                      autoritative <command>LS</command> instances
+                      in other scopes.)
+                    </para>
+                    <para>
+                      The <command>LS</command> MUST return any
+                      peer <command>LS</command> instances, and
+                      any lower-scope <command>LS</command> instances
+                      that match the summary-infoset query.
+                    </para>
+                    <para>
+                      The Referral list can only be empty if this
+                      <command>LS</command> is in the root scope
+                      and there are no matching records in the
+                      summary scope.
+                    </para>
+                    <para>
+                      Note: It will be a future optimization to allow
+                      recursive searches in the discovery phase.
+                      Therefore, eventually, it
+                      will not be required for the
+                      <command>LS</command> to return the parent
+                      scope if it is willing to make the query on
+                      behalf of the client and return the results.
+                      (Presumably caching them to optimize future
+                      queries.)
+                    </para>
+                  </listitem>
+                  <listitem>
+                    <para>
+                      <command>Authoratative:</command>
+                    </para>
+                    <para>
+                      This section is used to return the list
+                      of known authoratative <command>LS</command>
+                      instances.
+                    </para>
+                    <para>
+                      If the <command>LS</command> instance
+                      is authoratative for the given query,
+                      it will return itself.
+                    </para>
+                    <para>
+                      Note: this is where recursive searches could
+                      yeild additional authoritative <command>LS</command>
+                      instances from queries it has made on behalf of
+                      the client. If all participating
+                      <command>LS</command> instances supported
+                      recursive mode discovery, this would allow the
+                      response to the client to have a completely
+                      empty referral section, and a complete
+                      list of <command>Authoratative</command>
+                      instances in this section.
+                      However, for complete discovery to work, all clients
+                      MUST support iterative queries. Recursive
+                      queries are mearly an optimization.
+                    </para>
+                  </listitem>
                   </orderedlist>
                 </para>
+                <para>
+                    If both of these sections have empty lists, that
+                    indicates that there is no data in the global
+                    <command>LS</command> network of services that matches 
the
+                    given query.
+                </para>
               </listitem>  
               <listitem>
                 <para>
-                  The client will need to iterate through the list of 
returned
-                       <command>LS</command> instances. If the 
<command>LS</command>
-                       returns itself, this <command>LS</command> can be 
used in the
-                       following Metadata query phase. If the returned
-                       <command>LS</command> is different, a discovery query 
should
-                       be made to it. 
+                    The client will need to iterate through the list of all
+                    returned referral instances to find all
+                    <command>Authoratative</command> instances. Then, the
+                    client will need to make
+                    <xref linkend="system_search_metadata_query_phase" />
+                    queries to each and every instance found in the discovery
+                    phase to find the complete set of data that can
+                    potentially match the query.
                 </para>
               </listitem>    
             </orderedlist>
@@ -1672,10 +1692,11 @@
         </para>
         
         <para>
-          Once we have found the <command>HLS</command> (or
-          <command>HLS</command>s) that contain data in the range of our
-          discovery query, we can pose Metadata Queries to each of them. The
-          results will be failure or success.  
+            Once we have found the complete list of
+            <command>Authoritative</command> <command>LS</command> instances
+            from the discovery phase, we can pose Metadata Queries to each of
+            them. The results will be failure or success.  
+            <!-- Should we be listing out the messages for this too? (jwb) 
-->
         </para>
 
       </section>
@@ -2543,6 +2564,18 @@
               <nmwg:metadata id="metadata.1">
   
                 <!-- WHAT DO I LOOK LIKE?!? -->
+                <!-- I should have syntax to query for the combination
+                of eventType and topology. Some amount of wild-carding
+                should be available as well. (i.e. I'm interested in
+                all authoritative LS servers that have information about
+                a given router.) So - I (jwb) think a complete wildcard
+                of the eventType space should be allowed. As to the
+                topology part - there is already aggregation features
+                available. So, I think we should specify that valid
+                topology elements should be used.
+                i.e. the 'network' element can be used
+                to find specific data about a given network.
+                -->
 
               </nmwg:metadata>
   
@@ -2567,12 +2600,14 @@
             <nmwg:message type="LSDiscoveryResponse">
 
               <nmwg:metadata id="metadata.1.r">
-                <!-- may be any of these: -->
-                <nmwg:eventType>success</nmwg:eventType>
 
-                <nmwg:eventType>failure</nmwg:eventType>    
+                  <!-- possible event types (make uri's) for metadata here 
are:
 
-                <nmwg:eventType>referral</nmwg:eventType>
+                  <nmwg:eventType>referral</nmwg:eventType>
+                  <nmwg:eventType>authoratative</nmwg:eventType>
+
+                  <nmwg:eventType>error-codes...</nmwg:eventType>
+
               </nmwg:metadata>
   
               <nmwg:data id="data.1.r" metadataIdRef="metadata.1.r">
@@ -2580,7 +2615,10 @@
                 <!-- for failure: -->
                 <nmwgr:datum value="some message" />
     
-                <!-- for success/referral -->
+
+                <!-- for authoratative and/or referral
+                    list out the psservice info for each LS -->
+
                 <nmwg:metadata id="metadata.6">
                  <perfsonar:subject id="subject.6">
                     <psservice:service id="service.6">