com.metamatrix.api.core.message
Class MessageList

java.lang.Object
  com.metamatrix.api.core.message.MessageList

All Implemented Interfaces:

java.lang.Iterable, java.util.Collection, java.util.List

public class MessageList
extends java.lang.Object
implements java.util.List

An ordered collection of Message instances. This class implements List and thus can be used in the same exact manner as a List. However, there are additional methods on this class that provide various mechanisms for finding or removing Message instances that match particular categories, such as those that apply to a specific target or those with one of a set of message types.

This class contains a Statistics object that maintains by message type the counts of Message instances contained by this object. Note that these statistics do reflect changes to the MessageList object.

Since:

3.0

Nested Class Summary

class

MessageList.Statistics Class that maintains statistics for the MessageList's Message instances categorized by various types.

Constructor Summary

MessageList()
Construct an object with no Message instances.

MessageList(java.util.Collection messages)
Construct an object and add all of the Message instances in the specified collection.

Method Summary

void	add(int index, java.lang.Object message) Overrides the implementation of List
boolean	add(java.lang.Object message) Overrides the implementation of List
boolean	addAll(java.util.Collection messages) Overrides the implementation of List
boolean	addAll(int index, java.util.Collection messages) Overrides the implementation of List
void	clear() Overrides the implementation of List
boolean	contains(java.lang.Object message) Overrides the implementation of List
boolean	containsAll(java.util.Collection messages) Overrides the implementation of List
java.lang.Object	get(int index) Overrides the implementation of List
MessageList.Statistics	getStatistics() Return the Statistics instance that contains a breakdown by MessageType of the number of Message instances in this object.
int	indexOf(java.lang.Object message) Overrides the implementation of List
boolean	isEmpty() Overrides the implementation of List
java.util.Iterator	iterator() Overrides the implementation of List
java.util.Iterator	iteratorByTarget(java.lang.Object target) Return an iterator over the Message instances that have the specified Object as the message target.
java.util.Iterator	iteratorByType(int messageType) Return an iterator over the Message instances that have the specified message type.
java.util.Iterator	iteratorByType(int[] messageTypes) Return an iterator over the Message instances that have a message type included in the provided set.
int	lastIndexOf(java.lang.Object message) Overrides the implementation of List
java.util.ListIterator	listIterator() Overrides the implementation of List
java.util.ListIterator	listIterator(int index) Overrides the implementation of List
protected static boolean	matchesTarget(Message msg, java.lang.Object target) Helper method to determine whether the supplied message has a target that is exactly the same as the supplied object.
protected static boolean	matchesType(Message msg, int messageType) Helper method to determine whether the supplied message has a type that is exactly the same object as the supplied type.
protected static boolean	matchesType(Message msg, int[] messageTypes) Helper method to determine whether the supplied message has a type that is exactly the same as one of the the supplied types.
protected void	messageAdded(Message message) Can be overridden by subclasses to do specific work on a message when it is being added.
protected void	messageRemoved(Message message) Can be overridden by subclasses to do specific work on a message when it is being removed.
protected void	messagesCleared() Can be overridden by subclasses to do specific work when this list is being cleared.
java.lang.Object	remove(int index) Overrides the implementation of List
boolean	remove(java.lang.Object message) Overrides the implementation of List
boolean	removeAll(java.util.Collection messages) Overrides the implementation of List
boolean	removeByClass(java.lang.Class messageClass) Remove all Message instances that are instances of the specified Class.
boolean	removeByTarget(java.lang.Object messageTarget) Remove all Message instances that have the specified target
boolean	removeByType(int messageType) Remove all Message instances that have the specified type
boolean	removeByType(int[] messageTypes) Remove all Message instances that have the specified type
protected static boolean	removeMessagesWithTarget(java.util.List messages, java.lang.Object target) Helper method to remove all instances from the List of Message objects where the message target matches (using matchesTarget(Message, Object)) the supplied target.
boolean	retainAll(java.util.Collection messages) Overrides the implementation of List
java.lang.Object	set(int index, java.lang.Object message) Overrides the implementation of List
int	size() Overrides the implementation of List
java.util.List	subList(int fromIndex, int toIndex) Overrides the implementation of List
java.util.List	subListByTarget(java.lang.Object messageTarget) Returns a sublist of the Message instances that have the appropriate message types.
java.util.List	subListByType(int messageType) Returns a sublist of the Message instances that have the appropriate message types.
java.util.List	subListByType(int[] messageTypes) Returns a sublist of the Message instances that have the appropriate message types.
java.lang.Object[]	toArray() Returns an array containing all of the elements in this list in proper sequence.
java.lang.Object[]	toArray(java.lang.Object[] a) Returns an array containing all of the elements in this list in proper sequence; the runtime type of the returned array is that of the specified array.
protected static void	verifyMessage(java.lang.Object obj) Helper method to verify that the object is an instance of Message.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.List

equals, hashCode

Constructor Detail

MessageList

public MessageList()

Construct an object with no Message instances.

MessageList

public MessageList(java.util.Collection messages)

Construct an object and add all of the Message instances in the specified collection.

Parameters:

messages - the collection of Message instances that this object is to contain; if null, this object will be empty.

Method Detail

getStatistics

public MessageList.Statistics getStatistics()

Return the Statistics instance that contains a breakdown by MessageType of the number of Message instances in this object. The returned object is updated automatically whenever this MessageList is changed.

Returns:

the statistics object for this MessageList; never null

removeByTarget

public boolean removeByTarget(java.lang.Object messageTarget)

Remove all Message instances that have the specified target

Parameters:

messageTarget - the target for which messages are to be removed from this container.

Returns:

true if at least one message was removed, or false if no messages were removed

removeByClass

public boolean removeByClass(java.lang.Class messageClass)

Remove all Message instances that are instances of the specified Class.

Parameters:

messageClass - the Class whose instances are to be removed from this list.

Returns:

true if at least one message was removed, or false if no messages were removed

removeByType

public boolean removeByType(int messageType)

Remove all Message instances that have the specified type

Parameters:

messageType - the type for which messages are to be removed from this container.

Returns:

true if at least one message was removed, or false if no messages were removed

removeByType

public boolean removeByType(int[] messageTypes)

Remove all Message instances that have the specified type

Parameters:

messageTypes - the types for which messages are to be removed from this container.

Returns:

true if at least one message was removed, or false if no messages were removed

iteratorByTarget

public java.util.Iterator iteratorByTarget(java.lang.Object target)

Return an iterator over the Message instances that have the specified Object as the message target.

Parameters:

target - the message target

Returns:

iterator the iterator that will expose only Message instances that have the supplied target

iteratorByType

public java.util.Iterator iteratorByType(int messageType)

Return an iterator over the Message instances that have the specified message type.

Parameters:

messageType - the message type

Returns:

iterator the iterator that will expose only Message instances that have the supplied type

iteratorByType

public java.util.Iterator iteratorByType(int[] messageTypes)

Return an iterator over the Message instances that have a message type included in the provided set.

Parameters:

messageTypes - the array of message types over which this iterator is to expose

Returns:

iterator the iterator that will expose only Message instances that have a type in the supplied array

subListByTarget

public java.util.List subListByTarget(java.lang.Object messageTarget)

Returns a sublist of the Message instances that have the appropriate message types.

Parameters:

messageTarget - the message target

Returns:

the sublist that is to contain all messages in this MessageList that have the supplied target object

subListByType

public java.util.List subListByType(int messageType)

Returns a sublist of the Message instances that have the appropriate message types.

Parameters:

messageType - the message type

Returns:

the sublist that is to contain all messages in this MessageList that have the supplied type

subListByType

public java.util.List subListByType(int[] messageTypes)

Returns a sublist of the Message instances that have the appropriate message types.

Parameters:

messageTypes - the array of message types

Returns:

the sublist that is to contain all messages in this MessageList that have a type that is in the supplied array

removeMessagesWithTarget

protected static boolean removeMessagesWithTarget(java.util.List messages,
                                                  java.lang.Object target)

Helper method to remove all instances from the List of Message objects where the message target matches (using matchesTarget(Message, Object)) the supplied target.

Parameters:

messages - the list of messages; may not be null

target - the target

Returns:

true if at least one message was removed from the list because its target matched the supplied target

matchesTarget

protected static boolean matchesTarget(Message msg,
                                       java.lang.Object target)

Helper method to determine whether the supplied message has a target that is exactly the same as the supplied object.

Parameters:

msg - the message

target - the target

Returns:

true if the message's target is the same object as the supplied target (using the == operator), or false otherwise.

matchesType

protected static boolean matchesType(Message msg,
                                     int[] messageTypes)

Helper method to determine whether the supplied message has a type that is exactly the same as one of the the supplied types.

Parameters:

msg - the list of messages; may not be null

messageTypes - the types

Returns:

true if at the message's type is the same as one of the supplied types, or false otherwise

matchesType

protected static boolean matchesType(Message msg,
                                     int messageType)

Helper method to determine whether the supplied message has a type that is exactly the same object as the supplied type.

Parameters:

msg - the list of messages; may not be null

messageType - the type

Returns:

true if at the message's type is the same as the supplied type, or false otherwise

verifyMessage

protected static void verifyMessage(java.lang.Object obj)

Helper method to verify that the object is an instance of Message.

Parameters:

obj - the Object that is to be verified

Throws:

java.lang.IllegalArgumentException - if the object is not null and the object is not an instance of Message

add

public void add(int index,
                java.lang.Object message)

Overrides the implementation of List

Specified by:

add in interface java.util.List

Parameters:

index - the index

message - the message

Throws:

java.lang.IllegalArgumentException - if the messsage is not an instance of Message

See Also:

List.add(int, Object)

add

public boolean add(java.lang.Object message)

Overrides the implementation of List

Specified by:

add in interface java.util.Collection

Specified by:

add in interface java.util.List

Parameters:

message - the message

Returns:

true if the message was added

Throws:

java.lang.IllegalArgumentException - if the messsage is not an instance of Message

See Also:

Collection.add(Object)

addAll

public boolean addAll(java.util.Collection messages)

Overrides the implementation of List

Specified by:

addAll in interface java.util.Collection

Specified by:

addAll in interface java.util.List

Parameters:

messages - the messages to be added

Returns:

true if all of the messages were added

Throws:

java.lang.IllegalArgumentException - if the collection contains instances other than Message

See Also:

Collection.addAll(Collection)

addAll

public boolean addAll(int index,
                      java.util.Collection messages)

Overrides the implementation of List

Specified by:

addAll in interface java.util.List

Parameters:

index - the index

messages - the messages to be added

Returns:

true if at least one message was added

Throws:

java.lang.IllegalArgumentException - if the collection contains instances other than Message

See Also:

List.addAll(int, Collection)

clear

public void clear()

Overrides the implementation of List

Specified by:

clear in interface java.util.Collection

Specified by:

clear in interface java.util.List

See Also:

Collection.clear()

contains

public boolean contains(java.lang.Object message)

Overrides the implementation of List

Specified by:

contains in interface java.util.Collection

Specified by:

contains in interface java.util.List

Parameters:

message - the message

Returns:

true if this List contains the specified Message

See Also:

Collection.contains(Object)

containsAll

public boolean containsAll(java.util.Collection messages)

Overrides the implementation of List

Specified by:

containsAll in interface java.util.Collection

Specified by:

containsAll in interface java.util.List

Parameters:

messages - the messages

Returns:

true if this List contains all of the specified Messages

See Also:

Collection.containsAll(Collection)

get

public java.lang.Object get(int index)

Overrides the implementation of List

Specified by:

get in interface java.util.List

Parameters:

index - the index at which the Message instance is to be returned

Returns:

the Message object at the supplied index

See Also:

List.get(int)

indexOf

public int indexOf(java.lang.Object message)

Overrides the implementation of List

Specified by:

indexOf in interface java.util.List

Parameters:

message - the message

Returns:

the index of the supplied message in this List

See Also:

List.indexOf(Object)

isEmpty

public boolean isEmpty()

Overrides the implementation of List

Specified by:

isEmpty in interface java.util.Collection

Specified by:

isEmpty in interface java.util.List

Returns:

true if this List contains no Message instances.

See Also:

Collection.isEmpty()

iterator

public java.util.Iterator iterator()

Overrides the implementation of List

Specified by:

iterator in interface java.lang.Iterable

Specified by:

iterator in interface java.util.Collection

Specified by:

iterator in interface java.util.List

Returns:

the iterator

See Also:

Collection.iterator()

lastIndexOf

public int lastIndexOf(java.lang.Object message)

Overrides the implementation of List

Specified by:

lastIndexOf in interface java.util.List

Parameters:

message - the Message object

Returns:

the last index at which the supplied Message exists in this List

See Also:

List.lastIndexOf(Object)

listIterator

public java.util.ListIterator listIterator()

Overrides the implementation of List

Specified by:

listIterator in interface java.util.List

Returns:

the iterator

See Also:

List.listIterator()

listIterator

public java.util.ListIterator listIterator(int index)

Overrides the implementation of List

Specified by:

listIterator in interface java.util.List

Parameters:

index - the index at which the iterator is to begin

Returns:

the iterator

See Also:

List.listIterator(int)

messageRemoved

protected void messageRemoved(Message message)

Can be overridden by subclasses to do specific work on a message when it is being removed. This implementation does nothing.

Parameters:

message - the message being removed

messageAdded

protected void messageAdded(Message message)

Can be overridden by subclasses to do specific work on a message when it is being added. This implementation does nothing.

Parameters:

message - the message being added

messagesCleared

protected void messagesCleared()

Can be overridden by subclasses to do specific work when this list is being cleared. This implementation does nothing.

remove

public java.lang.Object remove(int index)

Overrides the implementation of List

Specified by:

remove in interface java.util.List

Parameters:

index - the index

Returns:

the Message that was at the supplied index

See Also:

List.remove(int)

remove

public boolean remove(java.lang.Object message)

Overrides the implementation of List

Specified by:

remove in interface java.util.Collection

Specified by:

remove in interface java.util.List

Parameters:

message - the Message to be removed

Returns:

true if the Message was removed from this List, or false otherwise

See Also:

Collection.remove(Object)

removeAll

public boolean removeAll(java.util.Collection messages)

Overrides the implementation of List

Specified by:

removeAll in interface java.util.Collection

Specified by:

removeAll in interface java.util.List

Parameters:

messages - the Message instances to be removed

Returns:

true if at least one Message was removed from this List, or false otherwise

See Also:

Collection.removeAll(Collection)

retainAll

public boolean retainAll(java.util.Collection messages)

Overrides the implementation of List

Specified by:

retainAll in interface java.util.Collection

Specified by:

retainAll in interface java.util.List

Parameters:

messages - the Message instances to be removed

Returns:

true if at least one Message was removed from this List, or false otherwise

See Also:

Collection.retainAll(Collection)

set

public java.lang.Object set(int index,
                            java.lang.Object message)

Overrides the implementation of List

Specified by:

set in interface java.util.List

Parameters:

index - the index

message - the Message

Returns:

the Message that was previously at the index

See Also:

List.set(int, Object)

size

public int size()

Overrides the implementation of List

Specified by:

size in interface java.util.Collection

Specified by:

size in interface java.util.List

Returns:

the number of messages currently in this List

See Also:

Collection.size()

subList

public java.util.List subList(int fromIndex,
                              int toIndex)

Overrides the implementation of List

Specified by:

subList in interface java.util.List

Parameters:

fromIndex - the starting index (inclusive)

toIndex - the ending index (exclusive)

Returns:

the sublist

See Also:

List.subList(int, int)

toArray

public java.lang.Object[] toArray()

Returns an array containing all of the elements in this list in proper sequence. Obeys the general contract of the Collection.toArray method.

Specified by:

toArray in interface java.util.Collection

Specified by:

toArray in interface java.util.List

Returns:

an array containing all of the elements in this list in proper sequence.

See Also:

Collection.toArray()

toArray

public java.lang.Object[] toArray(java.lang.Object[] a)

Returns an array containing all of the elements in this list in proper sequence; the runtime type of the returned array is that of the specified array. Obeys the general contract of the Collection.toArray(Object[]) method.

Specified by:

toArray in interface java.util.Collection

Specified by:

toArray in interface java.util.List

Parameters:

a - the array into which the elements of this list are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.

Returns:

an array containing the elements of this list.

Throws:

java.lang.ArrayStoreException - if the runtime type of the specified array is not a supertype of the runtime type of every element in this list.

See Also:

Collection.toArray(Object[])