Java tutorial
/* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * * Copyright (c) 1997-2017 Oracle and/or its affiliates. All rights reserved. * * The contents of this file are subject to the terms of either the GNU * General Public License Version 2 only ("GPL") or the Common Development * and Distribution License("CDDL") (collectively, the "License"). You * may not use this file except in compliance with the License. You can * obtain a copy of the License at * https://oss.oracle.com/licenses/CDDL+GPL-1.1 * or LICENSE.txt. See the License for the specific * language governing permissions and limitations under the License. * * When distributing the software, include this License Header Notice in each * file and include the License file at LICENSE.txt. * * GPL Classpath Exception: * Oracle designates this particular file as subject to the "Classpath" * exception as provided by Oracle in the GPL Version 2 section of the License * file that accompanied this code. * * Modifications: * If applicable, add the following below the License Header, with the fields * enclosed by brackets [] replaced by your own identifying information: * "Portions Copyright [year] [name of copyright owner]" * * Contributor(s): * If you wish your version of this file to be governed by only the CDDL or * only the GPL Version 2, indicate your decision by adding "[Contributor] * elects to include this software in this distribution under the [CDDL or GPL * Version 2] license." If you don't indicate a single choice of license, a * recipient has the option to distribute your version of this file under * either the CDDL, the GPL Version 2 or to extend the choice of license to * its licensees as provided above. However, if you add GPL Version 2 code * and therefore, elected the GPL Version 2 license, then the option applies * only if the new code is made subject to such option by the copyright * holder. */ package javax.mail; import java.io.Serializable; import java.util.*; /** * The Flags class represents the set of flags on a Message. Flags * are composed of predefined system flags, and user defined flags. <p> * * A System flag is represented by the <code>Flags.Flag</code> * inner class. A User defined flag is represented as a String. * User flags are case-independent. <p> * * A set of standard system flags are predefined. Most folder * implementations are expected to support these flags. Some * implementations may also support arbitrary user-defined flags. The * <code>getPermanentFlags</code> method on a Folder returns a Flags * object that holds all the flags that are supported by that folder * implementation. <p> * * A Flags object is serializable so that (for example) the * use of Flags objects in search terms can be serialized * along with the search terms. <p> * * <strong>Warning:</strong> * Serialized objects of this class may not be compatible with future * JavaMail API releases. The current serialization support is * appropriate for short term storage. <p> * * The below code sample illustrates how to set, examine, and get the * flags for a message. * <pre> * * Message m = folder.getMessage(1); * m.setFlag(Flags.Flag.DELETED, true); // set the DELETED flag * * // Check if DELETED flag is set on this message * if (m.isSet(Flags.Flag.DELETED)) * System.out.println("DELETED message"); * * // Examine ALL system flags for this message * Flags flags = m.getFlags(); * Flags.Flag[] sf = flags.getSystemFlags(); * for (int i = 0; i < sf.length; i++) { * if (sf[i] == Flags.Flag.DELETED) * System.out.println("DELETED message"); * else if (sf[i] == Flags.Flag.SEEN) * System.out.println("SEEN message"); * ...... * ...... * } * </pre> * <p> * * @see Folder#getPermanentFlags * @author John Mani * @author Bill Shannon */ public class Flags implements Cloneable, Serializable { private int system_flags = 0; // used as a case-independent Set that preserves the original case, // the key is the lowercase flag name and the value is the original private Hashtable<String, String> user_flags = null; private final static int ANSWERED_BIT = 0x01; private final static int DELETED_BIT = 0x02; private final static int DRAFT_BIT = 0x04; private final static int FLAGGED_BIT = 0x08; private final static int RECENT_BIT = 0x10; private final static int SEEN_BIT = 0x20; private final static int USER_BIT = 0x80000000; private static final long serialVersionUID = 6243590407214169028L; /** * This inner class represents an individual system flag. A set * of standard system flag objects are predefined here. */ public static final class Flag { /** * This message has been answered. This flag is set by clients * to indicate that this message has been answered to. */ public static final Flag ANSWERED = new Flag(ANSWERED_BIT); /** * This message is marked deleted. Clients set this flag to * mark a message as deleted. The expunge operation on a folder * removes all messages in that folder that are marked for deletion. */ public static final Flag DELETED = new Flag(DELETED_BIT); /** * This message is a draft. This flag is set by clients * to indicate that the message is a draft message. */ public static final Flag DRAFT = new Flag(DRAFT_BIT); /** * This message is flagged. No semantic is defined for this flag. * Clients alter this flag. */ public static final Flag FLAGGED = new Flag(FLAGGED_BIT); /** * This message is recent. Folder implementations set this flag * to indicate that this message is new to this folder, that is, * it has arrived since the last time this folder was opened. <p> * * Clients cannot alter this flag. */ public static final Flag RECENT = new Flag(RECENT_BIT); /** * This message is seen. This flag is implicitly set by the * implementation when this Message's content is returned * to the client in some form. The <code>getInputStream</code> * and <code>getContent</code> methods on Message cause this * flag to be set. <p> * * Clients can alter this flag. */ public static final Flag SEEN = new Flag(SEEN_BIT); /** * A special flag that indicates that this folder supports * user defined flags. <p> * * The implementation sets this flag. Clients cannot alter * this flag but can use it to determine if a folder supports * user defined flags by using * <code>folder.getPermanentFlags().contains(Flags.Flag.USER)</code>. */ public static final Flag USER = new Flag(USER_BIT); // flags are stored as bits for efficiency private int bit; private Flag(int bit) { this.bit = bit; } } /** * Construct an empty Flags object. */ public Flags() { } /** * Construct a Flags object initialized with the given flags. * * @param flags the flags for initialization */ @SuppressWarnings("unchecked") public Flags(Flags flags) { this.system_flags = flags.system_flags; if (flags.user_flags != null) this.user_flags = (Hashtable) flags.user_flags.clone(); } /** * Construct a Flags object initialized with the given system flag. * * @param flag the flag for initialization */ public Flags(Flag flag) { this.system_flags |= flag.bit; } /** * Construct a Flags object initialized with the given user flag. * * @param flag the flag for initialization */ public Flags(String flag) { user_flags = new Hashtable<>(1); user_flags.put(flag.toLowerCase(Locale.ENGLISH), flag); } /** * Add the specified system flag to this Flags object. * * @param flag the flag to add */ public void add(Flag flag) { system_flags |= flag.bit; } /** * Add the specified user flag to this Flags object. * * @param flag the flag to add */ public void add(String flag) { if (user_flags == null) user_flags = new Hashtable<>(1); user_flags.put(flag.toLowerCase(Locale.ENGLISH), flag); } /** * Add all the flags in the given Flags object to this * Flags object. * * @param f Flags object */ public void add(Flags f) { system_flags |= f.system_flags; // add system flags if (f.user_flags != null) { // add user-defined flags if (user_flags == null) user_flags = new Hashtable<>(1); Enumeration<String> e = f.user_flags.keys(); while (e.hasMoreElements()) { String s = e.nextElement(); user_flags.put(s, f.user_flags.get(s)); } } } /** * Remove the specified system flag from this Flags object. * * @param flag the flag to be removed */ public void remove(Flag flag) { system_flags &= ~flag.bit; } /** * Remove the specified user flag from this Flags object. * * @param flag the flag to be removed */ public void remove(String flag) { if (user_flags != null) user_flags.remove(flag.toLowerCase(Locale.ENGLISH)); } /** * Remove all flags in the given Flags object from this * Flags object. * * @param f the flag to be removed */ public void remove(Flags f) { system_flags &= ~f.system_flags; // remove system flags if (f.user_flags != null) { if (user_flags == null) return; Enumeration<String> e = f.user_flags.keys(); while (e.hasMoreElements()) user_flags.remove(e.nextElement()); } } /** * Remove any flags <strong>not</strong> in the given Flags object. * Useful for clearing flags not supported by a server. If the * given Flags object includes the Flags.Flag.USER flag, all user * flags in this Flags object are retained. * * @param f the flags to keep * @return true if this Flags object changed * @since JavaMail 1.6 */ public boolean retainAll(Flags f) { boolean changed = false; int sf = system_flags & f.system_flags; if (system_flags != sf) { system_flags = sf; changed = true; } // if we have user flags, and the USER flag is not set in "f", // determine which user flags to clear if (user_flags != null && (f.system_flags & USER_BIT) == 0) { if (f.user_flags != null) { Enumeration<String> e = user_flags.keys(); while (e.hasMoreElements()) { String key = e.nextElement(); if (!f.user_flags.containsKey(key)) { user_flags.remove(key); changed = true; } } } else { // if anything in user_flags, throw them away changed = user_flags.size() > 0; user_flags = null; } } return changed; } /** * Check whether the specified system flag is present in this Flags object. * * @param flag the flag to test * @return true of the given flag is present, otherwise false. */ public boolean contains(Flag flag) { return (system_flags & flag.bit) != 0; } /** * Check whether the specified user flag is present in this Flags object. * * @param flag the flag to test * @return true of the given flag is present, otherwise false. */ public boolean contains(String flag) { if (user_flags == null) return false; else return user_flags.containsKey(flag.toLowerCase(Locale.ENGLISH)); } /** * Check whether all the flags in the specified Flags object are * present in this Flags object. * * @param f the flags to test * @return true if all flags in the given Flags object are present, * otherwise false. */ public boolean contains(Flags f) { // Check system flags if ((f.system_flags & system_flags) != f.system_flags) return false; // Check user flags if (f.user_flags != null) { if (user_flags == null) return false; Enumeration<String> e = f.user_flags.keys(); while (e.hasMoreElements()) { if (!user_flags.containsKey(e.nextElement())) return false; } } // If we've made it till here, return true return true; } /** * Check whether the two Flags objects are equal. * * @return true if they're equal */ @Override public boolean equals(Object obj) { if (!(obj instanceof Flags)) return false; Flags f = (Flags) obj; // Check system flags if (f.system_flags != this.system_flags) return false; // Check user flags int size = this.user_flags == null ? 0 : this.user_flags.size(); int fsize = f.user_flags == null ? 0 : f.user_flags.size(); if (size == 0 && fsize == 0) return true; if (f.user_flags != null && this.user_flags != null && fsize == size) return user_flags.keySet().equals(f.user_flags.keySet()); return false; } /** * Compute a hash code for this Flags object. * * @return the hash code */ @Override public int hashCode() { int hash = system_flags; if (user_flags != null) { Enumeration<String> e = user_flags.keys(); while (e.hasMoreElements()) hash += e.nextElement().hashCode(); } return hash; } /** * Return all the system flags in this Flags object. Returns * an array of size zero if no flags are set. * * @return array of Flags.Flag objects representing system flags */ public Flag[] getSystemFlags() { Vector<Flag> v = new Vector<>(); if ((system_flags & ANSWERED_BIT) != 0) v.addElement(Flag.ANSWERED); if ((system_flags & DELETED_BIT) != 0) v.addElement(Flag.DELETED); if ((system_flags & DRAFT_BIT) != 0) v.addElement(Flag.DRAFT); if ((system_flags & FLAGGED_BIT) != 0) v.addElement(Flag.FLAGGED); if ((system_flags & RECENT_BIT) != 0) v.addElement(Flag.RECENT); if ((system_flags & SEEN_BIT) != 0) v.addElement(Flag.SEEN); if ((system_flags & USER_BIT) != 0) v.addElement(Flag.USER); Flag[] f = new Flag[v.size()]; v.copyInto(f); return f; } /** * Return all the user flags in this Flags object. Returns * an array of size zero if no flags are set. * * @return array of Strings, each String represents a flag. */ public String[] getUserFlags() { Vector<String> v = new Vector<>(); if (user_flags != null) { Enumeration<String> e = user_flags.elements(); while (e.hasMoreElements()) v.addElement(e.nextElement()); } String[] f = new String[v.size()]; v.copyInto(f); return f; } /** * Clear all of the system flags. * * @since JavaMail 1.6 */ public void clearSystemFlags() { system_flags = 0; } /** * Clear all of the user flags. * * @since JavaMail 1.6 */ public void clearUserFlags() { user_flags = null; } /** * Returns a clone of this Flags object. */ @SuppressWarnings("unchecked") @Override public Object clone() { Flags f = null; try { f = (Flags) super.clone(); } catch (CloneNotSupportedException cex) { // ignore, can't happen } if (this.user_flags != null) f.user_flags = (Hashtable) this.user_flags.clone(); return f; } /** * Return a string representation of this Flags object. * Note that the exact format of the string is subject to change. */ public String toString() { StringBuilder sb = new StringBuilder(); if ((system_flags & ANSWERED_BIT) != 0) sb.append("\\Answered "); if ((system_flags & DELETED_BIT) != 0) sb.append("\\Deleted "); if ((system_flags & DRAFT_BIT) != 0) sb.append("\\Draft "); if ((system_flags & FLAGGED_BIT) != 0) sb.append("\\Flagged "); if ((system_flags & RECENT_BIT) != 0) sb.append("\\Recent "); if ((system_flags & SEEN_BIT) != 0) sb.append("\\Seen "); if ((system_flags & USER_BIT) != 0) sb.append("\\* "); boolean first = true; if (user_flags != null) { Enumeration<String> e = user_flags.elements(); while (e.hasMoreElements()) { if (first) first = false; else sb.append(' '); sb.append(e.nextElement()); } } if (first && sb.length() > 0) sb.setLength(sb.length() - 1); // smash trailing space return sb.toString(); } /***** public static void main(String argv[]) throws Exception { // a new flags object Flags f1 = new Flags(); f1.add(Flags.Flag.DELETED); f1.add(Flags.Flag.SEEN); f1.add(Flags.Flag.RECENT); f1.add(Flags.Flag.ANSWERED); // check copy constructor with only system flags Flags fc = new Flags(f1); if (f1.equals(fc) && fc.equals(f1)) System.out.println("success"); else System.out.println("fail"); // check clone with only system flags fc = (Flags)f1.clone(); if (f1.equals(fc) && fc.equals(f1)) System.out.println("success"); else System.out.println("fail"); // add a user flag and make sure it still works right f1.add("MyFlag"); // shouldn't be equal here if (!f1.equals(fc) && !fc.equals(f1)) System.out.println("success"); else System.out.println("fail"); // check clone fc = (Flags)f1.clone(); if (f1.equals(fc) && fc.equals(f1)) System.out.println("success"); else System.out.println("fail"); // make sure user flag hash tables are separate fc.add("AnotherFlag"); if (!f1.equals(fc) && !fc.equals(f1)) System.out.println("success"); else System.out.println("fail"); // check copy constructor fc = new Flags(f1); if (f1.equals(fc) && fc.equals(f1)) System.out.println("success"); else System.out.println("fail"); // another new flags object Flags f2 = new Flags(Flags.Flag.ANSWERED); f2.add("MyFlag"); if (f1.contains(Flags.Flag.DELETED)) System.out.println("success"); else System.out.println("fail"); if (f1.contains(Flags.Flag.SEEN)) System.out.println("success"); else System.out.println("fail"); if (f1.contains(Flags.Flag.RECENT)) System.out.println("success"); else System.out.println("fail"); if (f1.contains("MyFlag")) System.out.println("success"); else System.out.println("fail"); if (f2.contains(Flags.Flag.ANSWERED)) System.out.println("success"); else System.out.println("fail"); System.out.println("----------------"); String[] s = f1.getUserFlags(); for (int i = 0; i < s.length; i++) System.out.println(s[i]); System.out.println("----------------"); s = f2.getUserFlags(); for (int i = 0; i < s.length; i++) System.out.println(s[i]); System.out.println("----------------"); if (f1.contains(f2)) // this should be true System.out.println("success"); else System.out.println("fail"); if (!f2.contains(f1)) // this should be false System.out.println("success"); else System.out.println("fail"); Flags f3 = new Flags(); f3.add(Flags.Flag.DELETED); f3.add(Flags.Flag.SEEN); f3.add(Flags.Flag.RECENT); f3.add(Flags.Flag.ANSWERED); f3.add("ANOTHERFLAG"); f3.add("MYFLAG"); f1.add("AnotherFlag"); if (f1.equals(f3)) System.out.println("equals success"); else System.out.println("fail"); if (f3.equals(f1)) System.out.println("equals success"); else System.out.println("fail"); System.out.println("f1 hash code " + f1.hashCode()); System.out.println("f3 hash code " + f3.hashCode()); if (f1.hashCode() == f3.hashCode()) System.out.println("success"); else System.out.println("fail"); } ****/ }