Javamail Api 简明教程

JavaMail API - Folder Management

到目前为止，我们在我们之前的章节中主要使用收件箱文件夹。这是大多数邮件所驻留的默认文件夹。某些系统可能会将其称为 INBOX，而另一些系统可能会将其称为其他名称。但是，您可以始终使用名称 INBOX 从 JavaMail API 访问它。

So far, we’ve worked in our previous chapters mostly with the INBOX folder. This is the default folder in which most mail resides. Some systems might call it as INBOX and some other might call it by some other name. But,you can always access it from the JavaMail API using the name INBOX.

JavaMail API 将文件夹表示为抽象 Folder 类的实例：

The JavaMail API represents folders as instances of the abstract Folder class:

public abstract class Folder extends Object

此类声明了用于从服务器请求命名文件夹、从文件夹中删除邮件、在文件夹中搜索特定邮件、列出文件夹中的邮件等的方法。

This class declares methods for requesting named folders from servers, deleting messages from folders, searching for particular messages in folders, listing the messages in a folder, and so forth.

Opening a Folder

我们无法直接创建文件夹，因为 Folder 类中的唯一构造函数受到保护。我们可以从以下位置获取文件夹：

We can’t create a folder directly as the only constructor in the Folder class is protected. We can get a Folder from:

  1. a Session

  2. a Store

  3. or another Folder

以上所有类都具有具有相似签名的相似 getFolder() 方法：

All the above classes have a similar getFolder() method with similar signature:

public abstract Folder getFolder(String name) throws MessagingException

某些有助于获取 Folder 对象的方法包括：

Some of the methods which help in getting the Folder object are:

Method

Description

boolean exists()

Checks if the folder really exists. Use this method before getting the Folder object.

abstract void open(int mode)

When you get a Folder, its closed. Use this method to open it. mode can be Folder.READ_ONLY or Folder.READ_WRITE.

abstract boolean isOpen()

This method returns true if the folder is open, false if it’s closed

abstract void close(boolean expunge)

Closes the folder. If the expunge argument is true, any deleted messages in the folder are deleted from the actual file on the server. Otherwise, they’re simply marked as deleted, but the messages can still be undeleted.

Basic Folder Info

下面是一些 Folder 类中的方法，它们返回有关文件夹的基本信息：

Following are some of the methods in Folder class which return basic information about a folder:

Method

Description

abstract String getName()

Returns the name of the folder, such as "TutorialsPoint Mail"

abstract String getFullName()

Returns the complete hierarchical name from the root such as “books/Manisha/TutorialsPoint Mail”.

URLName getURLName()

Return a URLName representing this folder.

abstract Folder getParent()

Returns the name of the folder that contains this folder i.e the parent folder. E.g "Manisha" from the previous "TutorialsPoint Mail" example.

abstract int getType()

Returns an int indicating whether the folder can contain messages and/or other folders.

int getMode()

It returns one of the two named constants Folder.READ_ONLY or Folder.READ_WRITE or -1 when the mode is unknown.

Store getStore()

Returns the Store object from which this folder was retrieved.

abstract char getSeparator()

Return the delimiter character that separates this Folder’s pathname from the names of immediate subfolders.

Managing Folder

以下是一些用于管理 Folder 的方法：

Following are some of the methods which help manage the Folder:

Method

Description

abstract boolean create(int type)

This creates a new folder in this folder’s Store. Where type would be:Folder.HOLDS_MESSAGES or Folder.HOLDS_FOLDERS. Returns true if folder is successfully created else returns false.

abstract boolean delete(boolean recurse)

This deletes the folder only if the folder is closed. Otherwise, it throws an IllegalStateException. If recurse is true, then subfolders are deleted.

abstract boolean renameTo(Folder f)

This changes the name of this folder. A folder must be closed to be renamed. Otherwise, an IllegalStateException is thrown.

Managing Messages in Folders

以下是一些用于管理 Folder 中邮件的方法：

Following are some of the methods that help manage the messages in Folder:

Method

Description

abstract void appendMessages(Message[] messages)

As the name implies, the messages in the array are placed at the end of this folder.

void copyMessages(Message[] messages, Folder destination)

This copies messages from this folder into a specified folder given as an argument.

abstract Message[] expunge()

To delete a message from a folder, set its Flags.Flag.DELETED flag to true. To physically remove deleted messages from a folder, you have to call this method.

Listing the Contents of a Folder

有四种方法可以列出文件夹包含的子文件夹：

There are four methods to list the folders that a folder contains:

Method

Description

Folder[] list()

This returns an array listing the folders that this folder contains.

Folder[] listSubscribed()

This returns an array listing all the subscribed folders that this folder contains.

abstract Folder[] list(String pattern)

This is similar to the list() method except that it allows you to specify a pattern. The pattern is a string giving the name of the folders that match.

Folder[] listSubscribed(String pattern)

This is similar to the listSubscribed() method except that it allows you to specify a pattern. The pattern is a string giving the name of the folders that match.

Checking for Mail

Method

Description

abstract int getMessageCount()

This method can be invoked on an open or closed folder. However, in the case of a closed folder, this method may (or may not) return -1 to indicate that the exact number of messages isn’t easily available.

abstract boolean hasNewMessages()

This returns true if new messages have been added to the folder since it was last opened.

int getNewMessageCount()

It returns the new message count by checking messages in the folder whose RECENT flag is set.

int getUnreadMessageCount()

This can be invoked on either an open or a closed folder. However, in the case of a closed folder, it may return -1 to indicate that the real answer would be too expensive to obtain.

Getting Messages from Folders

文件夹类提供了四种方法来从打开的文件夹中检索邮件：

The Folder class provides four methods for retrieving messages from open folders:

Method

Description

abstract Message getMessage(int messageNumber)

This returns the nth message in the folder. The first message in the folder is number 1.

Message[] getMessages()

This returns an array of Message objects representing all the messages in this folder.

Message[] getMessages(int start, int end)

This returns an array of Message objects from the folder, beginning with start and finishing with end, inclusive.

Message[] getMessages(int[] messageNumbers)

This returns an array containing only those messages specifically identified by number in the messageNumbers array.

void fetch(Message[] messages, FetchProfile fp)

Prefetch the items specified in the FetchProfile for the given Messages. The FetchProfile argument specifies which headers in the messages to prefetch.

Searching Folders

如果服务器支持搜索（很多 IMAP 服务器支持，但大多数 POP 服务器不支持），则很容易搜索某个文件夹以查找满足某些条件的邮件。条件通过 SearchTerm 对象进行编码。以下是两种搜索方法：

If the server supports searching (as many IMAP servers do and most POP servers don’t), it’s easy to search a folder for the messages meeting certain criteria. The criteria are encoded in SearchTerm objects. Following are the two search methods:

Method

Description

Message[] search(SearchTerm term)

Search this Folder for messages matching the specified search criterion. Returns an array containing the matching messages. Returns an empty array if no matches were found.

Message[] search(SearchTerm term, Message[] messages)

Search the given array of messages for those that match the specified search criterion. Returns an array containing the matching messages. Returns an empty array if no matches were found. The the specified Message objects must belong to this folder.

Flags

当您需要更改一个 Folder 中的所有消息的标志时，标志修改将很有用。以下是 Folder 类中提供的方法：

Flag modification is useful when you need to change flags for the entire set of messages in a Folder. Following are the methods provided in the Folder class:

Method

Description

void setFlags(Message[] messages, Flags flag, boolean value)

Sets the specified flags on the messages specified in the array.

void setFlags(int start, int end, Flags flag, boolean value)

Sets the specified flags on the messages numbered from start through end, both start and end inclusive.

void setFlags(int[] messageNumbers, Flags flag, boolean value)

Sets the specified flags on the messages whose message numbers are in the array.

abstract Flags getPermanentFlags()

Returns the flags that this folder supports for all messages.