net.sf.eBus.messages

Class EMessageList<E extends EMessage>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractList<E>

java.util.ArrayList<E>

net.sf.eBus.messages.EAbstractList<E>

net.sf.eBus.messages.EMessageList<E>

Type Parameters:

E - specifies the homogenous, concrete EMessage type stored in this list.

All Implemented Interfaces:

Serializable, Cloneable, Iterable<E>, Collection<E>, List<E>, RandomAccess

public final class EMessageList<E extends EMessage>
extends EAbstractList<E>
implements Serializable, Cloneable

This message field type allows multiple messages to be transported within another eBus message. A message list is message key homogenous. That is, a message list takes an eBus message key parameter and uses that key to verify that all messages placed in this list have the same key as the parameter. That also means that null messages may not be added to a message list.

The difference between EMessageList and EMessage[] is that EMessageList serializes the defining EMessageKey once and then each message instance in turn. This works because EMessageList items all use the same message key. EMessage[] allows messages with different message keys, so the message key is serialized for each message item. This greatly increases the serialization/de-serialization time and serialized buffer size.

This class extends ArrayList, providing all the features available in that class.

There is no limit as to the number of elements which may be placed into this list. But care must be taken not to overflow the eBus ByteBuffer when serializing for transport.

Author:

Charles W. Rapp

See Also:

Serialized Form

Field Summary

Fields inherited from class net.sf.eBus.messages.EAbstractList

mReadOnlyFlag

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

Constructors

Constructor and Description
EMessageList(Collection<E> c, EMessageKey key) Creates a message list instance containing the same elements as c and in the order returned by the collection's iterator.
EMessageList(EMessageKey key) Creates an empty message list instance with an initial capacity of ten.
EMessageList(int initialCapacity, EMessageKey key) Creates an empty message list instance with the specified initial capacity.

Method Summary

Modifier and Type	Method and Description
boolean	add(E e) Appends the specified element to the end of this list.
void	add(int index, E e) Inserts the specified element at the specified position in this list.
boolean	addAll(Collection<? extends E> c) Appends all of the elements in the specified collection to the end of this list, in the order that they are returned by the specified collection's Iterator.
boolean	addAll(int index, Collection<? extends E> c) Inserts all of the elements in the specified collection into this list, starting at the specified position.
EMessageKey	key() Returns the list element message key.
E	set(int index, E e) Replaces the element at the specified position in this list with the specified element.

Methods inherited from class net.sf.eBus.messages.EAbstractList

clear, isReadOnly, iterator, listIterator, listIterator, remove, remove, removeAll, removeIf, removeRange, replaceAll, retainAll, setReadOnly, sort, subList

Methods inherited from class java.util.ArrayList

clone, contains, ensureCapacity, forEach, get, indexOf, isEmpty, lastIndexOf, size, spliterator, toArray, toArray, trimToSize

Methods inherited from class java.util.AbstractList

equals, hashCode

Methods inherited from class java.util.AbstractCollection

containsAll, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.List

containsAll, equals, hashCode

Methods inherited from interface java.util.Collection

parallelStream, stream

Constructor Detail

EMessageList

public EMessageList(EMessageKey key)
             throws NullPointerException

Creates an empty message list instance with an initial capacity of ten.

Parameters:

key - list elements must be eBus messages containing this message key.

Throws:

NullPointerException - if key is null.

EMessageList

public EMessageList(int initialCapacity,
                    EMessageKey key)
             throws NullPointerException

Creates an empty message list instance with the specified initial capacity.

Parameters:

initialCapacity - the list initial capacity.

key - list elements must be eBus messages containing this message key.

Throws:

NullPointerException - if key is null.

EMessageList

public EMessageList(Collection<E> c,
                    EMessageKey key)
             throws NullPointerException,
                    IllegalArgumentException

Creates a message list instance containing the same elements as c and in the order returned by the collection's iterator.

Parameters:

c - place this collection's elements into this message list.

key - list elements must be eBus messages containing this message key.

Throws:

NullPointerException - if either c or key is null.

IllegalArgumentException - if c contains a message with a key that does not equal key.

Method Detail

add

public boolean add(E e)
            throws NullPointerException,
                   IllegalArgumentException,
                   UnsupportedOperationException

Appends the specified element to the end of this list.

Specified by:

add in interface Collection<E extends EMessage>

Specified by:

add in interface List<E extends EMessage>

Overrides:

add in class EAbstractList<E extends EMessage>

Parameters:

e - append this element to list.

Returns:

true (as specified by Collection.add(E)).

Throws:

NullPointerException - if e is null.

IllegalArgumentException - if e does not have a correct message key which matches this list's key.

UnsupportedOperationException - if this list is marked as read-only.

add

public void add(int index,
                E e)
         throws NullPointerException,
                IllegalArgumentException,
                IndexOutOfBoundsException

Inserts the specified element at the specified position in this list. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).

Specified by:

add in interface List<E extends EMessage>

Overrides:

add in class EAbstractList<E extends EMessage>

Parameters:

index - insert e into list at this index.

e - insert this element into list.

Throws:

NullPointerException - if e is null.

IllegalArgumentException - if e does not have a correct message key which matches this list's key.

IndexOutOfBoundsException - if index is out of range (index < 0 || index > this.size()).

UnsupportedOperationException - if this list is marked as read-only.

addAll

public boolean addAll(Collection<? extends E> c)
               throws NullPointerException,
                      IllegalArgumentException,
                      UnsupportedOperationException

Appends all of the elements in the specified collection to the end of this list, in the order that they are returned by the specified collection's Iterator. The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (This implies that the behavior of this call is undefined if the specified collection is this list, and this list is nonempty.)

Specified by:

addAll in interface Collection<E extends EMessage>

Specified by:

addAll in interface List<E extends EMessage>

Overrides:

addAll in class EAbstractList<E extends EMessage>

Parameters:

c - append the elements of c to this list.

Returns:

true if this list changed as a result of the call.

Throws:

NullPointerException - if c is null.

IllegalArgumentException - if c contains elements that are either null or messages that have message keys that do not match this list's message key.

UnsupportedOperationException - if this list is marked as read-only.

addAll

public boolean addAll(int index,
                      Collection<? extends E> c)
               throws NullPointerException,
                      IllegalArgumentException,
                      IndexOutOfBoundsException,
                      UnsupportedOperationException

Inserts all of the elements in the specified collection into this list, starting at the specified position. Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in the list in the order that they are returned by the specified collection's iterator.

Specified by:

addAll in interface List<E extends EMessage>

Overrides:

addAll in class EAbstractList<E extends EMessage>

Parameters:

index - insert c's elements into this list at this index.

c - collection containing insertion elements.

Returns:

true if this list changed as a result of the call.

Throws:

NullPointerException - if c is null.

IllegalArgumentException - if c contains elements that are either null or messages that have message keys that do not match this list's message key.

IndexOutOfBoundsException - if index is out of range (index < 0 || index > this.size()).

UnsupportedOperationException - if this list is marked as read-only.

set

public E set(int index,
             E e)
      throws NullPointerException,
             IllegalArgumentException,
             IndexOutOfBoundsException,
             UnsupportedOperationException

Replaces the element at the specified position in this list with the specified element.

Specified by:

set in interface List<E extends EMessage>

Overrides:

set in class EAbstractList<E extends EMessage>

Parameters:

index - replace element at this index.

e - put this element at specified index.

Returns:

the element previously at the specified position.

Throws:

NullPointerException - if e is null.

IllegalArgumentException - if e does not have a correct message key which matches this list's key.

IndexOutOfBoundsException - if index is out of range (index < 0 || index > this.size()).

UnsupportedOperationException - if this list is marked as read-only.

key

public EMessageKey key()

Returns the list element message key.

Returns:

message key.