org.xins.common.collections
Class ProtectedList

java.lang.Object
  java.util.AbstractCollection
      java.util.AbstractList
          org.xins.common.collections.ProtectedList

All Implemented Interfaces:

Cloneable, Collection, List

public final class ProtectedList

extends AbstractList

implements Cloneable

Modifiable List implementaton that can be protected from unauthorized changes.

A secret key must be passed when constructing a ProtectedPropertyReader instance. All modification methods on this object then require this same secret key to be passed, otherwise they fail with an IncorrectSecretKeyException.

Note that the secret key equality is always checked before the other preconditions. This means that if the secret key is incorrect, then the other preconditions will not even be checked. For example, if remove(null, -1) is called, then an IncorrectSecretKeyException is thrown for the mismatching secret key, and not an IndexOutOfBoundsException, for the negative index.

Since:

XINS 1.1.0

Version:

$Revision: 1.14 $ $Date: 2006/08/28 09:12:32 $

Author:

Anthony Goubard, Ernst de Haan

Field Summary

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

ProtectedList(Object secretKey)
Constructs an empty ProtectedList.

ProtectedList(Object secretKey, Collection c)
Constructs a new ProtectedList containing the elements of the specified collection, in the order they are returned by the collection's iterator.

ProtectedList(Object secretKey, int initialCapacity)
Constructs an empty ProtectedList with the specified initial capacity.

Method Summary

void	add(Object secretKey, Object element) Adds the specified element to the list.
Object	clone() Clones this object.
Object	get(int index) Returns the element at the specified position in this list.
void	remove(Object secretKey, int index) Removes the specified element.
int	size() Returns the number of elements in this list.

Methods inherited from class java.util.AbstractList

add, add, addAll, clear, equals, hashCode, indexOf, iterator, lastIndexOf, listIterator, listIterator, remove, removeRange, set, subList

Methods inherited from class java.util.AbstractCollection

addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.List

addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray

Constructor Detail

ProtectedList

public ProtectedList(Object secretKey,
                     int initialCapacity)
              throws IllegalArgumentException

Constructs an empty ProtectedList with the specified initial capacity.

Parameters:

secretKey - the secret key that must be passed to the modification methods in order to be authorized to modify this collection.

initialCapacity - the initial capacity, cannot be a negative number.

Throws:

IllegalArgumentException - if secretKey == null || initialCapacity < 0.

Since:

XINS 1.2.0

ProtectedList

public ProtectedList(Object secretKey)
              throws IllegalArgumentException

Constructs an empty ProtectedList.

Parameters:

secretKey - the secret key that must be passed to the modification methods in order to be authorized to modify this collection, cannot be null.

Throws:

IllegalArgumentException - if secretKey == null.

ProtectedList

public ProtectedList(Object secretKey,
                     Collection c)
              throws IllegalArgumentException

Constructs a new ProtectedList containing the elements of the specified collection, in the order they are returned by the collection's iterator.

Parameters:

secretKey - the secret key that must be passed to the modification methods in order to be authorized to modify this collection, cannot be null.

c - the collection whose elements are to be placed into this list, cannot be null.

Throws:

IllegalArgumentException - if secretKey == null || c == null.

Since:

XINS 1.2.0

Method Detail

get

public Object get(int index)
           throws IndexOutOfBoundsException

Returns the element at the specified position in this list.

Specified by:

get in interface List

Parameters:

index - the index of the element to return, must be >= 0 and < size().

Returns:

the element at the specified position in this list, can be null.

Throws:

IndexOutOfBoundsException - if index < 0 || index >= size().

size

public int size()

Returns the number of elements in this list. If this list contains more than Integer.MAX_VALUE elements, then Integer.MAX_VALUE is returned.

Specified by:

size in interface List

Returns:

the size of this list, maximized to Integer.MAX_VALUE.

add

public void add(Object secretKey,
                Object element)
         throws IncorrectSecretKeyException

Adds the specified element to the list.

The correct secret key must be passed. If it is incorrect, then an IncorrectSecretKeyException is thrown. Note that an identity check is done, not an equality check. So the Object.equals(Object) method is not used, but the == operator is.

Parameters:

secretKey - the secret key, must be identity-equal to the secret key passed to the constructor, cannot be null.

element - the element to add to the list, can be null.

Throws:

IncorrectSecretKeyException - if secretKey does not match the secret key passed to the constructor.

remove

public void remove(Object secretKey,
                   int index)
            throws IncorrectSecretKeyException,
                   IndexOutOfBoundsException

Removes the specified element.

The correct secret key must be passed. If it is incorrect, then an IncorrectSecretKeyException is thrown. Note that an identity check is done, not an equality check. So the Object.equals(Object) method is not used, but the == operator is.

Parameters:

secretKey - the secret key, must be identity-equal to the secret key passed to the constructor, cannot be null.

index - the position of the element to remove, must be >= 0 and < size().

Throws:

IncorrectSecretKeyException - if secretKey does not match the secret key passed to the constructor.

IndexOutOfBoundsException - if index < 0 || index >= size().

clone

public Object clone()

Clones this object. The returned object will be a new ProtectedList instance with the same secret key and the same elements.

Returns:

a new clone of this object, never null.