fipaos.util
Class FlagHandler

java.lang.Object
  |
  +--fipaos.util.FlagHandler
All Implemented Interfaces:
java.io.Serializable

public class FlagHandler
extends java.lang.Object
implements java.io.Serializable

FlagHandler provides an easy method of using bitwise flags to store state, minimising the use of multiple booleans for state management. FlagHandler is thread safe - no race conditions can occur when accessing the same FlagHandler from multiple threads.

See Also:
Serialized Form

Constructor Summary
FlagHandler()
          Constructs an empty FlagHandler - there are intially no flags set or known about.
 
Method Summary
 boolean addFlag(java.lang.String flag)
          Add a new flag to the handler.
 boolean addFlag(java.lang.String flag, java.lang.String mxflag)
          Add a new flag to the handler.
 boolean addFlag(java.lang.String flag, java.lang.String[] mxflags)
          Add a new flag to the handler.
 void clearAllFlags()
          Sets all of the flags to false (clears every flag);
 void clearFlag(java.lang.String flag)
          Clears a flag (set it to false).
 boolean containsFlag(java.lang.String flag)
          Checks to see if this handler contains the specified flag.
 int getNumberOfFlags()
          Returns the number of flags currently being handled.
 void setFlag(java.lang.String flag)
          Sets a flag to true, and sets any mutually exclusive flags to false.
 void setMutualExclusions(java.lang.String flag, java.lang.String[] mxflags)
          Adds a set of mutually exclusive flag markers to the specified flag.
 boolean testFlag(java.lang.String flag)
          Tests the value of the flag.
 void toggleFlag(java.lang.String flag)
          Toggles the value of the flag, clearing any mutually exclusive flags if this flag is set.
 java.lang.String toString()
          Returns a string based representation of the status of every flag in the handler.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

FlagHandler

public FlagHandler()
Constructs an empty FlagHandler - there are intially no flags set or known about. Add new flags using addFlag(), and then set, clear and test them using the appropriate methods.
Method Detail

addFlag

public boolean addFlag(java.lang.String flag)
Add a new flag to the handler. This will not set the flag, it will simply make the handler aware of the flag, and assign the flag a bit position. Once added, a flag cannot be removed.
Parameters:
flag - The flag name as a String. Flags are always referenced by string to ease programmer effort.
Returns:
True if the flag was added, false if the flag name is already in use or an error occurs

addFlag

public boolean addFlag(java.lang.String flag,
                       java.lang.String mxflag)
Add a new flag to the handler. This will not set the flag, it will simply make the handler aware of the flag, and assign the flag a bit position. Once added, a flag cannot be removed.
This method also sets the flag to be mutually exclusive with the second flag specified. This means that if this flag is set, then the mutually exclusive flag will be cleared automatically, and vice versa. More mutual exclusions can be set using the setMutualExclusions() method. The semantics of the mutual exclusion mean that clearing a flag will not set any mutually exclusive flags, even though setting a flag clears the mutually exclusive flags.
Parameters:
flag - The flag name as a String. Flags are always referenced by string to ease programmer effort.
mxflag - Another flag that this flag is mutually exclusive with
Returns:
True if the flag was added, false if the flag name is already in use or an error occurs

addFlag

public boolean addFlag(java.lang.String flag,
                       java.lang.String[] mxflags)
Add a new flag to the handler. This will not set the flag, it will simply make the handler aware of the flag, and assign the flag a bit position. Once added, a flag cannot be removed.
This method also sets the flag to be mutually exclusive with the array of flags specified. This means that if this flag is set, then the mutually exclusive flags will be cleared automatically, and vice versa. More mutual exclusions can be set using the setMutualExclusions() method. The semantics of the mutual exclusion mean that clearing a flag will not set any mutually exclusive flags, even though setting a flag clears the mutually exclusive flags.
Parameters:
flag - The flag name as a String. Flags are always referenced by string to ease programmer effort.
mxflags - An array of mutually exclusive flags
Returns:
True if the flag was added, false if the flag name is already in use or an error occurs

setFlag

public void setFlag(java.lang.String flag)
Sets a flag to true, and sets any mutually exclusive flags to false.
Parameters:
flag - The flag name as a String. Flags are always referenced by string to ease programmer effort.

clearFlag

public void clearFlag(java.lang.String flag)
Clears a flag (set it to false).
Parameters:
flag - The flag name as a String. Flags are always referenced by string to ease programmer effort.

testFlag

public boolean testFlag(java.lang.String flag)
Tests the value of the flag.
Parameters:
flag - The flag name as a String. Flags are always referenced by string to ease programmer effort.
Returns:
True is the flag is set, false if it not or is not present

toggleFlag

public void toggleFlag(java.lang.String flag)
Toggles the value of the flag, clearing any mutually exclusive flags if this flag is set.
Note: If this flag is cleared then the mutually exclusive flags are not set.
Parameters:
flag - The flag name as a String. Flags are always referenced by string to ease programmer effort.

containsFlag

public boolean containsFlag(java.lang.String flag)
Checks to see if this handler contains the specified flag.
Parameters:
flag - The flag name as a String. Flags are always referenced by string to ease programmer effort.
Returns:
True if the flag is in this handler, false otherwise

clearAllFlags

public void clearAllFlags()
Sets all of the flags to false (clears every flag);

getNumberOfFlags

public int getNumberOfFlags()
Returns the number of flags currently being handled. Useful if you want to calculate the number of flags that can still be put into this handler.
Returns:
The number of flags currently in use by this handler

setMutualExclusions

public void setMutualExclusions(java.lang.String flag,
                                java.lang.String[] mxflags)
Adds a set of mutually exclusive flag markers to the specified flag. These will automatically be cleared when this flag is set. If this flag is cleared then these flags are not automatically set.
Parameters:
flag - The flag to add to
mxflags - The mutually exclusive flag names

toString

public java.lang.String toString()
Returns a string based representation of the status of every flag in the handler.
Note: The list of flags returned is not sorted.
Overrides:
toString in class java.lang.Object
Returns:
A string representation of the status of the flags