javax.mail.FetchProfile Maven / Gradle / Ivy
/*
* 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;
}
}