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-2014 ForgeRock AS.
016 */
017
018package org.forgerock.openig.heap;
019
020import org.forgerock.json.fluent.JsonValue;
021import org.forgerock.json.fluent.JsonValueException;
022
023/**
024 * Manages a collection of associated objects created and initialized by {@link Heaplet}
025 * objects. A heap object may be lazily initialized, meaning that it or its dependencies
026 * may not be created until first requested from the heap.
027 */
028public interface Heap {
029
030    /**
031     * Returns an object from the heap with a specified name, or {@code null} if no such object exists.
032     *
033     * @param name
034     *         the name of the object in the heap to be retrieved.
035     * @param type
036     *         expected type of the heap object
037     * @param <T>
038     *         expected type of the heap object
039     * @return the requested object from the heap, or {@code null} if no such object exists.
040     * @throws HeapException
041     *         if an exception occurred during creation of the heap object or any of its dependencies.
042     * @throws org.forgerock.json.fluent.JsonValueException
043     *         if a heaplet (or one of its dependencies) has a malformed configuration object.
044     */
045    <T> T get(String name, Class<T> type) throws HeapException;
046
047    /**
048     * Resolves a mandatory object with the specified reference. If the object does not exist or the inline
049     * declaration cannot be build, a {@link JsonValueException} is thrown. If the reference is an inline object
050     * declaration, an anonymous object is added to the heap and returned.
051     * <p>
052     * Equivalent to:
053     * <pre>
054     *     heap.resolve(reference, type, false);
055     * </pre>
056     *
057     * @param reference
058     *         a JSON value containing the name of the heap object to retrieve.
059     * @param type
060     *         the expected type of the heap object.
061     * @param <T>
062     *         expected instance type
063     * @return the specified heap object.
064     * @throws HeapException
065     *         if there was an exception creating the heap object or any of its dependencies.
066     * @throws JsonValueException
067     *         if the name contains {@code null}, is not a string, or the specified heap object could not be retrieved
068     *         or has the wrong type or the reference is not a valid inline declaration.
069     */
070    <T> T resolve(JsonValue reference, Class<T> type) throws HeapException;
071
072    /**
073     * Resolves an object with the specified reference, optionally or not. If the reference is an inline object
074     * declaration, an anonymous object is added to the heap and returned. If the inline declaration cannot be build, a
075     * {@link JsonValueException} is thrown.
076     *
077     * @param reference
078     *         a JSON value containing either the name of the heap object to retrieve or an inline declaration.
079     * @param type
080     *         the expected type of the heap object.
081     * @param optional
082     *         Accept or not a JsonValue that contains {@literal null}.
083     * @param <T>
084     *         expected instance type
085     * @return the referenced heap object or {@code null} if name contains {@code null}.
086     * @throws HeapException
087     *         if there was an exception creating the heap object or any of its dependencies.
088     * @throws JsonValueException
089     *         if the reference is not a string, or the specified heap object has the wrong type or the reference is not
090     *         a valid inline declaration.
091     */
092    <T> T resolve(JsonValue reference, Class<T> type, boolean optional) throws HeapException;
093}