org.owasp.esapi.reference
Class AbstractAccessReferenceMap<K>

java.lang.Object
  org.owasp.esapi.reference.AbstractAccessReferenceMap<K>

All Implemented Interfaces:

java.io.Serializable, AccessReferenceMap<K>

Direct Known Subclasses:

IntegerAccessReferenceMap, RandomAccessReferenceMap

public abstract class AbstractAccessReferenceMap<K>
extends java.lang.Object
implements AccessReferenceMap<K>

Abstract Implementation of the AccessReferenceMap that is backed by ConcurrentHashMaps to provide a thread-safe implementation of the AccessReferenceMap. Implementations of this abstract class should implement the #getUniqueReference() method.

Since:

July 21, 2009

Author:

Chris Schmidt ([email protected])

See Also:

Serialized Form

Field Summary

protected java.util.Map<java.lang.Object,K>	dtoi The Direct to Indirect Map
protected java.util.Map<K,java.lang.Object>	itod The Indirect to Direct Map

Constructor Summary

AbstractAccessReferenceMap()
Instantiates a new access reference map.

AbstractAccessReferenceMap(int initialSize)
Instantiates a new access reference map with the specified size allotment to reduce Map resizing overhead.

AbstractAccessReferenceMap(java.util.Set<java.lang.Object> directReferences)
Deprecated. This constructor internally calls the abstract method getUniqueReference(). Since this is a constructor, any subclass that implements getUniqueReference() has not had it's own constructor run. This leads to strange bugs because subclass internal state is initializaed after calls to getUniqueReference() have already happened. If this constructor is desired in a subclass, consider running update(Set) in the subclass constructor instead.

AbstractAccessReferenceMap(java.util.Set<java.lang.Object> directReferences, int initialSize)
Deprecated. This constructor internally calls the abstract method getUniqueReference(). Since this is a constructor, any subclass that implements getUniqueReference() has not had it's own constructor run. This leads to strange bugs because subclass internal state is initializaed after calls to getUniqueReference() have already happened. If this constructor is desired in a subclass, consider running update(Set) in the subclass constructor instead.

Method Summary

<T> K	addDirectReference(T direct) Adds a direct reference to the AccessReferenceMap, then generates and returns an associated indirect reference.
<T> T	getDirectReference(K indirectReference) Get the original direct object reference from an indirect reference.
<T> K	getIndirectReference(T directReference) Get a safe indirect reference to use in place of a potentially sensitive direct object reference.
protected abstract K	getUniqueReference() Returns a Unique Reference Key to be associated with a new directReference being inserted into the AccessReferenceMap.
java.util.Iterator	iterator() Get an iterator through the direct object references.
<T> K	removeDirectReference(T direct) Removes a direct reference and its associated indirect reference from the AccessReferenceMap.
void	update(java.util.Set directReferences) Updates the access reference map with a new set of direct references, maintaining any existing indirect references associated with items that are in the new list.

Methods inherited from class java.lang.Object

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

Field Detail

itod

protected java.util.Map<K,java.lang.Object> itod

The Indirect to Direct Map

dtoi

protected java.util.Map<java.lang.Object,K> dtoi

The Direct to Indirect Map

Constructor Detail

AbstractAccessReferenceMap

public AbstractAccessReferenceMap()

Instantiates a new access reference map. Note that this will create the underlying Maps with an initialSize of ConcurrentHashMap.DEFAULT_INITIAL_CAPACITY and that resizing a Map is an expensive process. Consider using a constructor where the initialSize is passed in to maximize performance of the AccessReferenceMap.

See Also:

AbstractAccessReferenceMap(java.util.Set, int), AbstractAccessReferenceMap(int)

AbstractAccessReferenceMap

public AbstractAccessReferenceMap(int initialSize)

Instantiates a new access reference map with the specified size allotment to reduce Map resizing overhead.

Parameters:

initialSize - The initial size of the underlying maps

AbstractAccessReferenceMap

@Deprecated
public AbstractAccessReferenceMap(java.util.Set<java.lang.Object> directReferences)

Deprecated. This constructor internally calls the abstract method getUniqueReference(). Since this is a constructor, any subclass that implements getUniqueReference() has not had it's own constructor run. This leads to strange bugs because subclass internal state is initializaed after calls to getUniqueReference() have already happened. If this constructor is desired in a subclass, consider running update(Set) in the subclass constructor instead.

Instantiates a new access reference map with a set of direct references.

Parameters:

directReferences - the direct references

AbstractAccessReferenceMap

@Deprecated
public AbstractAccessReferenceMap(java.util.Set<java.lang.Object> directReferences,
                                             int initialSize)

Deprecated. This constructor internally calls the abstract method getUniqueReference(). Since this is a constructor, any subclass that implements getUniqueReference() has not had it's own constructor run. This leads to strange bugs because subclass internal state is initializaed after calls to getUniqueReference() have already happened. If this constructor is desired in a subclass, consider running update(Set) in the subclass constructor instead.

Instantiates a new access reference map with the specified size allotment and initializes the map with the passed in references. Note that if you pass in an initialSize that is less than the size of the passed in set, the map will need to be resized while it is being loaded with the references so it is best practice to verify that the size being passed in is always larger than the size of the set that is being passed in.

Parameters:

directReferences - The references to initialize the access reference map

initialSize - The initial size to set the map to.

Method Detail

getUniqueReference

protected abstract K getUniqueReference()

Returns a Unique Reference Key to be associated with a new directReference being inserted into the AccessReferenceMap.

Returns:

Reference Identifier

iterator

public java.util.Iterator iterator()

Get an iterator through the direct object references. No guarantee is made as to the order of items returned.

Specified by:

iterator in interface AccessReferenceMap<K>

Returns:

the iterator

addDirectReference

public <T> K addDirectReference(T direct)

Adds a direct reference to the AccessReferenceMap, then generates and returns an associated indirect reference.

Specified by:

addDirectReference in interface AccessReferenceMap<K>

Parameters:

direct - the direct reference

Returns:

the corresponding indirect reference

removeDirectReference

public <T> K removeDirectReference(T direct)
                        throws AccessControlException

Removes a direct reference and its associated indirect reference from the AccessReferenceMap.

Specified by:

removeDirectReference in interface AccessReferenceMap<K>

Parameters:

direct - the direct reference to remove

Returns:

the corresponding indirect reference

Throws:

AccessControlException - if the reference does not exist.

update

public final void update(java.util.Set directReferences)

Updates the access reference map with a new set of direct references, maintaining any existing indirect references associated with items that are in the new list. New indirect references could be generated every time, but that might mess up anything that previously used an indirect reference, such as a URL parameter.

Specified by:

update in interface AccessReferenceMap<K>

Parameters:

directReferences - a Set of direct references to add

getIndirectReference

public <T> K getIndirectReference(T directReference)

Get a safe indirect reference to use in place of a potentially sensitive direct object reference. Developers should use this call when building URL's, form fields, hidden fields, etc... to help protect their private implementation information.

Specified by:

getIndirectReference in interface AccessReferenceMap<K>

Parameters:

directReference - the direct reference

Returns:

the indirect reference

getDirectReference

public <T> T getDirectReference(K indirectReference)
                     throws AccessControlException

Get the original direct object reference from an indirect reference. Developers should use this when they get an indirect reference from a request to translate it back into the real direct reference. If an invalid indirect reference is requested, then an AccessControlException is thrown. If a type is implied the requested object will be cast to that type, if the object is not of the requested type, a AccessControlException will be thrown to the caller. For example:

 UserProfile profile = arm.getDirectReference( indirectRef );
 

Will throw a AccessControlException if the object stored in memory is not of type UserProfile. However,

 Object uncastObject = arm.getDirectReference( indirectRef );
 

Will never throw a AccessControlException as long as the object exists. If you are unsure of the object type of that an indirect reference references you should get the uncast object and test for type in the calling code.

 Object uncastProfile = arm.getDirectReference( indirectRef );
 if ( uncastProfile instanceof UserProfile ) {
     UserProfile userProfile = (UserProfile) uncastProfile;
     // ...
 } else {
     EmployeeProfile employeeProfile = (EmployeeProfile) uncastProfile;
     // ...
 }
 

Specified by:

getDirectReference in interface AccessReferenceMap<K>

Parameters:

indirectReference - the indirect reference

Returns:

the direct reference

Throws:

AccessControlException - if no direct reference exists for the specified indirect reference