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;
018
019import org.forgerock.json.fluent.JsonValue;
020import org.forgerock.openig.heap.HeapException;
021
022/**
023 * A Decorator is responsible for decorating existing object's instances.
024 * <p>
025 * A Decorator cannot change the base type of the provided delegate: for example
026 * if the given instance is a {@code Filter}, the decorated (and returned)
027 * instance must also be a {@code Filter}, sub-classing is ok though.
028 * <p>
029 * Decorators may be "global" to a heap or "local" to a component. Global
030 * decorators are applied to all components within the heap and any child heaps.
031 * Local decorators are only applied to their associated component. Decorators
032 * are applied such that inherited global decorators are applied first, then
033 * global decorators from the current heap, and finally local decorators. This
034 * means that requests will pass through decorators in the order local
035 * decorators, then global decorators, then inherited global decorators.
036 * <p>
037 * <b>Notice:</b> This API is still considered experimental and is subject to
038 * change in subsequent releases.
039 */
040public interface Decorator {
041
042    /**
043     * Returns {@code true} if this decorator is compatible with the provided component type. Note that a return value
044     * of {@code true} does not necessarily indicate that decoration will be performed since it may also depend on other
045     * factors
046     *
047     * @param type
048     *         type under test
049     * @return {@code true} if the decorator can decorate instance of the given type, {@code false} otherwise.
050     */
051    boolean accepts(Class<?> type);
052
053    /**
054     * Decorates the provided {@code delegate} instance with the provided {@code decoratorConfig} configuration.
055     * The implementation should take care of not changing the base type of the delegate.
056     *
057     * @param delegate
058     *         instance to be decorated
059     * @param decoratorConfig
060     *         the decorator configuration to apply
061     * @param context
062     *         contextual information of the decorated instance
063     * @return a decorated instance (or original delegate)
064     * @throws HeapException when decoration fails
065     */
066    Object decorate(Object delegate, JsonValue decoratorConfig, Context context) throws HeapException;
067}