Coverage Report

Coverage Report - com.sourceforge.jpatterns.patterns.bhv.chain.IHierarchyItem

Classes in this File

 package com.sourceforge.jpatterns.patterns.bhv.chain;
 
 import java.io.Serializable;
 import java.util.List;
 
 /**
  * This interface represents the concept of hierarchy composition of objects. This "hierarchy" idea includes relations "parent-child",
  * "container-element" etc. It also could be recursive - when the parent of one "hierarchy item" could be the child of amother parent.
  * etc.
  * <br/>
  * Details:
  * <ul>
  * <li>One parent could have lots of childs</li>
  * <li>One child could belong to lots of parent (some complicated system could allow us to do it). todo: check this and provide some
  * examples.</li>
  * <li></li>
  * </ul>
  * <p/>
  * todo: introduce permissions here
  * todo: think over another type of exception
  *
  * todo: IChainItem (direction of running - left > right, right > left), ITreeItem????
  *
  * todo: !!! (direction of running - left > right, right > left) - may be a field of hierarchy item???? In the case we go below
  * 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
  * interesting loops (we need some kind of engine/runner) not to allow to handlers to run all that by their self.
  *
  * $Author:: zmicer             $<br/>
  */
 public interface IHierarchyItem extends Serializable, Cloneable
 {
     /**
      * @return theoretically each <code>IHierarchyItem</code> could have the type which is returned here.
      *         In the case the implementation of this interface has not type it could return <code>null</code>.
      */
     String getType();
 
     /**
      * @return the <strong>above</strong> parent item of type <code>IHierarchyItem</code>. Null could be returned if this element is
      *         the on top of hierarchy.
      */
     IHierarchyItem getParent();
 
     /**
      * @return the <strong>top</strong> parent item of type <code>IHierarchyItem</code>. Null could be returned if this element is
      *         the on top of hierarchy.
      *
      * @throws UnsupportedOperationException in the case this hierarchy item is not allowed to see the top parent evidently.
      *                                       It depends on the configuration of the system.
      *                                       TODO: introduce this configuration
      */
     IHierarchyItem getTopParent() throws UnsupportedOperationException;
 
     /**
      * @return <code>List</code> of all the parent of this object (<strong>all the above recursive</strong> parents). Empty
      *         <code>List</code> could be returned if this element is the on top of hierarchy.
      *
      * @throws UnsupportedOperationException in the case this hierarchy item is not allowed to see all parent evidently.
      *                                       It depends on the configuration of the system.
      */
     List getAllParents() throws UnsupportedOperationException;
 
     /**
      * Return parent items by type specified. Empty <code>List</code> could be returned if this element is the on top of hierarchy.
      *
      * @param type type of the parents. Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
      *
      * @return <code>List</code> of all the parent of this object (<strong>all the above recursive</strong> parents)
      *
      * @throws UnsupportedOperationException in the case this hierarchy item is not allowed to see all parent by their type evidently.
      *                                       It depends on the configuration of the system.
      */
     List getParents(String type) throws UnsupportedOperationException;
 
     /**
      * @return <code>List</code> of the <code>IHierarchyItem</code> objects. Empty <code>List</code> could be returned if this element
      *         do not have any childs.
      */
     List getChilds();
 
     /**
      * @return <code>List</code> of the <code>IHierarchyItem</code> objects - all the childs of this item (even visible through
      *         recursion). Empty <code>List</code> could be returned if this element
      *         do not have any childs.
      *
      * @throws UnsupportedOperationException in the case this hierarchy item is not allowed to see all the childs evidently.
      *                                       It depends on the configuration of the system.
      */
     List getAllChilds() throws UnsupportedOperationException;
 
     /**
      * Return child items by types.
      *
      * @param type the type using which the returned items are specified. Empty <code>List</code> could be returned if this element
      *         do not have any childs.
      *
      * @return <code>List</code> of the <code>IHierarchyItem</code> objects - all the childs of this item (even visible through
      *         recursion).
      *
      * @throws UnsupportedOperationException in the case this hierarchy item is not allowed to see all the childs evidently.
      *                                       It depends on the configuration of the system.
      */
     List getChilds(String type) throws UnsupportedOperationException;
 
     /**
      * Handle the message passed to the method. In that case the message is just <code>String</code> notifying the
      * <code>IHierarchyItem</code> about some operation.
      * <br/>
      * Examples:<br/>
      * 1. when we need to print to the <code>System.out</code> details about the current item we could pass here smth like
      * "PRINT_THIS_ITEM_INFO". <br/>
      * 2. when we need to print all the items above' info we could pass "PRINT_ALL_THE_ITEMS_INFO".<br/>
      * Notes:
      * <ul>
      * <li>in the future this method could be extended by <code>Object handleMessage(String message, Object messageBody)</code> to
      * allow to pass some message related info - in the case of migrating under Java 5 it would be generics. todo: check it</li>
      * <li>Be noticed that implementation of this method could use {@link IHierarchyItem#getChainHandler(String)} to perform the
      * handle operation or could just compare the message with allowed types and perform smth. without the handler.</li>
      * </ul>
      *
      * @param message the message identifier. Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
      *
      * @throws UnsupportedOperationException in the case this hierarchy item is not allowed to handle the types of message specified
      *                                       here and it the system is not configured to pass the control to the parent item.
      *                                       It depends on the configuration of the system. TODO: introduce this configuration
      */
     void handleMessage(String message) throws UnsupportedOperationException;
 
     /**
      * Handle the message passed to the method. In that case the message is <code>IChainMessage</code> notifying the
      * <code>IHierarchyItem</code> about some operation. This message is rather complicated object cause it allows us to specify the
      * input and output parameters here (it could be done at the each stage of processing the message - at the hierarhical item,
      * at the handler, at the inner runner - depending on the security of the system).
      * <br/>
      * Notes:
      * <ul>
      * <li>Be noticed that implementation of this method could use {@link IHierarchyItem#getChainHandler(IChainMessage)} to perform
      * the handle operation or could just compare the message type with allowed types and perform smth. without the handler.</li>
      * </ul>
      *
      * @param message the message identifier. Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
      *
      * @throws UnsupportedOperationException in the case this hierarchy item is not allowed to handle the types of message specified
      *                                       here and it the system is not configured to pass the control to the parent item.
      *                                       It depends on the configuration of the system. TODO: introduce this configuration
      */
     void handleMessage(IChainMessage message) throws UnsupportedOperationException;
 
     /**
      * Returns the <code>IChainHandler</code> instance appropriate for this message type provided.
      *
      * @param message the type of message for which we have appropriate handler.
      *                Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
      *
      * @return instance of {@link IChainHandler} which could be used for performing this operation
      *
      * @throws UnsupportedOperationException in the case this item doesn't have appropriate handlers
      */
     IChainHandler getChainHandler(String message) throws UnsupportedOperationException;
 
     /**
      * Returns the <code>IChainHandler</code> instance appropriate for this message provided (implementation of the handler could
      * just take into attention the type of message ot could see at the implementation class or the state of message).
      * todo: specify at the configuration of the system opportunity to map the message to the handler by implemented class, and also
      * to introduce types of message for this implementation and allow to map different handler classes to it
      *
      * @param message the message for which we have appropriate handler.
      *                Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
      *
      * @return instance of {@link IChainHandler} which could be used for performing this operation
      *
      * @throws UnsupportedOperationException in the case this item doesn't have appropriate handlers
      */
     IChainHandler getChainHandler(IChainMessage message) throws UnsupportedOperationException;
 }

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		}