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 }