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.proxy;
22
23 import org.perfectjpattern.core.api.structural.*;
24
25 /**
26 * <b>Proxy Design Pattern</b>: Provide a surrogate or placeholder for
27 * another object to control access to it. (Gamma et al, Design Patterns)
28 * <br/><br/>
29 *
30 * <b>Responsibility</b> Abstract definition of the "Proxy": <br/>
31 * <br/>
32 * <ul>
33 * <li>maintains a reference that lets the proxy access the real subject.
34 * Proxy may refer to a Subject if the RealSubject and Subject interfaces are
35 * the same.</li>
36 * <li>provides an interface identical to Subject's so that a proxy can be
37 * substituted for for the real subject.</li>
38 * <li>controls access to the real subject and may be responsible for
39 * creating and deleting it.</li>
40 * <li>other responsibilites depend on the kind of proxy:
41 * <ul>
42 * <li>remote proxies are responsible for encoding a request and
43 * its arguments and for sending the encoded request to the real
44 * subject in a different address space.</li>
45 * <li>virtual proxies may cache additional information about the
46 * real subject so that they can postpone accessing it. For example,
47 * the ImageProxy from the Motivation caches the real images's
48 * extent.</li>
49 * <li>protection proxies check that the caller has the access
50 * permissions required to perform a request.</li>
51 * </ul>
52 * </ul>
53 *
54 * @param <S> <code>Subject</code> element type
55 *
56 * @author <a href="mailto:bravegag@hotmail.com">Giovanni Azua</a>
57 * @version $Revision: 1.0 $ $Date: Nov 25, 2007 3:06:58 PM $
58 */
59 public
60 interface IProxy<S>
61 extends ISurrogate<S>
62 {
63 //------------------------------------------------------------------------
64 // public
65 //------------------------------------------------------------------------
66 /**
67 * Returns the <code>Proxy</code> wrapper instance
68 *
69 * @return <code>Proxy</code> wrapper instance
70 */
71 public S
72 getSubject();
73
74 //------------------------------------------------------------------------
75 /**
76 * Returns the actual wrapped <code>Subject</code> instance
77 *
78 * @return actual wrapped <code>Subject</code> instance
79 */
80 public S
81 getRealSubject();
82 }