com.sun.jdmk.comm
Interface ClientNotificationHandler

All Superinterfaces:

NotificationRegistration

public interface ClientNotificationHandler

extends NotificationRegistration

This interface specifies the methods for a connector to allow a listener to receive notifications from a remote MBean in an agent.

To forward a notification from the agent to the connector client, the user can configure the connector to use either push or pull mode.

• In pull mode, the connector server on the agent side buffers all notifications until the connector client requests, or "pulls," them. The caller can configure the buffer cache size and overflow behavior in the connector server. The caller can also set the forwarding period to control how often notifications are pulled from the connector server.
• In push mode, the connector server forwards each and every notification to the connector client as it is received. In the current implementation, the cache and forwarding period are not used in push mode--notifications are forwarded immediately.

Field Summary

static int	DISCARD_NEW This constant controls the cache behavior for notification forwarding.
static int	DISCARD_OLD This constant controls the cache behavior for notification forwarding.
static int	NO_CACHE_LIMIT This constant controls the cache behavior for notification forwarding.
static int	PULL_MODE This constant is used to set the pull mode for notification forwarding.
static int	PUSH_MODE This constant is used to set the push mode for notification forwarding.

Method Summary

void	clearCache() Clear the notification cache.
int	getCacheSize() Gets the cache size of notifications waiting to be forwarded.
int	getMode() Gets the notification forwarding mode.
void	getNotifications() Retrieves all notifications in the cache.
int	getOverflowCount() Gets the number of notifications discarded because the cache limit has been reached.
int	getOverflowMode() Returns whether to discard the oldest message (DISCARD_OLD) or the the newest meesage (DISCARD_NEW), if the cache size excceds.
int	getPeriod() Gets the period for notification forwarding in milliseconds.
int	setCacheSize(int size, boolean discardOverflow) Sets the cache size of notifications waiting to be forwarded.
void	setMode(int mode) Sets the notification forwarding mode.
void	setOverflowCount(int count) Sets the number of notifications discarded, this number indicates the number of notifications discarded because the cache limit has been reached.
void	setOverflowMode(int of) Specifes whether to discard the oldest message (DISCARD_OLD) or the the newest message (DISCARD_NEW), if the cache size excceds.
void	setPeriod(int period) Specifies the period for notification forwarding in milliseconds.

Methods inherited from interface com.sun.jdmk.NotificationRegistration

addNotificationListener, removeNotificationListener

Field Detail

PUSH_MODE

public static final int PUSH_MODE

This constant is used to set the push mode for notification forwarding.

See Also:

Constant Field Values

PULL_MODE

public static final int PULL_MODE

This constant is used to set the pull mode for notification forwarding.

See Also:

Constant Field Values

DISCARD_OLD

public static final int DISCARD_OLD

This constant controls the cache behavior for notification forwarding. If the cache mode is set to this value and when the notification cache size is exceeded, the older messages will be discarded. This is default value for the cache behavior for notification forwarding.

See Also:

Constant Field Values

DISCARD_NEW

public static final int DISCARD_NEW

This constant controls the cache behavior for notification forwarding. If the cache mode is set to this value and when the notification cache size is exceeded, the newer messages will be discarded.

See Also:

Constant Field Values

NO_CACHE_LIMIT

public static final int NO_CACHE_LIMIT

This constant controls the cache behavior for notification forwarding. If the cache size is set to this value, there is no limitation of the notification cache size and notifications will never be discarded. This is default value for notification forwarding.

See Also:

Constant Field Values

Method Detail

setMode

public void setMode(int mode)
             throws IllegalArgumentException

Sets the notification forwarding mode. If set to PUSH_MODE, it is the agent to push notifications to the client, if set to PULL_MODE, it is the client to retrive notifications from the agent.

The default value is PUSH_MODE.

Parameters:

mode - set to PUSH_MODE or PULL_MODE.

Throws:

IllegalArgumentException - Thrown if the mode is not equal to PUSH_MODE nor PULL_MODE.

getMode

public int getMode()

Gets the notification forwarding mode. If set to PUSH_MODE, it is the agent to push notifications to the client, if set to PULL_MODE, it is the client to retrive notifications from the agent.

The default value is PUSH_MODE.

getNotifications

public void getNotifications()

Retrieves all notifications in the cache.

clearCache

public void clearCache()

Clear the notification cache. All notifications stored in the cache then will be discarded without being sent.

setPeriod

public void setPeriod(int period)

Specifies the period for notification forwarding in milliseconds.

If set to equal to or less than zero and the pull mode is used, no pull will be done. A user should explicitly call getNotifications to retrieve all notifications in the cache. This method has no effect in the push mode in the current implementation.

The default value is 1000 milliseconds.

Parameters:

period - The period in milliseconds.

getPeriod

public int getPeriod()

Gets the period for notification forwarding in milliseconds.

The default value is 1000 milliseconds.

setCacheSize

public int setCacheSize(int size,
                        boolean discardOverflow)

Sets the cache size of notifications waiting to be forwarded.

If set to NO_CACHE_LIMIT, notifications will never be discarded, but this may lead to OutOfMemory errors under stressed conditions. If set to zero, any notification will be discarded without being sent.

The default value is NO_CACHE_LIMIT.

Parameters:

size - the maximum number of notifications in the cache.

discardOverflow - effective only if current number of cached notifications exceeds the new size: if true, discard excess notifications; if false, the cache size will not be changed.

Returns:

The cache size currently set.

getCacheSize

public int getCacheSize()

Gets the cache size of notifications waiting to be forwarded.

If set to NO_CACHE_LIMIT, notifications will never be discarded, but this may lead to OutOfMemory errors under stressed conditions.

The default value is NO_CACHE_LIMIT.

setOverflowCount

public void setOverflowCount(int count)

Sets the number of notifications discarded, this number indicates the number of notifications discarded because the cache limit has been reached.

This count will be reset to zero if no more listener exists at the client side, because in this case the notification server will remove all information about this notification client.

Parameters:

count - The new value to set to overflow count.

getOverflowCount

public int getOverflowCount()

Gets the number of notifications discarded because the cache limit has been reached. This value can be reset by calling the method setOverFlowCount.

This count will be reset to zero if no more listener exists at the client side, because in this case the notification server will remove all information about this notification client.

setOverflowMode

public void setOverflowMode(int of)
                     throws IllegalArgumentException

Specifes whether to discard the oldest message (DISCARD_OLD) or the the newest message (DISCARD_NEW), if the cache size excceds.

The default mode is DISCARD_OLD.

Parameters:

of - The mode to specify.

Throws:

IllegalArgumentException - Thrown if the mode is not DISCARD_NEW nor DISCARD_OLD.

getOverflowMode

public int getOverflowMode()

Returns whether to discard the oldest message (DISCARD_OLD) or the the newest meesage (DISCARD_NEW), if the cache size excceds.

The default mode is DISCARD_OLD.