org.forgerock.openig.heap

Class HeapImpl

java.lang.Object

org.forgerock.openig.heap.HeapImpl

All Implemented Interfaces:

Heap

Direct Known Subclasses:

EnvironmentHeap

public class HeapImpl
extends Object
implements Heap

The concrete implementation of a heap. Provides methods to initialize and destroy a heap. A Heap can be part of a heap hierarchy: if the queried object is not found locally, and if it has a parent, the parent will be queried (and this, recursively until there is no parent anymore).

Field Summary

Fields

Modifier and Type	Field and Description
protected PropertyResolver	propertyResolver Resolves tokens.

Constructor Summary

Constructors

Constructor and Description
HeapImpl(HeapImpl parent, Name name) Builds a new heap that is a child of the given heap.
HeapImpl(HeapImpl parent, Name name, PropertyResolver propertyResolver) Builds a new heap that is a child of the given heap.
HeapImpl(Name name) Builds a root heap (will be referenced by children but has no parent itself).

Method Summary

Modifier and Type	Method and Description
void	addDefaultDeclaration(JsonValue object) Add a default JsonValue object declaration in this heap.
void	destroy() Destroys the objects on the heap and dereferences all associated objects.
<T> T	get(String name, Class<T> type) Returns an object from the heap with a specified name, or null if no such object exists.
<T> List<T>	getAll(Class<T> type) Returns all objects from the heap or its parent (if any), with the specified type or an empty list if no such object exists.
Handler	getHandler() Returns the Handler object referenced by the handler top-level attribute.
Name	getName() Returns the name of this heap.
Bindings	getProperties() Returns the properties from this heap and its parents if any.
JsonValue	init(JsonValue originalConfig, String... reservedFieldNames) Initializes the heap using the given configuration.
void	put(String name, Object object) Puts an object into the heap.
<T> T	resolve(JsonValue reference, Class<T> type) Resolves a mandatory object with the specified reference.
<T> T	resolve(JsonValue reference, Class<T> type, boolean optional) Resolves an object with the specified reference, optionally or not.
void	start() Allocate all objects using each heaplet instance's configuration.

Methods inherited from class java.lang.Object

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

Field Detail

propertyResolver

protected PropertyResolver propertyResolver

Resolves tokens.

Constructor Detail

HeapImpl

public HeapImpl(Name name)

Builds a root heap (will be referenced by children but has no parent itself). Provides a no-op PropertyResolver.

Parameters:

name - local name of this heap

HeapImpl

public HeapImpl(HeapImpl parent,
                Name name)

Builds a new heap that is a child of the given heap.

Parameters:

parent - parent heap (never null).

name - local name of this heap

HeapImpl

public HeapImpl(HeapImpl parent,
                Name name,
                PropertyResolver propertyResolver)

Builds a new heap that is a child of the given heap.

Parameters:

parent - parent heap.

name - local name of this heap (never null)

propertyResolver - initial property resolver to use (never null)

Method Detail

getName

public Name getName()

Description copied from interface: Heap

Returns the name of this heap.

Specified by:

getName in interface Heap

Returns:

the name of this heap.

init

public JsonValue init(JsonValue originalConfig,
                      String... reservedFieldNames)
               throws HeapException

Initializes the heap using the given configuration. Once complete, all heaplets will be loaded.

Parameters:

originalConfig - the configuration root.

reservedFieldNames - the names of reserved top level fields in the originalConfig which should not be parsed as global decorators.

Returns:

the configuration updated to include any token substitutions found in the original configuration.

Throws:

HeapException - if an exception occurs initializing the heap.

JsonValueException - if the configuration object is malformed.

start

public void start()
           throws HeapException

Allocate all objects using each heaplet instance's configuration.

Throws:

HeapException - if any object cannot be created.

addDefaultDeclaration

public void addDefaultDeclaration(JsonValue object)

Add a default JsonValue object declaration in this heap. This method should only be called prior to init(JsonValue, String...): values provided after init() has been called will be ignored. Notice that if the caller add 2 declarations with the same name, that will ends up with an exception thrown when heap will be initialized.

Parameters:

object - Object declaration (has to contains a name attribute)

getAll

public <T> List<T> getAll(Class<T> type)
                   throws HeapException

Description copied from interface: Heap

Returns all objects from the heap or its parent (if any), with the specified type or an empty list if no such object exists. Existing objects in the heap are not overridden by its parents if such exist.

Specified by:

getAll in interface Heap

Type Parameters:

T - expected type of the heap object

Parameters:

type - expected type to search for in the heap or its parent (if any).

Returns:

the requested object from the heap, or from its parent (if any), or an empty list if no such object exists.

Throws:

HeapException - if an exception occurred during the creation of a heap object or any of its dependencies.

get

public <T> T get(String name,
                 Class<T> type)
          throws HeapException

Description copied from interface: Heap

Returns an object from the heap with a specified name, or null if no such object exists.

Specified by:

get in interface Heap

Type Parameters:

T - expected type of the heap object

Parameters:

name - the name of the object in the heap to be retrieved.

type - expected type of the heap object

Returns:

the requested object from the heap, or null if no such object exists.

Throws:

HeapException - if an exception occurred during creation of the heap object or any of its dependencies.

resolve

public <T> T resolve(JsonValue reference,
                     Class<T> type)
              throws HeapException

Description copied from interface: Heap

Resolves a mandatory object with the specified reference. If the object does not exist or the inline declaration cannot be build, a JsonValueException is thrown. If the reference is an inline object declaration, an anonymous object is added to the heap and returned.

Equivalent to:

     
     heap.resolve(reference, type, false);
     
 

Specified by:

resolve in interface Heap

Type Parameters:

T - expected instance type

Parameters:

reference - a JSON value containing the name of the heap object to retrieve.

type - the expected type of the heap object.

Returns:

the specified heap object.

Throws:

HeapException - if there was an exception creating the heap object or any of its dependencies.

resolve

public <T> T resolve(JsonValue reference,
                     Class<T> type,
                     boolean optional)
              throws HeapException

Description copied from interface: Heap

Resolves an object with the specified reference, optionally or not. If the reference is an inline object declaration, an anonymous object is added to the heap and returned. If the inline declaration cannot be build, a JsonValueException is thrown.

Specified by:

resolve in interface Heap

Type Parameters:

T - expected instance type

Parameters:

reference - a JSON value containing either the name of the heap object to retrieve or an inline declaration.

type - the expected type of the heap object.

optional - Accept or not a JsonValue that contains null.

Returns:

the referenced heap object or null if name contains null.

Throws:

HeapException - if there was an exception creating the heap object or any of its dependencies.

put

public void put(String name,
                Object object)

Puts an object into the heap. If an object already exists in the heap with the specified name, it is overwritten.

Parameters:

name - name of the object to be put into the heap.

object - the object to be put into the heap.

destroy

public void destroy()

Destroys the objects on the heap and dereferences all associated objects. This method calls the heaplet destroy method for each object in the heap to provide a chance for system resources to be freed.

getHandler

public Handler getHandler()
                   throws HeapException

Returns the Handler object referenced by the handler top-level attribute. The returned object is fully decorated (including top-level reference decorations).

Returns:

the Handler object referenced by the handler top-level attribute

Throws:

HeapException - if object resolution failed

getProperties

public Bindings getProperties()

Description copied from interface: Heap

Returns the properties from this heap and its parents if any.

Specified by:

getProperties in interface Heap

Returns:

the properties from this heap and its parents if any.