org.xmlBlaster.util
Interface I_TimeoutManager

All Known Implementing Classes:

Timeout, TimeoutPooled

public interface I_TimeoutManager

Author:

xmlblast

Method Summary

Timestamp	addOrRefreshTimeoutListener(I_Timeout listener, long delay, java.lang.Object userData, Timestamp key) Checks if key is null -> addTimeoutListener else refreshTimeoutListener() in a thread save way.
Timestamp	addTimeoutListener(I_Timeout listener, long delay, java.lang.Object userData) Add a listener which gets informed after 'delay' milliseconds.
java.lang.String	dumpStatus()
long	elapsed(Timestamp key) How long am i running.
int	getSize() Get number of current used timers.
long	getTimeout(Timestamp key) Access the end of life span.
boolean	isExpired(Timestamp key) Is this handle expired?
Timestamp	refreshTimeoutListener(Timestamp key, long delay) Refresh a listener before the timeout happened.
void	removeAll() Reset all pending timeouts.
void	removeTimeoutListener(Timestamp key) Remove a listener before the timeout happened.
void	shutdown() Reset and stop the Timeout manager thread.
long	spanToTimeout(Timestamp key) How long to my timeout.

Method Detail

getSize

int getSize()

Get number of current used timers.

Returns:

The number of active timers

addTimeoutListener

Timestamp addTimeoutListener(I_Timeout listener,
                             long delay,
                             java.lang.Object userData)

Add a listener which gets informed after 'delay' milliseconds.

After the timeout happened, you are not registered any more. If you want to cycle timeouts, you need to register again.

Parameters:

listener - Your callback handle (you need to implement this interface).

delay - The timeout in milliseconds. You can pass 0L and the Timeout thread will fire immediately, this can be useful to dispatch a task to the timeoutlistener

userData - Some arbitrary data you supply, it will be routed back to you when the timeout occurs through method I_Timeout.timeout().

Returns:

A handle which you can use to unregister with removeTimeoutListener().

refreshTimeoutListener

Timestamp refreshTimeoutListener(Timestamp key,
                                 long delay)
                                 throws XmlBlasterException

Refresh a listener before the timeout happened.

NOTE: The returned timeout handle is different from the original one.

NOTE: If you are not sure if the key has elapsed already try this:

 timeout.removeTimeoutListener(timeoutHandle);
 timeoutHandle = timeout.addTimeoutListener(this, "1000L", "UserData");
 

Parameters:

key - The timeout handle you received by a previous addTimeoutListener() call.
It is invalid after this call.

delay - The timeout in milliseconds measured from now.

Returns:

A new handle which you can use to unregister with removeTimeoutListener()

Throws:

XmlBlasterException - if key is null or unknown or invalid because timer elapsed already

addOrRefreshTimeoutListener

Timestamp addOrRefreshTimeoutListener(I_Timeout listener,
                                      long delay,
                                      java.lang.Object userData,
                                      Timestamp key)
                                      throws XmlBlasterException

Checks if key is null -> addTimeoutListener else refreshTimeoutListener() in a thread save way.
Note however that your passed key is different from the returned key and you need to synchronize this call to avoid having a stale key (two threads enter this method the same time, the key gets invalid by the first thread and the second passed a stale key as the first thread has not yet returned to update 'key')

Throws:

XmlBlasterException

removeTimeoutListener

void removeTimeoutListener(Timestamp key)

Remove a listener before the timeout happened.

Parameters:

key - The timeout handle you received by a previous addTimeoutListener() call.

isExpired

boolean isExpired(Timestamp key)

Is this handle expired?

Parameters:

key - The timeout handle you received by a previous addTimeoutListener() call

Returns:

true/false

spanToTimeout

long spanToTimeout(Timestamp key)

How long to my timeout.

Parameters:

key - The timeout handle you received by a previous addTimeoutListener() call.

Returns:

Milliseconds to timeout, or -1 if not known.

elapsed

long elapsed(Timestamp key)

How long am i running.

Parameters:

key - The timeout handle you received by a previous addTimeoutListener() call.

Returns:

Milliseconds since creation, or -1 if not known.

getTimeout

long getTimeout(Timestamp key)

Access the end of life span.

Parameters:

key - The timeout handle you received by a previous addTimeoutListener() call.

Returns:

Time in milliseconds since midnight, January 1, 1970 UTC or -1 if not known.

removeAll

void removeAll()

Reset all pending timeouts.

shutdown

void shutdown()

Reset and stop the Timeout manager thread.

dumpStatus

java.lang.String dumpStatus()