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}