Coverage Report - com.sourceforge.jpatterns.patterns.bhv.chain.IHierarchyItem
 
Classes in this File Line Coverage Branch Coverage Complexity
IHierarchyItem
N/A 
N/A 
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  
 }