com.sun.sgs.service
Interface WatchdogService

All Superinterfaces:

Service

All Known Implementing Classes:

WatchdogServiceImpl

public interface WatchdogService
extends Service

The WatchdogService monitors the health of server nodes and notifies registered listeners of node status change events. It also provides information and notification services about node backup and recovery.

Method Summary

void	addNodeListener(NodeListener listener) Registers a listener to be notified when any node that this service monitors starts or fails.
void	addRecoveryListener(RecoveryListener listener) Adds the specified recovery listener for the local node.
long	currentAppTimeMillis() Returns the current global application time in milliseconds.
long	getAppTimeMillis(long systemTimeMillis) Converts a system time value representing the total elapsed time in milliseconds since midnight, January 1, 1970 UTC to an "application time" value.
Node	getBackup(long nodeId) Returns the node that is designated as the backup for the node with the specified nodeId, or null if no backup is currently designated.
Node.Health	getLocalNodeHealth() Returns the health of the local node.
Node.Health	getLocalNodeHealthNonTransactional() Returns the health of the local node.
Node	getNode(long nodeId) Returns node status information for the node with the specified nodeId, or null if the node is unknown.
Iterator<Node>	getNodes() Returns an iterator for the set of nodes that this service monitors.
long	getSystemTimeMillis(long appTimeMillis) Converts an "application time" value representing the total amount of time in milliseconds that the current application has been running since the initialize method was called on its AppListener object to a system time value.
boolean	isLocalNodeAlive() Returns true if the local node is considered alive, otherwise returns false.
boolean	isLocalNodeAliveNonTransactional() Returns true if the local node is considered alive, otherwise returns false.
void	reportFailure(long nodeId, String component) Informs the watchdog that a problem has occurred in a service or component.
void	reportHealth(long nodeId, Node.Health health, String component) Informs the watchdog of a node's health.
void	reportHealth(Node.Health health, String component) Informs the watchdog of this node's health.

Methods inherited from interface com.sun.sgs.service.Service

getName, ready, shutdown

Method Detail

getLocalNodeHealth

Node.Health getLocalNodeHealth()

Returns the health of the local node. This method should only be called from within a transaction.

Returns:

the health of the local node

Throws:

TransactionException - if there is a problem with the current transaction

getLocalNodeHealthNonTransactional

Node.Health getLocalNodeHealthNonTransactional()

Returns the health of the local node. This method returns the most recent information known to this service and may not be definitive. For definitive information, use the getLocalNodeHealth method.

This method may be invoked any time after this service is initialized, whether or not the calling context is inside or outside of a transaction.

Returns:

the health of the local node

isLocalNodeAlive

boolean isLocalNodeAlive()

Returns true if the local node is considered alive, otherwise returns false. This method should only be called from within a transaction.

Returns:

true if the local node is considered alive, and false otherwise

Throws:

TransactionException - if there is a problem with the current transaction

isLocalNodeAliveNonTransactional

boolean isLocalNodeAliveNonTransactional()

Returns true if the local node is considered alive, otherwise returns false. This method returns the most recent information known to this service and may not be definitive. For definitive information, use the isLocalNodeAlive method.

This method may be invoked any time after this service is initialized, whether or not the calling context is inside or outside of a transaction.

Returns:

true if the local node is considered alive, and false otherwise

getNodes

Iterator<Node> getNodes()

Returns an iterator for the set of nodes that this service monitors. The remove operation of the returned iterator is not supported and will throw UnsupportedOperationException if invoked. This method must be called within a transaction, and the returned iterator must only be used within that transaction.

Returns:

an iterator for the set of nodes that this service monitors

Throws:

TransactionException - if there is a problem with the current transaction

getNode

Node getNode(long nodeId)

Returns node status information for the node with the specified nodeId, or null if the node is unknown. This method should only be called within a transaction.

Parameters:

nodeId - a node ID

Returns:

node status information for the specified nodeId, or null

Throws:

IllegalArgumentException - if the specified nodeId is not within the range of valid IDs

TransactionException - if there is a problem with the current transaction

getBackup

Node getBackup(long nodeId)

Returns the node that is designated as the backup for the node with the specified nodeId, or null if no backup is currently designated. This method must be called within a transaction.

Note: this method should probably be moved to the Node interface, or it should throw an exception in the case where there is no existing node corresponding to nodeId.

Parameters:

nodeId - a node ID

Returns:

a backup node, or null

Throws:

IllegalArgumentException - if the specified nodeId is not within the range of valid IDs

TransactionException - if there is a problem with the current transaction

addNodeListener

void addNodeListener(NodeListener listener)

Registers a listener to be notified when any node that this service monitors starts or fails. Registered listeners are notified outside of a transaction.

This method must be invoked outside of a transaction.

Parameters:

listener - a node listener

Throws:

IllegalStateException - if this method is invoked from a transactional context

addRecoveryListener

void addRecoveryListener(RecoveryListener listener)

Adds the specified recovery listener for the local node. If the local node is designated as a backup for a node that fails, the specified listener will be notified (outside of a transaction) by having its recover method invoked, passing the failed node and a SimpleCompletionHandler whose completed method must be invoked when the recovery operations initiated by the listener are complete.

This method must be invoked outside of a transaction.

Parameters:

listener - a recovery listener

Throws:

IllegalStateException - if this method is invoked from a transactional context

reportHealth

void reportHealth(Node.Health health,
                  String component)

Informs the watchdog of this node's health. Multiple components may report on a node's health. The watchdog will use these reports to determine the overall node's health. The component parameter may be any identifying string, but is typically the class name of the component.

Once reportLocalHealth has been called with a health that returns false from its Health.isAlive method, the health of the local node can not be changed.

This method must be invoked outside of a transaction.

Parameters:

health - the health

component - the name of the component reporting health

Throws:

IllegalStateException - if this method is invoked from a transactional context

reportHealth

void reportHealth(long nodeId,
                  Node.Health health,
                  String component)

Informs the watchdog of a node's health. Multiple components may report on a node's health. The watchdog will use these reports to determine the overall node's health. The node specified as the nodeId can be the local node or a remote node. The component parameter may be any identifying string, but is typically the class name of the component.

Once reportHealth has been called with a health that returns false from its Health.isAlive method, the health of the specified node can not be changed.

This method must be invoked outside of a transaction.

Parameters:

nodeId - the id of the node

health - the health

component - the name of the component reporting health

Throws:

IllegalStateException - if this method is invoked from a transactional context

reportFailure

void reportFailure(long nodeId,
                   String component)

Informs the watchdog that a problem has occurred in a service or component. The watchdog will notify the server of the failure and then proceed to shutting down the node. The node specified as the nodeId can be the local node or a remote node. The component parameter may be any identifying string, but is typically the class name of the component.

Once reportFailure has been called, the health of the specified node can not be changed.

This method must be invoked outside of a transaction.

Parameters:

nodeId - the id of the node to shutdown

component - the name of the component that failed

Throws:

IllegalStateException - if this method is invoked from a transactional context

currentAppTimeMillis

long currentAppTimeMillis()

Returns the current global application time in milliseconds. This method returns the amount of time in milliseconds that the current application has been running since the initialize method was called on the application's AppListener object. Any time that passes while the application is not running does not affect this value. This means that this method can effectively be used to measure the global wall clock time of the current application's running state.

Note: This method cannot be reliably used to make fine-grained time comparisons across task boundaries. Unpredictable conditions such as network latency mean that the resulting value may be subject to some skew. Additionally, the global accuracy of the clock time may drift as much as a few seconds in either direction due to inherent inaccuracies recovering application time after a system crash.

Returns:

the current global application time in milliseconds

getAppTimeMillis

long getAppTimeMillis(long systemTimeMillis)

Converts a system time value representing the total elapsed time in milliseconds since midnight, January 1, 1970 UTC to an "application time" value. An application time value is the total amount of time in milliseconds that the current application has been running since the initialize method was called on its AppListener object.

Parameters:

systemTimeMillis - a system time value

Returns:

the given system time converted into application time

getSystemTimeMillis

long getSystemTimeMillis(long appTimeMillis)

Converts an "application time" value representing the total amount of time in milliseconds that the current application has been running since the initialize method was called on its AppListener object to a system time value. A system time value is the total elapsed time in milliseconds since midnight, January 1, 1970 UTC.

Parameters:

appTimeMillis - an application time value

Returns:

the given application time converted into system time