Documents

• Domain interface design powerpoint presentation

Overview of operation

This is an overview of the messages that pass between the ADIs and the actions the ADIs take

1. The client generates a MeasurementRequest containing

   characteristic

   A characteristic to measure, and/or

   tool

   One or more tools, with a rank indicating preference

   source

   sink

   The name of the source and sink routers

   credential

   Any credentials that can be used to authenticate/authorise the client

   and submits that the the RequestInterface of the Initiator ADI.
2. The initiator ADI does the following:
   • AAA based upon the credentials, calling host, local policy and so on
   • Resolve the initiator router to a PMC name, and add that to the MeasurementRequest.
   • If a characteristic is indicated but no tools are, add all the locally available tools that can measure that characteristic
   • Remove any tools that the PMC does not have
   • Add any credentials required
3. The initiator ADI then contacts the ResponseInterface of the acceptor ADI and transfers the MeasurementRequest
4. The acceptor ADI does the following:
   • AAA based upon the credentials, calling host, local policy and so on
   • Resolve the acceptor router to a PMC name, and add that to the MeasurementRequest.
   • If a characteristic is indicated but no tools are, add all the locally available tools that can measure that characteristic
   • Remove any tools that the PMC does not have
   • Add any credentials required (for example, the "capability" token)
   The MeasurementRequest is then returned to the initiator ADI.
5. The initiator ADI then contacts the PMC to schedule the measurement
6. Once the measurement is complete, the ADI returns a MeasurementReference to the client

In the event of any errors or problems, either ADI may return a SOAP fault indicating the nature of the problem. The initiator ADI will return the SOAP fault to the client; the acceptor ADI will return the fault to the initiator ADI, which will then pass the fault on to the client. The following scenarios are predicted:

No ability to measure a characteristic

In this case, a CharacteristicUnavailableException is thrown

None of the requested tools are suitable

A ToolUnavailableException is thrown

The measurement has been scheduled, but is expected to take some time

A TimeUnavailableException?? is thrown, with an indication of the next time the client should ask again

The measurement cannot be scheduled for the requested time ("now" in piPES)

A TimeUnavailableException is thrown, with an indication of the next time the client should ask again

AAA policy disallows a measurement

Throw a PermissionDeniedException

Something is wrong with the request

Throw a MalformedRequestException (if the request wasn't valid XML according to the schema, something else will be thrown by the web services engine)

Schemata

The following are WSDL/XSD definitions for various possible parts of an ADI.

These definitions are hopefully flexible enough to allow intercommunication between different architectures. Feel free to post comments.

Interface definitions

RequestInterface

This is the public interface to the ADI/PMC/PMP system

ResponseInterface

This is an interface used by ADIs to communicate with each other.

Types for the interfaces

Faults

The faults thrown by the Request and Response Interfaces. These correspond to "no" or "nearly no" answers from the interfaces, when answering a request for a measurement to be made. The "nearly no" answer is the TimeUnavailableException, which corresponds to an inability to make a reservation at the particular time, but gives a time at which it could be made.

MeasurementRequest

A measurement request. This type is used by both interfaces, and the generated java is passed around within the Interfaces, too.

MeasurementReference

This is a reference to a measurement, as returned by the Request Interface. It has one element which is of type anyType, so that any reference to any data may be used.

Interface descriptions

The Request- and ResponseInterface methods called "submitRequest" takes a single parameter of type MeasurementRequest. RequestInterface.submitRequest returns a MeasurementReference object. ResponseInterface.submitRequest returns a modified MeasurementRequest. Both methods can also throw SOAP faults instead of returning normally to indicate a problem: PermissionDeniedException, MalformedRequestException, ToolUnavailableException, CharacteristicUnavailableException or TimeUnavailableException.

The MeasurementRequest consists of the following elements:

characteristic

An optional element indicating the NMWG name of a characteristic to measure. It is of type CharacteristicSpec, which has one attribute called "name"

tool

Zero or more elements indicating the tools to use and a rank indicating the preferred tool to use. These are of type ToolSpec, which have two attributes: the "name" of the tool, and a "rank", which is an integer value with a more positive value indicating lower preference.

source and sink

At least one of each, indicating the source and sink of the requested measurement. These are likely to be the names of the routers with which a PMP is associated. They have an attribute called "host" which is the hostname of the PMP. Internally and between ADIs, a second attribute called "type" can be added, that indicates that the host is, say, a PMP, router, PMC etc.

when

An element indicating the time or times at which the measurement should be made. It consists of either an attribute called "now" which is a boolean, with true indicating that the measurement should be made as soon as possible, or time or crontab elements. The time element contains a time with the standard SOAP type dateTime, while the crontab element is a structure mimicking the crontab time specification format

credential

An element of type "any" (i.e. it can be any type). This is used to contain any credentials that may be useful when performing AAA for the measurement.

Some examples of questions and responses: Request, Error response (permission denied), Reference response.

Further types

These types can be used in the anyType elements of MeasurementRequest and MeasurementReference.

SQLReference

This is a reference to a mySQL record or records. It may be used in the MeasurementReference reference element.

Implementation

Here described is an implementation of the ADI.

RequestController

The RequestInterface and ResponseInterface both take very similar inputs, and respond with a very similar output. Therefore they are both implemented using the same class - a RequestController. The RequestController passes a MeasurementRequest to various handlers that implement the Check interface, see image. Each Check can modify the MeasurementRequest and return the modified object, return null (to indicate no change) or throw an Exception. Finally, the MeasurementRequest can be passed to an object implementing the Distributor interface, which should attempt to make the measurement or should throw an Exception.

Configuration

The RequestController takes its configuration from a Properties object passed to it at instantiation time. This Properties object is filled by the appropriate interface from a general configuration file, plus system properties. All of the RequestController's configuration should be stored in the Properties.

The Checks and Distributor to use is configured by specifying a class that implements CheckFactory or DistributorFactory interfaces, respectively. Each Factory is passed Properties object passed to the RequestController; any configuration of the Checks or Distributor can be added to the main configuration file as long as the properties used don't conflict with any other components' options.

RequestController Properties

The properties used to configure a RequestController. Each RequestController is given an "id" by the object that instantiates it; see RequestInterface and ResponseInterface documentation to see what "id"s the RequestControllers will receive.

requestController.<id>.checks=<check>[,<check>...]

A list of checks to perform in the order that they will be performed. Each name should be a valid Property name, as it will be used to identify properties related to it.

requestController.<id>.check.<check>.factory=<factory>

The classname of the CheckFactory used to instantiate each Check

requestController.<id>.distributor.factory

The classname of the factory used to instantiate the Distributor

The Check- and DistributorFactories can be individually configured using properties prefixed with:

• requestController.<id>.check.<check> and
• requestController.<id>.distributor,

respectively.

Two convenience factories are provided that instantiate a Check or Distributor without any extra configuration. These are NamedCheckFactory and NamedDistributorFactory. These factories take an extra configuration option

requestController.<id>.check.<check>.class

The classname of the Check to instantiate

requestController.<id>.distributor.class

The classname of the Distributor to instantiate