View Javadoc

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