| java.lang.Object
 javax.mail.Service
All known Subclasses: javax.mail.Store, javax.mail.Transport,
| Service | | abstract public class Service (Code) | | 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.
author:
Christopher Cotton
author:
Bill Shannon
author:
Kanwar Oberoi
version:
1.33, 07/05/14 |
| Inner Class :static class TerminatorEvent extends MailEvent | |
| 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. |
| Method Summary | |
| public synchronized void | addConnectionListener(ConnectionListener l)
Add a listener for Connection events on this service. | | public synchronized void | close()
Close this service and terminate its connection. | | public void | connect()
A generic connect method that takes no parameters. | | public void | connect(String host, String user, String password)
Connect to the specified address. | | public void | connect(String user, String password)
Connect to the current host using the specified username
and password. | | public synchronized void | connect(String host, int port, String user, String password)
Similar to connect(host, user, password) except a specific port
can be specified. | | protected void | finalize()
Stop the event dispatcher thread so the queue can be garbage collected. | | public synchronized URLName | getURLName()
Return a URLName representing this service. | | public synchronized boolean | isConnected()
Is this service currently connected?
This implementation uses a private boolean field to
store the connection state. | | protected synchronized 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.
The default implementation of the connect method
calls this method as needed. | | protected void | queueEvent(MailEvent event, Vector vector)
Add the event and vector of listeners to the queue to be delivered. | | public synchronized void | removeConnectionListener(ConnectionListener l)
Remove a Connection event listener. | | protected synchronized void | setConnected(boolean connected)
Set the connection state of this service. | | protected synchronized void | setURLName(URLName url)
Set the URLName representing this service.
Normally used to update the url field
after a service has successfully connected. | | public String | toString()
Return getURLName.toString() if this service has a URLName,
otherwise it will return the default toString. |
| debug | | protected boolean debug(Code) | | Debug flag for this service. Set from the session's debug
flag when this service is created.
|
| session | | protected Session session(Code) | | The session from which this service was created.
|
| Service | | protected Service(Session session, URLName urlname)(Code) | | Constructor.
Parameters:
session - Session object for this service
Parameters:
urlname - URLName object to be used for this service |
| addConnectionListener | | public synchronized void addConnectionListener(ConnectionListener l)(Code) | | 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: javax.mail.event.ConnectionEvent |
| close | | public synchronized void close() throws MessagingException(Code) | | 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 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.
See Also: javax.mail.event.ConnectionEvent
throws:
MessagingException - for errors while closing |
| connect | | public void connect() throws MessagingException(Code) | | 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 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.
exception:
AuthenticationFailedException - for authentication failures
exception:
MessagingException - for other failures
exception:
IllegalStateException - if the service is already connected
See Also: javax.mail.event.ConnectionEvent |
| connect | | public void connect(String host, String user, String password) throws MessagingException(Code) | | 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 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 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 to
Parameters:
user - the user name
Parameters:
password - this user's password
exception:
AuthenticationFailedException - for authentication failures
exception:
MessagingException - for other failures
exception:
IllegalStateException - if the service is already connected
See Also: javax.mail.event.ConnectionEvent
See Also: javax.mail.Session.setPasswordAuthentication |
| finalize | | protected void finalize() throws Throwable(Code) | | Stop the event dispatcher thread so the queue can be garbage collected.
|
| getURLName | | public synchronized URLName getURLName()(Code) | | 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.
the URLName representing this service
See Also: URLName |
| isConnected | | public synchronized boolean isConnected()(Code) | | 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.
true if the service is connected, false if it is not connected |
| notifyConnectionListeners | | protected synchronized void notifyConnectionListeners(int type)(Code) | | 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.
|
| protocolConnect | | protected boolean protocolConnect(String host, int port, String user, String password) throws MessagingException(Code) | | 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 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.
Parameters:
host - the name of the host to connect to
Parameters:
port - the port to use (-1 means use default port)
Parameters:
user - the name of the user to login as
Parameters:
password - the user's password true if connection successful, false if authentication failed
exception:
AuthenticationFailedException - for authentication failures
exception:
MessagingException - for non-authentication failures |
| queueEvent | | protected void queueEvent(MailEvent event, Vector vector)(Code) | | Add the event and vector of listeners to the queue to be delivered.
|
| removeConnectionListener | | public synchronized void removeConnectionListener(ConnectionListener l)(Code) | | 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: Service.addConnectionListener |
| setConnected | | protected synchronized void setConnected(boolean connected)(Code) | | Set the connection state of this service. The connection state
will automatically be set by the service implementation during the
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.
Parameters:
connected - true if the service is connected,false if it is not connected |
| setURLName | | protected synchronized void setURLName(URLName url)(Code) | | 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 new URLName should
be constructed with any unneeded fields removed.
The implementation in the Service class simply sets the
url field.
See Also: URLName |
| toString | | public String toString()(Code) | | Return getURLName.toString() if this service has a URLName,
otherwise it will return the default toString.
|
|
|