Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||||
IHierarchyItem |
|
| 1.0;1 |
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 | } |