1 //----------------------------------------------------------------------
2 //
3 // PerfectJPattern: "Design patterns are good but components are better!"
4 // IComposite.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.composite;
22
23 import java.util.*;
24
25 import org.perfectjpattern.core.api.structural.*;
26
27
28 /**
29 * <b>Composite Design Pattern</b>: Compose objects into tree structures to
30 * represent part-whole hierarchies. Composite lets clients treat individual
31 * objects and compositions of objects uniformly. (Gamma et al, Design Patterns)
32 * <br/><br/>
33 *
34 * <b>Responsibility</b> Abstract definition of the "Composite": <br/>
35 * <br/>
36 * <ul>
37 * <li>defines behavior for components having children.</li>
38 * <li>stores child components.</li>
39 * <li>implements child-related operations in the Component interface.</li>
40 * </ul>
41 *
42 * <br/>
43 * Example usage:
44 * <pre><code>
45 * //
46 * // Define a Component type interface (or use an existing one).
47 * //
48 * interface IComponent
49 * {
50 * //--------------------------------------------------------------------
51 * public void
52 * printValue(String aValue);
53 * }
54 *
55 * //
56 * // Implement a simple component.
57 * //
58 * class Component
59 * implements IComponent
60 * {
61 * //--------------------------------------------------------------------
62 * public void
63 * printValue(String aValue)
64 * {
65 * System.out.println(aValue);
66 * }
67 * }
68 *
69 * // create four Component instances
70 * IComponent myComponent1 = new Component();
71 * IComponent myComponent2 = new Component();
72 * IComponent myComponent3 = new Component();
73 * IComponent myComponent4 = new Component();
74 *
75 * // create Composite instance 1
76 * IComposite<IComponent> myComposite1 =
77 * new Composite<IComponent>(IComponent.class);
78 *
79 * // create Composite instance 2
80 * IComposite<IComponent> myComposite2 =
81 * new Composite<IComponent>(IComponent.class);
82 *
83 * // build compositions
84 * myComposite1.addAll(myComponent1, myComponent2);
85 *
86 * // also nest compositions
87 * myComposite2.addAll(myComponent3, myComponent4, myComposite1.
88 * getComponent());
89 *
90 * // call method on the Composite Component view that triggers
91 * // execution over the complete composition
92 * myComposite2.getComponent().printValue("Hello World!");
93 *
94 * </code></pre>
95 *
96 * @param <C> Component element type
97 *
98 * @author <a href="mailto:bravegag@hotmail.com">Giovanni Azua</a>
99 * @version $Revision: 1.0 $ $Date: Nov 18, 2007 9:51:14 PM $
100 */
101 public
102 interface IComposite<C>
103 extends ISurrogate<C>, List<C>
104 {
105 //------------------------------------------------------------------------
106 // public
107 //------------------------------------------------------------------------
108 /**
109 * Appends all of the elements in the specified array to the end of
110 * this list, in the order that they are returned by the specified
111 * collection's iterator (optional operation). The behavior of this
112 * operation is undefined if the specified collection is modified while
113 * the operation is in progress. (Note that this will occur if the
114 * specified collection is this list, and it's nonempty.)
115 *
116 * @param anElements Array containing elements to be added to this list
117 * @return <tt>true</tt> if this list changed as a result of the call
118 * @throws UnsupportedOperationException if the <tt>addAll</tt> operation
119 * is not supported by this list
120 * @throws IllegalArgumentException if the specified collection contains one
121 * or more null elements, or if the specified collection is null
122 * @throws IllegalArgumentException if some property of an element of the
123 * specified collection prevents it from being added to this list
124 * @throws IllegalArgumentException 'anElements' must not be null
125 * @throws IllegalArgumentException 'anElements' must not be empty
126 * @throws IllegalArgumentException 'anElements' must not contain null
127 * Elements
128 * @see #add(Object)
129 */
130 public boolean
131 addAll(C ... anElements)
132 throws IllegalArgumentException;
133 }