Page History

...

class SchemaProperty:
      <constructor>( name=<name-value>, 
                     type=<type-value>,
                     ...)
      .getName(): name of property (string)
      .getType(): AMQP typecode for encoding/decoding the property data
      .getAccess(): "RC"=read/create, "RW"=read/write, "RO"=read only (default)
      .isOptional(): True if this property is optional
      .getUnit(): string describing units (optional)
      .getMin(): minimum value (optional)
      .getMax(): maximum value (optional)
      .getMaxLen(): maximum length for string values (optional)
      .getDesc(): optional string description of this Property
      .getDirection(): "I"=input, "O"=output, or "IO"=input/output
                       (required for method arguments, otherwise
                       optional)
      .getSubtype(): string indicating the formal application type 
                     for the data, example: "URL", "Telephone number",
                     etc.
      .isPolled(): True if changes to the data cannot be practically 
                   monitored by an Agent.  Such a data item can only
                   be queried or polled - not published on change.
      .getReference(): if type==objId, name (str) of referenced class
                       (optional) 
      .isParentRef(): True if this property references an object in
                       which this object is in a child-parent
                       relationship.
      .getAttribute("name"): get the value of the attribute named
          "name". This method can be used to retrieve
          application-specific attributes.  "name" should start with
          the prefix "x-"
      .mapEncode(): returns a map encoding of the instance.

...

class SchemaMethod:
      <constructor>( [args=<map of name=<name-value>"name":<SchemaProperty> entries>],
                     [argsdesc=<map"description of the "name":<SchemaProperty> entries>]method")
      .getNamegetDesc(): name return human-readable description of the method.
      .getArgumentCount(): return the number of arguments
      .getArguments(): returns a copy of the map of "name":<SchemaProperty>
      .getArgument("name"): return the SchemaProperty for the parameter "name"

      .addArgument("name", SchemaProperty): adds an additional argument to
                  the parameter list.
      .mapEncode(): returns a map encoding of the SchemaMethod instance

...

class SchemaClass:
      <constructor>( package=<package-name-str>, 
                     class=<class-name-str>,
                     type=<SchemaTypeData|SchemaTypeEvent>),
                     desc=<description of schema>,
                     hash=<hash-str, format="%08x-%08x-%08x-%08x">)
      .getClassId(): return the SchemaClassId that identifies this
                      Schema instance.
      .getDesc(): return a human-readable description of this schema.
      .generateHash(): generate a hash over the body of the schema,
                       and return a string representation of the hash
                       in format  "%08x-%08x-%08x-%08x"
      .mapEncode(): returns a map encoding of the instance.


class SchemaObjectClass(SchemaClass):
      <constructor>( package=<package-name-str>, 
                     class=<class-name-str>,
                     type=<SchemaTypeData|SchemaTypeEvent>)
                     hash=<hash-str, format="%08x-%08x-%08x-%08x">,
                     _properties=<map of "name":SchemaProperty instances>,
                     _methods=<map of "name":SchemaMethod instances>)
      .getPrimaryKeyList(): return an order list of names of the
          property(s) that are used to construct the key for
          identifying unique instances of this class.

      .getPropertyCount(): return the number of data properties.
      .getProperties(): return a map of "name":<SchemaProperty>
          entries for each property in the object.
      .getProperty("name"): return the SchemaProperty associated with "name"

      .getMethodCount(): return the number of methods.
      .getMethods(): return a map of "name":<SchemaMethod> entries for
          each  method in the object.
      .getMethod("name"): return the SchemaMethod associated with the "name"

      .addProperty("name", SchemaProperty): add a new property
      .addMethod("name", SchemaMethod): add a new method.
      .appendPrimaryKey("name"): add "name" to the end of the list of
          names used to construct the primary key.


class SchemaEventClass(SchemaClass):
      <constructor>( package=<package-name-str>, 
                     class=<class-name-str>,
                     type=<SchemaTypeData|SchemaTypeEvent>)
                     hash=<hash-str, format="%08x-%08x-%08x-%08x">,
                     _properties=<map of "name":SchemaProperty instances>)
      .getPropertyCount(): return the number of data properties.
      .getProperties(): return a map of "name":<SchemaProperty>
          entries for each property in the event.
      .getProperty("name"): return the SchemaProperty associated with "name"

      .addProperty("name", SchemaProperty): add a new property.

...

class QmfData:
      <constructor>( map of "name"=<AMQP Type> pairs, _const=False )
      .isManaged(): returns False for QmfData instances.
      .isDescribed(): returns False for QmfData instances.
      .getProperty(name): return the value of the named property
                          data, returns None if named property is
                          not present. 
      .setProperty(name, value): set the value of the named
                             property data.  Creates a new property
                             if the named property does not exist.
                             Raises an exception if _const is True.
      .mapEncodegetProperties(): returnsreturn a map representation of the QmfData
 of "name"=<value> pairs for each
            instance, suitable for use by the constructor.
       of the object's properties. 
      .mapEncode(): returns a map representation of the QmfData
          instance, suitable for use by the constructor.

The map encoding of a QmfData Class is merely a map of the
"name"=<value> property pairs.

...

class QmfDescribed(QmfData):
      <constructor>( map of "name"=<AMQP Type> pairs, _const=False,
                     _schemaId=<class SchemaClassId>, SchemaCache )
      <constructor>( map encoding of a QmfDescribed instance, SchemaCache )
      .getSchemaClassId(): returns the identifier of the Schema that
                            describes the structure of the data.
      .getPrimaryKey(): return a string composed from concantenating
            the values of all properties whose names appear in the schema's
            Primary Key List.  Each value is converted to an AMQP
            string, then concantenated in the order given by the
            schema's Primary Key List.
      .getPropertiesmapEncode(): returnreturns a map representation of "name"=<value> pairs for eachthe QmfDescribed
        instance, suitable for              ofuse by the object's propertiesconstructor. 
      .mapEncode(): returns a map representation of the QmfDescribed
        instance, suitable for use by the constructor.

The map encoding of an instance of the QmfDescribed The map encoding of an instance of the QmfDescribed class:

...

class QmfManaged(QmfDescribed):
      <constructor>( map of "name"=<AMQP Type> pairs, _const=False,
                     _schemaId=<class SchemaClassId>, SchemaCache,
                     _agentId=<class AgentId> )
      <constructor>( map encoding of a QmfManaged instance, SchemaCache )
      .getObjectId(): return ObjectId for this object.

The map encoding of an instance of the QmfManaged class:

Object Identification

An instance of a managed object must be uniquely identified within the
management system. This is done by combining an object's Primary Key
with the identifier for the agent which manages the object.

Each managed object is identified by its Primary Key. The Primary Key
is constructed by concatenating the values of the object's properties
that are named in the schema's Primary Key List.

For example, assume a managed object with the following property map:

{"field1" : "foo",
 "field2" : "bar",
 "field3" : 42,
 "field4" : "baz"}

and assume the Primary Key List defined by the managed object's schema
is:

["field1", "field3"]

The Primary Key for this object would be:

"foo:42"

QMF inserts ":" between each field.

Note that these Primary Key values are not unique across Agents.
Therefore, a globally unique name for an instance of a managed object
is the concatenation of the object's name and the managing Agent's
AgentId. This unique object identifier is represented by the ObjectId class.

ObjectIds are considered hashable. That is, it is a requirement
that ObjectIds are deterministically sortable.

class ObjectId:
      <constructor>(agentid=class AgentId, 
                    key="primary key string")
      .getAgentId(): returns AgentId
      .getPrimaryKey(): returns the primary key string.
      .operators(==, !=, <, >) supported.
      .mapEncode(): returns a map representation of the ObjectId.

The map encoding of an instance of an ObjectId:

QmfEvent Class

A QMF Event is a type of QmfDescribed data that is not managed.
Events are notifications that are sent by Agents.
Unlike QmfManaged objects, events do not correspond to managed data on the
Agent. Instead, an event notifies a Console of a change in some
aspect of the system under management. For example, an event may
indicate that a threshold was exceeded, or a resource was returned.
The structure of an event is described by the SchemaEventClass. An
instance of an event is represented by the QmfEvent class.

      .getTimestamps(): returns a list of timestamps describing the
                        lifecycle of the object.  All timestamps are
                        represented by the AMQP timestamp type.
                        [0] = time of last update from Agent,
                        [1] = creation timestamp 
                        [2] = deletion timestamp, or zero if not deleted.
      .isDeleted(): True if deletion timestamp not zero.

The map encoding of an instance of the QmfManaged class:

Object Identification

An instance of a managed object must be uniquely identified within the
management system. This is done by combining an object's Primary Key
with the identifier for the agent which manages the object.

Each managed object is identified by its Primary Key. The Primary Key
is constructed by concatenating the values of the object's properties
that are named in the schema's Primary Key List.

For example, assume a managed object with the following property map:

{"field1" : "foo",
 "field2" : "bar",
 "field3" : 42,
 "field4" : "baz"}

and assume the Primary Key List defined by the managed object's schema
is:

["field1", "field3"]

The Primary Key for this object would be:

"foo:42"

QMF inserts ":" between each field.

Note that these Primary Key values are not unique across Agents.
Therefore, a globally unique name for an instance of a managed object
is the concatenation of the object's name and the managing Agent's
AgentId. This unique object identifier is represented by the ObjectId class.

ObjectIds are considered hashable. That is, it is a requirement
that ObjectIds are deterministically sortable.

class ObjectId

class QmfEvent(QmfDescribed):
      <constructor>(agentid=class timestampAgentId, agentId,
 map of "name"=<AMQP Type> pairs,
                     _const=False, _schemaId=<class SchemaClassId>,key="primary key string")
      .getAgentId(): returns AgentId
      .getPrimaryKey(): returns the primary    SchemaCache )key string.
      <constructor>.operators( map encoding of a QmfEvent instance, SchemaCache )==, !=, <, >) supported.
      .getTimestampmapEncode(): returnreturns a timestampmap indicatingrepresentation whenof the Event
                       occurred.
      .getAgentId(): return the class AgentId of this issuing agent.

The map encoding of an instance of the QmfDescribed class:

Data Management

The role of a QMF component determines how it will interact with
managment data. Therefore the QmfManaged class is subclassed
to provide an Agent specific implementation and a Console specific
implementation.

The Console application represents a managed data object by the
QmfConsoleData class. The Console has "read only" access to the
properties in the data object via this class. The
Console can also invoke the methods defined by the object via this
class. The actual data stored in this object is cached from the
Agent. In order to update the cached values, the Console invokes the
refresh() method.

Note that the refresh() and invokeMethod() methods require
communication with the remote Agent. As such, they may block. For
these two methods, the Console has the option of blocking in the call
until the call completes. Optionally, the Console can receive a
notification asynchronously when the operation is complete. See below
for more detail regarding synchronous and asynchronous API calls.

ObjectId.

The map encoding of an instance of an ObjectId:

QmfEvent Class

A QMF Event is a type of QmfDescribed data that is not managed.
Events are notifications that are sent by Agents.
Unlike QmfManaged objects, events do not correspond to managed data on the
Agent. Instead, an event notifies a Console of a change in some
aspect of the system under management. For example, an event may
indicate that a threshold was exceeded, or a resource was returned.
The structure of an event is described by the SchemaEventClass. An
instance of an event is represented by the QmfEvent class.

A timestamp - in milliseconds since midnight, January 1, 1970 UTC - is
associated with each QmfEvent instance.

class QmfEvent(QmfDescribed):
      <constructor>( timestamp, agentId, map of "name"=<AMQP Type> pairs,
                     _const=False, _schemaId=<class SchemaClassId>,
                     SchemaCache )
      <constructor>( map encoding of a QmfEvent instance, SchemaCache )
      .getTimestamp(): return a timestamp indicating when the Event
                       occurred.
      .getAgentId(): return the class AgentId of this issuing agent.

The map encoding of an instance of the QmfDescribed class:

Data Management

The role of a QMF component determines how it will interact with
managment data. Therefore the QmfManaged class is subclassed
to provide an Agent specific implementation and a Console specific
implementation.

The Console application represents a managed data object by the
QmfConsoleData class. The Console has "read only" access to the
properties in the data object via this class. The
Console can also invoke the methods defined by the object via this
class. The actual data stored in this object is cached from the
Agent. In order to update the cached values, the Console invokes the
refresh() method.

Note that the refresh() and invokeMethod() methods require
communication with the remote Agent. As such, they may block. For
these two methods, the Console has the option of blocking in the call
until the call completes. Optionally, the Console can receive a
notification asynchronously when the operation is complete. See below
for more detail regarding synchronous and asynchronous API calls.

class QmfConsoleData(QmfManaged):
      .refresh([reply-handle | timeout]): request that the Agent
                    update the value of this object's contents.
      .invokeMethod(name, inArgs{}, [[reply-handle] | [timeout]]): 
                          invoke the named method.

The Agent that manages the data represents it by the
QmfAgentData class. The Agent is responsible for managing the
values of the properties within the object, as well as
servicing the object's method calls. Unlike the Console, the Agent
has full control of the state of the object.

class QmfAgentData(QmfManaged):
      .destroy(): mark the object as deleted by setting the deletion
                  timestamp to the current time.
      .setProperty(name, value): update the value of the property.
      .incProperty(name, delta): add the delta to the property
      .decProperty(name, delta): subtract the delta from the property
      ?tbd?

Invoking Methods

A managed object's methods provide a mechanisms for a Console application to
perform a "remote procedure call" against the object. The method
actually executes on the Agent, and the result is passed back to the
Console on completion.

The value(s) returned to the Console when the method call completes
are represented by the MethodResult class. The MethodResult class
indicates whether the method call succeeded or not, and, on success,
provides access to all data returned by the method call.

Should a method call result in a failure, this failure is indicated by
the presence of a QmfData object in the MethodResult. This object is
described as an "exception", and contains a description of the reason
for the failure. There are no returned parameters when a method call
fails.

A successful method invokation is indicated by the absence of an
exception in the MethodResult. In addition, a map of returned
parameter values may be present. The structure of the returned
parameters is described by the SchemaMethod for the method.
The map contains only those parameters that the SchemaMethod marks
with an "output" direction.

class MethodResult:
      <constructor>( QmfData <exception> | <map of properties> )
      .getException(): returns exception data if method fails.
      .getArguments(): returns a map of "name"=<value> pairs
                       of all returned arguments.
      .getArgument(<name>): returns value of argument named "name".

Queries

A Query is a mechanism for interrogating the management database. A
Query represents a selector which is sent to an Agent. The Agent
applies the Query against the management database, and
returns those objects which meet the constraints described in the query.

Queries are expressed using the following map object:

{"query": {"what":<target>}
          {"where":<expression selector>}
          ...future selectors....
}

Where:

<target> indicates the desired object to match. These are
implemented as strings containing reserved words that identify the
target type. The query returns a list of instances of target types
that match the query. QMF queries will support the following values
for <target>:

<expression selector> describes a logical match expression
that is applied to the target. The expression can be built up from
the following syntax:

  binary_cmp=["eq", "ne", "lt", "le", "gt", "ge", "re_match"]
  unary_cmp=["present"]

  compare_exp = [binary_cmp, <name>, <value>] | 
                [unary_cmp, <name>]

  n_ary_logic = ["and", "or"]
  unary_logic = ["not"]

  logic_exp = [n_ary_logic, <expression>, <expression>, ... ] | 
              [unary_logic, <expression>] 

  expression = compare_exp | logic_exp

In implementation, n_ary operations may be expressed as (n+1)-element
lists in the format: <keyword>, <arg1>, <arg2>, ..., <argN>. Unary
operations may be expressed as 2-element lists in the format:
<keyword>, <arg1>

Examples:

     the conditional:
    
         "name" == "tross" or ("name" == "jross" 
                                and "address" == "1313 Spudboy Lane"
                                and "town" == "Utopia")

     would be expressed in a python-ish list as:
  
         ["or", ["eq", "name", "tross"],
                ["and", ["eq", "name", "jross"],
                        ["eq", "address", "1313 Spudboy Lane"],
                        ["eq", "town", "Utopia"]]]


     the conditional:

         !(("name" matches regular expression "?ross") and 
           (("age" property is present) or ("status" is not "sleepy")))

     would be:

        ["not", ["and", ["re_match", "name", "?ross"],
                        ["or", ["present", "age"],
                               ["ne", "status", "sleepy"]]]]

The valid set of <name> values in the expressions above is determined
by the <target> supplied in the "what" qualifier. The tables below
list the set of name strings allowed for each type of query:

a <expression selector> to apply against the
objects properties. The name strings of this <expression selector>
are the names of the object's properties.|

Example Queries

With the above syntax, QMF queries can be constructed using AMQP maps
and lists.

For example, a query for all known schema identifiers:

    {"query": {"what":"schema_id"}}

Note that the absence of a "where" clause acts as a "match all"
directive.

A query for all schema identifiers whose package names are equal to
the string "myPackage":

    {"query": {"where": ["eq", "package_name", "myPackage"],
  

class QmfConsoleData(QmfManaged):
      .getTimestamps(): returns a list of timestamps describing the
                        lifecycle of the object:
             "what":"schema_id"
           [0] = time of}
 last update from Agent, }

Query for all SchemaClass objects that match a given package and class
name:

    {"query": {"what":"schema",
               "where": ["and", ["eq",  [1] = creation timestamp 
"package_name", "myPackage"],
                             [2] = deletion timestamp["eq", or zero if not deleted.
"class_name", "someClass"]]
        .isDeleted(): True if deletion timestamp not zero.}
      .refresh([reply-handle | timeout]): request that the Agent
}

Query for an ObjectId whose primary key matches a given regular
expression:

    {"query": {"what":"object_id",
               "where": ["re_match", "primary_key", "foo*"]
     update the value of this object's contents.
   }
   .invokeMethod(name, }

Query for all QmfManaged objects from a particular schema, whose
"temperature" property is greater or equal to 50:

inArgs{}, [[reply-handle] | [timeout]]): 
    {"query": {"what":"mgt_data",
               "where": ["and", ["eq",    invoke the named method.

The Agent that manages the data represents it by the
QmfAgentData class. The Agent is responsible for managing the
values of the properties within the object, as well as
servicing the object's method calls. Unlike the Console, the Agent
has full control of the state of the object.

class QmfAgentData(QmfManaged):
"package_name", "myPackage"],
                         .destroy(): mark the object as deleted by setting the deletion
["eq", "class_name", "someClass"],
                       timestamp to the current time.
      .setProperty(name, value): update the value of the property.
["ge", "property(temperature)", 50]
                 .incProperty(name, delta): add the delta to the property]
      .decProperty(name, delta): subtract the delta from the property
  }
    ?tbd?

Invoking Methods

A managed object's methods provide a mechanisms for a Console application to
perform a "remote procedure call" against the object. The method
actually executes on the Agent, and the result is passed back to the
Console on completion.

The value(s) returned to the Console when the method call completes
are represented by the MethodResult class. The MethodResult class
indicates whether the method call succeeded or not, and, on success,
provides access to all data returned by the method call.

Should a method call result in a failure, this failure is indicated by
the presence of a QmfData object in the MethodResult. This object is
described as an "exception", and contains a description of the reason
for the failure. There are no returned parameters when a method call
fails.

A successful method invokation is indicated by the absence of an
exception in the MethodResult. In addition, a map of returned
parameter values may be present. The structure of the returned
parameters is described by the SchemaMethod for the method.
The map contains only those parameters that the SchemaMethod marks
with an "output" direction.

}

In the previous example, the agent will convert the value 50 to a
type compatible with the type given by the "temperature" property's
schema in order to do the comparison.

Query for all objects that match the given schema, which have a
property named "state" which does not match the regular expression
"$Error*", or whose "owner" property is not set to "Cartman".

    {"query": {"what":"mgt_data",
               "where": ["and", ["eq", "package_name", "myPackage"],
                                ["eq", "class_name", "someClass"],

class MethodResult:
      <constructor>( QmfData <exception> | <map of properties> )
      .getException(): returns exception data if method fails.
      .getArguments(): returns a map of "name"=<value> pairs
                       of all returned arguments.
      .getArgument(<name>): returns value of argument named "name".

Queries

A Query is a mechanism for interrogating the management database. A
Query represents a selector which is sent to an Agent. The Agent
applies the Query against the management database, and
returns those objects which meet the constraints contained in the query.

class Query:
      <constructor>(<SchemaClassId> | 
   ["or", ["not", ["re_match", "property(state)", "$Error"]],
                 <ObjectId> | 
                    <package-name>[, <class-name>])"ne", "property(owner)", "Cartman"]]
      .getSchemaClassId()
      .getObjectId()
      .getPackageName()
      .getClassName()

The target for a Query is determined by the constructor. When a Query
is created using a SchemaClassId, it will match against the
SchemaClass identified by that key. When a Query is created using an
ObjectId, it will match against the QmfObject or Event identified by
that ObjectId. When a Query is created with only a package name, it
will return all class names that belong to that package. If both the
package and class names are provided, the Query will match against the
SchemaClassId identified by the combination of those names.

 ]
              }
    }

Subscriptions

A subscription is a mechanism for monitoring management data for
changes in its state. A Console creates a subscription with an Agent
based on a Query. The Query specifies the set of management data that
is to be monitored. When the Agent detects changes to the selected
set, a notification is sent to the subscribing Console(s). A
Subscription is represented by the SubscriptionId class. A Console
must cancel the subscription when the console no longer needs to
monitor the data.

...

• the set of objects managed by that agent
• the schema that describes the objects owned by the agent
• a collection of consoles that are interfacing with the agent

...

class Agent:
      <constructor>( vendor=<vendor-string>,
                     product=<product-string>,
                     name=<name-string>,
                     class Notifier ): the vendor/product/name
            combination must uniquely identify this agent instance
            within the QMF domain.  The Notifier is used to alert the
            application to incoming method requests.
      .getAgentId(): return the agent identifier
      .setConnection( QPID Connection ): connect the agent to the AMQP cloud.
      .registerObjectClass( class SchemaObjectClass ): Register a
            schema for an object class with the agent.  The agent must
            have a registered schema for an object class before it can
            handle objects of that class.
      .registerEventClass( class SchemaEventClass ) : Register a
            schema for an event class with the agent.  The agent must
            have a registered schema for an event class before it can
            handle events of that class.
      .raiseEvent( class QmfEvent ): Cause the agent to raise the
            given event.
      .addObject( class QmfManaged, object_name=<object name str> ):
            passes a reference to an instance of a managed QMF object
            to the agent. The object name must uniquely identify this
            object among all objects known to this agent.  Returns a
            class ObjectId containing the object identifier. 
      .getWorkItemCount(): Returns the count of pending WorkItems that
            can be retrieved.
      .getNextWorkItem([timeout=0]): Obtains the next pending work
            item, or None if none available. 
      .releaseWorkItem(wi): Releases a WorkItem instance obtained by
            getNextWorkItem(). Called when the application has finished
            processing the WorkItem. 
      .methodResponse( handle=<handle from WorkItem>,
                       [output argument list],
                       result=<status code>,
                       exception=<QmfData> ): Indicate to the agent
            that the application has completed processing a method
            request. A result code of zero indicates success.  If the
            result code is non-zero, exception may optionally be set to a
            QmfData object that describes the failure.  On success, zero or
            more output arguments may be supplied as defined by the method's
            schema. 

...

11/20/2009 - First Revision
11/24/2009 - Added agent classes
12/01/2009 - Cleaned up Schema api and added map definitions.
12/04/2009 - Removed distinction between properties and statistics.
Object identification now based on Primary Key List.
Added more map definitions.
12/11/2009 - Formally define query implementation.

Todo List

• validation of described object vs its schema
• verify that schema's primary keys are present in the defined properties
• make schemas "const" once register with the agent