1 package com.sourceforge.jpatterns.patterns.bhv.chain;
2
3 import java.io.Serializable;
4 import java.util.List;
5
6 /**
7 * This interface represents the concept of hierarchy composition of objects. This "hierarchy" idea includes relations "parent-child",
8 * "container-element" etc. It also could be recursive - when the parent of one "hierarchy item" could be the child of amother parent.
9 * etc.
10 * <br/>
11 * Details:
12 * <ul>
13 * <li>One parent could have lots of childs</li>
14 * <li>One child could belong to lots of parent (some complicated system could allow us to do it). todo: check this and provide some
15 * examples.</li>
16 * <li></li>
17 * </ul>
18 * <p/>
19 * todo: introduce permissions here
20 * todo: think over another type of exception
21 *
22 * todo: IChainItem (direction of running - left > right, right > left), ITreeItem????
23 *
24 * todo: !!! (direction of running - left > right, right > left) - may be a field of hierarchy item???? In the case we go below
25 * the direction is changed to the opposite what allows us to step 3 items below and then to go to the top!!!! - it allows to organize
26 * interesting loops (we need some kind of engine/runner) not to allow to handlers to run all that by their self.
27 *
28 * $Author:: zmicer $<br/>
29 */
30 public interface IHierarchyItem extends Serializable, Cloneable
31 {
32 /**
33 * @return theoretically each <code>IHierarchyItem</code> could have the type which is returned here.
34 * In the case the implementation of this interface has not type it could return <code>null</code>.
35 */
36 String getType();
37
38 /**
39 * @return the <strong>above</strong> parent item of type <code>IHierarchyItem</code>. Null could be returned if this element is
40 * the on top of hierarchy.
41 */
42 IHierarchyItem getParent();
43
44 /**
45 * @return the <strong>top</strong> parent item of type <code>IHierarchyItem</code>. Null could be returned if this element is
46 * the on top of hierarchy.
47 *
48 * @throws UnsupportedOperationException in the case this hierarchy item is not allowed to see the top parent evidently.
49 * It depends on the configuration of the system.
50 * TODO: introduce this configuration
51 */
52 IHierarchyItem getTopParent() throws UnsupportedOperationException;
53
54 /**
55 * @return <code>List</code> of all the parent of this object (<strong>all the above recursive</strong> parents). Empty
56 * <code>List</code> could be returned if this element is the on top of hierarchy.
57 *
58 * @throws UnsupportedOperationException in the case this hierarchy item is not allowed to see all parent evidently.
59 * It depends on the configuration of the system.
60 */
61 List getAllParents() throws UnsupportedOperationException;
62
63 /**
64 * Return parent items by type specified. Empty <code>List</code> could be returned if this element is the on top of hierarchy.
65 *
66 * @param type type of the parents. Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
67 *
68 * @return <code>List</code> of all the parent of this object (<strong>all the above recursive</strong> parents)
69 *
70 * @throws UnsupportedOperationException in the case this hierarchy item is not allowed to see all parent by their type evidently.
71 * It depends on the configuration of the system.
72 */
73 List getParents(String type) throws UnsupportedOperationException;
74
75 /**
76 * @return <code>List</code> of the <code>IHierarchyItem</code> objects. Empty <code>List</code> could be returned if this element
77 * do not have any childs.
78 */
79 List getChilds();
80
81 /**
82 * @return <code>List</code> of the <code>IHierarchyItem</code> objects - all the childs of this item (even visible through
83 * recursion). Empty <code>List</code> could be returned if this element
84 * do not have any childs.
85 *
86 * @throws UnsupportedOperationException in the case this hierarchy item is not allowed to see all the childs evidently.
87 * It depends on the configuration of the system.
88 */
89 List getAllChilds() throws UnsupportedOperationException;
90
91 /**
92 * Return child items by types.
93 *
94 * @param type the type using which the returned items are specified. Empty <code>List</code> could be returned if this element
95 * do not have any childs.
96 *
97 * @return <code>List</code> of the <code>IHierarchyItem</code> objects - all the childs of this item (even visible through
98 * recursion).
99 *
100 * @throws UnsupportedOperationException in the case this hierarchy item is not allowed to see all the childs evidently.
101 * It depends on the configuration of the system.
102 */
103 List getChilds(String type) throws UnsupportedOperationException;
104
105 /**
106 * Handle the message passed to the method. In that case the message is just <code>String</code> notifying the
107 * <code>IHierarchyItem</code> about some operation.
108 * <br/>
109 * Examples:<br/>
110 * 1. when we need to print to the <code>System.out</code> details about the current item we could pass here smth like
111 * "PRINT_THIS_ITEM_INFO". <br/>
112 * 2. when we need to print all the items above' info we could pass "PRINT_ALL_THE_ITEMS_INFO".<br/>
113 * Notes:
114 * <ul>
115 * <li>in the future this method could be extended by <code>Object handleMessage(String message, Object messageBody)</code> to
116 * allow to pass some message related info - in the case of migrating under Java 5 it would be generics. todo: check it</li>
117 * <li>Be noticed that implementation of this method could use {@link IHierarchyItem#getChainHandler(String)} to perform the
118 * handle operation or could just compare the message with allowed types and perform smth. without the handler.</li>
119 * </ul>
120 *
121 * @param message the message identifier. Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
122 *
123 * @throws UnsupportedOperationException in the case this hierarchy item is not allowed to handle the types of message specified
124 * here and it the system is not configured to pass the control to the parent item.
125 * It depends on the configuration of the system. TODO: introduce this configuration
126 */
127 void handleMessage(String message) throws UnsupportedOperationException;
128
129 /**
130 * Handle the message passed to the method. In that case the message is <code>IChainMessage</code> notifying the
131 * <code>IHierarchyItem</code> about some operation. This message is rather complicated object cause it allows us to specify the
132 * input and output parameters here (it could be done at the each stage of processing the message - at the hierarhical item,
133 * at the handler, at the inner runner - depending on the security of the system).
134 * <br/>
135 * Notes:
136 * <ul>
137 * <li>Be noticed that implementation of this method could use {@link IHierarchyItem#getChainHandler(IChainMessage)} to perform
138 * the handle operation or could just compare the message type with allowed types and perform smth. without the handler.</li>
139 * </ul>
140 *
141 * @param message the message identifier. Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
142 *
143 * @throws UnsupportedOperationException in the case this hierarchy item is not allowed to handle the types of message specified
144 * here and it the system is not configured to pass the control to the parent item.
145 * It depends on the configuration of the system. TODO: introduce this configuration
146 */
147 void handleMessage(IChainMessage message) throws UnsupportedOperationException;
148
149 /**
150 * Returns the <code>IChainHandler</code> instance appropriate for this message type provided.
151 *
152 * @param message the type of message for which we have appropriate handler.
153 * Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
154 *
155 * @return instance of {@link IChainHandler} which could be used for performing this operation
156 *
157 * @throws UnsupportedOperationException in the case this item doesn't have appropriate handlers
158 */
159 IChainHandler getChainHandler(String message) throws UnsupportedOperationException;
160
161 /**
162 * Returns the <code>IChainHandler</code> instance appropriate for this message provided (implementation of the handler could
163 * just take into attention the type of message ot could see at the implementation class or the state of message).
164 * todo: specify at the configuration of the system opportunity to map the message to the handler by implemented class, and also
165 * to introduce types of message for this implementation and allow to map different handler classes to it
166 *
167 * @param message the message for which we have appropriate handler.
168 * Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
169 *
170 * @return instance of {@link IChainHandler} which could be used for performing this operation
171 *
172 * @throws UnsupportedOperationException in the case this item doesn't have appropriate handlers
173 */
174 IChainHandler getChainHandler(IChainMessage message) throws UnsupportedOperationException;
175 }