THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
| No Format |
|---|
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.
|
...
| No Format |
|---|
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 "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.
|
The map encoding of an instance of the SchemaObjectClass class extends the map of its parent class with elements for the following class properties.
...
| No Format |
|---|
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
|
...
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.
| No Format |
|---|
class SubscriptionId:
?tbd?
|
...
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.
...
The original QMF API defined a set of callback methods that a Console
application needed to provide in order to process asynchronous QMF
events. Each asynchonous event defined its own callback method.
The new API replaces this callback model with a work-queue approach.
All asynchronous events are represented by a WorkItem object. When
a QMF event occurs it is translated into a WorkItem object and placed
in a FIFO queue. It is left to the console application to drain
this queue as needed.
This new API does require the console application to provide a single
callback. The callback is used to notify the console application that
WorkItem object(s) are pending on the work queue. This callback is
invoked by QMF when the work queue transitions from the empty to the
non-empty state. To avoid any potential threading issues, the console
application is not allowed to call any QMF API from within the
callback context. The purpose of the callback is to allow the console
application to schedule itself to drain the work queue at the next
available opportunity.
For example, a console application may be designed using a select()
loop. The application waits in the select() for any of a number
of different descriptors to become ready. In this case, the callback
could be written to simply make one of the descriptors ready, and then
return. This would cause the application to exit the wait state, and
start processing pending events.
The callback is represented by the Notifier virtual base class. This
base class contains a single method. A console application derives a
custom handler from this class, and makes it available to the Console
object.
| No Format |
|---|
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.
|
The WorkItem class represents a single notification event that is read
from the work queue:
| No Format |
|---|
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?).
|
...
The console application maintains a list of all known remote Agents.
Each Agent is represented by the Agent class:
| No Format |
|---|
class Agent:
.get_name(): returns the identifying name string of the agent. This name is 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?
|
...
| No Format |
|---|
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
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.
|
...
The AgentExternal class must be used by those applications that
implement the external store model. The AgentExternal class extends
the Agent class by adding interfaces that notify the application when
it needs to service a request for management operations from the
agent.
| No Format |
|---|
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.
|
...
The Agent uses the same notification driven work queue model as the
Console. In the Agent case, the WorkItem supports the following set
of work types:
- METHOD_CALL
- QUERY
- SUBSCRIBE
- UNSUBSCRIBE
In the case of an internal store agent implementation, only the
METHOD_CALL work item is generated. An external store agent must support
all work item types.
| No Format |
|---|
METHOD_CALL parameters: ( name=<method name>,
[argument list],
object identifier,
user_id=<authenticated id of the user> )
|
The METHOD_CALL WorkItem describes a method call that must be serviced by the
application on behalf of this agent. On completion of the
method call, the application must invoke the agent's
methodResponse() method.
| No Format |
|---|
QUERY parameters: ( class Query,
user_id=<authenticated id of the user> )
|
The QUERY WorkItem describes a query that the application must
service. The application should call the queryResponse() method for
each object that satisfies the query. When complete, the application
must call the queryComplete() method. If a failure occurs, the
application should indicate the error to the agent by calling the
queryComplete() method with a description of the error.
...
The SUBSCRIBE WorkItem provides a query that the application should
monitor until the subscription is cancelled. On receipt of this
WorkItem, the application should call the subscriptionResponse() agent
method to acknowledge the response. Whenever the matching objects are
updated, the application should call queryResponse() for each updated
object, followed by a call to queryComplete() when done. The
subscription remains in effect until an UNSUBSCRIBE WorkItem for the
subscription is received.
...
Alerts the application that the corresponding subscription has been
cancelled. The application should no longer supply query updates
against the subscribed query.
...