View Javadoc

1   /*
2    * $Header: /home/cvs/jakarta-commons/validator/src/share/org/apache/commons/validator/util/Flags.java,v 1.8 2004/02/21 17:10:30 rleland Exp $
3    * $Revision: 1.8 $
4    * $Date: 2004/02/21 17:10:30 $
5    *
6    * ====================================================================
7    * Copyright 2003-2004 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      public Flags(long flags) {
62          super();
63          this.flags = flags;
64      }
65  
66      /***
67       * Returns the current flags.
68       */
69      public long getFlags() {
70          return this.flags;
71      }
72  
73      /***
74       * Tests whether the given flag is on.  If the flag is not a power of 2 
75       * (ie. 3) this tests whether the combination of flags is on.
76       */
77      public boolean isOn(long flag) {
78          return (this.flags & flag) > 0;
79      }
80  
81      /***
82       * Tests whether the given flag is off.  If the flag is not a power of 2 
83       * (ie. 3) this tests whether the combination of flags is off.
84       */
85      public boolean isOff(long flag) {
86          return (this.flags & flag) == 0;
87      }
88  
89      /***
90       * Turns on the given flag.  If the flag is not a power of 2 (ie. 3) this
91       * turns on multiple flags.
92       */
93      public void turnOn(long flag) {
94          this.flags |= flag;
95      }
96  
97      /***
98       * Turns off the given flag.  If the flag is not a power of 2 (ie. 3) this
99       * turns off multiple flags.
100      */
101     public void turnOff(long flag) {
102         this.flags &= ~flag;
103     }
104 
105     /***
106      * Turn off all flags.
107      */
108     public void turnOffAll() {
109         this.flags = 0;
110     }
111     
112     /***
113      * Turn off all flags.  This is a synonym for <code>turnOffAll()</code>.
114      * @since Validator 1.1.1
115      */
116     public void clear() {
117         this.flags = 0;
118     }
119 
120     /***
121      * Turn on all 64 flags.
122      */
123     public void turnOnAll() {
124         this.flags = Long.MAX_VALUE;
125     }
126 
127     /***
128      * Clone this Flags object.
129      * @see java.lang.Object#clone()
130      */
131     public Object clone() {
132         try {
133             return super.clone();
134         } catch(CloneNotSupportedException e) {
135             throw new RuntimeException("Couldn't clone Flags object.");
136         }
137     }
138 
139     /***
140      * Tests if two Flags objects are in the same state.
141      * @param obj object being tested
142      * @see java.lang.Object#equals(java.lang.Object)
143      */
144     public boolean equals(Object obj) {
145         if (!(obj instanceof Flags)) {
146             return false;
147         }
148 
149         if (obj == this) {
150             return true;
151         }
152 
153         Flags f = (Flags) obj;
154 
155         return this.flags == f.flags;
156     }
157 
158     /***
159      * The hash code is based on the current state of the flags.
160      * @see java.lang.Object#hashCode()
161      */
162     public int hashCode() {
163         return (int) this.flags;
164     }
165 
166     /***
167      * Returns a 64 length String with the first flag on the right and the 
168      * 64th flag on the left.  A 1 indicates the flag is on, a 0 means it's 
169      * off.
170      */
171     public String toString() {
172         StringBuffer bin = new StringBuffer(Long.toBinaryString(this.flags));
173         for (int i = 64 - bin.length(); i > 0; i--) {
174             bin.insert(0, "0");
175         }
176         return bin.toString();
177     }
178 
179 }