javax.mail
クラス Service

java.lang.Object
  上位を拡張 javax.mail.Service
直系の既知のサブクラス:
Store, Transport

public abstract class Service
extends Object

ストアやトランスポートといったメッセージングサービスに 共通の機能を含む abstract クラスです。

メッセージングサービスは Session から作成され、 URLName を使用して名前が付けられます。 サービスは使用する前に接続しなければなりません。 接続イベントが送信され、接続状態を反映します。


フィールドの概要
protected  boolean debug
          このサービスのデバッグフラグです。
protected  Session session
          このサービスが作成されたセッションです。
protected  URLName url
          このサービスの URLName です。
 
コンストラクタの概要
protected Service(Session session, URLName urlname)
          コンストラクタです。
 
メソッドの概要
 void addConnectionListener(ConnectionListener l)
          このサービス上に Connection イベントのリスナーを追加します。
 void close()
          このサービスを閉じ、接続を終了させます。
 void connect()
          パラメータを 1 つも受け取らない汎用的な接続メソッド。
 void connect(String host, int port, String user, String password)
          特定のポートを指定可能である点を除き、 connect(host, user, password) と同じです。
 void connect(String user, String password)
          Connect to the current host using the specified username and password.
 void connect(String host, String user, String password)
          指定されたアドレスに接続します。
protected  void finalize()
          キューがガベージコレクト可能になるように、イベントディスパッチャスレッドを停止します。
 URLName getURLName()
          このサービスを表す URLName を返します。
 boolean isConnected()
          サービスの接続状態を返します。
protected  void notifyConnectionListeners(int type)
          全ての ConnectionListener に通知します。
protected  boolean protocolConnect(String host, int port, String user, String password)
          サービス実装はこのメソッドをオーバーライドし、 実際のプロトコル固有の接続を試行しなければなりません。
protected  void queueEvent(MailEvent event, Vector vector)
          リスナーの event と vector を配信キューに追加します。
 void removeConnectionListener(ConnectionListener l)
          Connection イベントのリスナーを削除します。
protected  void setConnected(boolean connected)
          このサービスの接続状態を設定します。
protected  void setURLName(URLName url)
          このサービスを表す URLName を設定します。
 String toString()
          このサービスが URLName を持つ場合は、getURLName.toString() を返します。
 
クラス java.lang.Object から継承されたメソッド
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

フィールドの詳細

session

protected Session session
このサービスが作成されたセッションです。


url

protected URLName url
このサービスの URLName です。


debug

protected boolean debug
このサービスのデバッグフラグです。 このサービスが作成される時に、セッションのデバッグフラグから設定されます。

コンストラクタの詳細

Service

protected Service(Session session,
                  URLName urlname)
コンストラクタです。

パラメータ:
session - このサービスの Session オブジェクト
urlname - このサービスに使用される URLName オブジェクト
メソッドの詳細

connect

public void connect()
             throws MessagingException
パラメータを 1 つも受け取らない汎用的な接続メソッド。 サブクラスは適切な認証スキーマを実装できます。 追加情報を必要とするサブクラスについては、特定のプロパティを使用するか、 又はポップアップウィンドウを使用して対話型で追加情報を取得する事になります。

接続が正常終了すると、このサービス上の全ての ConnectionListener に "open" ConnectionEvent が配信されます。

殆どのクライアントは単にこのメソッドを呼び出し、サービスに接続しなければなりません。

既に接続済みのサービスに接続するとエラーになります。

ここで提供される実装は、単に次の connect(String, String, String) メソッドを null と共に呼び出すだけです。

例外:
AuthenticationFailedException - 認証の障害の場合
MessagingException - 他の障害の場合
IllegalStateException - このサービスがすでに接続されている場合
関連項目:
ConnectionEvent

connect

public void connect(String host,
                    String user,
                    String password)
             throws MessagingException
指定されたアドレスに接続します。 このメソッドはユーザ名とパスワードを要求する単純な認証スキーマを提供します。

接続が正常終了すると、このサービス上の全ての ConnectionListener に "open" な ConnectionEvent が配信されます。

既に接続済みのサービスに接続するとエラーになります。

Service クラスにおける実装は、ホスト、ユーザ、及びパスワードのデフォルトをセッション、 このサービスの URLName、及び提供されるパラメータから収集した後、 protocolConnect メソッドを呼び出します。 protocolConnect メソッドが false を返す場合、 ユーザには不足情報の入力要求が表示され、protocolConnect メソッドが再び呼び出されます。 サブクラスは protocolConnect メソッドをオーバーライドしなければなりません。 又、サブクラスは getURLName メソッドを実装するか、 このクラス中の実装を使用しなければなりません。

接続が成功すると、パスワード等、接続作成に使用された情報を含む URLName と共に setURLName メソッドが呼び出されます。

渡されるパスワードが null で、これがこのサービスについて最初に成功した接続の場合、 ユーザから収集されたユーザ名とパスワードは、今後他の Service オブジェクトインスタンスを 使用してこの同じサービスに接続試行した場合のデフォルトとして保存されます (接続情報は通常、常に特定の Service オブジェクトインスタンス内に保存されます)。 パスワードは Session メソッド setPasswordAuthenticaiton を使用して保存されます。 渡されるパスワードが null でない場合、アプリケーションがパスワードを明示的に管理しているという前提で、 そのパスワードは保存されません。

パラメータ:
host - 接続先のホスト
user - ユーザ名
password - ユーザのパスワード
例外:
AuthenticationFailedException - 認証の障害の場合
MessagingException - 他の障害の場合
IllegalStateException - このサービスが既に接続されている場合
関連項目:
ConnectionEvent, Session.setPasswordAuthentication(javax.mail.URLName, javax.mail.PasswordAuthentication)

connect

public void connect(String user,
                    String password)
             throws MessagingException
Connect to the current host using the specified username and password. This method is equivalent to calling the connect(host, user, password) method with null for the host name.

パラメータ:
user - ユーザ名
password - ユーザのパスワード
例外:
AuthenticationFailedException - 認証の障害の場合
MessagingException - 他の障害の場合
IllegalStateException - このサービスが既に接続されている場合
導入されたバージョン:
JavaMail 1.4
関連項目:
ConnectionEvent, Session.setPasswordAuthentication(javax.mail.URLName, javax.mail.PasswordAuthentication), connect(String, String, String)

connect

public void connect(String host,
                    int port,
                    String user,
                    String password)
             throws MessagingException
特定のポートを指定可能である点を除き、 connect(host, user, password) と同じです。

パラメータ:
host - 接続先のホスト
port - 接続先のポート (-1 はデフォルトのポートを意味する)
user - ユーザ名
password - ユーザのパスワード
例外:
AuthenticationFailedException - 認証の障害の場合
MessagingException - 他の障害の場合
IllegalStateException - このサービスが既に接続されている場合
関連項目:
connect(java.lang.String, java.lang.String, java.lang.String), ConnectionEvent

protocolConnect

protected boolean protocolConnect(String host,
                                  int port,
                                  String user,
                                  String password)
                           throws MessagingException
サービス実装はこのメソッドをオーバーライドし、 実際のプロトコル固有の接続を試行しなければなりません。 connect メソッドのデフォルトの実装は、 必要に応じてこのメソッドを呼び出します。

認証の為にユーザ名またはパスワードが必要だが、 対応するパラメータが null の場合、protocolConnect メソッドは false を返さなければなりません。 connect メソッドは必要に応じてユーザに入力を要求し、 不足した情報を供給します。 又、供給されたユーザ名又はパスワードの為に認証が失敗した場合、 このメソッドは false を返すことがあります。 認証の障害時に、このメソッドは AuthenticationFailedException をスローする事もあります。 この例外には、障害に関する詳細記述した String メッセージが含まれる事があります。

protocolConnect メソッドは例外をスローし、 認証に関連しない障害を報告しなければなりません。 例として、無効なホスト名又はポート番号、認証処理中の接続切断、 サーバの停止等があります。

パラメータ:
host - 接続先のホスト名
port - 使用するポート (-1 はデフォルトポートの使用を意味する)
user - ログインするユーザ名
password - ユーザのパスワード
戻り値:
接続が成功した場合は true、認証が失敗した場合は false
例外:
AuthenticationFailedException - 認証の障害の場合
MessagingException - 認証以外の障害の場合

isConnected

public boolean isConnected()
サービスの接続状態を返します。

この実装は private の boolean フィールドを使用して、接続状態を格納します。 このメソッドはそのフィールドの値を返します。

サブクラスはこのメソッドをオーバーライドし、 全てのメッセージストアへの接続を確認します。

戻り値:
サービスが接続されている場合は true、接続されていない場合は false

setConnected

protected void setConnected(boolean connected)
このサービスの接続状態を設定します。接続状態は、 connect 及び close メソッドで、 サービス実装により自動的に設定されます。 サービスが自動的に切断された場合、サブクラスはこのメソッドを呼び出して、 状態を設定する必要があります。

このクラスにおける実装は、isConnected メソッド により返される privateフィールドを単に設定するだけです。

パラメータ:
connected - サービスが接続されている場合は true、接続されていない場合は false

close

public void close()
           throws MessagingException
このサービスを閉じ、接続を終了させます。 クローズの ConnectionEvent は全ての ConnectionListener に配信されます。 このサービスに属する全ての Messaging コンポーネント (Folder、Message 等) は、 このサービスが閉じた後無効になります。 このメソッドが MessagingException のスローにより異常終了した場合でも、 このサービスは閉じられます。

この実装は setConnected(false) を使用して、 このサービスの接続状態を false に設定します。 その後、クローズの ConnectionEvent を全ての登録済み ConnectionListener に送信します。 実装固有の終了処理を行う為にこのメソッドをオーバーライドするサブクラスは、 最後の手順としてこのメソッドを呼び出し、イベント通知を確実にしなければなりません。 恐らく finally 節に super.close() への呼び出しを含める事が考えられます。

例外:
MessagingException - クローズ中のエラーの場合
関連項目:
ConnectionEvent

getURLName

public URLName getURLName()
このサービスを表す URLName を返します。 返される URLName はパスワードフィールドを含みません

サブクラスは、URLName が標準形式にのっとっていない場合、 このメソッドをオーバーライドしなければなりません。

Service クラスにおける実装は、パスワードとファイル情報を 取り除いた url フィールド (通常はコピー) を返します。

戻り値:
このサービスを表す URLName
関連項目:
URLName

setURLName

protected void setURLName(URLName url)
このサービスを表す URLName を設定します。 通常、サービスの接続が正常終了した後、 url フィールドを更新する為に使用されます。

サブクラスは、URL が標準形式にのっとっていない場合、 このメソッドをオーバーライドしなければなりません。 特に、URL が URLName によりサポートされる全ての可能なフィールドを要求しない場合、 サブクラスはこのメソッドをオーバーライドしなければなりません。 その場合、新しい URLName は、 削除された任意の不要なフィールドを使用して構築する必要があります。

Service クラスにおける実装は、単に url フィールドを設定します。

関連項目:
URLName

addConnectionListener

public void addConnectionListener(ConnectionListener l)
このサービス上に 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 に通知します。 Service 実装はこのメソッドを使用して、 接続イベントをブロードキャストしなければなりません。

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


toString

public String toString()
このサービスが URLName を持つ場合は、getURLName.toString() を返します。 そうでない場合は、デフォルトの toString を返します。

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

queueEvent

protected void queueEvent(MailEvent event,
                          Vector vector)
リスナーの event と vector を配信キューに追加します。


finalize

protected void finalize()
                 throws Throwable
キューがガベージコレクト可能になるように、イベントディスパッチャスレッドを停止します。

オーバーライド:
クラス Object 内の finalize
例外:
Throwable