Resource Management Interface Specs Scott Jackson

Release v. 3.0.3 Brett Bode

13 MAY 2004 David Jackson

Kevin Walker

Scalable Systems Software Resource Management and Accounting Protocol (SSSRMAP) Message Format

Status of this Memo

This is a specification defining an XML message format used between Scalable Systems Software components. It is intended that this specification will continue to evolve as these interfaces are implemented and thoroughly tested by time and experience.

Abstract

This document is a specification describing a message format for the interaction of resource management and accounting software components developed as part of the Scalable Systems Software Center. The SSSRMAP Message Format defines a request-response syntax supporting both functional and object-oriented messages. The protocol is specified in XML Schema Definition. The message elements defined in this specification are intended to be framed within the Envelope and Body elements defined in the SSSRMAP Wire Protocol specification document.

Table of Contents

1 Introduction. 2

2 Conventions Used in this Document 2

2.1 Keywords. 2

2.2 XML Case Conventions. 3

2.3 Schema Definitions. 3

3 Encoding. 3

3.1 Schema Header and Namespaces. 3

3.2 Element Descriptions. 4

3.2.1 The Request Element 4

3.2.2 The Object Element 5

3.2.3 The Get Element 5

3.2.4 The Set Element 6

3.2.5 The Where Element 7

3.2.6 The Option Element 8

3.2.7 The Data Element 9

3.2.8 The File Element 9

3.2.9 The Count Element 11

3.2.10 The Response Element 11

3.2.11 The Status Element 12

3.2.12 The Value Element 12

3.2.13 The Code Element 12

3.2.14 The Message Element 13

3.3 Modified XPATH Expressions. 13

3.3.1 Sample Modified XPATH expressions. 13

3.4 Examples. 15

3.4.1 Sample Requests. 15

3.4.2 Sample Responses. 16

4 Error Reporting. 17

5 Acknowledgements. 20

6 References. 20

1 Introduction

A major objective of the Scalable Systems Software [SSS] Center is to create a scalable and modular infrastructure for resource management and accounting on terascale clusters including resource scheduling, grid-scheduling, node daemon support, comprehensive usage accounting and user interfaces emphasizing portability to terascale vendor operating systems. Existing resource management and accounting components feature disparate APIs (Application Programming Interfaces) requiring various forms of application coding to interact with other components.

This document proposes a common message format expressed in an XML request-response syntax to be considered as the foundation of a standard for communications between and among resource management and accounting software components. In this document this standard is expressed in two levels of generality. The features of the core SSSRMAP protocol common to all resource management and accounting components in general are described in the main body of this document. The aspects of the syntax specific to individual components are described in component-specific binding documents.

2 Conventions Used in this Document

2.1 Keywords

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119 [RFC2119].

2.2 XML Case Conventions

In order to enforce a consistent capitalization and naming convention across all SSSRMAP specifications “Upper Camel Case” (UCC) and “Lower Camel Case” (LCC) Capitalization styles shall be used. UCC style capitalizes the first character of each word and compounds the name. LCC style capitalizes the first character of each word except the first word. [XML_CONV][FED_XML]

1. SSSRMAP XML Schema and XML instance documents SHALL use the following conventions:

· Element names SHALL be in UCC convention (example: <UpperCamelCaseElement/>.

· Attribute names SHALL be in LCC convention (example: <UpperCamelCaseElement lowerCamelCaseAttribute=”Whatever”/>.

2. General rules for all names are:

· Acronyms SHOULD be avoided, but in cases where they are used, the capitalization SHALL remain (example: XMLSignature).

· Underscores (_), periods (.) and dashes (-) MUST NOT be used (example: use JobId instead of JOB.ID, Job_ID or job-id).

2.3 Schema Definitions

SSSRMAP Schema Definitions appear like this

In case of disagreement between the schema file and this specification, the schema file takes precedence.

3 Encoding

Encoding tells how a message is represented when exchanged. SSSRMAP data exchange messages SHALL be defined in terms of XML schema [XML_SCHEMA].

3.1 Schema Header and Namespaces

The header of the schema definition is as follows:

<?xml version="1.0" encoding="UTF-8"?>

<schema

xmlns=”http://www.w3.org/2001/XMLSchema”

xmlns:sssrmap=”http://www.scidac.org/ScalableSystems/SSSRMAP”

targetNamespace=”http://www.scidac.org/ScalableSystems/SSSRMAP”

elementFormDefault="qualified">

3.2 Element Descriptions

The following subsections describe the elements that make up SSSRMAP messages. SSSRMAP messages are transmitted in the Body and Envelope elements as described in the SSSRMAP Wire Protocol specification [WIRE_PROTOCOL].

3.2.1 The Request Element

The Request element specifies an individual request. An object-oriented request will have at least one Object element while a functional request will not have one. Depending on context, the Request element MAY contain one or more Get elements or one or more Set elements and any number of Where elements. Option, Data, File or Count elements may also be included. If a component supports it, chunking may be requested where large response data is possible. Setting the chunking attribute to “true” requests that the server break a large response into multiple chunks (each with their own envelope) so they can be processed in separate pieces.

Only an action attribute is required. All other attributes are optional.

· action – specifies the action or function to be performed

· actor – The authenticated user sending the request

· id -- uniquely maps the request to the appropriate response

· chunking -- requests that segmentation be used for large response data if set to “true”

· chunkSize -- requests that the segmentation size be no larger than the specified amount

</choice>

</choice>

</complexType>

3.2.2 The Object Element

The Object element is used in an object-oriented request to specify the object receiving the action. It is possible to have multiple Object elements in a request if an implementation supports multi-object queries.

The object class name is specified as text content. All attributes are optional.

· join – the type of join to be performed with the preceding object

o A join attribute of “inner” specifies an inner join. This is the default.

o A join attribute of “fullouter” specifies a full outer join.

o A join attribute of “leftOuter” specifies a left outer join.

o A join attribute of “rightOuter” specifies a right outer join.

o A join attribute of “cross” specifies a cross join.

o A join attribute of “union” specifies a union join.

</extension>

</simpleContent>

</complexType>

3.2.3 The Get Element

The Get element is used to indicate the data fields to be returned in a query. Get is typically used within requests with action=”query”. Multiple Get elements cause the fields to be returned in the order specified. If no Get elements are specified, the query will return a default set of fields.

Only a name attribute is required. All other attributes are optional.

· name – the name of the data field to be returned. This MUST be of the form of a “Modified XPATH expression” as described in a later section.

· op – the operator to be used to aggregate or perform an operation on the returned values.

o An op attribute of “sort” specifies an ascending sort operation

o An op attribute of “tros” specifies a descending sort operation

o An op attribute of “sum” returns the sum (only valid for numeric values)

o An op attribute of “max” returns the maximum value

o An op attribute of “min” returns the minimum value

o An op attribute of “count” returns the number of values

o An op attribute of “average” returns the average of the values

o An op attribute of “groupby” signifies that aggregates are grouped by this field

· object -- specifies the object for which you want the named attribute in a multi-object query.

· units – the units in which to return the value (if applicable)

</complexType>

</restriction>

</simpleType>

3.2.4 The Set Element

The Set element is used to specify the object data fields to be assigned values. Set is typically used within requests with action=”Create” or action=”Modify”. The use of Get or Set elements within a request are mutually exclusive.

The assignment value (to which the field is being changed) is specified as the text content. A Set element without a value may be used as an assertion flag. Only the name attribute is required. All other attributes are optional.

· name – the name of the field being assigned a value. This MUST be of the form of a “Modified XPATH expression” as described in a later section.

· op – the operator to be used in assigning a new value to the name. If an op attribute is not specified and a value is specified, the specified value will be assigned to the named field (“assign”).

o An op attribute of “assign” assigns value to the named field

o An op attribute of “inc” increments the named field by the value

o An op attribute of “dec” decrements the named field by the value

· units – the units corresponding to the value being set

</extension>

</simpleContent>

</complexType>

</restriction>

</simpleType>

3.2.5 The Where Element

A Request element may contain one or more Where elements that specify the search conditions for which objects the action is to be performed on.

The condition value (against which the field is tested) is specified as the text content. A Where element without a value may be used as a truth test. Only the name attribute is required. All other attributes are optional.