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.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.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}