org.xins.common.collections
Class ProtectedPropertyReader

java.lang.Object
  org.xins.common.collections.AbstractPropertyReader
      org.xins.common.collections.ProtectedPropertyReader

All Implemented Interfaces:

PropertyReader, Serializable

public final class ProtectedPropertyReader

extends AbstractPropertyReader

Modifiable PropertyReader 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 set(null, null) is called, then an IncorrectSecretKeyException is thrown for the mismatching secret key, and not an instance of the superclass IllegalArgumentException, for the missing name argument.

Since:

XINS 1.0.0

Version:

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

Author:

Ernst de Haan

See Also:

Serialized Form

Constructor Summary

ProtectedPropertyReader(Object secretKey)
Constructs a new ProtectedPropertyReader.

Method Summary

void	clear(Object secretKey) Removes all properties.
void	copyFrom(Object secretKey, PropertyReader source) Copies all entries from the specified property reader into this one.
void	remove(Object secretKey, String name) Removes the specified property.
void	set(Object secretKey, String name, String value) Sets the specified property to the specified value.

Methods inherited from class org.xins.common.collections.AbstractPropertyReader

get, getNames, getPropertiesMap, size

Methods inherited from class java.lang.Object

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

Constructor Detail

ProtectedPropertyReader

public ProtectedPropertyReader(Object secretKey)
                        throws IllegalArgumentException

Constructs a new ProtectedPropertyReader.

Parameters:

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

Throws:

IllegalArgumentException - if secretKey == null.

Method Detail

set

public void set(Object secretKey,
                String name,
                String value)
         throws IncorrectSecretKeyException,
                IllegalArgumentException

Sets the specified property to the specified value.

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.

name - the name of the property to set or reset, cannot be null.

value - the value for the property, can be null.

Throws:

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

IllegalArgumentException - if name == null.

remove

public void remove(Object secretKey,
                   String name)
            throws IncorrectSecretKeyException,
                   IllegalArgumentException

Removes the specified property.

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.

name - the name of the property to remove, cannot be null.

Throws:

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

IllegalArgumentException - if name == null.

clear

public void clear(Object secretKey)
           throws IncorrectSecretKeyException

Removes all properties.

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.

Throws:

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

Since:

XINS 1.2.0

copyFrom

public void copyFrom(Object secretKey,
                     PropertyReader source)
              throws IncorrectSecretKeyException,
                     IllegalArgumentException

Copies all entries from the specified property reader into this one.

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.

source - the PropertyReader containing the key/value pairs to copy to this object, cannot be null.

Throws:

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

IllegalArgumentException - if source == null || source == this or if the specified PropertyReader contains an entry which has the name equal to null.

Since:

XINS 1.2.0