1 //----------------------------------------------------------------------
2 //
3 // PerfectJPattern: "Design patterns are good but components are better!"
4 // IDecorator.java Copyright (c) 2009 Giovanni Azua Garcia
5 // bravegag@hotmail.com
6 //
7 // This program is free software; you can redistribute it and/or
8 // modify it under the terms of the GNU General Public License
9 // as published by the Free Software Foundation; either version 3
10 // of the License, or (at your option) any later version.
11 //
12 // This program is distributed in the hope that it will be useful,
13 // but WITHOUT ANY WARRANTY; without even the implied warranty of
14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 // GNU General Public License for more details.
16 //
17 // You should have received a copy of the GNU General Public License
18 // along with this program; if not, see <http://www.gnu.org/licenses/>.
19 //
20 //----------------------------------------------------------------------
21 package org.perfectjpattern.core.api.structural.decorator;
22
23 import org.perfectjpattern.core.api.structural.ISurrogate;
24
25 /**
26 * <b>Decorator Design Pattern</b>: Attach additional responsibilities to an
27 * object dynamically. Decorators provide a flexible alternative to
28 * subclassing for extending functionality. (Gamma et al, Design Patterns)
29 * <br/><br/>
30 *
31 * <b>Responsibility</b> Abstract definition of the "Decorator": <br/>
32 * <br/>
33 * <ul>
34 * <li>maintains a reference to a Component object and defines an interface
35 * that conforms to Component's interface.</li>
36 * </ul>
37 *
38 * <b>Note:</b> Concrete decorator implementations that offer added
39 * functionality i.e. additional methods, must ensure implementing
40 * the delta <code><D> - <C></code> otherwise a
41 * {@link NoSuchMethodError} will occur. This was a deliberate choice towards
42 * more flexibility rather than stronger type safety. Note that {@link #
43 * getComponent()} will return the <code>Decorator</code> and not the
44 * <code>Component</code> type, therefore the concrete <code>Decorator</code>
45 * should implement the delta functionality. See the Decorator example code
46 * for details.
47 * <br/><br/>
48 * @see ISurrogate
49 * @param <C> <code>Component</code> element type. Interface type
50 * being decorated.
51 * @param <D> <code>Decorator</code> element type. This type covers the
52 * following two use-cases:
53 * <ul>
54 * <li>If the Decorator does not offer added functionality then
55 * this type is the same as <C></li>
56 * <li>Otherwise <D> will be a subclass of <C> that
57 * is, it will comply to <C> and offer extra functionality</li>
58 * </ul>
59 * @author <a href="mailto:bravegag@hotmail.com">Giovanni Azua</a>
60 * @version $Revision: 1.0 $ $Date: Nov 25, 2007 3:06:58 PM $
61 */
62 public
63 interface IDecorator<C, D extends C>
64 extends ISurrogate<D>
65 {
66 //------------------------------------------------------------------------
67 // public
68 //------------------------------------------------------------------------
69 /**
70 * Returns the actual decorated <code>Component</code> instance
71 *
72 * @return actual decorated <code>Component</code> instance
73 */
74 public C
75 getDecorated();
76 }