package propagation;

/**
 * The <code>StateItem</code> interface represents an electrical switch to
 * supervise, e.g., a sensor's component like power supply, sensor unit, network IF, etc.
 * A <code>StateItem</code> is distinguished by item id in the associated parent <code>Node</code>.
 * The state field represents device's state (either it's ok or failure). It has 4 digits.
 * <p/>
 * The first digit represents if the state item is summary (overall status) or not. A summary state item
 * represents the overall status of that node, e.g., if any part of the items are malfucntioning, the
 * summary item may (or may not) show failure (depending on the rule).
 * 1 means physical item and 2 means summary item.<p>
 * If it is physical item, then
 * the fourth digit signifies whether it is failure or not.
 * 0 means ok, and
 * 1 means failure.
 * The second and third digits represent the state's severity, repsectively. The larger
 * number means the more serious the failure.
 * <p/>
 * If it's summary item,
 * then third and fourth digits represent the state's severity. The severity of 0
 * means there is no failure overall, e.g., the overall <code>Node</code> is functioning.
 * <pre>
 * 1041 : physical failure, severity is 4
 * 1031 : physical failure, severity is 3
 * 2000 : summary state, not failure
 * 2004 : summary is failure, severity is 4
 * </pre>
 *
 * @author y-komori
 * @@org.jboss.cache.aop.InstanceOfAopMarker
 */
public interface StateItem {
   /**
    * A constant which represents a state is changed.
    */
   public static final boolean STATE_CHANGED = true;

   /**
    * A constant which represents a state is not changed.
    */
   public static final boolean STATE_NOT_CHANGED = false;

   /**
    * Returns this <code>StateItem</code>'s ID.
    * The item ID is given only once when a StateItem instance is created.
    *
    * @return this <code>StateItem</code>'s item ID
    */
   public long getItemId();

   /**
    * Sets the specified state to this <code>StateItem</code> object.
    * As a result of setting the state, returns
    * <code>StateItem.STATE_CHANGED</code> if it's state is changed from it's
    * old state.
    * Returns <code>StateItem.STATE_NOT_CHANGED</code> if it's state stays
    * constant.
    *
    * @param state a state to be set.
    * @return <code>StateItem.STATE_CHANGED</code> if it's state is changed
    *         from it's old state, <code>StateItem.STATE_NOT_CHANGED</code>
    *         if it's state stays constant.
    */
   public boolean setState(long state);

   /**
    * Returns this StateItem's state.
    *
    * @return this StateItem's state
    */
   public long getState();

   /**
    * A logical name to associate with this item.
    * @param name
    */ 
   public void setName(String name);

   public String getName();
}
