001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2010-2011 ApexIdentity Inc.
015 * Portions Copyright 2011-2015 ForgeRock AS.
016 */
017
018package org.forgerock.openig.heap;
019
020import java.util.List;
021
022import org.forgerock.json.JsonValue;
023import org.forgerock.json.JsonValueException;
024
025/**
026 * Manages a collection of associated objects created and initialized by {@link Heaplet}
027 * objects. A heap object may be lazily initialized, meaning that it or its dependencies
028 * may not be created until first requested from the heap.
029 */
030public interface Heap {
031
032    /**
033     * Returns an object from the heap with a specified name, or {@code null} if no such object exists.
034     *
035     * @param name
036     *         the name of the object in the heap to be retrieved.
037     * @param type
038     *         expected type of the heap object
039     * @param <T>
040     *         expected type of the heap object
041     * @return the requested object from the heap, or {@code null} if no such object exists.
042     * @throws HeapException
043     *         if an exception occurred during creation of the heap object or any of its dependencies.
044     * @throws org.forgerock.json.JsonValueException
045     *         if a heaplet (or one of its dependencies) has a malformed configuration object.
046     */
047    <T> T get(String name, Class<T> type) throws HeapException;
048
049    /**
050     * Returns all objects from the heap or its parent (if any), with the
051     * specified type or an empty list if no such object exists. Existing
052     * objects in the heap are not overridden by its parents if such exist.
053     *
054     * @param type
055     *            expected type to search for in the heap or its parent (if
056     *            any).
057     * @param <T>
058     *            expected type of the heap object
059     * @return the requested object from the heap, or from its parent (if any),
060     *         or an empty list if no such object exists.
061     * @throws HeapException
062     *             if an exception occurred during the creation of a heap object
063     *             or any of its dependencies.
064     * @throws JsonValueException
065     *             if a heaplet (or one of its dependencies) has a malformed
066     *             configuration object.
067     */
068    <T> List<T> getAll(Class<T> type) throws HeapException;
069
070    /**
071     * Resolves a mandatory object with the specified reference. If the object does not exist or the inline
072     * declaration cannot be build, a {@link JsonValueException} is thrown. If the reference is an inline object
073     * declaration, an anonymous object is added to the heap and returned.
074     * <p>
075     * Equivalent to:
076     * <pre>
077     *     {@code
078     *     heap.resolve(reference, type, false);
079     *     }
080     * </pre>
081     *
082     * @param reference
083     *         a JSON value containing the name of the heap object to retrieve.
084     * @param type
085     *         the expected type of the heap object.
086     * @param <T>
087     *         expected instance type
088     * @return the specified heap object.
089     * @throws HeapException
090     *         if there was an exception creating the heap object or any of its dependencies.
091     * @throws JsonValueException
092     *         if the name contains {@code null}, is not a string, or the specified heap object could not be retrieved
093     *         or has the wrong type or the reference is not a valid inline declaration.
094     */
095    <T> T resolve(JsonValue reference, Class<T> type) throws HeapException;
096
097    /**
098     * Resolves an object with the specified reference, optionally or not. If the reference is an inline object
099     * declaration, an anonymous object is added to the heap and returned. If the inline declaration cannot be build, a
100     * {@link JsonValueException} is thrown.
101     *
102     * @param reference
103     *         a JSON value containing either the name of the heap object to retrieve or an inline declaration.
104     * @param type
105     *         the expected type of the heap object.
106     * @param optional
107     *         Accept or not a JsonValue that contains {@literal null}.
108     * @param <T>
109     *         expected instance type
110     * @return the referenced heap object or {@code null} if name contains {@code null}.
111     * @throws HeapException
112     *         if there was an exception creating the heap object or any of its dependencies.
113     * @throws JsonValueException
114     *         if the reference is not a string, or the specified heap object has the wrong type or the reference is not
115     *         a valid inline declaration.
116     */
117    <T> T resolve(JsonValue reference, Class<T> type, boolean optional) throws HeapException;
118}