THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
A subscription allows a Console application to monitor specific 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 data within the selected set, a notification is sent to the The Agent will periodically publish updates to the subscribing Console(s). The notification update contains a snapshot of the of the changed monitored data.
A subscription remains in effect for a predetermined amount of time, as configured on the Agent. Once the subscription expires, no further notifications are generated should the data changeupdates are published. A console may elect to refresh a subscription prior to its expiration. Alternatively, a Console may explicitly cancel the subscription when the data no longer needs to be monitored.
...
- AGENT_ADDED
- AGENT_DELETED
- NEW_PACKAGE
- NEW_CLASS
- OBJECT_UPDATE
- EVENT_RECEIVED
- AGENT_HEARTBEAT
- SUBSCRIBE_RESPONSE
- RESUBSCRIBESUBSCRIPTION_RESPONSE
- SUBSCRIPTION_INDICATION
...
OBJECT_UPDATE
TBD.
EVENT_RECEIVED
TBD
...
SUBSCRIBE_RESPONSE
The SUBSCRIPTIONSUBSCRIBE_RESPONSE WorkItem returns the result of a subscription request made by this Console. This WorkItem is generated when the Console's create_subscription() is called in an asychronous manner, rather than pending for the result. This WorkItem is also used to return the status of an asychronous call to the Console's refresh_subscription() method.
The get_params() method of a SUBSCRIPTIONSUBSCRIBE_RESPONSE WorkItem will return an instance of the following object:
| No Format |
|---|
class SubscriptionParamsSubscribeParams: .get_subscription_id(): If the subscription is successful, this method returns a SubscriptionId object. Should the subscription fail, this method returns None, and get_error() can be used to obtain an application-specific QmfData error object. .get_expirationpublish_dateinterval(): returns athe datetimetime objectinterval containingin theseconds timestamp (utc) whenon which the subscription Agent will publish updates will automatically expire iffor not renewed by the consolethis subscription. .get_errorlifetime(): (optional) returns anthe application-specifictime QmfDatainterval objectin indicatingseconds whyfor the subscription. The subscription will automatically expire after this interval if not renewed by the console. .get_error(): (optional) returns an application-specific QmfData object indicating why the subscription request failed. Returns None if not supported. .get_console_handle(): returns the console handle as passed to the create_subscription() call. |
The SubscriptionId object must be used when the subscription is refreshed or cancelled . The SubscriptionId - it must be passed to the Console's refresh_subscription() and cancel_subscription() methods. The value of the SubscriptionId does not change over the lifetime of the subscription.
The console handle will be provided by the Agent on each data indication event that corresponds to this subscription. It should not change for the lifetime of the subscription.
The get_handle() method returns the reply handle provided to the create_subscription get_handle() method returns the application handle provided to the create_subscription() method call. This handle is merely the handle used for the asynchronous response, it is not associated with the subscription in any other way.
Once a subscription is created, the Agent that maintains the subscription will periodically issue an initial update updates for the subscribed data. This update will contain the current values of the subscribed data, and will appear as the first SUBSCRIPTION_INDICATION WorkItem for this subscription.
...
The SUBSCRIPTION_INDICATION WorkItem signals the arrival of an update to subscribed data from the ConsoleAgent.
The get_params() method of a SUBSCRIPTION_INDICATION WorkItem will return a list of updated data objects.The get_handle() method will return the application's subscription context handle originally supplied to the Console's an instance of the following object:
| No Format |
|---|
class SubscribeIndication: .get_console_handle(): returns the console handle as passed to the create_subscription() |
...
call |
...
.
.get_data(): returns a list containing all updated data objects associated with the subscripion.
|
The get_handle() method returns None.
RESUBSCRIBE_RESPONSE
The RESUBSCRIBE_RESPONSE WorkItem is generated in response to a subscription refresh request made by this Console. This WorkItem is generated when the Console's refresh_subscription() is called in an asychronous manner, rather than pending for the result.
The get_params() method of a RESUBSCRIBE_RESPONSE WorkItem will return an instance of the following object
Local representation of a remote Agent.
The console application maintains a list of all known remote Agents. Each Agent is represented by the Agent class:
| No Format |
|---|
class AgentSubscribeParams: .get_subscription_nameid(): returnsIf the identifyingre-subscription nameis stringsuccessful, ofthis themethod agent.returns an Thisinstance nameof is used to send AMQP messages directly to this agent. the original SubscriptionId object. .is_active(): returns True if the agent is alive (heartbeats have not timed out) Should the subscription fail, this method returns None, and .invokeget_methoderror(name, inArgs{}, [[reply-handle] | [timeout]]): invoke the named method against the agent) can be used to obtain an application-specific QmfData error object. .enableget_publish_eventsinterval(): allows reception of events from this agent. returns the time interval in seconds on which the Agent will publish updates .disable_events for this subscription. .get_lifetime(): prevents reception of events from this agent returns the time interval in seconds for the subscription. The subscription will automatically expire after this interval if not renewed by the console. .destroyget_error(): releases this Agent instance. Once called, the console application should not reference this instance again(optional) returns an application-specific QmfData object indicating why the re-subscription request failed. Returns None on successful resubscribe. ?tbd? |
The Console Object.
.get_console_handle(): returns the console handle as passed to the create_subscription() call, if available.
Note: if the Agent failed the resubscribe request due to an unrecognized subscription, this call may
return None.
|
The get_handle() method returns the reply handle provided to the refresh_subscription() method call. This handle is merely the handle used for the asynchronous response, it is not associated with the subscription in any other way.
Local representation of a remote Agent.
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 used to send AMQP messages directly to this agent.
.is_active(): 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.
.enable_events(): allows reception of events from this agent.
.disable_events(): prevents reception of events from this agent.
.destroy(): releases this Agent instance. Once called, the console application should not reference this instance again.
?tbd?
|
The Console Object.
The Console The Console class is the top-level object used by a console application. All QMF console functionality is made available by this object. A console application must instatiate one of these objects.
...
| 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.
.add_connection(QPID Connection): Connect the console to the AMQP cloud.
.remove_connection(conn): Remove the AMQP connection from the console. Un-does the add_connection() 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.
.get_address():
Get the AMQP address this Console is listening to (type str).
.find_agent( 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.
.enable_agent_discovery( [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 abe queryused forto thefilter agent
and block (with default timeout override) waiting for a responsenotifications.
.enabledisable_agent_discovery( [Query] ): Called to enabledisable the asynchronousasync Agent Discovery process enabled by calling enable_agent_discovery().
Once enabled, AGENT_ADDED
.get_workitem_count(): Returns the count of pending WorkItems that can be retrieved.
and AGENT_DELETED work items can arrive on the WorkQueue. If a query is supplied, it will be used to filter agent
.get_next_workitem([timeout=0]): Obtains the next pending work item, or None if none available.
.release_workitem(wi): Releases a WorkItem instance obtained by getNextWorkItem(). Called when the application has finished
processing the notificationsWorkItem.
.disableget_agent_discoveryagents(): CalledReturns toa disablelist theof asyncavailable Agentagents Discovery process enabled by calling enable_agent_discovery().(class Agent)
.get_workitem_count(agent( name string ): ReturnsReturn the countclass ofAgent pendingfor WorkItemsthe thatnamed canagent, beif retrievedknown.
.get_next_workitempackages([timeout=0] [class Agent] ): ObtainsReturns thea nextlist pendingof workthe item,names orof Noneall ifknown none availablepackages.
.release_workitem(wi): Releases a WorkItem instance obtained by getNextWorkItem(). Called when the application has finished
If an optional Agent is provided, then
only those packages available from that processingAgent theare WorkItemreturned.
.get_agents(classes( [class Agent] ): Returns a list of SchemaClassIds for all available agents (class Agent)
Schema. If an optional Agent is provided,
.get_agent( name string ): Returnthen the classreturned AgentSchemaClassIds forare thelimited namedto agent,those ifSchema known to the given Agent.
.get_packagesschema( class SchemaClassId [, class Agent] ): ReturnsReturn a list of all available theclass namesSchemaClass ofacross all known packages.agents.
If an optional Agent is provided, then
onlyrestrict the returned schema to those packagessupported availableby from that Agent are returned.
.get_classesobjects( [class Agent] ): Returns a list of SchemaClassIds for all available Schema. If an optional Agent is provided,
_SchemaClassId= | _package=, _class= |
_object_identifier=,
then the returned SchemaClassIds are limited to those Schema known to the given Agent.
[timeout=],
.get_schema( class SchemaClassId [, class list-of-class-Agent] ): Returnperform a blocking list of all available class SchemaClass across all known agents.query for QmfConsoleObjects. Returns a list (possibly empty) of matching
If anobjects. optionalThe Agentselector isfor provided,the restrictquery themay returnedbe schemaeither:
to those supported by that Agent.
* .get_objects(class _SchemaClassId= | _package=, _class= |
- all objects whose schema match the schema identified by _SchemaClassId parameter.
_object_identifier=,
* package/class name - all objects whose schema are contained by the named package and class.
[timeout=],
* the object identified by _object_identifier
[list-of-class-Agent] ): perform aThis blockingmethod querywill forblock QmfConsoleObjects.until all Returnsknown aagents listreply, (possiblyor empty)the oftimeout matching
expires. Once the timeout expires, all
objects. The selector for the query maydata beretrieved either:
to date is returned. If a list of agents is supplied, *then classthe SchemaClassIdquery -is allsent objectsto whoseonly schema match the schema identified by _SchemaClassId parameter.
* package/class name - all objects whose schema are contained by the named package and class.
those agents.
.create_subscription( agent, class Query, console_handle [, reply_handle] [, timeout],
* the object identified by _object_identifier
[, publish_interval] [, lifetime] ): creates a subscription to the agent
This method will block untilusing allthe knowngiven agentsQuery. reply, orThe theconsole_handle timeoutis expires. Once the timeout expires, all
an application-provided handle that will accompany each subscription update
data retrieved tosend datefrom isthe returnedAgent. If Subscription aupdates listwill ofappear agentsas is supplied, thenSUBSCRIPTION_INDICATION WorkItems on the query is sent to only those agents.
Console's work queue.
The .create_subscription( agent, class Query, app_context [, reply_handle] [, timeout] ): creates a subscription to the agentpublish_interval is the requested time interval in seconds on which the Agent should publish updates. The lifetime
usingparameter is the given Query. The app_context is an application-provided handle that will accompany each subscription updaterequested time interval in seconds for which this subscription should remain in effect. Both the
sendrequested lifetime fromand the agent. Subscription updates will appear as SUBSCRIPTION_INDICATION WorkItems on the Console's work queuepublish_interval may be overridden by the Agent, as indicated in the subscription response.
This method may be called asynchronously by providing a reply_handle argument. When called asynchronously, the result
of this method call is returned in a SUBSCRIPTIONSUBSCRIBE_RESPONSE WorkItem with a handle matching the value of reply_handle.
Timeout can be used to override the console's
default reply timeout. When called synchronously, this method returns a class
SubscriptionParams object containing
SubscribeParams object containing the result of the subscription request.
.refresh_subscription( SubscriptionId [, lifetime] [,reply_handle] [, timeout] ): renews renews a subscription identified by
SubscriptionId. The Console may request a new subscription identifiedduration by SubscriptionId providing a requested lifetime. This
method may be called asynchronously by providing a reply_handle argument. When called asynchronously, the result
of this method call is returned in a SUBSCRIPTIONSUBSCRIBE_RESPONSE WorkItem. Timeout can be used to override the console's
default reply timeout. When called synchronously, this method returns a class SubscriptionParamsSubscribeParams object containing
the result of the subscription request.
.cancel_subscription( SubscriptionId ): terminates the given subscription.
|
...
| 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)
.alloc_object_id( 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.
.free_object_id( name="object name" ): indicate to QMF that the named object is no longer available to be managed.
.query_response( 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.
.query_complete( 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 query_complete(). If the query should
fail - for example, due to authentication error - the result should be set to a non-zero error code ?TBD?.
.subscription_response( handle=<handle from WorkItem>,
console_handle=<handle provided by Console for this subscription>,
subscription_handle=<agent-provided context>,
expire_time=<datetime>lifetime=<seconds>, publish_interval=<seconds>,
error=<QmfData>): Indicate the result of a SUBSCRIBE_REQUEST WorkItem.
If the subscription request or subscription refresh.
is successful, the Agent application must provide a unique subscription_handle. If replying
If replying to a sucessful subscription refresh, the Agentoriginal applicationsubscription_handle must be providesupplied. a unique subscription_handle. If replyingThe lifetime parameter should be
set to athe sucessful subscription refresh,duration of the original subscription_handle mustin beseconds. supplied. The expirepublish_timeinterval should be set to the time interval in seconds
thebetween UTCsuccessive timestamppublications whenon thethis subscription next expires. If the subscription or refresh fails, the subscription_handle
should be set to None and error may be set to an application-specific QmfData instance that describes the error. Should
a refresh request fail, the console_handle may be set to None if unknown.
.subscription_indicationindicate(subscriptionconsole_handle, [list of subscribed data]): Send a list of updated subscribed data to the Console.
.subscription_cancel(handle=<handle from WorkItem>, subscriptionconsole_handle): Acknowledge a Subscription Cancel WorkItem.
|
...
- METHOD_CALL
- QUERY
- SUBSCRIBE_REQUEST
- RESUBSCRIBE_REQUEST
- UNSUBSCRIBE_REQUEST
Note Well: 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.
...
The SUBSCRIBE_REQUEST WorkItem provides a query that the agent application should monitor must periodically publish until the subscription is cancelled or expires. On receipt of this WorkItem, the application should call the Agent::subscription_response() method to acknowledge the request. Whenever the matching objects are modifiedOn each publish interval, the application should call Agent::subscription_indicate() method for each updated
object, followed by a call to subscription_complete() when done, passing a list of the objects that satisfy the query. The subscription remains in effect until an UNSUBSCRIBE_REQUEST WorkItem for the subscription is received, or the subscription expires.
If this WorkItem is intended to refresh an existing subscription, the ::get_subscription_id() method call will return the subscription handle provided by the Agent to the original subscription request. If this WorkItem is intended to create a new subscription, then the ::get_subscription_id() will return None.
TBD.....
The METHOD_CALL WorkItem describes a method call that must be serviced by the application on behalf of this agent.
The get_params() method of a METHOD_CALL WorkItem will return an instance of the following object:
The get_params() method call of the SUBSCRIBE_REQUEST WorkItem returns an instance of the following object:
| No Format |
|---|
class SubscriptionParams:
.get_console_handle(): returns the handle that the console uses to identify this subscription.
This handle must be passed along with every published update from the Agent.
.get_query(): returns the QmfQuery object associated with the subscription. |
| No Format |
class MethodCallParams: .get_publish_nameinterval(): returns a string containing the name of the method call the requested time interval in seconds for updates. Returns zero if the Agent's default interval should be used. .get_object_idlifetime(): returns the requested identifierlifetime for the object on which this subscription. Zero if the Agent's methoddefault subscription needslifetime toshould be invokedused. Returns None iff there is no associated object (a method call against the agent itself). .get_args(): returns a map of input arguments for the method. Arguments are in "name"=<value> pairs. Returns None if no arguments are supplied. .get_user .get_user_id(): returns authenticated user id of Console if present, else None. |
The Agent application must call the AgentExternal::subscription_response() method in response to this WorkItem.
The get_handle() WorkItem method returns the reply handle which should be passed to the Agent's subscription_response() method.
RESUBSCRIBE_REQUEST
The RESUBSCRIBE_REQUEST is sent by a Console to renew an existing subscription. The Console may request a new duration for the subscription, otherwise the previous lifetime interval is repeated.
The get_params() method call of the RESUBSCRIBE_REQUEST WorkItem returns an instance of the following object:
| No Format |
|---|
class ResubscribeParams: .get_subscription_id(): returns authenticated user id of caller if present, else None. |
On completion of the method call, the application must provide the result of the call to the Agent. This is done by invoking the Agent's method_response() method. The method_response() method must be passed the handle from the METHOD_CALL WorkItem.
On successful completion of a method call, any output arguments from the method call must be passed in the out_args map parameter, in name=<value> pairs. The error parameter must be set to None.
If the method call fails the application must indicate the failure by passing a QmfData instance via the error parameter. The structure of this QmfData is application-specific, and meant to provide a description of the failure to the console.
UNSUBSCRIBE
| No Format |
|---|
UNSUBSCRIBE parameters: ( <handle associated with subscription> )
|
the subscription identifier provided by the Agent.
.get_lifetime(): returns the requested lifetime for the subscription. Zero if the previous
interval should be used.
.get_user_id(): returns the authenticated user id of the Console if present, else None.
|
The Agent application must call the AgentExternal:subscription_reponse method in response to this WorkItem.
The get_handle() WorkItem method returns the reply handle which should be passed to the Agent's subscription_reponse() method
UNSUBSCRIBE_REQUEST
The UNSUBSCRIBE_REQUEST is sent by a Console to terminate an existing subscription.
The get_params() method call returns the subscription identifier assigned by the Agent when the subscription is created.
The Agent application should terminate the given subscription if it exists, and cancel sending any further updates against itTBD
Alerts the application that the corresponding subscription has been
cancelled. The application should no longer supply query updates
against the subscribed query.