1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
5 *
6 * The contents of this file are subject to the terms of either the GNU
7 * General Public License Version 2 only ("GPL") or the Common Development
8 * and Distribution License("CDDL") (collectively, the "License"). You
9 * may not use this file except in compliance with the License. You can obtain
10 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
11 * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
12 * language governing permissions and limitations under the License.
13 *
14 * When distributing the software, include this License Header Notice in each
15 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
16 * Sun designates this particular file as subject to the "Classpath" exception
17 * as provided by Sun in the GPL Version 2 section of the License file that
18 * accompanied this code. If applicable, add the following below the License
19 * Header, with the fields enclosed by brackets [] replaced by your own
20 * identifying information: "Portions Copyrighted [year]
21 * [name of copyright owner]"
22 *
23 * Contributor(s):
24 *
25 * If you wish your version of this file to be governed by only the CDDL or
26 * only the GPL Version 2, indicate your decision by adding "[Contributor]
27 * elects to include this software in this distribution under the [CDDL or GPL
28 * Version 2] license." If you don't indicate a single choice of license, a
29 * recipient has the option to distribute your version of this file under
30 * either the CDDL, the GPL Version 2 or to extend the choice of license to
31 * its licensees as provided above. However, if you add GPL Version 2 code
32 * and therefore, elected the GPL Version 2 license, then the option applies
33 * only if the new code is made subject to such option by the copyright
34 * holder.
35 */
36
37 /*
38 * @(#)Flags.java 1.22 07/05/14
39 */
40
41 package javax.mail;
42
43 import java.io.Serializable;
44 import java.util;
45
46 /**
47 * The Flags class represents the set of flags on a Message. Flags
48 * are composed of predefined system flags, and user defined flags. <p>
49 *
50 * A System flag is represented by the <code>Flags.Flag</code>
51 * inner class. A User defined flag is represented as a String.
52 * User flags are case-independent. <p>
53 *
54 * A set of standard system flags are predefined. Most folder
55 * implementations are expected to support these flags. Some
56 * implementations may also support arbitrary user-defined flags. The
57 * <code>getPermanentFlags</code> method on a Folder returns a Flags
58 * object that holds all the flags that are supported by that folder
59 * implementation. <p>
60 *
61 * A Flags object is serializable so that (for example) the
62 * use of Flags objects in search terms can be serialized
63 * along with the search terms. <p>
64 *
65 * <strong>Warning:</strong>
66 * Serialized objects of this class may not be compatible with future
67 * JavaMail API releases. The current serialization support is
68 * appropriate for short term storage. <p>
69 *
70 * The below code sample illustrates how to set, examine and get the
71 * flags for a message. <p>
72 * <pre>
73 *
74 * Message m = folder.getMessage(1);
75 * m.setFlag(Flags.Flag.DELETED, true); // set the DELETED flag
76 *
77 * // Check if DELETED flag is set of this message
78 * if (m.isSet(Flags.Flag.DELETED))
79 * System.out.println("DELETED message");
80 *
81 * // Examine ALL system flags for this message
82 * Flags flags = m.getFlags();
83 * Flags.Flag[] sf = flags.getSystemFlags();
84 * for (int i = 0; i < sf.length; i++) {
85 * if (sf[i] == Flags.Flag.DELETED)
86 * System.out.println("DELETED message");
87 * else if (sf[i] == Flags.Flag.SEEN)
88 * System.out.println("SEEN message");
89 * ......
90 * ......
91 * }
92 * </pre>
93 * <p>
94 *
95 * @see Folder#getPermanentFlags
96 * @author John Mani
97 * @author Bill Shannon
98 */
99
100 public class Flags implements Cloneable, Serializable {
101
102 private int system_flags = 0;
103 private Hashtable user_flags = null;
104
105 private final static int ANSWERED_BIT = 0x01;
106 private final static int DELETED_BIT = 0x02;
107 private final static int DRAFT_BIT = 0x04;
108 private final static int FLAGGED_BIT = 0x08;
109 private final static int RECENT_BIT = 0x10;
110 private final static int SEEN_BIT = 0x20;
111 private final static int USER_BIT = 0x80000000;
112
113 private static final long serialVersionUID = 6243590407214169028L;
114
115 /**
116 * This inner class represents an individual system flag. A set
117 * of standard system flag objects are predefined here.
118 */
119 public static final class Flag {
120 /**
121 * This message has been answered. This flag is set by clients
122 * to indicate that this message has been answered to.
123 */
124 public static final Flag ANSWERED = new Flag(ANSWERED_BIT);
125
126 /**
127 * This message is marked deleted. Clients set this flag to
128 * mark a message as deleted. The expunge operation on a folder
129 * removes all messages in that folder that are marked for deletion.
130 */
131 public static final Flag DELETED = new Flag(DELETED_BIT);
132
133 /**
134 * This message is a draft. This flag is set by clients
135 * to indicate that the message is a draft message.
136 */
137 public static final Flag DRAFT = new Flag(DRAFT_BIT);
138
139 /**
140 * This message is flagged. No semantic is defined for this flag.
141 * Clients alter this flag.
142 */
143 public static final Flag FLAGGED = new Flag(FLAGGED_BIT);
144
145 /**
146 * This message is recent. Folder implementations set this flag
147 * to indicate that this message is new to this folder, that is,
148 * it has arrived since the last time this folder was opened. <p>
149 *
150 * Clients cannot alter this flag.
151 */
152 public static final Flag RECENT = new Flag(RECENT_BIT);
153
154 /**
155 * This message is seen. This flag is implicitly set by the
156 * implementation when the this Message's content is returned
157 * to the client in some form. The <code>getInputStream</code>
158 * and <code>getContent</code> methods on Message cause this
159 * flag to be set. <p>
160 *
161 * Clients can alter this flag.
162 */
163 public static final Flag SEEN = new Flag(SEEN_BIT);
164
165 /**
166 * A special flag that indicates that this folder supports
167 * user defined flags. <p>
168 *
169 * The implementation sets this flag. Clients cannot alter
170 * this flag but can use it to determine if a folder supports
171 * user defined flags by using
172 * <code>folder.getPermanentFlags().contains(Flags.Flag.USER)</code>.
173 */
174 public static final Flag USER = new Flag(USER_BIT);
175
176 // flags are stored as bits for efficiency
177 private int bit;
178 private Flag(int bit) {
179 this.bit = bit;
180 }
181 }
182
183
184 /**
185 * Construct an empty Flags object.
186 */
187 public Flags() { }
188
189 /**
190 * Construct a Flags object initialized with the given flags.
191 *
192 * @param flags the flags for initialization
193 */
194 public Flags(Flags flags) {
195 this.system_flags = flags.system_flags;
196 if (flags.user_flags != null)
197 this.user_flags = (Hashtable)flags.user_flags.clone();
198 }
199
200 /**
201 * Construct a Flags object initialized with the given system flag.
202 *
203 * @param flag the flag for initialization
204 */
205 public Flags(Flag flag) {
206 this.system_flags |= flag.bit;
207 }
208
209 /**
210 * Construct a Flags object initialized with the given user flag.
211 *
212 * @param flag the flag for initialization
213 */
214 public Flags(String flag) {
215 user_flags = new Hashtable(1);
216 user_flags.put(flag.toLowerCase(Locale.ENGLISH), flag);
217 }
218
219 /**
220 * Add the specified system flag to this Flags object.
221 *
222 * @param flag the flag to add
223 */
224 public void add(Flag flag) {
225 system_flags |= flag.bit;
226 }
227
228 /**
229 * Add the specified user flag to this Flags object.
230 *
231 * @param flag the flag to add
232 */
233 public void add(String flag) {
234 if (user_flags == null)
235 user_flags = new Hashtable(1);
236 user_flags.put(flag.toLowerCase(Locale.ENGLISH), flag);
237 }
238
239 /**
240 * Add all the flags in the given Flags object to this
241 * Flags object.
242 *
243 * @param f Flags object
244 */
245 public void add(Flags f) {
246 system_flags |= f.system_flags; // add system flags
247
248 if (f.user_flags != null) { // add user-defined flags
249 if (user_flags == null)
250 user_flags = new Hashtable(1);
251
252 Enumeration e = f.user_flags.keys();
253
254 while (e.hasMoreElements()) {
255 String s = (String)e.nextElement();
256 user_flags.put(s, f.user_flags.get(s));
257 }
258 }
259 }
260
261 /**
262 * Remove the specified system flag from this Flags object.
263 *
264 * @param flag the flag to be removed
265 */
266 public void remove(Flag flag) {
267 system_flags &= ~flag.bit;
268 }
269
270 /**
271 * Remove the specified user flag from this Flags object.
272 *
273 * @param flag the flag to be removed
274 */
275 public void remove(String flag) {
276 if (user_flags != null)
277 user_flags.remove(flag.toLowerCase(Locale.ENGLISH));
278 }
279
280 /**
281 * Remove all flags in the given Flags object from this
282 * Flags object.
283 *
284 * @param f the flag to be removed
285 */
286 public void remove(Flags f) {
287 system_flags &= ~f.system_flags; // remove system flags
288
289 if (f.user_flags != null) {
290 if (user_flags == null)
291 return;
292
293 Enumeration e = f.user_flags.keys();
294 while (e.hasMoreElements())
295 user_flags.remove(e.nextElement());
296 }
297 }
298
299 /**
300 * Check whether the specified system flag is present in this Flags object.
301 *
302 * @return true of the given flag is present, otherwise false.
303 */
304 public boolean contains(Flag flag) {
305 return (system_flags & flag.bit) != 0;
306 }
307
308 /**
309 * Check whether the specified user flag is present in this Flags object.
310 *
311 * @return true of the given flag is present, otherwise false.
312 */
313 public boolean contains(String flag) {
314 if (user_flags == null)
315 return false;
316 else
317 return user_flags.containsKey(flag.toLowerCase(Locale.ENGLISH));
318 }
319
320 /**
321 * Check whether all the flags in the specified Flags object are
322 * present in this Flags object.
323 *
324 * @return true if all flags in the given Flags object are present,
325 * otherwise false.
326 */
327 public boolean contains(Flags f) {
328 // Check system flags
329 if ((f.system_flags & system_flags) != f.system_flags)
330 return false;
331
332 // Check user flags
333 if (f.user_flags != null) {
334 if (user_flags == null)
335 return false;
336 Enumeration e = f.user_flags.keys();
337
338 while (e.hasMoreElements()) {
339 if (!user_flags.containsKey(e.nextElement()))
340 return false;
341 }
342 }
343
344 // If we've made it till here, return true
345 return true;
346 }
347
348 /**
349 * Check whether the two Flags objects are equal.
350 *
351 * @return true if they're equal
352 */
353 public boolean equals(Object obj) {
354 if (!(obj instanceof Flags))
355 return false;
356
357 Flags f = (Flags)obj;
358
359 // Check system flags
360 if (f.system_flags != this.system_flags)
361 return false;
362
363 // Check user flags
364 if (f.user_flags == null && this.user_flags == null)
365 return true;
366 if (f.user_flags != null && this.user_flags != null &&
367 f.user_flags.size() == this.user_flags.size()) {
368 Enumeration e = f.user_flags.keys();
369
370 while (e.hasMoreElements()) {
371 if (!this.user_flags.containsKey(e.nextElement()))
372 return false;
373 }
374 return true;
375 }
376
377 return false;
378 }
379
380 /**
381 * Compute a hash code for this Flags object.
382 *
383 * @return the hash code
384 */
385 public int hashCode() {
386 int hash = system_flags;
387 if (user_flags != null) {
388 Enumeration e = user_flags.keys();
389 while (e.hasMoreElements())
390 hash += ((String)e.nextElement()).hashCode();
391 }
392 return hash;
393 }
394
395 /**
396 * Return all the system flags in this Flags object. Returns
397 * an array of size zero if no flags are set.
398 *
399 * @return array of Flags.Flag objects representing system flags
400 */
401 public Flag[] getSystemFlags() {
402 Vector v = new Vector();
403 if ((system_flags & ANSWERED_BIT) != 0)
404 v.addElement(Flag.ANSWERED);
405 if ((system_flags & DELETED_BIT) != 0)
406 v.addElement(Flag.DELETED);
407 if ((system_flags & DRAFT_BIT) != 0)
408 v.addElement(Flag.DRAFT);
409 if ((system_flags & FLAGGED_BIT) != 0)
410 v.addElement(Flag.FLAGGED);
411 if ((system_flags & RECENT_BIT) != 0)
412 v.addElement(Flag.RECENT);
413 if ((system_flags & SEEN_BIT) != 0)
414 v.addElement(Flag.SEEN);
415 if ((system_flags & USER_BIT) != 0)
416 v.addElement(Flag.USER);
417
418 Flag[] f = new Flag[v.size()];
419 v.copyInto(f);
420 return f;
421 }
422
423 /**
424 * Return all the user flags in this Flags object. Returns
425 * an array of size zero if no flags are set.
426 *
427 * @return array of Strings, each String represents a flag.
428 */
429 public String[] getUserFlags() {
430 Vector v = new Vector();
431 if (user_flags != null) {
432 Enumeration e = user_flags.elements();
433
434 while (e.hasMoreElements())
435 v.addElement(e.nextElement());
436 }
437
438 String[] f = new String[v.size()];
439 v.copyInto(f);
440 return f;
441 }
442
443 /**
444 * Returns a clone of this Flags object.
445 */
446 public Object clone() {
447 Flags f = null;
448 try {
449 f = (Flags)super.clone();
450 } catch (CloneNotSupportedException cex) {
451 // ignore, can't happen
452 }
453 if (this.user_flags != null && f != null)
454 f.user_flags = (Hashtable)this.user_flags.clone();
455 return f;
456 }
457
458 /*****
459 public static void main(String argv[]) throws Exception {
460 // a new flags object
461 Flags f1 = new Flags();
462 f1.add(Flags.Flag.DELETED);
463 f1.add(Flags.Flag.SEEN);
464 f1.add(Flags.Flag.RECENT);
465 f1.add(Flags.Flag.ANSWERED);
466
467 // check copy constructor with only system flags
468 Flags fc = new Flags(f1);
469 if (f1.equals(fc) && fc.equals(f1))
470 System.out.println("success");
471 else
472 System.out.println("fail");
473
474 // check clone with only system flags
475 fc = (Flags)f1.clone();
476 if (f1.equals(fc) && fc.equals(f1))
477 System.out.println("success");
478 else
479 System.out.println("fail");
480
481 // add a user flag and make sure it still works right
482 f1.add("MyFlag");
483
484 // shouldn't be equal here
485 if (!f1.equals(fc) && !fc.equals(f1))
486 System.out.println("success");
487 else
488 System.out.println("fail");
489
490 // check clone
491 fc = (Flags)f1.clone();
492 if (f1.equals(fc) && fc.equals(f1))
493 System.out.println("success");
494 else
495 System.out.println("fail");
496
497 // make sure user flag hash tables are separate
498 fc.add("AnotherFlag");
499 if (!f1.equals(fc) && !fc.equals(f1))
500 System.out.println("success");
501 else
502 System.out.println("fail");
503
504 // check copy constructor
505 fc = new Flags(f1);
506 if (f1.equals(fc) && fc.equals(f1))
507 System.out.println("success");
508 else
509 System.out.println("fail");
510
511 // another new flags object
512 Flags f2 = new Flags(Flags.Flag.ANSWERED);
513 f2.add("MyFlag");
514
515 if (f1.contains(Flags.Flag.DELETED))
516 System.out.println("success");
517 else
518 System.out.println("fail");
519
520 if (f1.contains(Flags.Flag.SEEN))
521 System.out.println("success");
522 else
523 System.out.println("fail");
524
525 if (f1.contains(Flags.Flag.RECENT))
526 System.out.println("success");
527 else
528 System.out.println("fail");
529
530 if (f1.contains("MyFlag"))
531 System.out.println("success");
532 else
533 System.out.println("fail");
534
535 if (f2.contains(Flags.Flag.ANSWERED))
536 System.out.println("success");
537 else
538 System.out.println("fail");
539
540
541 System.out.println("----------------");
542
543 String[] s = f1.getUserFlags();
544 for (int i = 0; i < s.length; i++)
545 System.out.println(s[i]);
546 System.out.println("----------------");
547 s = f2.getUserFlags();
548 for (int i = 0; i < s.length; i++)
549 System.out.println(s[i]);
550
551 System.out.println("----------------");
552
553 if (f1.contains(f2)) // this should be true
554 System.out.println("success");
555 else
556 System.out.println("fail");
557
558 if (!f2.contains(f1)) // this should be false
559 System.out.println("success");
560 else
561 System.out.println("fail");
562
563 Flags f3 = new Flags();
564 f3.add(Flags.Flag.DELETED);
565 f3.add(Flags.Flag.SEEN);
566 f3.add(Flags.Flag.RECENT);
567 f3.add(Flags.Flag.ANSWERED);
568 f3.add("ANOTHERFLAG");
569 f3.add("MYFLAG");
570
571 f1.add("AnotherFlag");
572
573 if (f1.equals(f3))
574 System.out.println("equals success");
575 else
576 System.out.println("fail");
577 if (f3.equals(f1))
578 System.out.println("equals success");
579 else
580 System.out.println("fail");
581 System.out.println("f1 hash code " + f1.hashCode());
582 System.out.println("f3 hash code " + f3.hashCode());
583 if (f1.hashCode() == f3.hashCode())
584 System.out.println("success");
585 else
586 System.out.println("fail");
587 }
588 ****/
589 }
Save This Page