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