JavaMail API 1.6.2 · javax.mail.Service

Modifier and Type	Field and Description
private boolean	connected
private final Vector<ConnectionListener>	connectionListeners
protected boolean	debug Debug flag for this service.
private final EventQueue	q The queue of events to be delivered.
protected Session	session The session from which this service was created.
protected volatile URLName	url The `URLName` of this service.

Access	Constructor and Description
protected	Service(Session Session object for this service session, URLName URLName object to be used for this service urlname) Constructor.

Method Summary

Modifier and Type	Method and Description
public void	addConnectionListener(ConnectionListener the Listener for Connection events l) Add a listener for Connection events on this service.
public synchronized void	close() Implements java.lang.AutoCloseable.close. Close this service and terminate its connection.
public void	connect() A generic connect method that takes no parameters.
public void	connect(String the host to connect to host, String the user name user, String this user's password password) Connect to the specified address.
public void	connect(String the user name user, String this user's password password) Connect to the current host using the specified username and password.
public synchronized void	connect(String the host to connect to host, int the port to connect to (-1 means the default port) port, String the user name user, String this user's password password) Similar to connect(host, user, password) except a specific port can be specified.
protected void	finalize() Overrides java.lang.Object.finalize. Stop the event dispatcher thread so the queue can be garbage collected.
pack-priv EventQueue	getEventQueue() Package private method to allow Folder to get the EventQueue for a Store.
pack-priv Session	getSession() Package private method to allow Folder to get the Session for a Store.
public URLName	Returns: the URLName representing this service getURLName() Return a URLName representing this service.
public synchronized boolean	Returns: true if the service is connected, false if it is not connected isConnected() Is this service currently connected?
protected void	notifyConnectionListeners(int the ConnectionEvent type type) Notify all ConnectionListeners.
protected boolean	Returns: true if connection successful, false if authentication failed protocolConnect(String the name of the host to connect to host, int the port to use (-1 means use default port) port, String the name of the user to login as user, String the user's password password) The service implementation should override this method to perform the actual protocol-specific connection attempt.
protected void	queueEvent(MailEvent the event event, Vector<? extends EventListener> the vector of listeners vector) Add the event and vector of listeners to the queue to be delivered.
public void	removeConnectionListener(ConnectionListener the listener l) Remove a Connection event listener.
protected synchronized void	setConnected(boolean true if the service is connected, false if it is not connected connected) Set the connection state of this service.
protected void	setURLName(URLName the URLName url) Set the URLName representing this service.
public String	toString() Overrides java.lang.Object.toString. Return `getURLName.toString()` if this service has a URLName, otherwise it will return the default `toString`.

Inherited from java.lang.Object:: clone equals getClass hashCode notify notifyAll wait wait wait

connected	back to summary
private boolean connected

connectionListeners	back to summary
private final Vector<ConnectionListener> connectionListeners

debug	back to summary
protected boolean debug Debug flag for this service. Set from the session's debug flag when this service is created.

q	back to summary
private final EventQueue q The queue of events to be delivered.

session	back to summary
protected Session session The session from which this service was created.

url	back to summary
protected volatile URLName url The `URLName` of this service.

Service	back to summary
protected Service(Session session, URLName urlname) Constructor. Parameters session:Session Session object for this service urlname:URLName URLName object to be used for this service

Method Detail

addConnectionListener back to summary

addConnectionListener	back to summary
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:ConnectionListener the Listener for Connection events See Also `javax.mail.event.ConnectionEvent`

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:ConnectionListener: the Listener for Connection events

See Also

javax.mail.event.ConnectionEvent

close back to summary

close	back to summary
public synchronized void close() throws MessagingException Implements java.lang.AutoCloseable.close. 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. Exceptions MessagingException: for errors while closing See Also `javax.mail.event.ConnectionEvent`

public synchronized void close() throws MessagingException

Implements java.lang.AutoCloseable.close.

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.

Exceptions

MessagingException:: for errors while closing

See Also

javax.mail.event.ConnectionEvent

connect back to summary

connect	back to summary
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 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. Exceptions MessagingException: for other failures AuthenticationFailedException: for authentication failures IllegalStateException: if the service is already connected See Also `javax.mail.event.ConnectionEvent`

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 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.

Exceptions

MessagingException:: for other failures
AuthenticationFailedException:: for authentication failures
IllegalStateException:: if the service is already connected

See Also

javax.mail.event.ConnectionEvent

connect back to summary

connect	back to summary
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 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:String the host to connect to user:String the user name password:String this user's password Exceptions MessagingException: for other failures AuthenticationFailedException: for authentication failures IllegalStateException: if the service is already connected See Also `javax.mail.event.ConnectionEvent`, `javax.mail.Session#setPasswordAuthentication`

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 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:String: the host to connect to
user:String: the user name
password:String: this user's password

Exceptions

MessagingException:: for other failures
AuthenticationFailedException:: for authentication failures
IllegalStateException:: if the service is already connected

connect back to summary

connect	back to summary
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:String the user name password:String this user's password Exceptions MessagingException: for other failures AuthenticationFailedException: for authentication failures IllegalStateException: if the service is already connected Since JavaMail 1.4 See Also `javax.mail.event.ConnectionEvent`, `javax.mail.Session#setPasswordAuthentication`, `connect(java.lang.String, java.lang.String, java.lang.String)`

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:String: the user name
password:String: this user's password

Exceptions

MessagingException:: for other failures
AuthenticationFailedException:: for authentication failures
IllegalStateException:: if the service is already connected

Since

JavaMail 1.4

connect back to summary

connect	back to summary
public synchronized 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:String the host to connect to port:int the port to connect to (-1 means the default port) user:String the user name password:String this user's password Exceptions MessagingException: for other failures AuthenticationFailedException: for authentication failures IllegalStateException: if the service is already connected See Also `connect(java.lang.String, java.lang.String, java.lang.String)`, `javax.mail.event.ConnectionEvent`

public synchronized 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:String: the host to connect to
port:int: the port to connect to (-1 means the default port)
user:String: the user name
password:String: this user's password

Exceptions

MessagingException:: for other failures
AuthenticationFailedException:: for authentication failures
IllegalStateException:: if the service is already connected

finalize back to summary

finalize	back to summary
protected void finalize() throws Throwable Overrides java.lang.Object.finalize. Stop the event dispatcher thread so the queue can be garbage collected. Annotations @Override Exceptions Throwable: Doc from java.lang.Object.finalize. the `Exception` raised by this method

protected void finalize() throws Throwable

Overrides java.lang.Object.finalize.

Stop the event dispatcher thread so the queue can be garbage collected.

Annotations

@Override

Exceptions

Throwable:

Doc from java.lang.Object.finalize.

the Exception raised by this method

getEventQueue	back to summary
pack-priv EventQueue getEventQueue() Package private method to allow Folder to get the EventQueue for a Store.

getSession	back to summary
pack-priv Session getSession() Package private method to allow Folder to get the Session for a Store.

getURLName back to summary

getURLName	back to summary
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:URLName the URLName representing this service See Also `URLName`

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:URLName: the URLName representing this service
See Also: URLName

isConnected	back to summary
public synchronized 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:boolean true if the service is connected, false if it is not connected

isConnected

back to summary

public synchronized 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:boolean: true if the service is connected, false if it is not connected

notifyConnectionListeners	back to summary
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. Parameters type:int the ConnectionEvent type

notifyConnectionListeners

back to summary

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.

Parameters

type:int: the ConnectionEvent type

protocolConnect back to summary

protocolConnect	back to summary
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 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:String the name of the host to connect to port:int the port to use (-1 means use default port) user:String the name of the user to login as password:String the user's password Returns:boolean true if connection successful, false if authentication failed Exceptions MessagingException: for non-authentication failures AuthenticationFailedException: for authentication failures

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 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:String: the name of the host to connect to
port:int: the port to use (-1 means use default port)
user:String: the name of the user to login as
password:String: the user's password

Returns:boolean

true if connection successful, false if authentication failed

Exceptions

MessagingException:: for non-authentication failures
AuthenticationFailedException:: for authentication failures

queueEvent	back to summary
protected void queueEvent(MailEvent event, Vector<? extends EventListener> vector) Add the event and vector of listeners to the queue to be delivered. Parameters event:MailEvent the event vector:Vector<? extends EventListener> the vector of listeners

queueEvent

back to summary

protected void queueEvent(MailEvent event, Vector<? extends EventListener> vector)

Add the event and vector of listeners to the queue to be delivered.

Parameters

event:MailEvent: the event
vector:Vector<? extends EventListener>: the vector of listeners

removeConnectionListener back to summary

removeConnectionListener	back to summary
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:ConnectionListener the listener See Also `addConnectionListener`

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:ConnectionListener: the listener

See Also

addConnectionListener

setConnected back to summary

setConnected	back to summary
protected synchronized 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` 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:boolean true if the service is connected, false if it is not connected

protected synchronized 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 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:boolean: true if the service is connected, false if it is not connected

setURLName back to summary

setURLName	back to summary
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 new `URLName` should be constructed with any unneeded fields removed. The implementation in the Service class simply sets the `url` field. Parameters url:URLName the URLName See Also `URLName`

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 new URLName should be constructed with any unneeded fields removed.

The implementation in the Service class simply sets the url field.

Parameters

url:URLName: the URLName

See Also

URLName

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Return `getURLName.toString()` if this service has a URLName, otherwise it will return the default `toString`. Returns:String Doc from java.lang.Object.toString. a string representation of the object. Annotations @Override

public String toString()

Overrides java.lang.Object.toString.

Return getURLName.toString() if this service has a URLName, otherwise it will return the default toString.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object.

Annotations

@Override

public abstract Class Service

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail