Package: FetchProfile

FetchProfile

name	instruction	branch	complexity	line	method
FetchProfile()	M: 9 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 4 C: 0 0%	M: 1 C: 0 0%
add(FetchProfile.Item)	M: 13 C: 0 0%	M: 2 C: 0 0%	M: 2 C: 0 0%	M: 4 C: 0 0%	M: 1 C: 0 0%
add(String)	M: 13 C: 0 0%	M: 2 C: 0 0%	M: 2 C: 0 0%	M: 4 C: 0 0%	M: 1 C: 0 0%
contains(FetchProfile.Item)	M: 12 C: 0 0%	M: 4 C: 0 0%	M: 3 C: 0 0%	M: 1 C: 0 0%	M: 1 C: 0 0%
contains(String)	M: 12 C: 0 0%	M: 4 C: 0 0%	M: 3 C: 0 0%	M: 1 C: 0 0%	M: 1 C: 0 0%
getHeaderNames()	M: 17 C: 0 0%	M: 2 C: 0 0%	M: 2 C: 0 0%	M: 5 C: 0 0%	M: 1 C: 0 0%
getItems()	M: 17 C: 0 0%	M: 2 C: 0 0%	M: 2 C: 0 0%	M: 5 C: 0 0%	M: 1 C: 0 0%

Coverage

1: /*
2: * Copyright (c) 1997, 2023 Oracle and/or its affiliates. All rights reserved.
3: *
4: * This program and the accompanying materials are made available under the
5: * terms of the Eclipse Public License v. 2.0, which is available at
6: * http://www.eclipse.org/legal/epl-2.0.
7: *
8: * This Source Code may also be made available under the following Secondary
9: * Licenses when the conditions for such availability set forth in the
10: * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
11: * version 2 with the GNU Classpath Exception, which is available at
12: * https://www.gnu.org/software/classpath/license.html.
13: *
14: * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
15: */
16:
17: package jakarta.mail;
18:
19: import java.util.Vector;
20:
21: /**
22: * Clients use a FetchProfile to list the Message attributes that
23: * it wishes to prefetch from the server for a range of messages.<p>
24: *
25: * Messages obtained from a Folder are light-weight objects that
26: * typically start off as empty references to the actual messages.
27: * Such a Message object is filled in "on-demand" when the appropriate
28: * get*() methods are invoked on that particular Message. Certain
29: * server-based message access protocols (Ex: IMAP) allow batch
30: * fetching of message attributes for a range of messages in a single
31: * request. Clients that want to use message attributes for a range of
32: * Messages (Example: to display the top-level headers in a headerlist)
33: * might want to use the optimization provided by such servers. The
34: * <code>FetchProfile</code> allows the client to indicate this desire
35: * to the server. <p>
36: *
37: * Note that implementations are not obligated to support
38: * FetchProfiles, since there might be cases where the backend service
39: * does not allow easy, efficient fetching of such profiles. <p>
40: *
41: * Sample code that illustrates the use of a FetchProfile is given
42: * below:
43: * <blockquote>
44: * <pre>
45: *
46: * Message[] msgs = folder.getMessages();
47: *
48: * FetchProfile fp = new FetchProfile();
49: * fp.add(FetchProfile.Item.ENVELOPE);
50: * fp.add("X-mailer");
51: * folder.fetch(msgs, fp);
52: *
53: * </pre></blockquote>
54: *
55: * @author John Mani
56: * @author Bill Shannon
57: * @see jakarta.mail.Folder#fetch
58: */
59:
60: public class FetchProfile {
61:
62: private Vector<Item> specials; // specials
63: private Vector<String> headers; // vector of header names
64:
65: /**
66: * This inner class is the base class of all items that
67: * can be requested in a FetchProfile. The items currently
68: * defined here are <code>ENVELOPE</code>, <code>CONTENT_INFO</code>
69: * and <code>FLAGS</code>. The <code>UIDFolder</code> interface
70: * defines the <code>UID</code> Item as well. <p>
71: *
72: * Note that this class only has a protected constructor, therby
73: * restricting new Item types to either this class or subclasses.
74: * This effectively implements a enumeration of allowed Item types.
75: *
76: * @see UIDFolder
77: */
78:
79: public static class Item {
80: /**
81: * This is the Envelope item. <p>
82: *
83: * The Envelope is an aggregration of the common attributes
84: * of a Message. Implementations should include the following
85: * attributes: From, To, Cc, Bcc, ReplyTo, Subject and Date.
86: * More items may be included as well. <p>
87: *
88: * For implementations of the IMAP4 protocol (RFC 2060), the
89: * Envelope should include the ENVELOPE data item. More items
90: * may be included too.
91: */
92: public static final Item ENVELOPE = new Item("ENVELOPE");
93:
94: /**
95: * This item is for fetching information about the
96: * content of the message. <p>
97: *
98: * This includes all the attributes that describe the content
99: * of the message. Implementations should include the following
100: * attributes: ContentType, ContentDisposition,
101: * ContentDescription, Size and LineCount. Other items may be
102: * included as well.
103: */
104: public static final Item CONTENT_INFO = new Item("CONTENT_INFO");
105:
106: /**
107: * SIZE is a fetch profile item that can be included in a
108: * <code>FetchProfile</code> during a fetch request to a Folder.
109: * This item indicates that the sizes of the messages in the specified
110: * range should be prefetched.
111: *
112: * @since JavaMail 1.5
113: */
114: public static final Item SIZE = new Item("SIZE");
115:
116: /**
117: * This is the Flags item.
118: */
119: public static final Item FLAGS = new Item("FLAGS");
120:
121: private String name;
122:
123: /**
124: * Constructor for an item. The name is used only for debugging.
125: *
126: * @param name the item name
127: */
128: protected Item(String name) {
129: this.name = name;
130: }
131:
132: /**
133: * Include the name in the toString return value for debugging.
134: */
135: @Override
136: public String toString() {
137: return getClass().getName() + "[" + name + "]";
138: }
139: }
140:
141: /**
142: * Create an empty FetchProfile.
143: */
144: public FetchProfile() {
145: specials = null;
146: headers = null;
147: }
148:
149: /**
150: * Add the given special item as one of the attributes to
151: * be prefetched.
152: *
153: * @param item the special item to be fetched
154: * @see FetchProfile.Item#ENVELOPE
155: * @see FetchProfile.Item#CONTENT_INFO
156: * @see FetchProfile.Item#FLAGS
157: */
158: public void add(Item item) {
159:• if (specials == null)
160: specials = new Vector<>();
161: specials.addElement(item);
162: }
163:
164: /**
165: * Add the specified header-field to the list of attributes
166: * to be prefetched.
167: *
168: * @param headerName header to be prefetched
169: */
170: public void add(String headerName) {
171:• if (headers == null)
172: headers = new Vector<>();
173: headers.addElement(headerName);
174: }
175:
176: /**
177: * Returns true if the fetch profile contains the given special item.
178: *
179: * @param item the Item to test
180: * @return true if the fetch profile contains the given special item
181: */
182: public boolean contains(Item item) {
183:• return specials != null && specials.contains(item);
184: }
185:
186: /**
187: * Returns true if the fetch profile contains the given header name.
188: *
189: * @param headerName the header to test
190: * @return true if the fetch profile contains the given header name
191: */
192: public boolean contains(String headerName) {
193:• return headers != null && headers.contains(headerName);
194: }
195:
196: /**
197: * Get the items set in this profile.
198: *
199: * @return items set in this profile
200: */
201: public Item[] getItems() {
202:• if (specials == null)
203: return new Item[0];
204:
205: Item[] s = new Item[specials.size()];
206: specials.copyInto(s);
207: return s;
208: }
209:
210: /**
211: * Get the names of the header-fields set in this profile.
212: *
213: * @return headers set in this profile
214: */
215: public String[] getHeaderNames() {
216:• if (headers == null)
217: return new String[0];
218:
219: String[] s = new String[headers.size()];
220: headers.copyInto(s);
221: return s;
222: }
223: }