Flags


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