"qmf.<domain-string>.direct/<name-string>"

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

["field1", "field3"]

"foo42"

class QmfData:
      <constructor>( _values=map of "name"=<AMQP Type> pairs, 
                     _subtypes=optional map of "name"=<AMQP String> pairs for subtype information,
                     _desc=optional AMQP string containing a human-readable description for this data object.
                     _object_id=optional AMQP string that uniquely identifies this QmfData instance.
                     _schema=optional <class SchemaClass> reference
                     _const=False )
      <constructor>( _map=map representation of QmfData, as generated by mapEncode() method, 
                     _schema=optional <class SchemaClass> reference
                     _const=False)
      .isManaged(): returns True if object identifier string assigned, else False.
      .isDescribed(): returns True if schema is associated with this instance
      .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. 
      .setSubType(name, subType): set or modify the subtype associated with name.
      .get_object_id(): returns the object id string associated with the object instance, or None if no id assigned.
      .get_schema_class_id: returns the identifier of the Schema that describes the structure of the data, or None if no schema.
      .mapEncode(): returns a map representation of the QmfData instance, suitable for use by the constructor.

class QmfEvent(QmfData):
      <constructor>( timestamp, 
                     _values=map of "name"=<AMQP Type> pairs,
                     _subtypes=optional map of "name"=<AMQP String> pairs for subtype information,
                     _desc=optional AMQP string containing a human-readable description for this data object.
                     _schema=optional <class SchemaEventClass> )
       <constructor>( _map= map encoding of a QmfEvent instance, 
                     _schema=optional <class SchemaEventClass> )
      .getTimestamp(): return a timestamp indicating when the Event occurred.

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>( classId=<class SchemaClassId>, 
                     _desc=optional AMQP string containing a human-readable description for this schema)
      .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"

class SchemaObjectClass(SchemaClass):
      <constructor>( classId=<class SchemaClassId>, 
                     _desc=optional AMQP string containing a human-readable description for this schema,
                     _props=map of "name"=<SchemaProperty> instances,
                     _meths=map of "name"=<SchemaMethod> instances,
                     _id_names=(optional) ordered list of "name"s used to identify the properties whose values are used to construct the object identifier)

      .get_id_names(): return an ordered list of names of the values that are used to construct the key for identifying unique instances of this class.  Returns None if no list defined.
      .getPropertyCount(): return the count of SchemaProperty's in this instance.
      .getProperties(): return a map of "name":<SchemaProperty> entries for each value in the object.
      .getProperty("name"): return the SchemaProperty associated with "name", else None if "name" value does not exist.

      .getMethodCount(): return the count SchemaMethod's in this instance.
      .getMethods(): return a map of "name":<SchemaMethod> entries for each method associated with the object.
      .getMethod("name"): return the SchemaMethod associated with the "name", else None if "name" does not exist or is not a method.

      .addProperty("name", SchemaProperty): add a new property.
      .addMethod("name", SchemaMethod): add a new method.
      .set_id_names([name-list]): set the value of the order list of names to use when constructing the object identifier.

class SchemaEventClass(SchemaClass):
      <constructor>( classId=<class SchemaClassId>,
                     _desc=optional AMQP string containing a human-readable description for this event,
                     _props=map of "name":SchemaProperty instances)
      .getPropertyCount(): return the number of 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.

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

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

  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"]}]
                          }
                         ]
                }]
        }

class QmfQuery:
      <constructor>(_target=<target map>,
                    _predicate=(optional)<predicate map>)
      .get_target(): return target map
      .get_predicate(): return predicate map
      .evaluate(QmfData): evaluate query against a QmfData instance.  Returns True if query matches the instance, else false.
      .mapEncode(): returns a map encoding of the QmfQuery instance

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

class QmfConsoleData(QmfData):
      .get_timestamps(): 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.
      .get_create_time(): returns the creation timestamp
      .get_update_time(): returns the update timestamp
      .get_delete_time(): returns the deletion timestamp, or zero if not yet deleted.
      .is_deleted(): True if deletion timestamp not zero.

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

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:
      .get_name(): returns the identifying name string of the agent.  This name is used to send AMQP messages directly to this agent.
      .isActive(): returns True if the agent is alive (heartbeats have not timed out)
      .invoke_method(name, inArgs{}, [[reply-handle] | [timeout]]): 
                          invoke the named method against the agent.
      ?tbd?

class Console:
      <constructor>(name=<name-str>, 
                    domain=(optional) domain string for console's AMQP address,
                    notifier=<class Notifier>,
                    reply_timeout=<default for all blocking calls>,
                    agent_timeout=<default timeout for agent heartbeat>,
                    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( name string, [timeout] ): Query for the presence of a specific agent in the QMF domain. 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_ADDED and AGENT_DELETED 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( name string ): 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.

      .getObjects( _SchemaClassId= | _package=, _class= |
                    _object_identifier=,
                   [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 _object_identifier
           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( "com.aCompany.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 QmfAgentData(QmfData):
      .destroy(): mark the object as deleted by setting the deletion
                  timestamp to the current time.
      .setValue(name, value): update the value of the property.
      .incValue(name, delta): add the delta to the property
      .decValue(name, delta): subtract the delta from the property
      ?tbd?

class Agent:
      <constructor>( name=<name-string>,
                     domain=(optional) domain string for agent's AMQP address,
                     notifier=class Notifier,
                     heartbeat_interval=30,
                     max_msg_size=65535)
      .get_name(): return the name string of the agent.
      .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 QmfAgentData ):
            passes a reference to an instance of a managed QMF object
            to the agent. The object's name must uniquely identify this
            object among all objects known to this agent.
      .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>(name=<name-string>,
                    domain=(optional) domain string for agent's AMQP address,
                    notifier= class Notifier,
                    heartbeat_interval=30,
                    max_msg_size=65535)
      .allocObjectId( name="object name"): indicate to QMF that the named object is available to be managed.  Once this method returns, the agent will service requests from consoles referencing this data.
      .freeObjectId( name="object name" ): indicate to QMF that the named object is no longer available to be managed.
      .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],
                            object identifier,
                            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> )