View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *      http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17  package org.apache.commons.validator.util;
    18
    19  import java.io.Serializable;
    20
    21  /***
    22   * Represents a collection of 64 boolean (on/off) flags.  Individual flags
    23   * are represented by powers of 2.  For example,<br/>
    24   * Flag 1 = 1<br/>
    25   * Flag 2 = 2<br/>
    26   * Flag 3 = 4<br/>
    27   * Flag 4 = 8<br/><br/>
    28   * or using shift operator to make numbering easier:<br/>
    29   * Flag 1 = 1 &lt;&lt; 0<br/>
    30   * Flag 2 = 1 &lt;&lt; 1<br/>
    31   * Flag 3 = 1 &lt;&lt; 2<br/>
    32   * Flag 4 = 1 &lt;&lt; 3<br/>
    33   *
    34   * <p>
    35   * There cannot be a flag with a value of 3 because that represents Flag 1
    36   * and Flag 2 both being on/true.
    37   * </p>
    38   *
    39   * @version $Revision: 478334 $ $Date: 2006-11-22 21:31:54 +0000 (Wed, 22 Nov 2006) $
    40   */
    41  public class Flags implements Serializable {
    42
    43      /***
    44       * Represents the current flag state.
    45       */
    46      private long flags = 0;
    47
    48      /***
    49       * Create a new Flags object.
    50       */
    51      public Flags() {
    52          super();
    53      }
    54
    55      /***
    56       * Initialize a new Flags object with the given flags.
    57       *
    58       * @param flags collection of boolean flags to represent.
    59       */
    60      public Flags(long flags) {
    61          super();
    62          this.flags = flags;
    63      }
    64
    65      /***
    66       * Returns the current flags.
    67       *
    68       * @return collection of boolean flags represented.
    69       */
    70      public long getFlags() {
    71          return this.flags;
    72      }
    73
    74      /***
    75       * Tests whether the given flag is on.  If the flag is not a power of 2
    76       * (ie. 3) this tests whether the combination of flags is on.
    77       *
    78       * @param flag Flag value to check.
    79       *
    80       * @return whether the specified flag value is on.
    81       */
    82      public boolean isOn(long flag) {
    83          return (this.flags & flag) > 0;
    84      }
    85
    86      /***
    87       * Tests whether the given flag is off.  If the flag is not a power of 2
    88       * (ie. 3) this tests whether the combination of flags is off.
    89       *
    90       * @param flag Flag value to check.
    91       *
    92       * @return whether the specified flag value is off.
    93       */
    94      public boolean isOff(long flag) {
    95          return (this.flags & flag) == 0;
    96      }
    97
    98      /***
    99       * Turns on the given flag.  If the flag is not a power of 2 (ie. 3) this
    100      * turns on multiple flags.
    101      *
    102      * @param flag Flag value to turn on.
    103      */
    104     public void turnOn(long flag) {
    105         this.flags |= flag;
    106     }
    107
    108     /***
    109      * Turns off the given flag.  If the flag is not a power of 2 (ie. 3) this
    110      * turns off multiple flags.
    111      *
    112      * @param flag Flag value to turn off.
    113      */
    114     public void turnOff(long flag) {
    115         this.flags &= ~flag;
    116     }
    117
    118     /***
    119      * Turn off all flags.
    120      */
    121     public void turnOffAll() {
    122         this.flags = 0;
    123     }
    124
    125     /***
    126      * Turn off all flags.  This is a synonym for <code>turnOffAll()</code>.
    127      * @since Validator 1.1.1
    128      */
    129     public void clear() {
    130         this.flags = 0;
    131     }
    132
    133     /***
    134      * Turn on all 64 flags.
    135      */
    136     public void turnOnAll() {
    137         this.flags = Long.MAX_VALUE;
    138     }
    139
    140     /***
    141      * Clone this Flags object.
    142      *
    143      * @return a copy of this object.
    144      * @see java.lang.Object#clone()
    145      */
    146     public Object clone() {
    147         try {
    148             return super.clone();
    149         } catch(CloneNotSupportedException e) {
    150             throw new RuntimeException("Couldn't clone Flags object.");
    151         }
    152     }
    153
    154     /***
    155      * Tests if two Flags objects are in the same state.
    156      * @param obj object being tested
    157      * @see java.lang.Object#equals(java.lang.Object)
    158      *
    159      * @return whether the objects are equal.
    160      */
    161     public boolean equals(Object obj) {
    162         if (!(obj instanceof Flags)) {
    163             return false;
    164         }
    165
    166         if (obj == this) {
    167             return true;
    168         }
    169
    170         Flags f = (Flags) obj;
    171
    172         return this.flags == f.flags;
    173     }
    174
    175     /***
    176      * The hash code is based on the current state of the flags.
    177      * @see java.lang.Object#hashCode()
    178      *
    179      * @return the hash code for this object.
    180      */
    181     public int hashCode() {
    182         return (int) this.flags;
    183     }
    184
    185     /***
    186      * Returns a 64 length String with the first flag on the right and the
    187      * 64th flag on the left.  A 1 indicates the flag is on, a 0 means it's
    188      * off.
    189      *
    190      * @return string representation of this object.
    191      */
    192     public String toString() {
    193         StringBuffer bin = new StringBuffer(Long.toBinaryString(this.flags));
    194         for (int i = 64 - bin.length(); i > 0; i--) {
    195             bin.insert(0, "0");
    196         }
    197         return bin.toString();
    198     }
    199
    200 }