|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
javax.mail Class Service
java.lang.Object javax.mail.Service
public abstract class Service
- extends Object
包含常用于消息传递服务(比如 store 和 transport)的功能的抽象类。
消息传递服务是从 Session
中创建的,并使用 URLName
命名。在使用某个服务之前,必须先连接到该服务。发送 Connection 事件以反映其连接状态。
version | 1.33, 07/05/14 |
An abstract class that contains the functionality common to messaging services, such as stores and transports.
A messaging service is created from a Session
and is
named using a URLName
. A service must be connected
before it can be used. Connection events are sent to reflect
its connection status.
- Version:
- 1.33, 07/05/14
- Author:
- Christopher Cotton, Bill Shannon, Kanwar Oberoi
Field Summary | |
---|---|
protected boolean |
debug
Debug flag for this service. |
protected Session |
session
The session from which this service was created. |
protected URLName |
url
The URLName of this service. |
Constructor Summary | |
---|---|
protected |
Service(Session session,
URLName urlname)
Constructor. |
Method Summary | |
---|---|
void |
addConnectionListener(ConnectionListener l)
Add a listener for Connection events on this service. |
void |
close()
Close this service and terminate its connection. |
void |
connect()
A generic connect method that takes no parameters. |
void |
connect(String host,
int port,
String user,
String password)
Similar to connect(host, user, password) except a specific port can be specified. |
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)
Connect to the specified address. |
protected void |
finalize()
Stop the event dispatcher thread so the queue can be garbage collected. |
URLName |
getURLName()
Return a URLName representing this service. |
boolean |
isConnected()
Is this service currently connected? |
protected void |
notifyConnectionListeners(int type)
Notify all ConnectionListeners. |
protected boolean |
protocolConnect(String host,
int port,
String user,
String password)
The service implementation should override this method to perform the actual protocol-specific connection attempt. |
protected void |
queueEvent(MailEvent event,
Vector vector)
Add the event and vector of listeners to the queue to be delivered. |
void |
removeConnectionListener(ConnectionListener l)
Remove a Connection event listener. |
protected void |
setConnected(boolean connected)
Set the connection state of this service. |
protected void |
setURLName(URLName url)
Set the URLName representing this service. |
String |
toString()
Return getURLName.toString() if this service has a URLName,
otherwise it will return the default toString . |
Methods inherited from class java.lang.Object |
---|
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
英文文档:
session
protected Session session
- The session from which this service was created.
英文文档:
url
protected URLName url
- The
URLName
of this service.
英文文档:
debug
protected boolean debug
- Debug flag for this service. Set from the session's debug
flag when this service is created.
Constructor Detail |
---|
protected
Service(Session session, URLName urlname)
构造方法。
session | 此服务的 Session 对象 |
urlname | 要用于此服务的 URLName 对象 |
Service
protected Service(Session session, URLName urlname)
- Constructor.
- Parameters:
session
- Session object for this serviceurlname
- URLName object to be used for this service
Method Detail |
---|
public void
connect() throws MessagingException
不带参数的常规 connect 方法。子类可以实现相应的验证方案。需要额外信息的子类可能想要使用某些属性,或者可能使用弹出窗口以交互方式获得这些信息。
如果连接成功,则向此服务上的所有 ConnectionListener
传送一个 "open" ConnectionEvent
。
大多数客户端应该只调用此方法连接到该服务。
连接已经连接的服务是一个错误。
此处提供的实现仅使用 null 调用以下 connect(String, String, String)
方法。
Throws | AuthenticationFailedException: 用于验证失败 |
Throws | MessagingException: 用于其他失败 |
Throws | IllegalStateException: 如果已经连接该服务 |
See also | javax.mail.event.ConnectionEvent |
connect
public void connect() throws MessagingException
- A generic connect method that takes no parameters. Subclasses
can implement the appropriate authentication schemes. Subclasses
that need additional information might want to use some properties
or might get it interactively using a popup window.
If the connection is successful, an "open"
ConnectionEvent
is delivered to anyConnectionListeners
on this service.Most clients should just call this method to connect to the service.
It is an error to connect to an already connected service.
The implementation provided here simply calls the following
connect(String, String, String)
method with nulls. - Throws:
AuthenticationFailedException
- for authentication failuresMessagingException
- for other failuresIllegalStateException
- if the service is already connected- See Also:
ConnectionEvent
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,则如上所述将选择默认值。
如果传入的密码为 null,并且这是第一次成功连接到此服务,则从用户处收集的用户名和密码将被保存为默认值,用于后续使用其他 Service 对象实例时到此同一服务的连接尝试(连接信息通常总是保存在特定 Service 对象实例中)。密码是使用 Session 方法 setPasswordAuthentication
保存的。假定应用程序显式管理密码,那么即使传入的密码不为 null,也不保存该密码。
host | 要连接到的主机 |
user | 用户名 |
password | 此用户的密码 |
Throws | AuthenticationFailedException: 用于验证失败 |
Throws | MessagingException: 用于其他失败 |
Throws | IllegalStateException: 如果已经连接该服务 |
See also | javax.mail.event.ConnectionEvent, setPasswordAuthentication |
connect
public void connect(String host, String user, String password) throws MessagingException
- Connect to the specified address. This method provides a simple
authentication scheme that requires a username and password.
If the connection is successful, an "open"
ConnectionEvent
is delivered to anyConnectionListeners
on this service.It is an error to connect to an already connected service.
The implementation in the Service class will collect defaults for the host, user, and password from the session, from the
URLName
for this service, and from the supplied parameters and then call theprotocolConnect
method. If theprotocolConnect
method returnsfalse
, the user will be prompted for any missing information and theprotocolConnect
method will be called again. The subclass should override theprotocolConnect
method. The subclass should also implement thegetURLName
method, or use the implementation in this class.On a successful connection, the
setURLName
method is called with a URLName that includes the information used to make the connection, including the password.If the username passed in is null, a default value will be chosen as described above. If the password passed in is null and this is the first successful connection to this service, the user name and the password collected from the user will be saved as defaults for subsequent connection attempts to this same service when using other Service object instances (the connection information is typically always saved within a particular Service object instance). The password is saved using the Session method
setPasswordAuthentication
. If the password passed in is not null, it is not saved, on the assumption that the application is managing passwords explicitly. - Parameters:
host
- the host to connect touser
- the user namepassword
- this user's password- Throws:
AuthenticationFailedException
- for authentication failuresMessagingException
- for other failuresIllegalStateException
- if the service is already connected- See Also:
ConnectionEvent
,Session.setPasswordAuthentication(javax.mail.URLName, javax.mail.PasswordAuthentication)
public void
connect(String user, String password) throws MessagingException
使用指定用户名和密码连接到当前主机。此方法等效于使用 null 作为主机名调用 connect(host, user, password)
方法。
user | 用户名 | |
password | 此用户的密码 | |
Throws | AuthenticationFailedException: 用于验证失败 | |
Throws | MessagingException: 用于其他失败 | |
Throws | IllegalStateException: 如果已经连接该服务 | |
since |
| |
See also | javax.mail.event.ConnectionEvent, setPasswordAuthentication, connect(java.lang.String, java.lang.String, java.lang.String) |
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. - Parameters:
user
- the user namepassword
- this user's password- Throws:
AuthenticationFailedException
- for authentication failuresMessagingException
- for other failuresIllegalStateException
- if the service is already connected- Since:
- JavaMail 1.4
- See Also:
ConnectionEvent
,Session.setPasswordAuthentication(javax.mail.URLName, javax.mail.PasswordAuthentication)
,connect(java.lang.String, java.lang.String, java.lang.String)
public void
connect(String host, int port, String user, String password) throws MessagingException
类似于 connect(host, user, password),但是可指定特定端口。
host | 要连接到的主机 |
port | 要连接到的端口(-1 表示默认端口) |
user | 用户名 |
password | 此用户的密码 |
Throws | AuthenticationFailedException: 用于验证失败 |
Throws | MessagingException: 用于其他失败 |
Throws | IllegalStateException: 如果已经连接该服务 |
See also | connect(java.lang.String, java.lang.String, java.lang.String), javax.mail.event.ConnectionEvent |
connect
public void connect(String host, int port, String user, String password) throws MessagingException
- Similar to connect(host, user, password) except a specific port
can be specified.
- Parameters:
host
- the host to connect toport
- the port to connect to (-1 means the default port)user
- the user namepassword
- this user's password- Throws:
AuthenticationFailedException
- for authentication failuresMessagingException
- for other failuresIllegalStateException
- if the service is already connected- See Also:
connect(java.lang.String, java.lang.String, java.lang.String)
,ConnectionEvent
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 | 用户的密码 |
return | 如果连接成功,则返回 true;如果验证失败,则返回 false |
Throws | AuthenticationFailedException: 用于验证失败 |
Throws | MessagingException: 用于非验证失败 |
protocolConnect
protected boolean protocolConnect(String host, int port, String user, String password) throws MessagingException
- The service implementation should override this method to
perform the actual protocol-specific connection attempt.
The default implementation of the
connect
method calls this method as needed.The
protocolConnect
method should returnfalse
if a user name or password is required for authentication but the corresponding parameter is null; theconnect
method will prompt the user when needed to supply missing information. This method may also returnfalse
if authentication fails for the supplied user name or password. Alternatively, this method may throw an AuthenticationFailedException when authentication fails. This exception may include a String message with more detail about the failure.The
protocolConnect
method should throw an exception to report failures not related to authentication, such as an invalid host name or port number, loss of a connection during the authentication process, unavailability of the server, etc. - Parameters:
host
- the name of the host to connect toport
- the port to use (-1 means use default port)user
- the name of the user to login aspassword
- the user's password- Returns:
- true if connection successful, false if authentication failed
- Throws:
AuthenticationFailedException
- for authentication failuresMessagingException
- for non-authentication failures
public boolean
isConnected()
此服务目前是否被连接?
此实现使用私有 boolean 字段存储连接状态。此方法返回该字段的值。
子类可能想重写此方法以验证到该消息存储的任何连接是否仍然处于活动状态。
return | 如果该服务被连接,则返回 true;如果该服务未被连接,则返回 false |
isConnected
public boolean isConnected()
- Is this service currently connected?
This implementation uses a private boolean field to store the connection state. This method returns the value of that field.
Subclasses may want to override this method to verify that any connection to the message store is still alive.
- Returns:
- true if the service is connected, false if it is not connected
protected void
setConnected(boolean connected)
设置此服务的连接状态。在调用 connect
和 close
方法期间,连接状态将由该服务实现自动设置。如果到该服务的连接自动断开,则子类将需要调用此方法设置状态。
此类中的实现仅设置 isConnected
方法返回的私有字段。
connected | 如果该服务被连接,则为 true;如果该服务未被连接,则为 false |
setConnected
protected void setConnected(boolean connected)
- Set the connection state of this service. The connection state
will automatically be set by the service implementation during the
connect
andclose
methods. Subclasses will need to call this method to set the state if the service was automatically disconnected.The implementation in this class merely sets the private field returned by the
isConnected
method. - Parameters:
connected
- true if the service is connected, false if it is not connected
public void
close() throws MessagingException
关闭此服务并终止其连接。向所有 ConnectionListener 传送 close ConnectionEvent。在此服务关闭后,所有属于此服务的 Messaging 组件(Folder、Message,等等)都是无效的。注意,即使此方法通过抛出 MessagingException 异常终止,服务也会关闭。
此实现使用 setConnected(false)
将此服务的 connected 状态设置为 false
。然后它会向所有注册的 ConnectionListener 发送 close ConnectionEvent。重写此方法以进行特定于实现的清除的子类应该调用此方法,作为确保事件通知的最后一步(可能通过在 finally
子句中包含对 super.close()
的调用来完成)。
Throws | MessagingException: 用于关闭时发生的错误 |
See also | javax.mail.event.ConnectionEvent |
close
public void close() throws MessagingException
- Close this service and terminate its connection. A close
ConnectionEvent is delivered to any ConnectionListeners. Any
Messaging components (Folders, Messages, etc.) belonging to this
service are invalid after this service is closed. Note that the service
is closed even if this method terminates abnormally by throwing
a MessagingException.
This implementation uses
setConnected(false)
to set this service's connected state tofalse
. It will then send a close ConnectionEvent to any registered ConnectionListeners. Subclasses overriding this method to do implementation specific cleanup should call this method as a last step to insure event notification, probably by including a call tosuper.close()
in afinally
clause. - Throws:
MessagingException
- for errors while closing- See Also:
ConnectionEvent
public URLName
getURLName()
返回表示此服务的 URLName。返回的 URLName 不 包括密码字段。
如果 URLName 不符合标准格式,则子类应该仅重写此方法。
Service 类中的实现返回带有已剔除密码和文件信息的 url
字段(通常是其副本)。
return | 表示此服务的 URLName |
See also | javax.mail.URLName |
getURLName
public URLName getURLName()
- Return a URLName representing this service. The returned URLName
does not include the password field.
Subclasses should only override this method if their URLName does not follow the standard format.
The implementation in the Service class returns (usually a copy of) the
url
field with the password and file information stripped out. - Returns:
- the URLName representing this service
- See Also:
URLName
protected void
setURLName(URLName url)
设置表示此服务的 URLName。通常用于在已成功连接某个服务之后更新 url
字段。
如果 URL 不符合标准格式,则子类应该仅重写此方法。尤其是,如果 URL 并不需要 URLName
支持的所有可能字段,则子类应该重写此方法;应该构造移除了所有不需要字段的新的 URLName
。
Service 类中的实现仅设置 url
字段。
See also | javax.mail.URLName |
setURLName
protected void setURLName(URLName url)
- Set the URLName representing this service.
Normally used to update the
url
field after a service has successfully connected.Subclasses should only override this method if their URL does not follow the standard format. In particular, subclasses should override this method if their URL does not require all the possible fields supported by
URLName
; a newURLName
should be constructed with any unneeded fields removed.The implementation in the Service class simply sets the
url
field. - See Also:
URLName
public void
addConnectionListener(ConnectionListener l)
为此服务上的 Connection 事件添加侦听器。
此处提供的默认实现将此侦听器添加到 ConnectionListener 的内部列表。
l | Connection 事件的 Listener |
See also | javax.mail.event.ConnectionEvent |
addConnectionListener
public void addConnectionListener(ConnectionListener l)
- Add a listener for Connection events on this service.
The default implementation provided here adds this listener to an internal list of ConnectionListeners.
- Parameters:
l
- the Listener for Connection events- See Also:
ConnectionEvent
public void
removeConnectionListener(ConnectionListener l)
移除 Connection 事件侦听器。
此处提供的默认实现将从 ConnectionListener 的内部列表中移除此侦听器。
l | 侦听器 |
See also | addConnectionListener |
removeConnectionListener
public void removeConnectionListener(ConnectionListener l)
- Remove a Connection event listener.
The default implementation provided here removes this listener from the internal list of ConnectionListeners.
- Parameters:
l
- the listener- See Also:
addConnectionListener(javax.mail.event.ConnectionListener)
protected void
notifyConnectionListeners(int type)
通知所有 ConnectionListener。服务实现应该使用此方法广播 Connection 事件。
提供的默认实现将该事件加入到内部事件队列。事件分发程序线程取消队列中事件的排队,并将其分发给注册的 ConnectionListener。注意,事件分发发生在不同的线程中,因此避免了可能出现的死锁问题。
notifyConnectionListeners
protected void notifyConnectionListeners(int type)
- Notify all ConnectionListeners. Service implementations are
expected to use this method to broadcast connection events.
The provided default implementation queues the event into an internal event queue. An event dispatcher thread dequeues events from the queue and dispatches them to the registered ConnectionListeners. Note that the event dispatching occurs in a separate thread, thus avoiding potential deadlock problems.
public String
toString()
如果此服务有 URLName,则返回 getURLName.toString()
;否则将返回默认 toString
。
英文文档:
toString
public String toString()
- Return
getURLName.toString()
if this service has a URLName, otherwise it will return the defaulttoString
.
protected void
queueEvent(MailEvent event, java.util.Vector<E> vector)
将侦听器的事件和向量添加到将要传送的队列。
英文文档:
将侦听器的事件和向量添加到将要传送的队列。
queueEvent
protected void queueEvent(MailEvent event, Vector vector)
- Add the event and vector of listeners to the queue to be delivered.
protected void
finalize() throws Throwable
停止事件分发程序线程,这样可以对队列进行垃圾回收。
英文文档:
finalize
protected void finalize() throws Throwable
- Stop the event dispatcher thread so the queue can be garbage collected.
- Throws:
Throwable
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Submit a bug or feature
Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.
PS : 未经我党受权你也可自由散发此文档。 如有任何错误请自行修正;若因此而造成任何损失请直接找人民主席,请勿与本人联系。谢谢!