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 2014 ForgeRock AS. 015 */ 016 017package org.forgerock.openig.decoration.helper; 018 019import java.util.Map; 020 021import org.forgerock.json.fluent.JsonValue; 022import org.forgerock.openig.decoration.Decorator; 023import org.forgerock.openig.heap.Heap; 024import org.forgerock.openig.heap.HeapException; 025import org.forgerock.openig.heap.Heaplet; 026import org.forgerock.openig.heap.Name; 027 028/** 029 * A base class for decorator heaplets. 030 * <p> 031 * It supports an additional {@link #start()} lifecycle method that is performed within the {@link #create 032 * (Name, JsonValue, Heap)} method. 033 * <p> 034 * This class does not attempt to perform any heap object extraction/resolution when creating objects. 035 */ 036public abstract class DecoratorHeaplet implements Heaplet { 037 /** The fully qualified name of the object to be created. */ 038 protected Name name; 039 /** The heaplet's object configuration object. */ 040 protected JsonValue config; 041 /** Where objects should be put and where object dependencies should be retrieved. */ 042 protected Heap heap; 043 /** The object created by the heaplet's {@link #create()} method. */ 044 protected Decorator object; 045 046 /** 047 * Can only be called by sub-classes. 048 */ 049 protected DecoratorHeaplet() { } 050 051 @Override 052 public Object create(Name name, JsonValue config, Heap heap) throws HeapException { 053 this.name = name; 054 this.config = config.required().expect(Map.class); 055 this.heap = heap; 056 this.object = create(); 057 start(); 058 return object; 059 } 060 061 @Override 062 public void destroy() { 063 // default does nothing 064 } 065 066 /** 067 * Called to request the heaplet create an object. Called by 068 * {@link DecoratorHeaplet#create(Name, JsonValue, Heap)} after initializing 069 * the protected field members. Implementations should parse configuration 070 * but not acquire resources, start threads, or log any initialization 071 * messages. These tasks should be performed by the {@link #start()} method. 072 * 073 * @return The created object. 074 * @throws HeapException 075 * if an exception occurred during creation of the heap object 076 * or any of its dependencies. 077 * @throws org.forgerock.json.fluent.JsonValueException 078 * if the heaplet (or one of its dependencies) has a malformed 079 * configuration. 080 */ 081 public abstract Decorator create() throws HeapException; 082 083 /** 084 * Called to request the heaplet start an object. Called by 085 * {@link DecoratorHeaplet#create(Name, JsonValue, Heap)} after creating and 086 * configuring the object. Implementations should override this method if they need to 087 * acquire resources, start threads, or log any initialization messages. 088 * 089 * @throws HeapException 090 * if an exception occurred while starting the heap object or 091 * any of its dependencies. 092 */ 093 public void start() throws HeapException { 094 // default does nothing 095 } 096}