danger.util
Interface ActiveList

All Known Subinterfaces:

ActiveFolder

All Known Implementing Classes:

FilteredActiveList, StdActiveFolder, StdActiveList

public interface ActiveList

A list of items that has hooks for notification of updates. Notification happens via the ActiveList.Delegate. Also, particular implementations of this interface may provide other means of notification. This interface only defines methods for accessing, not modifying, the list; however, particular implementations of this interface generally provide a means of modification.

Nested Class Summary

static interface	ActiveList.Delegate Interface for delegates that get notified on changes to instances of ActiveList.
static interface	ActiveList.ForEach Callback interface used for calls to forEach(danger.util.ActiveList.ForEach).
static class	ActiveList.WeakDelegateList List of delegates which are held onto weakly.

Method Summary

void	addDelegate(ActiveList.Delegate delegate) Add a new delegate to this instance.
int	eqIndexOf(Object item) Get the index of the given item in the list, compared with ==.
void	forEach(ActiveList.ForEach callback) Call the given callback on each of the items in this list, in order.
Object	getItem(int which) Get the nth item in this list.
void	getItems(int srcBegin, int srcEnd, Object[] dest, int destBegin) Get a range of items atomically with respect to other operations on this instance.
void	removeDelegate(ActiveList.Delegate delegate) Remove a delegate from this instance that was previously added via a call to addDelegate(danger.util.ActiveList.Delegate).
int	size() Get the number of items in this list.

Method Detail

addDelegate

void addDelegate(ActiveList.Delegate delegate)

Add a new delegate to this instance. Note: In general, instances implementing this interface are encouraged to hold onto delegates weakly. This means that it is not sufficient to simply construct a delegate, add it, and then do nothing else with it; one must also keep a reference to it elsewhere. Otherwise, after a garbage collect, it will get removed automatically from the list of live delegates.

Parameters:

delegate - non-null; the delegate to add

Throws:

NullPointerException - thrown if delegate == null

removeDelegate

void removeDelegate(ActiveList.Delegate delegate)

Remove a delegate from this instance that was previously added via a call to addDelegate(danger.util.ActiveList.Delegate).

Parameters:

delegate - non-null; the delegate to remove

Throws:

IllegalArgumentException - thrown if the delegate had not been added as a delegate of this instance

size

int size()

Get the number of items in this list.

Returns:

>= 0; the number of items

getItem

Object getItem(int which)

Get the nth item in this list.

Parameters:

which - >= 0 && < size(); which item to get

Returns:

null-ok; the nth item

getItems

void getItems(int srcBegin,
              int srcEnd,
              Object[] dest,
              int destBegin)

Get a range of items atomically with respect to other operations on this instance.

Parameters:

srcBegin - >= 0; the first item to get

srcEnd - >= srcBegin && <= size(); the index just past the last item to get

dest - non-null; the destination buffer

destBegin - >= 0 && <= (dest.length - (srcEnd - srcBegin)); where in dest to store the items

Throws:

NullPointerException - thrown if dest == null

IndexOutOfBoundsException - thrown if any of the indices is bad

forEach

void forEach(ActiveList.ForEach callback)

Call the given callback on each of the items in this list, in order. All the callbacks happen as a single atomic operation with respect to other operations on this list. As such, if the callback misbehaves, it can wedge this instance for an indefinite period of time (e.g., deadlock).

Parameters:

callback - non-null; the callback object

eqIndexOf

int eqIndexOf(Object item)

Get the index of the given item in the list, compared with ==.

Parameters:

item - null-ok; the item to look for

Returns:

>= -1; the index of the item or -1 if there is no such item