All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.mail.FetchProfile Maven / Gradle / Ivy

There is a newer version: 1.6.2
Show newest version
/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 1997-2013 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://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
 * or packager/legal/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 packager/legal/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.util.Vector;

/**
 * Clients use a FetchProfile to list the Message attributes that 
 * it wishes to prefetch from the server for a range of messages.

* * Messages obtained from a Folder are light-weight objects that * typically start off as empty references to the actual messages. * Such a Message object is filled in "on-demand" when the appropriate * get*() methods are invoked on that particular Message. Certain * server-based message access protocols (Ex: IMAP) allow batch * fetching of message attributes for a range of messages in a single * request. Clients that want to use message attributes for a range of * Messages (Example: to display the top-level headers in a headerlist) * might want to use the optimization provided by such servers. The * FetchProfile allows the client to indicate this desire * to the server.

* * Note that implementations are not obligated to support * FetchProfiles, since there might be cases where the backend service * does not allow easy, efficient fetching of such profiles.

* * Sample code that illustrates the use of a FetchProfile is given * below: *

*
 *
 *  Message[] msgs = folder.getMessages();
 *
 *  FetchProfile fp = new FetchProfile();
 *  fp.add(FetchProfile.Item.ENVELOPE);
 *  fp.add("X-mailer");
 *  folder.fetch(msgs, fp);
 *
 * 

* * @see javax.mail.Folder#fetch * @author John Mani * @author Bill Shannon */ public class FetchProfile { private Vector specials; // specials private Vector headers; // vector of header names /** * This inner class is the base class of all items that * can be requested in a FetchProfile. The items currently * defined here are ENVELOPE, CONTENT_INFO * and FLAGS. The UIDFolder interface * defines the UID Item as well.

* * Note that this class only has a protected constructor, therby * restricting new Item types to either this class or subclasses. * This effectively implements a enumeration of allowed Item types. * * @see UIDFolder */ public static class Item { /** * This is the Envelope item.

* * The Envelope is an aggregration of the common attributes * of a Message. Implementations should include the following * attributes: From, To, Cc, Bcc, ReplyTo, Subject and Date. * More items may be included as well.

* * For implementations of the IMAP4 protocol (RFC 2060), the * Envelope should include the ENVELOPE data item. More items * may be included too. */ public static final Item ENVELOPE = new Item("ENVELOPE"); /** * This item is for fetching information about the * content of the message.

* * This includes all the attributes that describe the content * of the message. Implementations should include the following * attributes: ContentType, ContentDisposition, * ContentDescription, Size and LineCount. Other items may be * included as well. */ public static final Item CONTENT_INFO = new Item("CONTENT_INFO"); /** * SIZE is a fetch profile item that can be included in a * FetchProfile during a fetch request to a Folder. * This item indicates that the sizes of the messages in the specified * range should be prefetched.

* * @since JavaMail 1.5 */ public static final Item SIZE = new Item("SIZE"); /** * This is the Flags item. */ public static final Item FLAGS = new Item("FLAGS"); private String name; /** * Constructor for an item. The name is used only for debugging. * * @param name the item name */ protected Item(String name) { this.name = name; } /** * Include the name in the toString return value for debugging. */ public String toString() { return getClass().getName() + "[" + name + "]"; } } /** * Create an empty FetchProfile. */ public FetchProfile() { specials = null; headers = null; } /** * Add the given special item as one of the attributes to * be prefetched. * * @param item the special item to be fetched * @see FetchProfile.Item#ENVELOPE * @see FetchProfile.Item#CONTENT_INFO * @see FetchProfile.Item#FLAGS */ public void add(Item item) { if (specials == null) specials = new Vector(); specials.addElement(item); } /** * Add the specified header-field to the list of attributes * to be prefetched. * * @param headerName header to be prefetched */ public void add(String headerName) { if (headers == null) headers = new Vector(); headers.addElement(headerName); } /** * Returns true if the fetch profile contains the given special item. * * @param item the Item to test * @return true if the fetch profile contains the given special item */ public boolean contains(Item item) { return specials != null && specials.contains(item); } /** * Returns true if the fetch profile contains the given header name. * * @param headerName the header to test * @return true if the fetch profile contains the given header name */ public boolean contains(String headerName) { return headers != null && headers.contains(headerName); } /** * Get the items set in this profile. * * @return items set in this profile */ public Item[] getItems() { if (specials == null) return new Item[0]; Item[] s = new Item[specials.size()]; specials.copyInto(s); return s; } /** * Get the names of the header-fields set in this profile. * * @return headers set in this profile */ public String[] getHeaderNames() { if (headers == null) return new String[0]; String[] s = new String[headers.size()]; headers.copyInto(s); return s; } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy