|
JavaTM 2 Platform Ent. Ed. v1.4 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjavax.mail.Service
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.
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 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 |
protected Session session
protected URLName url
URLName
of this service.
protected boolean debug
Constructor Detail |
protected Service(Session session, URLName urlname)
session
- Session object for this serviceurlname
- URLName object to be used for this serviceMethod Detail |
public void connect() throws MessagingException
If the connection is successful, an "open" ConnectionEvent
is delivered to any ConnectionListeners
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.
AuthenticationFailedException
- for authentication failures
MessagingException
- for other failures
IllegalStateException
- if the service is already connectedConnectionEvent
public void connect(String host, String user, String password) throws MessagingException
If the connection is successful, an "open" ConnectionEvent
is delivered to any ConnectionListeners
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 the protocolConnect
method.
If the protocolConnect
method returns false
,
the user will be prompted for any missing information and the
protocolConnect
method will be called again. The
subclass should override the protocolConnect
method.
The subclass should also implement the getURLName
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 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 setPasswordAuthenticaiton
. If the
password passed in is not null, it is not saved, on the assumption
that the application is managing passwords explicitly.
host
- the host to connect touser
- the user namepassword
- this user's password
AuthenticationFailedException
- for authentication failures
MessagingException
- for other failures
IllegalStateException
- if the service is already connectedConnectionEvent
,
Session.setPasswordAuthentication(javax.mail.URLName, javax.mail.PasswordAuthentication)
public void connect(String host, int port, String user, String password) throws MessagingException
host
- the host to connect toport
- the port to connect to (-1 means the default port)user
- the user namepassword
- this user's password
AuthenticationFailedException
- for authentication failures
MessagingException
- for other failures
IllegalStateException
- if the service is already connectedconnect(java.lang.String, java.lang.String, java.lang.String)
,
ConnectionEvent
protected boolean protocolConnect(String host, int port, String user, String password) throws MessagingException
connect
method
calls this method as needed.
The protocolConnect
method should return
false
if a user name or password is required
for authentication but the corresponding parameter is null;
the connect
method will prompt the user when
needed to supply missing information. This method may
also return false
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.
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
AuthenticationFailedException
- for authentication failures
MessagingException
- for non-authentication failurespublic boolean isConnected()
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.
protected void setConnected(boolean connected)
connect
and close
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.
connected
- true if the service is connected,
false if it is not connectedpublic void close() throws MessagingException
This implementation uses setConnected(false)
to set
this service's connected state to false
. 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 to super.close()
in a finally
clause.
MessagingException
- for errors while closingConnectionEvent
public URLName getURLName()
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.
URLName
protected void setURLName(URLName url)
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 new URLName
should
be constructed with any unneeded fields removed.
The implementation in the Service class simply sets the
url
field.
URLName
public void addConnectionListener(ConnectionListener l)
The default implementation provided here adds this listener to an internal list of ConnectionListeners.
l
- the Listener for Connection eventsConnectionEvent
public void removeConnectionListener(ConnectionListener l)
The default implementation provided here removes this listener from the internal list of ConnectionListeners.
l
- the listeneraddConnectionListener(javax.mail.event.ConnectionListener)
protected void notifyConnectionListeners(int type)
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()
getURLName.toString()
if this service has a URLName,
otherwise it will return the default toString
.
protected void queueEvent(MailEvent event, Vector vector)
protected void finalize() throws Throwable
Throwable
|
JavaTM 2 Platform Ent. Ed. v1.4 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 2003 Sun Microsystems, Inc. All rights reserved.