com.ibm.ia.testdriver

Class DebugInfoReceiverQueue

java.lang.Object

com.ibm.ia.testdriver.DebugInfoReceiverQueue

All Implemented Interfaces:

DebugReceiver

public class DebugInfoReceiverQueue
extends java.lang.Object
implements DebugReceiver

A reference implementation of the DebugReceiver interface. A queue abstraction for caching DebugInfo elements allows for capacity bounds and the definition of a retention policy. Elements are maintained in a FIFO order and stored and retrieved on a per agent basis. Retrieval can be blocking or non-blocking and the caching of new elements can be dynamically suspended and resumed on a solution wide basis.

This class was not explicitly designed to be extended.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DebugInfoReceiverQueue.DiscardPolicy Define the the retention policy options for the agent queues.

Constructor Summary

Constructors

Constructor and Description
DebugInfoReceiverQueue() Deprecated. Use DebugInfoReceiverQueue(DriverProperties).
DebugInfoReceiverQueue(DriverProperties driverProperties) Create a new DebugInfoReceiverQueue cache for the agents of a given solution.

Method Summary

Methods

Modifier and Type	Method and Description
void	addDebugInfo(DebugInfo instance, java.lang.String sourceagent) The default policy is to discard the newest (arriving) elements if the capacity limits for a given agent queue are reached.
java.lang.String[]	agentQueueNames() Answers with the names of all agent queues in use for caching at the time of the call.
void	clearDebugInfo() Remove all DebugInfo elements from all agent queues.
void	clearDebugInfo(java.lang.String agent) Remove all DebugInfo elements from the target agent queue.
int	getCapacity() Answers with the maximum element capacity of the individual agent queues.
DebugInfo	getDebugInfo(java.lang.String agent) Retrieves the element at the head of the queue for a given agent, removing it from the queue.
DebugInfo[]	getDebugInfo(java.lang.String agent, int count) Retrieves and removes at most the given number of available elements from the named agent queue.
DebugInfo	getDebugInfo(java.lang.String agent, long timeout, java.util.concurrent.TimeUnit unit) Retrieves and removes the element at the head of the given agent queue, waiting up to the specified wait time if necessary for an element to become available.
DebugInfo[]	getDebugInfo(java.lang.String agent, long timeout, java.util.concurrent.TimeUnit unit, int count) Retrieves and removes at most the given number of available elements from the named agent queue, waiting up to the specified amount of time for those elements to appear.
DebugInfoReceiverQueue.DiscardPolicy	getDiscardPolicy() Answers with the current state of the agent queue retention policy.
boolean	isPaused() Answers whether the the caching of new DebugInfo elements has been suspended.
DebugInfo	peekDebugInfo(java.lang.String agent) Retrieves the element at the head of the queue for the given agent.
void	setDiscardPolicy(DebugInfoReceiverQueue.DiscardPolicy policy) Set the retention policy for all agent queues.
void	setPaused(boolean pause) Suspend or resume the caching of DebugInfo elements on a solution wide basis.
int	sizeDebugInfo(java.lang.String agent) Answers the number of DebugInfo elements in a given agent's queue at the time of the call.
DebugInfo	takeDebugInfo(java.lang.String agent) Retrieves and removes the element at the head of this agent queue, waiting if necessary until an element becomes available.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DebugInfoReceiverQueue

@Deprecated
public DebugInfoReceiverQueue()

Deprecated. Use DebugInfoReceiverQueue(DriverProperties).

Create a new DebugInfoReceiverQueue cache for the agents of a given solution. Capacity limits for the agent element queues are set to the default value from DriverProperties class.

DebugInfoReceiverQueue

public DebugInfoReceiverQueue(DriverProperties driverProperties)

Create a new DebugInfoReceiverQueue cache for the agents of a given solution. Capacity limits for the agent element queues are set to the value from the supplied DriverProperties class.

Parameters:

driverProperties - a DriverProperties object containing the desired capacity limit for agent queues

Method Detail

addDebugInfo

public void addDebugInfo(DebugInfo instance,
                java.lang.String sourceagent)

The default policy is to discard the newest (arriving) elements if the capacity limits for a given agent queue are reached. It is possible to change the policy to one where the oldest elements are evicted instead.

Specified by:

addDebugInfo in interface DebugReceiver

sourceagent - - the name of the agent which generated the event

See Also:

DebugReceiver.addDebugInfo(com.ibm.ia.common.debug.DebugInfo, java.lang.String)

peekDebugInfo

public DebugInfo peekDebugInfo(java.lang.String agent)

Retrieves the element at the head of the queue for the given agent. The element is not removed from the queue. No guarantee is made that the element will be available for retrieval at a subsequent point in time.

Parameters:

agent - the name of agent queue to peek into

Returns:

A DebugInfo element or null if the queue is empty or there is no queue for the agent

takeDebugInfo

public DebugInfo takeDebugInfo(java.lang.String agent)
                        throws java.lang.InterruptedException

Retrieves and removes the element at the head of this agent queue, waiting if necessary until an element becomes available.

Throws:

java.lang.InterruptedException - if interrupted while waiting

Parameters:

agent - the name of agent queue to take from

Returns:

A DebugInfo element from the head of the agent's queue, null if there is no queue for the requested agent

getDebugInfo

public DebugInfo getDebugInfo(java.lang.String agent)

Retrieves the element at the head of the queue for a given agent, removing it from the queue.

Parameters:

agent - the name of agent queue to get from

Returns:

A DebugInfo element or null if the queue is empty or there is no queue for the agent

getDebugInfo

public DebugInfo getDebugInfo(java.lang.String agent,
                     long timeout,
                     java.util.concurrent.TimeUnit unit)
                       throws java.lang.InterruptedException

Retrieves and removes the element at the head of the given agent queue, waiting up to the specified wait time if necessary for an element to become available.

Throws:

java.lang.InterruptedException - if interrupted while waiting

Parameters:

agent - the name of the agent queue to get from

timeout - how long to wait in units of unit before returning

unit - a TimeUnit describing how to interpret the timeout value

Returns:

A DebugInfo element or null if the time to wait expires and the queue is still empty or there is no queue for the agent

getDebugInfo

public DebugInfo[] getDebugInfo(java.lang.String agent,
                       int count)

Retrieves and removes at most the given number of available elements from the named agent queue.

Parameters:

agent - the name of the agent queue to get from

count - the maximum number of DebugInfo elements to return

Returns:

an array of DebugInfo elements where the size of the array is from zero up to the count

getDebugInfo

public DebugInfo[] getDebugInfo(java.lang.String agent,
                       long timeout,
                       java.util.concurrent.TimeUnit unit,
                       int count)
                         throws java.lang.InterruptedException

Retrieves and removes at most the given number of available elements from the named agent queue, waiting up to the specified amount of time for those elements to appear. No order or sequence guarantees are made if this call is interleaved with other retrieval methods in a threaded environment. When only one element is desired (i.e. count is 1) then use getDebugInfo(String, long, TimeUnit).

Throws:

java.lang.InterruptedException - if interrupted while waiting

Parameters:

agent - the agent queue to get from

timeout - how long to wait in units of unit before returning

unit - a TimeUnit describing how to interpret the timeout value

count - the maximum number of DebugInfo elements to return

Returns:

an array of DebugInfo elements where the size of the array is from zero up to the count

agentQueueNames

public java.lang.String[] agentQueueNames()

Answers with the names of all agent queues in use for caching at the time of the call. Initially there are no queues. When a DebugInfo object arrives a new queue is created. When an agent queue is cleared via clearDebugInfo(String) or clearDebugInfo() it is dropped until a new DebugInfo arrives.

Returns:

an array of String containing the names of all agent queues

sizeDebugInfo

public int sizeDebugInfo(java.lang.String agent)

Answers the number of DebugInfo elements in a given agent's queue at the time of the call.

Parameters:

agent - the name of agent queue to size

Returns:

the number of DebugInfo elements in the agent queue, -1 if the size could not be determined

clearDebugInfo

public void clearDebugInfo()

Remove all DebugInfo elements from all agent queues. Caching is automatically paused during this operation if it was not paused already. The state of caching is restored before exiting.

clearDebugInfo

public void clearDebugInfo(java.lang.String agent)

Remove all DebugInfo elements from the target agent queue. Caching is automatically paused during this operation if it was not paused already. The state of caching is restored before exiting.

Parameters:

agent - the name of the agent queue to clear

getCapacity

public int getCapacity()

Answers with the maximum element capacity of the individual agent queues. When this capacity is reached, incoming DebugInfo elements are handled according to the queue retention policy.

Returns:

the maximum number of DebugInfo elements each agent queue can hold

getDiscardPolicy

public DebugInfoReceiverQueue.DiscardPolicy getDiscardPolicy()

Answers with the current state of the agent queue retention policy.

Returns:

DISCARDNEWEST if arriving elements are to be discarded or DISCARDOLDEST if the oldest elements should be evicted instead

setDiscardPolicy

public void setDiscardPolicy(DebugInfoReceiverQueue.DiscardPolicy policy)

Set the retention policy for all agent queues. When the arrival of a new DebugInfo element would cause an agent's queue to exceed its capacity, elements are discarded or evicted from the queue. The elements to be discarded can be the arriving elements or the oldest elements in the queue.

Parameters:

policy - DISCARDNEWEST to have arriving elements discarded or DISCARDOLDEST to have the oldest elements removed from the queue

isPaused

public boolean isPaused()

Answers whether the the caching of new DebugInfo elements has been suspended. When caching is suspended arriving DebugInfo elements are discarded.

Returns:

a boolean value of true if caching is suspended, false if caching is active

setPaused

public void setPaused(boolean pause)

Suspend or resume the caching of DebugInfo elements on a solution wide basis. When caching is paused, arriving DebugInfo elements are discarded.

Parameters:

pause - a boolean value of true suspends caching, false resumes