javax.mail
クラス Folder

java.lang.Object
  上位を拡張 javax.mail.Folder
直系の既知のサブクラス:
DefaultFolder, IMAPFolder, POP3Folder

public abstract class Folder
extends Object

Folder は、メールメッセージのフォルダを表す抽象クラスです。 サブクラスはプロトコル別の Folder を実装します。

Folder は Message、他の Folder 又はそれらの両方を含む事ができる為、 Store のデフォルトフォルダをルートとするツリー状の階層を提供します (一部の Folder 実装には、 同じ Folder 中の Message と他の Folder を許可しない物があります)。

フォルダ名の解釈は実装により異なります。 フォルダの完全名中の各階層レベルは、それぞれ階層区切り文字で分割されます。

大文字と小文字を区別しない完全フォルダ名 (つまり、 Store のデフォルトフォルダに対する完全名) INBOX は、 "このサーバ上のこのユーザの為の主フォルダ" を意味する為に予約されています。 全ての Store が INBOX フォルダを提供するわけではなく、 全てのユーザが常に INBOX フォルダを持つわけでもありません。 この機能を提供する Store 内にこのフォルダが存在する場合に、 それを指すために INBOX という名前が予約されています。

Store から取得される Folder オブジェクトは、バックエンドストアに実在する必要はありません。 exists() メソッドはフォルダが存在するかどうかを検査します。 create() メソッドは Folder を作成します。

Folder は最初閉じた状態にあります。一部のメソッドは、この状態の時に有効です。 そうしたメソッドの説明にはこの事が記述されています。 Folder はその 'open' メソッドを呼び出す事により開かれます。 この状態では、open()delete()、 及び renameTo() を除く全ての Folder メソッドが有効です。

Folder を取得する方法は、Store 又は Folder 上で getFolder() メソッドを呼び出すか、 Folder 上で list() 又は listSubscribed() メソッドを呼び出すしかありません。 これらのメソッドにより返される Folder オブジェクトは、Store によりキャッシュされません。 その為、getFolder(folder_name) を同じ folder_name で複数回呼び出すと、 異なった Folder オブジェクトが返されます。 list() 及び listSubscribed() についても同様です。

Folder 内の Message オブジェクトは、Folder によりキャッシュされます。 その為、同じメッセージ番号上で getMessage(msgno) を複数回呼び出すと、 同じ Message オブジェクトが返されます。これはこの Folder 上で消去が行われるまで変わりません。

Message のメッセージ番号は、包含する Folder が消去メソッドにより消去されると、 セッション内で変更になる場合があります。 メッセージへの参照としてメッセージ番号を使用するクライアントはこの点に注意しなければならず、 状況に対処する準備が必要になります (恐らく既存のメッセージ番号参照を消し、再度読み込む事による)。 こうした複雑さから、クライアントはメッセージ番号でなく、 Message オブジェクトを使用してメッセージを参照するほうが適切です。 消去される Message オブジェクトは依然として除去する必要がありますが、 そのフォルダ中の他の Message オブジェクトは消去による影響を受けません。


フィールドの概要
static int HOLDS_FOLDERS
          このフォルダは他のフォルダを含む事ができます。
static int HOLDS_MESSAGES
          このフォルダはメッセージを含む事ができます。
protected  int mode
          このフォルダのオープンモードです。
static int READ_ONLY
          Folder は読み取り専用です。
static int READ_WRITE
          このフォルダの状態と内容は変更する事ができます。
protected  Store store
          親ストアです。
 
コンストラクタの概要
protected Folder(Store store)
          Store オブジェクトを使用するコンストラクタです。
 
メソッドの概要
 void addConnectionListener(ConnectionListener l)
          この Folder に Connection イベントのリスナーを追加します。
 void addFolderListener(FolderListener l)
          この Folder に Folder イベントのリスナーを追加します。
 void addMessageChangedListener(MessageChangedListener l)
          この Folder に MessageChanged イベントのリスナーを追加します。
 void addMessageCountListener(MessageCountListener l)
          この Folder に MessageCount イベントのリスナーを追加します。
abstract  void appendMessages(Message[] msgs)
          指定された Messages をこのフォルダに追加します。
abstract  void close(boolean expunge)
          この Folder を閉じます。
 void copyMessages(Message[] msgs, Folder folder)
          この Folder から指定された Message を別の Folder にコピーします。
abstract  boolean create(int type)
          このフォルダを Store 上に作成します。
abstract  boolean delete(boolean recurse)
          この Folder を削除します。
abstract  boolean exists()
          このフォルダが物理的に Store 上に存在するかどうかを検査します。
abstract  Message[] expunge()
          DELETED のマークが付いている消去 (永続的な削除) メッセージです。
 void fetch(Message[] msgs, FetchProfile fp)
          指定された Message の FetchProfile に指定された項目を先読みします。
protected  void finalize()
           
 int getDeletedMessageCount()
          この Folder 中の削除済みメッセージの数を取得します。
abstract  Folder getFolder(String name)
          指定された名前に対応する Folder オブジェクトを返します。
abstract  String getFullName()
          この Folder の完全な名前を返します。
abstract  Message getMessage(int msgnum)
          指定されたメッセージ番号に対応する Message オブジェクトを取得します。
abstract  int getMessageCount()
          この Folder 中のメッセージの数を取得します。
 Message[] getMessages()
          この Folder から全ての Message オブジェクトを取得します。
 Message[] getMessages(int[] msgnums)
          配列で指定されたメッセージ番号の Message オブジェクトを取得します。
 Message[] getMessages(int start, int end)
          メッセージ番号が start から end 迄の範囲 (start と end を含む) にある Message オブジェクトを取得します。
 int getMode()
          このフォルダのオープンモードを返します。
abstract  String getName()
          この Folder の名前を返します。
 int getNewMessageCount()
          この Folder 中の新規メッセージの数を取得します。
abstract  Folder getParent()
          このフォルダの親フォルダを返します。
abstract  Flags getPermanentFlags()
          この Folder がサポートする永続フラグを取得します。
abstract  char getSeparator()
          この Folder のパス名をすぐ下のサブフォルダ名から分離する区切り文字を返します。
 Store getStore()
          この Folder オブジェクトを所有する Store を返します。
abstract  int getType()
          この Folder の型、つまり、このフォルダがメッセージかサブフォルダ、 又はその両方を保持可能かどうかを返します。
 int getUnreadMessageCount()
          この Folder 中の未読メッセージの数を取得します。
 URLName getURLName()
          このフォルダを表す URLName を返します。
abstract  boolean hasNewMessages()
          この表示が最後にリセットされてから、この Folder に新規メッセージが存在する場合は true を返します。
abstract  boolean isOpen()
          この Folder が 'open' 状態にあるかどうかを示します。
 boolean isSubscribed()
          この Folder がサブスクライブされる場合に true を返します。
 Folder[] list()
          この Folder の下にあるフォルダの一覧を返す簡易メソッド。
abstract  Folder[] list(String pattern)
          指定されたパターンに一致するこの Folder の名前空間に属する Folder の一覧を返します。
 Folder[] listSubscribed()
          この Folder の下にあるサブスクライブされたフォルダの一覧を返す簡易メソッド。
 Folder[] listSubscribed(String pattern)
          指定されたパターンに一致するこの Folder の名前空間に 属するサブスクライブされた Folder の一覧を返します。
protected  void notifyConnectionListeners(int type)
          すべての ConnectionListener に通知します。
protected  void notifyFolderListeners(int type)
          この Folder とこのフォルダの Store 上に登録されている全ての FolderListener に通知します。
protected  void notifyFolderRenamedListeners(Folder folder)
          この Folder とこのフォルダの Store 上に登録されている全ての FolderListener に、 このフォルダの名前変更について通知します。
protected  void notifyMessageAddedListeners(Message[] msgs)
          全ての MessageCountListener に、このフォルダへのメッセージ追加を通知します。
protected  void notifyMessageChangedListeners(int type, Message msg)
          全ての MessageChangedListener に通知します。
protected  void notifyMessageRemovedListeners(boolean removed, Message[] msgs)
          全ての MessageCountListener に、このフォルダからのメッセージ削除を通知します。
abstract  void open(int mode)
          この Folder を開きます。
 void removeConnectionListener(ConnectionListener l)
          Connection イベントリスナーを削除します。
 void removeFolderListener(FolderListener l)
          Folder イベントリスナーを削除します。
 void removeMessageChangedListener(MessageChangedListener l)
          MessageChanged リスナーを削除します。
 void removeMessageCountListener(MessageCountListener l)
          MessageCount リスナーを削除します。
abstract  boolean renameTo(Folder f)
          この Folder の名前を変更します。
 Message[] search(SearchTerm term)
          指定された検索基準に一致するメッセージについてこの Folder を検索します。
 Message[] search(SearchTerm term, Message[] msgs)
          指定された検索基準に一致するメッセージについて、 指定されたメッセージ配列を検索します。
 void setFlags(int[] msgnums, Flags flag, boolean value)
          メッセージ番号が配列中に存在するメッセージ上に指定されたフラグを設定します。
 void setFlags(int start, int end, Flags flag, boolean value)
          指定されたフラグを、start から end まで (start と end の両方を含む) の番号のメッセージ上に設定します。
 void setFlags(Message[] msgs, Flags flag, boolean value)
          配列中に指定されたメッセージ上に指定されたフラグを設定します。
 void setSubscribed(boolean subscribe)
          この Folder をサブスクライブ又はサブスクライブ解除します。
 String toString()
          デフォルトの toString() をオーバーライドします。
 
クラス java.lang.Object から継承されたメソッド
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

フィールドの詳細

store

protected Store store
親ストアです。


mode

protected int mode
このフォルダのオープンモードです。オープンモードは、 Folder.READ_ONLY 又は Folder.READ_WRITE で、 不明な場合は -1 です。

導入されたバージョン:
JavaMail 1.1

HOLDS_MESSAGES

public static final int HOLDS_MESSAGES
このフォルダはメッセージを含む事ができます。

関連項目:
定数フィールド値

HOLDS_FOLDERS

public static final int HOLDS_FOLDERS
このフォルダは他のフォルダを含む事ができます。

関連項目:
定数フィールド値

READ_ONLY

public static final int READ_ONLY
Folder は読み取り専用です。 このフォルダの状態と内容を変更する事はできません。

関連項目:
定数フィールド値

READ_WRITE

public static final int READ_WRITE
このフォルダの状態と内容は変更する事ができます。

関連項目:
定数フィールド値
コンストラクタの詳細

Folder

protected Folder(Store store)
Store オブジェクトを使用するコンストラクタです。

パラメータ:
store - このフォルダを保持する Store
メソッドの詳細

getName

public abstract String getName()
この Folder の名前を返します。

このメソッドは閉じた Folder 上で呼び出すことができます。

戻り値:
Folder の名前

getFullName

public abstract String getFullName()
この Folder の完全な名前を返します。 フォルダがこの Store のルート階層の下にある場合、 返される名前はルートへの相対名になります。 そうでない場合は、階層区切り文字で始まる絶対名が返されます。

このメソッドは閉じた Folder 上で呼び出す事ができます。

戻り値:
Folder の完全な名前

getURLName

public final URLName getURLName()
                         throws MessagingException
このフォルダを表す URLName を返します。 返される URLName は、ストアにアクセスする為に使用されるパスワードを含みません

戻り値:
このフォルダを表す URLName
例外:
MessagingException
導入されたバージョン:
JavaMail 1.1
関連項目:
URLName

getStore

public final Store getStore()
この Folder オブジェクトを所有する Store を返します。 このメソッドは閉じた Folder で呼び出すことができます。

戻り値:
Store

getParent

public abstract Folder getParent()
                          throws MessagingException
このフォルダの親フォルダを返します。 このメソッドは閉じた Folder 上で呼び出す事ができます。 このフォルダがフォルダ階層の最上位にある場合、このメソッドは null を返します。

Folder オブジェクトはキャッシュされないので、このメソッドを呼び出すと、 新規の異なる Folder オブジェクトが返されます。

戻り値:
親フォルダ
例外:
MessagingException

exists

public abstract boolean exists()
                        throws MessagingException
このフォルダが物理的に Store 上に存在するかどうかを検査します。 このメソッドは閉じた Folder 上で呼び出す事ができます。

戻り値:
フォルダが存在する場合は true、そうでない場合は false
例外:
MessagingException - 一般にサーバへの接続が失われた場合
関連項目:
create(int)

list

public abstract Folder[] list(String pattern)
                       throws MessagingException
指定されたパターンに一致するこの Folder の名前空間に属する Folder の一覧を返します。 パターンは、階層区切り文字以外の任意の文字に一致するワイルドカード文字 "%"、 及び全ての文字に一致する "*" を含む事ができます。

フォルダ階層の例を以下に示します。

    Personal/
       Finance/
          Stocks
          Bonus
          StockOptions
       Jokes
 
"Personal" 上の list("*") は階層全体を返します。
"Personal" 上の list("%") は "Finance" と "Jokes" を返します。
"Personal" 上の list("Jokes") は "Jokes" を返します。
"Finance" 上の list("Stock*") は "Stocks" と "StockOptions" を返します。

Folder オブジェクトは Store によりキャッシュされないので、 同じパターンでこのメソッドを複数回呼び出すと、 多くの異なる Folder オブジェクトが返されます。

このメソッドは閉じた Folder 上で呼び出す事ができます。

パラメータ:
pattern - 一致パターン
戻り値:
一致する Folder オブジェクトの配列。一致する Folder が存在しない場合は、空の配列を返します。
例外:
FolderNotFoundException - このフォルダが存在しない場合
MessagingException
関連項目:
listSubscribed(java.lang.String)

listSubscribed

public Folder[] listSubscribed(String pattern)
                        throws MessagingException
指定されたパターンに一致するこの Folder の名前空間に 属するサブスクライブされた Folder の一覧を返します。 フォルダがサブスクリプションをサポートしない場合、 このメソッドは list を呼び出しその結果を返す必要があります。 (ここで提供されるデフォルトの実装はこれを行う) パターンは list に関するワイルドカードを含む事ができます。

Note that, at a given level of the folder hierarchy, a particular folder may not be subscribed, but folders underneath that folder in the folder hierarchy may be subscribed. In order to allow walking the folder hierarchy, such unsubscribed folders may be returned, indicating that a folder lower in the hierarchy is subscribed. The isSubscribed method on a folder will tell whether any particular folder is actually subscribed.

Folder オブジェクトは Store によりキャッシュされないので、 同じパターンでこのメソッドを複数回呼び出すと、 多くの異なる Folder オブジェクトが返されます。

このメソッドは閉じた Folder 上で呼び出す事ができます。

パラメータ:
pattern - 一致パターン
戻り値:
一致するサブスクライブされた Folder オブジェクトの配列。 一致するサブスクライブされたフォルダが存在しない場合は、空の配列を返します。
例外:
FolderNotFoundException - このフォルダが存在しない場合
MessagingException
関連項目:
list(java.lang.String)

list

public final Folder[] list()
                    throws MessagingException
この Folder の下にあるフォルダの一覧を返す簡易メソッド。 このメソッドは、一致パターンに "%" を使用して、 list(String pattern) メソッドを呼び出すだけです。 このメソッドは閉じた Folder 上で呼び出す事ができます。

戻り値:
この Folder の下にある Folder オブジェクトの配列。 サブフォルダが存在しない場合は、空の配列を返します。
例外:
FolderNotFoundException - このフォルダが存在しない場合
MessagingException
関連項目:
list(java.lang.String)

listSubscribed

public final Folder[] listSubscribed()
                              throws MessagingException
この Folder の下にあるサブスクライブされたフォルダの一覧を返す簡易メソッド。 このメソッドは、一致パターンに "%" を使用して、 listSubscribed(String pattern) メソッドを呼び出すだけです。 このメソッドは閉じた Folder 上で呼び出す事ができます。

戻り値:
この Folder の下にあるサブスクライブされた Folder オブジェクトの配列。 サブスクライブされたサブフォルダが存在しない場合は、空の配列を返します。
例外:
FolderNotFoundException - このフォルダが存在しない場合
MessagingException
関連項目:
listSubscribed(java.lang.String)

getSeparator

public abstract char getSeparator()
                           throws MessagingException
この Folder のパス名をすぐ下のサブフォルダ名から分離する区切り文字を返します。 このメソッドは閉じた Folder 上で呼び出す事ができます。

戻り値:
階層区切り文字
例外:
FolderNotFoundException - このフォルダが存在しない場合
MessagingException

getType

public abstract int getType()
                     throws MessagingException
この Folder の型、つまり、このフォルダがメッセージかサブフォルダ、 又はその両方を保持可能かどうかを返します。 返される値は、適切なビットが設定された整数ビットフィールドです。 このメソッドは閉じたフォルダ上で呼び出す事ができます。

戻り値:
適切なビットが設定された整数
例外:
FolderNotFoundException - このフォルダが存在しない場合
MessagingException
関連項目:
HOLDS_FOLDERS, HOLDS_MESSAGES

create

public abstract boolean create(int type)
                        throws MessagingException
このフォルダを Store 上に作成します。 このフォルダが作成されると、パスに含まれる存在しない全てのフォルダも作成されます。

作成が成功すると、この Folder とこの Store に登録されている 任意の FolderListener に CREATED FolderEvent が配信されます。

パラメータ:
type - このフォルダの型
戻り値:
作成が成功する場合は true、そうでない場合は false
例外:
MessagingException
関連項目:
HOLDS_FOLDERS, HOLDS_MESSAGES, FolderEvent

isSubscribed

public boolean isSubscribed()
この Folder がサブスクライブされる場合に true を返します。

このメソッドは閉じた Folder 上で呼び出す事ができます。

ここで提供されるデフォルトの実装は true を返すだけです。

戻り値:
この Folder がサブスクライブされる場合は true

setSubscribed

public void setSubscribed(boolean subscribe)
                   throws MessagingException
この Folder をサブスクライブ又はサブスクライブ解除します。 全ての Store がサブスクリプションをサポートするわけではありません。

このメソッドは閉じた Folder 上で呼び出す事ができます。

ここで提供される実装は MethodNotSupportedException をスローするだけです。

パラメータ:
subscribe - true to subscribe, false to unsubscribe
例外:
FolderNotFoundException - このフォルダが存在しない場合
MethodNotSupportedException - このストアがサブスクリプションをサポートしない場合
MessagingException

hasNewMessages

public abstract boolean hasNewMessages()
                                throws MessagingException
この表示が最後にリセットされてから、この Folder に新規メッセージが存在する場合は true を返します。 この表示がいつ設定またはリセットされるかは、Folder の実装により異なります (IMAP の場合は、サーバに依存します)。 このメソッドを使用して、Folder を開かずに "新規メールをチェック" する軽量な操作を実装できます。 (例えば、メールボックス及びフラグを監視して新規メールをチェックするスレッド等) このメソッドは、Folder 中の任意のメッセージに RECENT フラグが 設定されているかどうかを示す必要があります。

これは新規メールのインクリメンタルチェックではありません。 つまり、このメソッドが最後に呼び出された時以降に、 新規メッセージが到着したかどうかを判定する為に使用する事はできません。 インクリメンタルチェックを実装するには、Folder を開く必要があります。

このメソッドは、Message を含む事ができる閉じた Folder 上で呼び出す事ができます。

戻り値:
Store が新規の Message を含む場合は true
例外:
FolderNotFoundException - このフォルダが存在しない場合
MessagingException

getFolder

public abstract Folder getFolder(String name)
                          throws MessagingException
指定された名前に対応する Folder オブジェクトを返します。 このフォルダは、Store 内に物理的に存在する必要はありません。 Folder 上の exists() メソッドは、 フォルダが Store 上に実在するかどうかを示します。

一部の Store で、名前が階層区切り文字で始まる場合、絶対パスにする事ができます。 それ以外の場合、名前はこの Folder への相対名と解釈されます。

Folder オブジェクトは Store によりキャッシュされないので、 同じ名前でこのメソッドを複数回呼び出すと、 多くの異なる Folder オブジェクトが返されます。

このメソッドは閉じた Folder 上で呼び出す事ができます。

パラメータ:
name - Folder の名前
戻り値:
Folder オブジェクト
例外:
MessagingException

delete

public abstract boolean delete(boolean recurse)
                        throws MessagingException
この Folder を削除します。 このメソッドは閉じた Folder 上でのみ成功します。

recurse フラグは、削除がサブフォルダに影響するかどうかを制御します。 true の場合、全てのサブフォルダが削除された後、このフォルダ自身が削除されます。 false の場合、動作はフォルダの型により異なります。 以下に詳しく述べます。

戻り値:
Folder が正常に削除された場合は true
例外:
FolderNotFoundException - このフォルダが存在しない場合
IllegalStateException - このフォルダが閉じた状態にない場合
MessagingException
関連項目:
FolderEvent

renameTo

public abstract boolean renameTo(Folder f)
                          throws MessagingException
この Folder の名前を変更します。 このメソッドは閉じた Folder 上でのみ成功します。

名前の変更が成功すると、このフォルダとこのフォルダを含む Store に登録 されている FolderListener に RENAMED FolderEvent が配信されます。

パラメータ:
f - この Folder の新しい名前を表すフォルダ
戻り値:
Folder の名前が正常に変更された場合は true
例外:
FolderNotFoundException - このフォルダが存在しない場合
IllegalStateException - このフォルダが閉じた状態にない場合
MessagingException
関連項目:
FolderEvent

open

public abstract void open(int mode)
                   throws MessagingException
この Folder を開きます。このメソッドは、 Message を含む事が可能でかつ閉じている Folder 上でのみ有効です。

このフォルダが正常に開くと、この Folder 上に登録されている 全ての ConnectionListener に OPENED ConnectionEvent が配信されます。

特定の Store 上の同じフォルダへの接続を複数開く場合の効果は、実装により異なります。 一部の実装は複数の読み手を許可しますが、書き手はただ 1 人しか許可しません。 又別の実装は複数の読み手と書き手を許可します。

パラメータ:
mode - Folder READ_ONLY または READ_WRITE を開く
例外:
FolderNotFoundException - このフォルダが存在しない場合
IllegalStateException - このフォルダが閉じた状態にない場合
MessagingException
関連項目:
READ_ONLY, READ_WRITE, getType(), ConnectionEvent

close

public abstract void close(boolean expunge)
                    throws MessagingException
この Folder を閉じます。このメソッドは開いた Folder 上でのみ有効です。

この Folder 上に登録されている全ての ConnectionListener に CLOSED ConnectionEvent が配信されます。 MessagingException のスローにより、このメソッドが異常終了した場合でもフォルダは閉じられます。

パラメータ:
expunge - このフラグが true の場合、全ての削除メッセージを消去します。
例外:
IllegalStateException - このフォルダが開かれていない場合
MessagingException
関連項目:
ConnectionEvent

isOpen

public abstract boolean isOpen()
この Folder が 'open' 状態にあるかどうかを示します。

戻り値:
この Folder が 'open' 状態にある場合は true

getMode

public final int getMode()
このフォルダのオープンモードを返します。 Folder.READ_ONLYFolder.READ_WRITE、 又はオープンモードが不明な場合は -1 を返します (通常、 古い Folder プロバイダがこの新しいメソッドを使用できる様に更新されていないだけの理由による)。

戻り値:
このフォルダのオープンモード
例外:
IllegalStateException - このフォルダが開かれていない場合
導入されたバージョン:
JavaMail 1.1

getPermanentFlags

public abstract Flags getPermanentFlags()
この Folder がサポートする永続フラグを取得します。 サポートされる全てのフラグを含む Flags オブジェクトを返します。

特殊フラグ Flags.USER は、 この Folder が任意のユーザ定義フラグをサポートする事を示します。

フォルダのサポートされる永続フラグは、フォルダが開かれるまで使用できません。

戻り値:
永続フラグ、または不明の場合は null

getMessageCount

public abstract int getMessageCount()
                             throws MessagingException
この Folder 中のメッセージの数を取得します。

このメソッドは閉じたフォルダ上で呼び出す事ができます。 但し、一部のフォルダ実装では、メッセージ数の取得は、 実際のフォルダのオープンを含む負荷の大きい操作になる場合があります。 そうした場合、プロバイダは閉じた状態でのこの機能をサポートしない様に選択できます。 この場合、このメソッドは -1 を返す必要があります。

閉じたフォルダ上でこのメソッドを呼び出すクライアントは、 これが負荷の大きい操作になる可能性がある事に注意する必要があります。 この場合、クライアントは戻り値 -1 に対する処理も準備する必要があります。

戻り値:
メッセージの数。このメソッドが閉じたフォルダ上で呼び出された場合、 一部の実装では -1 が返されることがあります。
例外:
FolderNotFoundException - このフォルダが存在しない場合
MessagingException

getNewMessageCount

public int getNewMessageCount()
                       throws MessagingException
この Folder 中の新規メッセージの数を取得します。

このメソッドは閉じたフォルダ上で呼び出す事ができます。 但し、一部のフォルダ実装について、新規メッセージ数の取得は、 実際のフォルダのオープンを含む負荷の大きい操作になる場合があります。 そうした場合、プロバイダは閉じた状態でのこの機能をサポートしない様に選択できます。 この場合、このメソッドは -1 を返す必要があります。

閉じたフォルダ上でこのメソッドを呼び出すクライアントは、 これが負荷の大きい操作になる可能性がある事に注意する必要があります。 この場合、クライアントは戻り値 -1 に対する処理も準備する必要があります。

このフォルダが閉じている場合、この実装は -1 を返します。そうでない場合、 この実装は getMessage(int) を使用してフォルダ中の各 Message を取得し、 RECENT フラグが設定されているかどうかをチェックします。 このフラグが設定されているメッセージの数が返されます。

戻り値:
新規メッセージの数。このメソッドが閉じたフォルダ上で呼び出された場合、 一部の実装では -1 が返される事があります。
例外:
FolderNotFoundException - このフォルダが存在しない場合
MessagingException

getUnreadMessageCount

public int getUnreadMessageCount()
                          throws MessagingException
この Folder 中の未読メッセージの数を取得します。

このメソッドは閉じたフォルダ上で呼び出す事ができます。 但し、一部のフォルダ実装について、未読メッセージ数の取得は、 実際のフォルダのオープンを含む負荷の大きい操作になる場合があります。 そうした場合、プロバイダは閉じた状態でのこの機能をサポートしない様に選択できます。 この場合、このメソッドは -1 を返す必要があります。

閉じたフォルダ上でこのメソッドを呼び出すクライアントは、 これが負荷の大きい操作になる可能性がある事に注意する必要があります。 この場合、クライアントは戻り値 -1 に対する処理も準備する必要があります。

このフォルダが閉じている場合、この実装は -1 を返します。 そうでない場合、この実装は getMessage(int) を使用してフォルダ中の各 Message を取得し、 SEEN フラグが設定されているかどうかをチェックします。 このフラグが設定されていないメッセージの数が返されます。

戻り値:
未読メッセージの数。このメソッドが閉じたフォルダ上で呼び出された場合、 一部の実装では -1 が返される事があります。
例外:
FolderNotFoundException - このフォルダが存在しない場合
MessagingException

getDeletedMessageCount

public int getDeletedMessageCount()
                           throws MessagingException
この Folder 中の削除済みメッセージの数を取得します。

このメソッドは閉じたフォルダ上で呼び出す事ができます。 但し、一部のフォルダ実装について、削除済みメッセージ数の取得は、 実際のフォルダのオープンを含む負荷の大きい操作になる場合があります。 そうした場合、プロバイダは閉じた状態でのこの機能をサポートしない様に選択できます。 この場合、このメソッドは -1 を返す必要があります。

閉じたフォルダ上でこのメソッドを呼び出すクライアントは、 これが負荷の大きい操作になる可能性がある事に注意する必要があります。 この場合、クライアントは戻り値 -1 に対する処理も準備する必要があります。

このフォルダが閉じている場合、この実装は -1 を返します。 そうでない場合、この実装は getMessage(int) を使用してフォルダ中の各 Message を取得し、 DELETED フラグが設定されているかどうかをチェックします。

戻り値:
削除済みメッセージの数。このメソッドが閉じたフォルダ上で呼び出された場合、 一部の実装では -1 が返される事があります。
例外:
FolderNotFoundException - このフォルダが存在しない場合
MessagingException
導入されたバージョン:
JavaMail 1.3

getMessage

public abstract Message getMessage(int msgnum)
                            throws MessagingException
指定されたメッセージ番号に対応する Message オブジェクトを取得します。 Message オブジェクトのメッセージ番号は、この Message の Folder 中の相対位置です。 メッセージには 1 からフォルダ中のメッセージの数迄の番号が割り当てられます。 特定の Message のメッセージ番号は、Folder 中の他のメッセージが削除され、 Folder が消去された場合、セッション中に変更になる事があります。

Message オブジェクトは、オンデマンドで満たされる実際のメッセージへの軽量な参照です。 従って、Folder 実装は軽量な Message オブジェクトを提供する必要があります。

Folder オブジェクトと異なり、同じメッセージ番号を使用して繰り返し getMessage を呼び出した場合、 このフォルダで消去されたメッセージがない限り、同じ Message オブジェクトが返されます。

フォルダが消去されると、セッション中にメッセージ番号が変更になる事がある為、 クライアントはメッセージへの参照としてメッセージ番号を使用するべきではありません。 代わりに Message オブジェクトを使用して下さい。

パラメータ:
msgnum - メッセージ番号
戻り値:
Message オブジェクト
例外:
FolderNotFoundException - このフォルダが存在しない場合
IllegalStateException - このフォルダが開かれていない場合
IndexOutOfBoundsException - メッセージ番号が範囲外の場合
MessagingException
関連項目:
getMessageCount(), fetch(javax.mail.Message[], javax.mail.FetchProfile)

getMessages

public Message[] getMessages(int start,
                             int end)
                      throws MessagingException
メッセージ番号が start から end 迄の範囲 (start と end を含む) にある Message オブジェクトを取得します。 メッセージ番号は 0 ではなく、1 から始まります。

Message オブジェクトは、オンデマンドで満たされる実際のメッセージへの軽量な参照です。 従って、Folder 実装は軽量な Message オブジェクトを提供する必要があります。

この実装は getMessage(index) を使用して、必要な Message オブジェクトを取得します。 返される配列は (end - start + 1) Message オブジェクトを含みます。

パラメータ:
start - 最初のメッセージの番号
end - 最後のメッセージの番号
戻り値:
Message オブジェクト
例外:
FolderNotFoundException - このフォルダが存在しない場合
IllegalStateException - このフォルダが開かれていない場合
IndexOutOfBoundsException - start 又は end のメッセージ番号が範囲外の場合
MessagingException
関連項目:
fetch(javax.mail.Message[], javax.mail.FetchProfile)

getMessages

public Message[] getMessages(int[] msgnums)
                      throws MessagingException
配列で指定されたメッセージ番号の Message オブジェクトを取得します。

Message オブジェクトは、オンデマンドで満たされる実際のメッセージへの軽量な参照です。 従って、Folder 実装は軽量な Message オブジェクトを提供する必要があります。

この実装は getMessage(index) を使用して、必要な Message オブジェクトを取得します。 返される配列は msgnums.length Message オブジェクトを含みます。

パラメータ:
msgnums - メッセージ番号の配列
戻り値:
Message オブジェクトの配列
例外:
FolderNotFoundException - このフォルダが存在しない場合
IllegalStateException - このフォルダが開かれていない場合
IndexOutOfBoundsException - 指定された配列中のいずれかのメッセージ番号が範囲外の場合
MessagingException
関連項目:
fetch(javax.mail.Message[], javax.mail.FetchProfile)

getMessages

public Message[] getMessages()
                      throws MessagingException
この Folder から全ての Message オブジェクトを取得します。 フォルダが空の場合は、空の配列を返します。 クライアントはフォルダ中のメッセージへの参照として、 (シーケンス番号ではなく) Message オブジェクトを使用できます。 このメソッドは Message オブジェクトをクライアントへ供給します。 Folder 実装はオンデマンドで満たされる軽量な Message オブジェクトを提供する必要があります。

この実装は getMessageCount() を呼び出して現在のメッセージカウントを取得した後、 getMessage() を使用して Message オブジェクトを 1 からメッセージ数まで取得します。

戻り値:
Message オブジェクトの配列。フォルダが空の場合は空の配列
例外:
FolderNotFoundException - このフォルダが存在しない場合
IllegalStateException - このフォルダが開かれていない場合
MessagingException
関連項目:
fetch(javax.mail.Message[], javax.mail.FetchProfile)

appendMessages

public abstract void appendMessages(Message[] msgs)
                             throws MessagingException
指定された Messages をこのフォルダに追加します。 このメソッドは閉じた Folder 上で呼び出す事ができます。 メッセージがフォルダに到着した際、適切な MessageCountEvent が このフォルダに登録されている全ての MessageCountListener に配信されます。

指定されたメッセージ配列中の Message が消去された Message だと判明しても、 Folder 実装はこの操作を中止してはいけません。

パラメータ:
msgs - 追加される Message の配列
例外:
FolderNotFoundException - このフォルダが存在しない場合
MessagingException - 追加が失敗した場合

fetch

public void fetch(Message[] msgs,
                  FetchProfile fp)
           throws MessagingException
指定された Message の FetchProfile に指定された項目を先読みします。

クライアントはこのメソッドを使用して、指定された 項目全体が指定されたメッセージ範囲で必要になる事を示します。 実装は、指定されたメッセージ範囲のこれらの項目を効率的な方法で取得する必要があります。 このメソッドは、該当項目を先読みする実装に関するヒントに過ぎません。

例として、ヘッダビューウィンドウに、フォルダ中の全てのメッセージに対する Subject、 From、および X-mailer ヘッダを入力するクライアントを示します。

 
  Message[] msgs = folder.getMessages();
  
  FetchProfile fp = new FetchProfile();
  fp.add(FetchProfile.Item.ENVELOPE);
  fp.add("X-mailer");
  folder.fetch(msgs, fp);
  
  for (int i = 0; i < folder.getMessageCount(); i++) {
      display(msg[i].getFrom());
      display(msg[i].getSubject());
      display(msg[i].getHeader("X-mailer"));
  }
 
 

ここで提供される実装は、単に戻るだけです。 このメソッドを現実に実装するプロバイダは、このメソッドをオーバーライドする必要があります。

パラメータ:
msgs - これらのメッセージのフェッチ項目
fp - FetchProfile
例外:
IllegalStateException - このフォルダが開かれていない場合
MessagingException.
MessagingException

setFlags

public void setFlags(Message[] msgs,
                     Flags flag,
                     boolean value)
              throws MessagingException
配列中に指定されたメッセージ上に指定されたフラグを設定します。 これにより、この Message を含んでいるフォルダ上に登録されている 全ての MessageChangedListener に適切な MessageChangedEvent が配信される事になります。

指定された Message オブジェクトは、このフォルダに属している必要があります。 Folder 実装によっては、メッセージのグループに対する Flags の設定操作を最適化している場合があるので、 クライアントは各 Message について Message.setFlags を呼び出すのではなく、 このメソッドを使用するとよいでしょう。

この実装は、単に各 Message オブジェクト上で setFlags() を呼び出すだけです。 この操作を最適化できるような特定の Folder 実装では、最適化すべきです。 又、配列中の Message が消去された Message であると判明した場合、実装は操作を中止してはいけません。

パラメータ:
msgs - メッセージオブジェクトの配列
flag - 設定されるフラグを含む Flags オブジェクト
value - フラグにこのブール値を設定する
例外:
IllegalStateException - このフォルダが開かれていない場合、又は READ_ONLY で開かれている場合
MessagingException
関連項目:
Message.setFlags(javax.mail.Flags, boolean), MessageChangedEvent

setFlags

public void setFlags(int start,
                     int end,
                     Flags flag,
                     boolean value)
              throws MessagingException
指定されたフラグを、start から end まで (start と end の両方を含む) の番号のメッセージ上に設定します。 メッセージ番号は 0 ではなく 1 から始まります。これにより、 この Message を含んでいるフォルダ上に登録されている 全ての MessageChangedListener に適切な MessageChangedEvent が配信される事になります。

Folder 実装によっては、メッセージのグループについて Flags の設定操作を最適化している場合があるので、 クライアントは各 Message に対して Message.setFlags を 呼び出すよりもこのメソッドを使用するとよいでしょう。

デフォルトの実装は getMessage(int) を使用して 各 Message オブジェクトを取得した後、 そのオブジェクト上で setFlags を呼び出してフラグを設定します。 この操作を最適化できる様な特定の Folder 実装では、最適化すべきです。 又、メッセージ番号が消去されたメッセージを参照する場合でも、 実装は操作を中止してはいけません。

パラメータ:
start - 最初のメッセージの番号
end - 最後のメッセージの番号
flag - 設定されるフラグを含む Flags オブジェクト
value - フラグにこのブール値を設定する
例外:
IllegalStateException - このフォルダが開かれていない場合、又は READ_ONLY で開かれている場合
IndexOutOfBoundsException - start 又は end のメッセージ番号が範囲外の場合
MessagingException
関連項目:
Message.setFlags(javax.mail.Flags, boolean), MessageChangedEvent

setFlags

public void setFlags(int[] msgnums,
                     Flags flag,
                     boolean value)
              throws MessagingException
メッセージ番号が配列中に存在するメッセージ上に指定されたフラグを設定します。 これにより、この Message を含んでいるフォルダ上に登録されている 全ての MessageChangedListener に適切な MessageChangedEvent が配信される事になります。

Folder 実装によっては、メッセージのグループについて Flags の設定操作を 最適化している場合があるので、クライアントは各 Message に 対して Message.setFlags を呼び出すよりもこのメソッドを使用するとよいでしょう。

デフォルトの実装は getMessage(int) を使用して 各 Message オブジェクトを取得した後、 そのオブジェクト上で setFlags を呼び出してフラグを設定します。 この操作を最適化できる様な特定の Folder 実装では、最適化すべきです。 又、メッセージ番号が消去されたメッセージを参照する場合でも、 実装は操作を中止してはいけません。

パラメータ:
msgnums - メッセージ番号の配列
flag - 設定されるフラグを含む Flags オブジェクト
value - フラグにこのブール値を設定する
例外:
IllegalStateException - このフォルダが開かれていない場合、又は READ_ONLY で開かれている場合
IndexOutOfBoundsException - 指定された配列中の何れかのメッセージ番号が範囲外の場合
MessagingException
関連項目:
Message.setFlags(javax.mail.Flags, boolean), MessageChangedEvent

copyMessages

public void copyMessages(Message[] msgs,
                         Folder folder)
                  throws MessagingException
この Folder から指定された Message を別の Folder にコピーします。 この操作はこれらの Message をコピー先 Folder に追加します。 コピー先 Folder が開かれている必要はありません。メッセージがフォルダ中に到着すると、 コピー先フォルダ上に登録されている全ての MessageCountListener に適切な MessageCountEvent が配信されます。

指定された Message オブジェクトは、このフォルダに属している必要があります。 Folder 実装によっては、サーバ内コピーを行う事により、このメソッドを最適化できます。

この実装は単にコピー先フォルダ上で appendMessages() を呼び出し、 指定された Message を追加します。コピー先フォルダの Store がこのフォルダの Store と同じ場合、 サーバ内コピーをサポートできる様な特定の Folder 実装では、その様な最適化を行うべきです。 又、配列中の Message が消去された Message と判明した場合でも、実装は操作を中止してはいけません。

パラメータ:
msgs - メッセージオブジェクトの配列
folder - メッセージのコピー先フォルダ
例外:
FolderNotFoundException - コピー先フォルダが存在しない場合
IllegalStateException - このフォルダが開かれていない場合
MessagingException
関連項目:
appendMessages(javax.mail.Message[])

expunge

public abstract Message[] expunge()
                           throws MessagingException
DELETED のマークが付いている消去 (永続的な削除) メッセージです。 消去されたメッセージオブジェクトを含む配列を返します。 これらの各メッセージオブジェクト上の getMessageNumber メソッドは、 Message の元 (つまり、消去前) のシーケンス番号を返します。 フォルダ上に登録されている全ての MessageCountListener に、 消去されたメッセージを含む MessageCountEvent が配信されます。

メッセージの消去により、消去メッセージ以降の Message オブジェクトの番号が再度割り当てられます。 メッセージへの参照としてメッセージ番号を使用するクライアントはこの点に注意しなければならず、 状況に対処する準備が必要になります (既存のメッセージ番号キャッシュを消去し、再度読込む)。 こうした複雑さから、クライアントはメッセージ番号でなく Message オブジェクトを使用してメッセージを参照する方が適切です。 消去される Message オブジェクトは依然として除去する必要がありますが、 フォルダ中の他の Message オブジェクトは消去による影響を受けません。

メッセージが削除された後、対応する Message オブジェクト上 では isExpunged 及び getMessageNumber メソッドのみが依然有効です。 その他のメソッドは MessageRemovedException をスローする場合があります。

戻り値:
消去された Message オブジェクトの配列
例外:
FolderNotFoundException - このフォルダが存在しない場合
IllegalStateException - このフォルダが開かれていない場合
MessagingException
関連項目:
Message.isExpunged(), MessageCountEvent

search

public Message[] search(SearchTerm term)
                 throws MessagingException
指定された検索基準に一致するメッセージについてこの Folder を検索します。 一致するメッセージを含む配列を返します。 一致するものが見つからない場合は、空の配列を返します。

この実装は search(term, getMessages()) を呼び出し、 このフォルダ中の全てのメッセージについて検索を適用します。 サーバ側の検索を実装可能なプロバイダは、このメソッドを オーバーライドしてより効率的な実装を提供するとよいでしょう。

パラメータ:
term - 検索基準
戻り値:
一致するメッセージの配列
例外:
SearchException - 検索条件が複雑すぎて実装が処理できない場合
FolderNotFoundException - このフォルダが存在しない場合
IllegalStateException - このフォルダが開かれていない場合
MessagingException
関連項目:
SearchTerm

search

public Message[] search(SearchTerm term,
                        Message[] msgs)
                 throws MessagingException
指定された検索基準に一致するメッセージについて、 指定されたメッセージ配列を検索します。 一致するメッセージを含む配列を返します。 一致するものが見つからない場合は、空の配列を返します。

指定された Message オブジェクトは、このフォルダに属している必要があります

この実装は指定されたメッセージの配列の要素それぞれに対し、 指定された条件で match() メソッドを呼び出す事により、 各メッセージに検索基準を適用します。一致に成功したメッセージが返されます。 サーバ側の検索を実装可能なプロバイダは、このメソッドをオーバーライドし、 より効率的な実装を提供するとよいでしょう。 検索条件が複雑すぎるか、サーバ側で実行できないユーザ定義条件を含む場合、 プロバイダは SearchException をスローするか、 又は super.search() を呼び出す事でこの実装を呼び出して、 (最適化されていない) クライアント側での検索に任せる事が可能です。

パラメータ:
term - 検索基準
msgs - 検索されるメッセージ
戻り値:
一致するメッセージの配列
例外:
SearchException - 検索条件が複雑すぎて実装が処理できない場合
IllegalStateException - このフォルダが開かれていない場合
MessagingException
関連項目:
SearchTerm

addConnectionListener

public void addConnectionListener(ConnectionListener l)
この Folder に Connection イベントのリスナーを追加します。

ここで提供される実装は、このリスナーを内部の ConnectionListener リストに追加します。

パラメータ:
l - Connection イベントの Listener
関連項目:
ConnectionEvent

removeConnectionListener

public void removeConnectionListener(ConnectionListener l)
Connection イベントリスナーを削除します。

ここで提供される実装は、このリスナーを内部の ConnectionListener リストから削除します。

パラメータ:
l - リスナー
関連項目:
addConnectionListener(javax.mail.event.ConnectionListener)

notifyConnectionListeners

protected void notifyConnectionListeners(int type)
すべての ConnectionListener に通知します。 Folder 実装は、このメソッドを使用して接続イベントをブロードキャストする必要があります。

提供される実装は、イベントを内部イベントキューに入れます。 イベントディスパッチャスレッドはキューからイベントを出し、 登録された ConnectionListener にディスパッチします。 イベントディスパッチは別個のスレッドで起こる為、デッドロック問題を防ぎます。

パラメータ:
type - ConnectionEvent の型
関連項目:
ConnectionEvent

addFolderListener

public void addFolderListener(FolderListener l)
この Folder に Folder イベントのリスナーを追加します。

ここで提供される実装は、このリスナーを内部の FolderListener リストに追加します。

パラメータ:
l - Folder イベントの Listener
関連項目:
FolderEvent

removeFolderListener

public void removeFolderListener(FolderListener l)
Folder イベントリスナーを削除します。

ここで提供される実装は、このリスナーを内部の FolderListener リストから削除します。

パラメータ:
l - リスナー
関連項目:
addFolderListener(javax.mail.event.FolderListener)

notifyFolderListeners

protected void notifyFolderListeners(int type)
この Folder とこのフォルダの Store 上に登録されている全ての FolderListener に通知します。 Folder 実装はこのメソッドを使用して、Folder イベントをブロードキャストする必要があります。

ここで提供される実装は、イベントを内部イベントキューに入れます。 イベントディスパッチャスレッドはイベントをキューから出し、 このフォルダ上に登録されている FolderListener にディスパッチします。 又、実装はこのフォルダの Store 上で notifyFolderListeners を呼び出し、 ストア上に登録されているすべての FolderListener に通知します。

パラメータ:
type - FolderEvent の型
関連項目:
notifyFolderRenamedListeners(javax.mail.Folder)

notifyFolderRenamedListeners

protected void notifyFolderRenamedListeners(Folder folder)
この Folder とこのフォルダの Store 上に登録されている全ての FolderListener に、 このフォルダの名前変更について通知します。Folder 実装はこのメソッドを使用して、 フォルダの名前変更に関する Folder イベントをブロードキャストする必要があります。

ここで提供される実装は、イベントを内部イベントキューに入れます。 イベントディスパッチャスレッドはイベントをキューから出し、 このフォルダ上に登録されている FolderListener にディスパッチします。 又、実装はこのフォルダの Store 上で notifyFolderRenamedListeners を呼び出し、 ストア上に登録されている全ての FolderListener に通知します。

パラメータ:
folder - 新しい名前を表すフォルダ
導入されたバージョン:
JavaMail 1.1
関連項目:
notifyFolderListeners(int)

addMessageCountListener

public void addMessageCountListener(MessageCountListener l)
この Folder に MessageCount イベントのリスナーを追加します。

ここで提供される実装は、このリスナーを内部の MessageCountListener リストに追加します。

パラメータ:
l - MessageCount イベントの Listener
関連項目:
MessageCountEvent

removeMessageCountListener

public void removeMessageCountListener(MessageCountListener l)
MessageCount リスナーを削除します。

ここで提供される実装は、このリスナーを内部の MessageCountListener リストから削除します。

パラメータ:
l - リスナー
関連項目:
addMessageCountListener(javax.mail.event.MessageCountListener)

notifyMessageAddedListeners

protected void notifyMessageAddedListeners(Message[] msgs)
全ての MessageCountListener に、このフォルダへのメッセージ追加を通知します。 Folder 実装はこのメソッドを使用し、新規メッセージの到着を 示す MessageCount イベントをブロードキャストする必要があります。

提供される実装は、イベントを内部イベントキューに入れます。 イベントディスパッチャスレッドはキューからイベントを出し、 登録された MessageCountListener にディスパッチします。 イベントディスパッチは別個のスレッドで起こる為、デッドロック問題を防ぎます。


notifyMessageRemovedListeners

protected void notifyMessageRemovedListeners(boolean removed,
                                             Message[] msgs)
全ての MessageCountListener に、このフォルダからのメッセージ削除を通知します。 Folder 実装はこのメソッドを使用し、メッセージの削除を 示す MessageCount イベントをブロードキャストする必要があります。

提供される実装は、イベントを内部イベントキューに入れます。 イベントディスパッチャスレッドはキューからイベントを出し、 登録された MessageCountListener にディスパッチします。 イベントディスパッチは別個のスレッドで起こる為、デッドロック問題を防ぎます。


addMessageChangedListener

public void addMessageChangedListener(MessageChangedListener l)
この Folder に MessageChanged イベントのリスナーを追加します。

ここで提供される実装は、このリスナーを内部の MessageChangedListener リストに追加します。

パラメータ:
l - MessageChanged イベントの Listener
関連項目:
MessageChangedEvent

removeMessageChangedListener

public void removeMessageChangedListener(MessageChangedListener l)
MessageChanged リスナーを削除します。

ここで提供される実装は、このリスナーを内部の MessageChangedListener リストから削除します。

パラメータ:
l - リスナー
関連項目:
addMessageChangedListener(javax.mail.event.MessageChangedListener)

notifyMessageChangedListeners

protected void notifyMessageChangedListeners(int type,
                                             Message msg)
全ての MessageChangedListener に通知します。 Folder 実装はこのメソッドを使用して、MessageChanged イベントをブロードキャストする必要があります。

提供される実装は、イベントを内部イベントキューに入れます。 イベントディスパッチャスレッドはキューからイベントを出し、 登録された MessageChangedListener にディスパッチします。 イベントディスパッチは別個のスレッドで起こる為、デッドロック問題を防ぎます。


finalize

protected void finalize()
                 throws Throwable
オーバーライド:
クラス Object 内の finalize
例外:
Throwable

toString

public final String toString()
デフォルトの toString() をオーバーライドします。 Folder.getFullName() からの String を返すか、 それが null の場合はデフォルトの toString() 動作を使用します。

オーバーライド:
クラス Object 内の toString