SchemaTypeData:
SchemaTypeEvent:

class SchemaClassId:
      <constructor>( package=<package-name-str>, 
                     class=<class-name-str>,
                     type=<SchemaTypeData|SchemaTypeEvent>)
                     hash=<hash-str, format="%08x-%08x-%08x-%08x">, 
      .getPackageName(): returns <package-name-str>
      .getClassName(): returns <class-name-str>
      .getHashString(): returns <hash-str, "%08x-%08x-%08x-%08x">
      .getType(): returns SchemaTypeObject or SchemaTypeEvent
      .mapEncode(): returns a map encoding of the instance.

class SchemaProperty:
      <constructor>( name=<name-value>, 
                     type=<type-value>,
                     ...)
      .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":<SchemaProperty> entries>],
                     desc="description of the method")
      .getDesc(): 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(QmfData):
      <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.
      .generateHash(): generate a hash over the body of the schema, and return a string representation of the hash in format  "%08x-%08x-%08x-%08x"


The map encoding of an instance of the SchemaClass class extends the map of its parent class with elements for the following class properties.

||Index||Optional||Type||Description||
|"_schema_id"|N|map|Map containing the SchemaClassId for this object.|



class SchemaObjectClass(SchemaClass):
      <constructor>( package=<package-name-str>, 
                     class=<class-name-str>,
                     type=<SchemaTypeData|SchemaTypeEvent>)
                     hash=<hash-str, format="%08x-%08x-%08x-%08x">,
                     map of "name":SchemaProperty|SchemaMethod instances)
      .getPrimaryKeyList(): return an ordered list of names of the property(s) that are used to construct the key for identifying unique instances of this class.
      .getPropertyCount(): return the count of the values that are of type SchemaProperty.
      .getProperties(): return a map of "name":<SchemaProperty> entries for each value in the object that is of type SchemaProperty.
      .getProperty("name"): return the SchemaProperty associated with "name", else None if "name" does not exist or is not a property value.

      .getMethodCount(): return the count of the values that are of type SchemaMethod.
      .getMethods(): return a map of "name":<SchemaMethod> entries for each value in the object that is of type SchemaMethod.
      .getMethod("name"): return the SchemaMethod associated with the "name", else None if "name" does not exist or is not a method value.

      .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.

The map encoding of an instance of the SchemaObjectClass class extends the map of its parent class with elements for the following class properties.

||Index||Optional||Type||Description||
|"_primary_key"|Y|list|Order list of property names used to construct the primary key for objects defined by this schema|




class SchemaEventClass(SchemaClass):
      <constructor>( package=<package-name-str>, 
                     class=<class-name-str>,
                     type=<SchemaTypeData|SchemaTypeEvent>)
                     hash=<hash-str, format="%08x-%08x-%08x-%08x">,
                     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, 
                     optional map of "name"=<AMQP String> pairs for subtype information,
                     optional AMQP string containing a human-readable description for this data object.
                     _const=False )
      .isManaged(): returns False for QmfData instances.
      .isDescribed(): returns False for QmfData instances.
      .getDesc(): return the description of this object if present, else None
      .getValue(name): return the value of the named data item, returns None if named property is not present.
      .hasValue(name): returns True if the named data item is present in the map, else False.
      .setValue(name, value, subType=None): set the value of the named data item. Creates a new item if the named data does not exist. Raises an exception if _const is True. 
      .getSubType(name): returns the sub type description string, else None if not present.
      .mapEncode(): returns a map representation of the QmfData instance, suitable for use by the constructor.

class QmfDescribed(QmfData):
      <constructor>( map of "name"=<AMQP Type> pairs, 
                     optional map of "name"=<AMQP String> pairs for subtype information,
                     _const=False,
                     _schema=<class SchemaObjectClass>)
      <constructor>( map encoding of a QmfDescribed instance, _schema )
      .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.
      .mapEncode(): returns a map representation of the QmfDescribed
        instance, suitable for use by the constructor.

class QmfManaged(QmfDescribed):
      <constructor>( map of "name"=<AMQP Type> pairs, 
                     optional map of "name"=<AMQP String> pairs for subtype information,
                     _const=False,
                     _schema=<class SchemaObjectClass>,
                     _agentId=<class AgentId> )
      <constructor>( map encoding of a QmfManaged instance, SchemaCache )
      .getObjectId(): return ObjectId for this object.
      .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.
      .getCreateTime(): returns the creation timestamp
      .getUpdateTime(): returns the update timestamp
      .getDeleteTime(): returns the deletion timestamp, or zero if not yet deleted.
      .isDeleted(): True if deletion timestamp not zero.

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

["field1", "field3"]

"foo:42"

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.

class QmfEvent(QmfDescribed):
      <constructor>( timestamp, 
                     agentId, 
                     map of "name"=<AMQP Type> pairs,
                     optional map of "name"=<AMQP String> pairs for subtype information,
                     _const=False, 
                     _schema=<class SchemaEventClass> )
      <constructor>( map encoding of a QmfEvent instance, _schema )
      .getTimestamp(): return a timestamp indicating when the Event occurred.
      .getAgentId(): return the class AgentId of the agent that issued the event.

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.

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?

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".

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

{"<target name string>": <optional map of target qualifiers>}

    {"_package_name": name of the package defining the objects (string),
     "_class_name": name of the class defining the objects (string)}

    {"what": {"object_id": {"_package_name": "myPackage,
                            "_class_name": "myClass"}
             }
    }

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

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

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

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

  expression = compare_exp | logic_exp

    {operator: [operand1, operand2, ...]}

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

     would be expressed in a python map 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": [{"exists": ["age"]},
                                  {"ne": ["status", "sleepy"]}]
                          }
                         ]
                }]
        }

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

    {"query": {"where": {"eq": ["_package_name", "myPackage"]},
               "what": {"schema_id": None}
              }
    }

    {"query": {"what": {"schema": None}
               "where": {"and": [{"eq": ["_package_name", "myPackage"]},
                                 {"eq": ["_class_name", "someClass"]}]}
              }
    }

    {"query": {"what": {"object_id": {"_package_name": "myPackage,
                                      "_class_name": "myClass"}},
               "where": {"re_match": ["_primary_key", "foo*"]}
              }
    }

    {"query": {"what": {"object": {"_package_name": "aPackage,
                                   "_class_name": "someClass"}},
               "where": {"ge": ["temperature", 50]}
              }
    }

    {"query": {"what": {"object": {"_package_name": "aPackage,
                                   "_class_name": "someClass"}},
               "where": {"or": [{"not": [{"re_match": ["state", "$Error"]}]},
                                {"ne": ["owner", "Cartman"]}]
                        }
              }
    }

class SubscriptionId:
      ?tbd?

class AgentId:
      <constructor>( vendor, product, name )
      .getVendor(): return the vendor name string
      .getProduct(): return the product name string
      .getName(): return agent component name string

class Notifier:
    .indication():  Called when the internal work queue becomes
    non-empty due to the arrival of one or more WorkItems. This method
    will be called by the internal QMF management thread - it is
    illegal to invoke any QMF APIs from within this callback.  The
    purpose of this callback is to indicate that the application
    should schedule itself to process the work items.  

class WorkItem:
    #
    # Enumeration of the types of WorkItems produced by the Console
    #
    AGENT_ADDED = 1
    AGENT_DELETED = 2
    NEW_PACKAGE = 3
    NEW_CLASS = 4
    OBJECT_UPDATE = 5
    EVENT_RECEIVED = 7
    AGENT_HEARTBEAT = 8

    .getType(): Identifies the type of work item by returning one of
    the above type codes. 

    .getHandle(): return the handle for an asynchronous operation, if present.

    .getParams(): Returns the data payload of the work item.  The type
    of this object is determined by the type of the workitem (?TBD?). 

class Agent:
      .getAgentId(): returns the AgentId
      .isActive(): returns True if the agent is alive (heartbeats have
      not timed out)
      ?tbd?

class Console:
      <constructor>(name=<name-str>, 
                    notifier=<class Notifier>,
                    timeout=<default for all blocking calls>,
                    subscription_duration=<default lifetime of a subscription>)

      .destroy(timeout=None): Must be called to release Console's resources.

      .addConnection(QPID Connection): Connect the console to the AMQP cloud.

      .removeConnection(conn): Remove the AMQP connection from the
          console.  Un-does the addConnection() operation, and
          releases any agents associated with the connection.  All
          blocking methods are unblocked and given a failure status.
          All outstanding asynchronous operations are cancelled
          without producing WorkItems.

      .getAddress():
          Get the AMQP address this Console is listening to (type str).

      .findAgent( class AgentId, [timeout] ): Query for the
      presence of a specific agent. Returns a class Agent if the agent
      is present.  If the agent is not already known to the console,
      this call will send a query for the agent and block (with default
      timeout override) waiting for a response.

      .enableAgentDiscovery( [Query] ): Called to enable the asynchronous
          Agent Discovery process. Once enabled, AGENT_ADD work items
          can arrive on the WorkQueue.  If a query is supplied, it
          will be used to filter agent notifications.

      .disableAgentDiscovery(): Called to disable the async Agent
      Discovery process enabled by calling enableAgentDiscovery().  

      .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. 

      .getAgents(): Returns a list of available agents (class Agent)

      .getAgent( class AgentId ): Return the class Agent for the
          named agent, if known. 

      .getPackages( [class Agent] ): Returns a list of the names of
          all known packages.  If an optional Agent is provided, then
          only those packages available from that Agent are returned.

      .getClasses( [class Agent] ):  Returns a list of SchemaClassIds
          for all available Schema.  If an optional Agent is provided,
          then the returned SchemaClassIds are limited to those
          Schema known to the given Agent.

      .getSchema( class SchemaClassId [, class Agent]): Return a list
          of all available class SchemaClass across all known agents.
          If an optional Agent is provided, restrict the returned
          schema to those supported by that Agent.

      .makeObject( SchemaClassId, **kwargs ): returns an uninitialized
      instance of a QmfDescribed data object.

      .getObjects( _SchemaClassId= | _package=, _class= |
                    _objectId=,
                   [timeout=],
                   [list-of-class-Agent] ): perform a blocking query
           for QmfConsoleObjects.  Returns a list (possibly empty) of matching
           objects. The selector for the query may be either:
           * class SchemaClassId - all objects whose schema match the
                    schema identified by _SchemaClassId parameter.
           * package/class name - all objects whose schema are
                    contained by the named package and class.
           * the object identified by _objectId
           This method will block until all known agents reply, or the
                    timeout expires. Once the timeout expires, all
                    data retrieved to date is returned.  
           If a list of agents is supplied, then the query is sent to
                    only those agents.  


      .createSubscription( class Query [, duration=<secs> [, list of agents] ): creates a
            subscription using the given Query.  If a list of agents
            is provided, the Query will apply only to those agents.
            Otherwise it will apply to all active agents, including
            those discovered during the lifetime of the subscription.
            The duration argument can be used to override the
            console's default subscription lifetime for this
            subscription.  Returns a class SubscriptionId.

      .refreshSubscription( SubscriptionId [, duration=<secs>] ):
      (re)activates a subscription.  Uses the console default duration
      unless the duration is explicitly specified.

      .cancelSubscription( SubscriptionId ): terminates the
      subscription. 

logging.info( "Starting Connection" )
conn = Connection("localhost")
conn.connect()

logging.info( "Starting Console" )
myConsole = Console()
myConsole.addConnection( conn )

logging.info( "Finding Agent" )
myAgent = myConsole.findAgent( AgentId( "aCompany.com", "Examples", "anAgent" ), _timeout=5 )

if myAgent:
   logging.info( "Agent Found: %s" % myAgent )
else:
   logging.info( "No Agent Found!")

logging.info( "Removing connection" )
myConsole.removeConnection( conn )

logging.info( "Destroying console:" )
myConsole.destroy( _timeout=10 )

class MyNotifier(Notifier):
    def __init__(self, context):
        self._myContext = context
        self.WorkAvailable = False

    def indication(self):
        print("Indication received! context=%d" % self._myContext)
        self.WorkAvailable = True

noteMe = MyNotifier( 668 )

logging.info( "Starting Connection" )
conn = Connection("localhost")
conn.connect()

myConsole = Console(notifier=noteMe)
myConsole.addConnection( conn )

myConsole.enableAgentDiscovery()
logging.info("Waiting...")


while not noteMe.WorkAvailable:
    print("No work yet...sleeping!")
    time.sleep(1)


print("Work available = %d items!" % myConsole.getWorkItemCount())
wi = myConsole.getNextWorkitem(timeout=0)
while wi:
    print("work item %d:%s" % (wi.getType(), str(wi.getParams())))
    wi = myConsole.getNextWorkitem(timeout=0)


logging.info( "Removing connection" )
myConsole.remove_connection( conn )

logging.info( "Destroying console:" )
myConsole.destroy( 10 )

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. 

class AgentExternal(Agent):
      <constructor>(vendor, product, name, class Notifier)
      .allocObjectId( name="object name"): create a class ObjectId
            using the object name provided.  The object name must be
            unique across all objects known to this agent.  Returns a
            class ObjectId.  Once this method returns, the agent will
            service requests from consoles referencing this ObjectId.
      .freeObjectId( class ObjectId ): releases the ObjectId
            previously allocated by allocObjectId() method.  Once
            this call is complete, the agent will reject all further
            requests from consoles referencing this ObjectId.
      .queryResponse( handle=<handle from WorkItem>,
                      class QmfAgentObject): send a managed object in 
            reply to a received query. Note that ownership of the
            object instance is returned to the caller on return from
            this call. 
      .queryComplete( handle=<handle from WorkItem>, 
                      result=<status code> ):  Indicate to the agent
            that the application has completed processing a query request.
            Zero or more calls to the queryResponse() method should be
            invoked before calling queryComplete().  If the query should
            fail - for example, due to authentication error - the result
            should be set to a non-zero error code ?TBD?.
      .subscriptionResponse( handle=<handle from WorkItem>,
                             result=<status code>,
                             subscription_handle=<application context>):
            Indicate the status of a subscription request.  If result
            is zero, the subscription is accepted by the application,
            and an subscription handle is provided.  This handle must
            be passed to the application when the agent unsubscribes.

  METHOD_CALL parameters: ( name=<method name>, 
                            [argument list],
                            class ObjectId,
                            user_id=<authenticated id of the user> )

  QUERY parameters: ( class Query, 
                      user_id=<authenticated id of the user> )

  SUBSCRIBE parameters: ( class Query, 
                          user_id=<authenticated id of the user> )

  UNSUBSCRIBE parameters: ( <handle associated with subscription> )