Apama Documentation : Developing Apama Applications : Developing Apama Applications in Event Modeler : Using Standard Blocks : The Utility blocks : Status v2.0
Status v2.0
The Status block obtains the status of an object managed by a service monitor. For example, you can use the Status block to obtain the status of a market, a connection, or some other component. The objects for which you can obtain status and the meaning of various parameters depend on the service monitor providing the status.
Usage notes
You use the Status block with the com.apama.statusreport.* events, which are defined in StatusSupport.mon in the monitors directory of your Apama installation directory. There are four com.apama.statusreport event types:
*SubscribeStatus events — the Status block sends a SubscribeStatus event to a service monitor to initiate receipt of status events from that service. A SubscribeStatus event identifies the ID of the service you want to receive status from, the object you want status for, the sub-service ID, if there is one, to receive status from, and the connection to use if there is a choice.
In a SubscribeStatus event, when the service ID is an empty string, the Status block is initiating a status subscription with each service monitor that is listening for SubscribeStatus events that have an empty string for the service ID. In this case, you should expect to receive status events from more than one service.
*UnsubscribeStatus — the Status block sends an UnsubscribeStatus event to a service monitor to terminate receiving status from that service. An UnsubscribeStatus event identifies the same information as a SubscribeStatus event.
*Status — a subscribed service sends a Status event to the Status block to provide the status information. A service sends a Status event as the result of a new subscription and whenever there is a change in status. In addition to identifying the service that the information is from and the object that the information is for, the Status event contains a string that contains a status description, a sequence that contains one or more key words, a Boolean indication of whether the object is in a state in which it can be used, and a dictionary that contains any other information that the service can provide.
*StatusError — a subscribed service sends a StatusError event to the Status block when it cannot provide status information. In addition to identifying the service that the event is from and the object that the event pertains to, the StatusError event contains a free-form string that describes the problem, and a Boolean indication of whether the status subscription was terminated.
The Status block uses these events to interface with any service monitor that supports the com.apama.statusreport interface. In other words, these events form the message exchange protocol (MEP) between the Status block in your Apama application and service monitors. For example, a service monitor might be the part of your adapter that makes the features of the adapter available to your Apama application.
Parameters
Parameter
Description
serviceID
String that identifies the service monitor that you want to subscribe to for status information. Leave blank (empty string) to subscribe to all service monitors that are currently listening for com.apama.statusreport.SubscribeStatus messages.
object
String that identifies the object that you want status for. The service monitor defines the values that you can specify here. For example, a service monitor might provide status for Connection or Market.
subServiceID
For service monitors that provide sub-services, this string identifies the sub-service that you want to subscribe to for status information. If the service monitor has no sub-services, leave this parameter blank.
connection
For service monitors that provide status for several instances of the specified object, this string identifies the instance for which you want to obtain status information. If the service monitor provides status for only one instance, leave this parameter blank. For example, an adapter might connect to multiple sources of data. You would use this parameter to specify the data connection you are interested in. The service monitor must define the allowable values for the connection parameter.
extract key 1 extract key 2 extract key 3
These three parameters make it convenient to obtain particular values from the extracted parametern output fields in the Status block output feed.
Each parameter is a string that specifies a key whose value you want to obtain in the status received from the service monitor. For example, when you set the extract key 1 parameter to the value of a key defined in the service monitor, the Status output feed contains the specified key's value in its extracted parameter 1 field.
These fields make it easier to access particular elements in the extra parameters field of the output feed. You do not need to parse the payload string in the extra parameters field yourself.
Operations
Operation
Description
start
Initiates subscription to the service monitor identified by the serviceID parameter, for information about the component identified by the object parameter. If the specified service monitor has sub-services or provides information about more than one object instance, the subscription is for the sub-service and connection identified by the values that the subServiceID and connection Status block parameters have when the start operation is called.
If the value of the serviceID parameter is an empty string, the start operation initiates a subscription to each service monitor that is listening for SubscribeStatus events that have an empty string in their serviceID field.
Under the covers, the Status block routes a SubscribeStatus event to the correlator. This event takes its values from the current values of the Status block parameters.
After a service monitor receives a SubscribeStatus event, it starts sending Status events to the subscribing scenario.
stop
Terminates the subscription to the service monitor identified by the serviceID parameter. If the value of the serviceID parameter is an empty string, the stop operation terminates the subscription to each service monitor that is listening for UnsubscribeStatus events that have an empty string in their serviceID field.
Under the covers, the Status block routes an UnsubscribeStatus event to the correlator. This event takes its values from the current values of the Status block parameters.
If a scenario terminates without invoking the stop operation for a subscription, the block routes the appropriate UnsubscribeStatus events upon termination of the scenario.
Input feeds
This block has no input feeds.
Output feeds
Feed
Field
Description
Status
serviceID
String that identifies the service monitor that is providing the status.
object
String that identifies the object that the status is for.
subServiceID
String that identifies the sub-service that is providing the status. This is blank if the service has no sub-services.
connection
String that identifies the object instance that status is being provided for.
description
String that contains human-readable text that describes the status.
summaries
One word or a series of space-separated words that describe the status. For example, Connected, Disconnected, LoginFailed. The service monitor defines and documents the words that can appear in the summaries field. While the description field is for a human reader, the summaries field contains key words that a scenario can act on. For example, suppose summaries contains Disconnected. The scenario can define a rule that specifies what to do when this service is disconnected.
available
Boolean value that indicates whether the object is in a state where it can be used. For example, if you specify Market as the object, a value of true in the available field might mean that the market is open and accepting orders.
extra parameters
Payload-format string that contains any other information that the service monitor provides for the object.
extracted parameter 1
extracted parameter 2
extracted parameter 3
Each of these parameters is a string that contains the value of one of the key/value pairs that is in the extra parameters output field. The particular key value that the field contains is determined by the value that the corresponding extract key n block parameter had when the block's start operation was invoked.
For example, suppose that the extract key 1 parameter has a value of time. The block then invokes the start operation to subscribe to a particular service monitor. When the block receives status information from that monitor, the block inserts the value of time, for example, "12:34:56" into the extracted parameter 1 field and then sends the information to its Status output feed.
received status
Boolean value that indicates whether a Status event has been received from the specified service monitor.
Initially, this field is false. When the block receives a Status event, it sets this field to true. When the block unsubscribes from the specified service monitor or when the block receives a StatusError event, the block sets the received status field to false.
A value of true means that the information in the Status output feed is from the latest Status event and no error has since been signaled by the service monitor. In other words, you can trust the information in the Status output feed.
fault
Boolean value that indicates whether there was an error obtaining status information for the specified object. When the service monitor sends a StatusError event, the block sets this field to true. You should consider any information from this service monitor to be stale.
total
Integer that indicates the number of objects for which all of the following are true:
*The block is receiving status information for the object.
*The block has not received a StatusError event from the service monitor since the block received the previous Status event.
*The object is in a state in which it can be used. That is, the value of the available output field is true.
This field makes it convenient to track when a subscription is no longer providing status information. For example, if a Status block has 4 subscriptions but total = 3, then the scenario can take some action such as restoring the subscription, or not using stale data.
Copyright © 2013-2016 Software AG, Darmstadt, Germany.
Product LogoContact Support   |   Community   |   Feedback