ToS Messages

From GEANT2-JRA1 Wiki

Contents

[edit]

Introduction

This page contains supported requests to Topology Service and its responses.

Collaboration Diagram about ToS Messages
Enlarge
Collaboration Diagram about ToS Messages

Below each one of XML example there are some descriptions which fields are required and which are optional. XML fields are referenced by XPath.

[edit]

Topology Service Messages

[edit]

SetupDataDBRequest

The tipical interaction is that the client requests a database download to the server, sending a SetupDataDBRequest message: 

<nmwg:message type="SetupDataDBRequest" 
              id="message_id1"
              xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/">
      <nmwg:metadata id="metadata_id1">
              <nmwg:parameters id="param1">
		      <nmwg:parameter name="Time">now</nmwg:parameter>
		      <nmwg:parameter name="domain_id">1</nmwg:parameter>
	      </nmwg:parameters>
	      <nmwg:eventType>select</nmwg:eventType>
      </nmwg:metadata>
      <nmwg:data id="request_id1" metadataIdRef="metadata_id1"/>
</nmwg:message>
  • required: /nmwg:message[@type="SetupDataDBRequest"]
  • required: /nmwg:message[@id]
  • required: /nmwg:message/nmwg:metadata/nmwg:parameters/nmwg:parameter[@Time] MUST be now, so it's the unique value supported at this moment. In the future, it could has this value or a time.
  • required: /nmwg:message/nmwg:metadata/nmwg:parameters/nmwg:parameter[@domain_id] is the ID of the domain that we're asking for its database
  • required: /nmwg:message/nmwg:data (only one)

In the future, it will be a parameter, called TimeFrame, indicating a time interval from which any change in the topology has ocurred should be reported. This implies that reponses should have to be incremental otherwise even small changes in the topology would imply big transfers (not decided yet how to implement that in xml).

[edit]

SetupDataDBResponse

As a response for SetupDataDBRequest, a service gets SetupDataDBResponse containing the data of the database that it has asked: 

<nmwg:message id="message_id1_resp" 
              messageIdRef="message_id1"
              type="SetupDataDBResponse"
              xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/">
    <nmwg:metadata id="metadata_id1">
        <nmwg:eventType>success.tops.downloaddb</nmwg:eventType>
        <nmwg:key id="localhost.-98cd6d:10fba23cd68:-7776">
            <nmwg:parameters id="localhost.-98cd6d:10fba23cd68:-7775">
                <nmwg:parameter name="request_id" value="d64a3a81-1a8c-49b4-a21e-02bd650096b2"/>
                <nmwg:parameter name="id" value="1"/>
            </nmwg:parameters>
        </nmwg:key>
    </nmwg:metadata>
    <nmwg:data id="TOPSDownloadDBResponse" metadataIdRef="metadata_id1">
        <nmwgtopo3:node id="localhost.-98cd6d:10fba23cd68:-7fe4" xmlns:nmwgtopo3="http://ggf.org/ns/nmwg/topology/base/3.0/">
            <nmwgtopo3:interface
                id="localhost.-98cd6d:10fba23cd68:-7feb" interfaceIdRef="59620"/>
            <nmwgtopo3:hostName>example.localhost.localdomain</nmwgtopo3:hostName>
            <nmwgtopo3:name type="unspecified">example.localhost.localdomain</nmwgtopo3:name>
        </nmwgtopo3:node>
        <nmwgtopol3:link id="localhost.-98cd6d:10fba23cd68:-7b4b" xmlns:nmwgtopol3="http://ggf.org/ns/nmwg/topology/l3/3.0/">
            <nmwgtopol3:name>192.168.3.38/0</nmwgtopol3:name>
            <nmwgtopol3:interface
                id="localhost.-98cd6d:10fba23cd68:-7b4c" interfaceIdRef="59477">
                <nmwgtopol3:type>unused</nmwgtopol3:type>
                <nmwgtopol3:capacity>0</nmwgtopol3:capacity>
                <nmwgtopol3:netmask>192.168.3.38/32</nmwgtopol3:netmask>
            </nmwgtopol3:interface>
        </nmwgtopol3:link>
    </nmwg:data>
</nmwg:message>
  • required: /nmwg:message[@type="SetupDataDBResponse"]
  • required: /nmwg:message[@id]
  • required: /nmwg:message[@messageIdRef] (contains reference to request id)
  • required: /nmwg:message/nmwg:metadata/nmwg:eventType (contains result code, see Result codes and Result code hierarchy)
  • required: /nmwg:message/nmwg:metadata/nmwg:key/nmwg:parameters/nmwg:parameter[@id] is the ID of the domain which we've asked for
  • required: /nmwg:message/nmwg:metadata/nmwg:key/nmwg:parameters/nmwg:parameter[@request_id] is a key representing the request message
  • required: /nmwg:message/nmwg:data[@id='TOPSDownloadDBResponse'] contains the database data
[edit]

SetupDataRequest

Warning: this message is not developed yet

This interaction is done in order to inform the client when topology changes. In order to implement it, the client must include a ttl (time to live) parameter in the message SetupDataDBRequest shown above. This process can be seen as a registration. Whenever a topology change happens that applies to the request the client made in that message, the server will send the whole topology (updated) to the client. 

<nmwg:message id="message_id3" 
              messageIdRef="message_id1"
	      type="SetupDataRequest"		   
	      xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/" 
	      xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/" 
	      xmlns:select="http://ggf.org/ns/nmwg/ops/select/2.0/">
    <nmwg:metadata id="metadata_id1">
          <nmwg:key>
                <nmwg:parameters id="param1">
                      <nmwg:parameter name="request_id" value="d64a3a81-1a8c-49b4-a21e-02bd650096b2"/>
                </nmwg:parameters>
          </nmwg:key>
    </nmwg:metadata>
    <nmwg:data id="localhost.localdomain.71c64c59:10d7d8f60f2:-6197" metadataIdRef="metadata_id1">
        <nmwgtopo3:node id="localhost.-98cd6d:10fba23cd68:-7fe4" xmlns:nmwgtopo3="http://ggf.org/ns/nmwg/topology/base/3.0/">
            <nmwgtopo3:interface
                id="localhost.-98cd6d:10fba23cd68:-7feb" interfaceIdRef="59620"/>
            <nmwgtopo3:hostName>example.localhost.localdomain</nmwgtopo3:hostName>
            <nmwgtopo3:name type="unspecified">example.localhost.localdomain</nmwgtopo3:name>
        </nmwgtopo3:node>
        <nmwgtopol3:link id="localhost.-98cd6d:10fba23cd68:-7b4b" xmlns:nmwgtopol3="http://ggf.org/ns/nmwg/topology/l3/3.0/">
            <nmwgtopol3:name>192.168.3.38/0</nmwgtopol3:name>
            <nmwgtopol3:interface
                id="localhost.-98cd6d:10fba23cd68:-7b4c" interfaceIdRef="59477">
                <nmwgtopol3:type>unused</nmwgtopol3:type>
                <nmwgtopol3:capacity>0</nmwgtopol3:capacity>
                <nmwgtopol3:netmask>192.168.3.38/32</nmwgtopol3:netmask>
            </nmwgtopol3:interface>
        </nmwgtopol3:link>
    </nmwg:data>
</nmwg:message>

The server notifies the client a topology change that the client was interested in and sends the updated result as if the query issued a message like the first SetupDataDBRequest shown above. This notification is sent as soon as possible when the change happens.

  • The server includes a response with the same key and the topology in the same way as in message SetupDataDBResponse
  • It doesn't include a result code or a ttl

This message is sent to the notifier URL specified in message SetupDataDBRequest. Basic management of notifications failures is handled. Following cases have been taken into account:

  • The client doesn't answer/is dead/communication cannot be established
  • The client configuration has changed the notifier URL and no longer accepts notifications in previous notifier URL or returns an error code.

The following rules apply:

  • If the topology server fails to notify the client for 3 topology changes all requests of that client are expired.
  • A successful message develivery resets this counter.
[edit]

SetupDataResponse

Client replies to message SetupDataRequest, optionally the client can include updated value for the ttl that the client specified in the message SetupDataDBRequest. 

<nmwg:message id="message_id4" 
              messageIdRef="message_id3"
	      type="SetupDataResponse"		   
	      xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/" 
	      xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/" 
	      xmlns:select="http://ggf.org/ns/nmwg/ops/select/2.0/">
    <nmwg:metadata id="metadata_id1">
          <nmwg:key>
                <nmwg:parameters id="param1">
                      <nmwg:parameter name="request_id" value="d64a3a81-1a8c-49b4-a21e-02bd650096b2"/>
		      <nmwg:parameter name="ttl">3600</nmwg:parameter>
                </nmwg:parameters>
          </nmwg:key>
	  <nmwg:eventType>success.tops.downloaddb</nmwg:eventType>
    </nmwg:metadata>
</nmwg:message>

The client includes the following information:

  • key, to uniquely identify the initial request
  • return code of the notification
  • ttl (optional). The client is guaranteed that it can use a ttl value as large as the one confirmed in message [2].
[edit]

SetupDataUpdateTTLRequest

Warning: this message is not developed yet

The client requests an update of the validity of a previous request. This update can be to extend the time to live or to expire it (a de-registration of the request). 

<nmwg:message id="message_id5" 
              messageIdRef="message_id1"
	      type="SetupDataUpdateTTLRequest"		   
	      xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/" 
	      xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/" 
	      xmlns:select="http://ggf.org/ns/nmwg/ops/select/2.0/">
    <nmwg:metadata id="metadata_id1">
          <nmwg:key>
                <nmwg:parameters id="param1">
                      <nmwg:parameter name="request_id" value="d64a3a81-1a8c-49b4-a21e-02bd650096b2"/>
		      <nmwg:parameter name="ttl">0</nmwg:parameter>
                </nmwg:parameters>
          </nmwg:key>
	  <nmwg:eventType>select</nmwg:eventType>
    </nmwg:metadata>
    <nmwg:data id="data1" metadataIdRef="metadata_id1"/>
</nmwg:message>

The update request includes the following information

  • It includes a ttl, value of 0 means timeout or deregistration
[edit]

SetupDataUpdateTTLResponse

The server sends a confirmation for client's request for update the time to live for update (re-registration) or timeout (de-registration) of the query specified in the key. 

<nmwg:message id="message_id4" 
              messageIdRef="message_id3"
	      type="SetupDataUpdateTTLResponse"		   
	      xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/" 
	      xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/" 
	      xmlns:select="http://ggf.org/ns/nmwg/ops/select/2.0/">
    <nmwg:metadata id="metadata_id1">
          <nmwg:key>
                <nmwg:parameters id="param1">
                      <nmwg:parameter name="request_id" value="d64a3a81-1a8c-49b4-a21e-02bd650096b2"/>
		      <nmwg:parameter name="ttl">3600</nmwg:parameter>
                </nmwg:parameters>
          </nmwg:key>
	  <nmwg:eventType>success.tops.ttl_update</nmwg:eventType>
    </nmwg:metadata>
</nmwg:message>

The response includes the following information:

  • It includes the key
  • It includes the result code of the operation
Retrieved from "http://wiki.perfsonar.net/jra1-wiki/index.php/ToS_Messages"
Personal tools