/*
* 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.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);
Author: John Mani, Bill Shannon See Also: - fetch.fetch
/**
* Clients use a FetchProfile to list the Message attributes that
* it wishes to prefetch from the server for a range of messages.<p>
*
* 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
* <code>FetchProfile</code> allows the client to indicate this desire
* to the server. <p>
*
* 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. <p>
*
* Sample code that illustrates the use of a FetchProfile is given
* below:
* <blockquote>
* <pre>
*
* Message[] msgs = folder.getMessages();
*
* FetchProfile fp = new FetchProfile();
* fp.add(FetchProfile.Item.ENVELOPE);
* fp.add("X-mailer");
* folder.fetch(msgs, fp);
*
* </pre></blockquote><p>
*
* @see javax.mail.Folder#fetch
* @author John Mani
* @author Bill Shannon
*/
public class FetchProfile {
private Vector<Item> specials; // specials
private Vector<String> 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 Also: - UIDFolder
/**
* This inner class is the base class of all items that
* can be requested in a FetchProfile. The items currently
* defined here are <code>ENVELOPE</code>, <code>CONTENT_INFO</code>
* and <code>FLAGS</code>. The <code>UIDFolder</code> interface
* defines the <code>UID</code> Item as well. <p>
*
* 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.
/**
* This is the Envelope item. <p>
*
* 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. <p>
*
* 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.
/**
* This item is for fetching information about the
* content of the message. <p>
*
* 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
/**
* SIZE is a fetch profile item that can be included in a
* <code>FetchProfile</code> during a fetch request to a Folder.
* This item indicates that the sizes of the messages in the specified
* range should be prefetched. <p>
*
* @since JavaMail 1.5
*/
public static final Item SIZE = new Item("SIZE");
This is the Flags item.
/**
* 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.
Params: - name – the item 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.
/**
* Include the name in the toString return value for debugging.
*/
@Override
public String toString() {
return getClass().getName() + "[" + name + "]";
}
}
Create an empty FetchProfile.
/**
* Create an empty FetchProfile.
*/
public FetchProfile() {
specials = null;
headers = null;
}
Add the given special item as one of the attributes to
be prefetched.
Params: - item – the special item to be fetched
See Also:
/**
* 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.
Params: - headerName – header to be prefetched
/**
* 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.
Params: - item – the Item to test
Returns: true if the fetch profile contains the given special item
/**
* 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.
Params: - headerName – the header to test
Returns: true if the fetch profile contains the given header name
/**
* 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.
Returns: items set in this profile
/**
* 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.
Returns: headers set in this profile
/**
* 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;
}
}