com.sourceforge.jpatterns.patterns.bhv.chain
Interface IHierarchyItem

All Superinterfaces:

Cloneable, Serializable

public interface IHierarchyItem
extends Serializable, Cloneable

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.
Details:

• One parent could have lots of childs
• One child could belong to lots of parent (some complicated system could allow us to do it). todo: check this and provide some examples.

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 $

Method Summary

List	getAllChilds()
List	getAllParents()
IChainHandler	getChainHandler(IChainMessage message) Returns the IChainHandler 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).
IChainHandler	getChainHandler(String message) Returns the IChainHandler instance appropriate for this message type provided.
List	getChilds()
List	getChilds(String type) Return child items by types.
IHierarchyItem	getParent()
List	getParents(String type) Return parent items by type specified.
IHierarchyItem	getTopParent()
String	getType()
void	handleMessage(IChainMessage message) Handle the message passed to the method.
void	handleMessage(String message) Handle the message passed to the method.

Method Detail

getType

String getType()

Returns:

theoretically each IHierarchyItem could have the type which is returned here. In the case the implementation of this interface has not type it could return null.

getParent

IHierarchyItem getParent()

Returns:

the above parent item of type IHierarchyItem. Null could be returned if this element is the on top of hierarchy.

getTopParent

IHierarchyItem getTopParent()
                            throws UnsupportedOperationException

Returns:

the top parent item of type IHierarchyItem. 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

getAllParents

List getAllParents()
                   throws UnsupportedOperationException

Returns:

List of all the parent of this object (all the above recursive parents). Empty List 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.

getParents

List getParents(String type)
                throws UnsupportedOperationException

Return parent items by type specified. Empty List could be returned if this element is the on top of hierarchy.

Parameters:

type - type of the parents. Can not be null (otherwise IllegalArgumentException would appear).

Returns:

List of all the parent of this object (all the above recursive 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.

getChilds

List getChilds()

Returns:

List of the IHierarchyItem objects. Empty List could be returned if this element do not have any childs.

getAllChilds

List getAllChilds()
                  throws UnsupportedOperationException

Returns:

List of the IHierarchyItem objects - all the childs of this item (even visible through recursion). Empty List 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.

getChilds

List getChilds(String type)
               throws UnsupportedOperationException

Return child items by types.

Parameters:

type - the type using which the returned items are specified. Empty List could be returned if this element do not have any childs.

Returns:

List of the IHierarchyItem 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.

handleMessage

void handleMessage(String message)
                   throws UnsupportedOperationException

Handle the message passed to the method. In that case the message is just String notifying the IHierarchyItem about some operation.
Examples:
1. when we need to print to the System.out details about the current item we could pass here smth like "PRINT_THIS_ITEM_INFO".
2. when we need to print all the items above' info we could pass "PRINT_ALL_THE_ITEMS_INFO".
Notes:

• in the future this method could be extended by Object handleMessage(String message, Object messageBody) to allow to pass some message related info - in the case of migrating under Java 5 it would be generics. todo: check it
• Be noticed that implementation of this method could use getChainHandler(String) to perform the handle operation or could just compare the message with allowed types and perform smth. without the handler.

Parameters:

message - the message identifier. Can not be null (otherwise IllegalArgumentException 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

handleMessage

void handleMessage(IChainMessage message)
                   throws UnsupportedOperationException

Handle the message passed to the method. In that case the message is IChainMessage notifying the IHierarchyItem 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).
Notes:

• Be noticed that implementation of this method could use getChainHandler(IChainMessage) to perform the handle operation or could just compare the message type with allowed types and perform smth. without the handler.

Parameters:

message - the message identifier. Can not be null (otherwise IllegalArgumentException 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

getChainHandler

IChainHandler getChainHandler(String message)
                              throws UnsupportedOperationException

Returns the IChainHandler instance appropriate for this message type provided.

Parameters:

message - the type of message for which we have appropriate handler. Can not be null (otherwise IllegalArgumentException would appear).

Returns:

instance of IChainHandler which could be used for performing this operation

Throws:

UnsupportedOperationException - in the case this item doesn't have appropriate handlers

getChainHandler

IChainHandler getChainHandler(IChainMessage message)
                              throws UnsupportedOperationException

Returns the IChainHandler 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

Parameters:

message - the message for which we have appropriate handler. Can not be null (otherwise IllegalArgumentException would appear).

Returns:

instance of IChainHandler which could be used for performing this operation

Throws:

UnsupportedOperationException - in the case this item doesn't have appropriate handlers