001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019
020 package javax.mail;
021
022 /**
023 * @version $Rev: 582797 $ $Date: 2007-10-08 08:29:12 -0400 (Mon, 08 Oct 2007) $
024 */
025 public interface UIDFolder {
026 /**
027 * A special value than can be passed as the <code>end</code> parameter to
028 * {@link Folder#getMessages(int, int)} to indicate the last message in this folder.
029 */
030 public static final long LASTUID = -1;
031
032 /**
033 * Get the UID validity value for this Folder.
034 *
035 * @return The current UID validity value, as a long.
036 * @exception MessagingException
037 */
038 public abstract long getUIDValidity() throws MessagingException;
039
040 /**
041 * Retrieve a message using the UID rather than the
042 * message sequence number. Returns null if the message
043 * doesn't exist.
044 *
045 * @param uid The target UID.
046 *
047 * @return the Message object. Returns null if the message does
048 * not exist.
049 * @exception MessagingException
050 */
051 public abstract Message getMessageByUID(long uid)
052 throws MessagingException;
053
054 /**
055 * Get a series of messages using a UID range. The
056 * special value LASTUID can be used to mark the
057 * last available message.
058 *
059 * @param start The start of the UID range.
060 * @param end The end of the UID range. The special value
061 * LASTUID can be used to request all messages up
062 * to the last UID.
063 *
064 * @return An array containing all of the messages in the
065 * range.
066 * @exception MessagingException
067 */
068 public abstract Message[] getMessagesByUID(long start, long end)
069 throws MessagingException;
070
071 /**
072 * Retrieve a set of messages by explicit UIDs. If
073 * any message in the list does not exist, null
074 * will be returned for the corresponding item.
075 *
076 * @param ids An array of UID values to be retrieved.
077 *
078 * @return An array of Message items the same size as the ids
079 * argument array. This array will contain null
080 * entries for any UIDs that do not exist.
081 * @exception MessagingException
082 */
083 public abstract Message[] getMessagesByUID(long[] ids)
084 throws MessagingException;
085
086 /**
087 * Retrieve the UID for a message from this Folder.
088 * The argument Message MUST belong to this Folder
089 * instance, otherwise a NoSuchElementException will
090 * be thrown.
091 *
092 * @param message The target message.
093 *
094 * @return The UID associated with this message.
095 * @exception MessagingException
096 */
097 public abstract long getUID(Message message) throws MessagingException;
098
099 /**
100 * Special profile item used for fetching UID information.
101 */
102 public static class FetchProfileItem extends FetchProfile.Item {
103 public static final FetchProfileItem UID = new FetchProfileItem("UID");
104
105 protected FetchProfileItem(String name) {
106 super(name);
107 }
108 }
109 }