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}