Class Service
- java.lang.Object
-
- javax.mail.Service
-
- All Implemented Interfaces:
java.lang.AutoCloseable
public abstract class Service extends java.lang.Object implements java.lang.AutoCloseable
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 aURLName
. A service must be connected before it can be used. Connection events are sent to reflect its connection status.
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description 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(java.lang.String host, int port, java.lang.String user, java.lang.String password)
Similar to connect(host, user, password) except a specific port can be specified.void
connect(java.lang.String user, java.lang.String password)
Connect to the current host using the specified username and password.void
connect(java.lang.String host, java.lang.String user, java.lang.String password)
Connect to the specified address.URLName
getURLName()
Return a URLName representing this service.boolean
isConnected()
Is this service currently connected?void
removeConnectionListener(ConnectionListener l)
Remove a Connection event listener.java.lang.String
toString()
ReturngetURLName.toString()
if this service has a URLName, otherwise it will return the defaulttoString
.
-
-
-
Method Detail
-
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 failuresjava.lang.IllegalStateException
- if the service is already connected- See Also:
ConnectionEvent
-
connect
public void connect(java.lang.String host, java.lang.String user, java.lang.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 failuresjava.lang.IllegalStateException
- if the service is already connected- See Also:
ConnectionEvent
,Session.setPasswordAuthentication(javax.mail.URLName, javax.mail.PasswordAuthentication)
-
connect
public void connect(java.lang.String user, java.lang.String password) throws MessagingException
Connect to the current host using the specified username and password. This method is equivalent to calling theconnect(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 failuresjava.lang.IllegalStateException
- 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)
-
connect
public void connect(java.lang.String host, int port, java.lang.String user, java.lang.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 failuresjava.lang.IllegalStateException
- if the service is already connected- See Also:
connect(java.lang.String, java.lang.String, java.lang.String)
,ConnectionEvent
-
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
-
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.- Specified by:
close
in interfacejava.lang.AutoCloseable
- Throws:
MessagingException
- for errors while closing- See Also:
ConnectionEvent
-
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
-
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
-
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)
-
toString
public java.lang.String toString()
ReturngetURLName.toString()
if this service has a URLName, otherwise it will return the defaulttoString
.- Overrides:
toString
in classjava.lang.Object
-
-