Movatterモバイル変換

Class Service

java.lang.Object  |  +--javax.mail.Service

Direct Known Subclasses:

Store,Transport

public abstract classService

extends java.lang.Object

An abstract class that contains the functionality common to messaging services, such as stores and transports.

A messaging service is created from aSession and is named using aURLName. A service must be connected before it can be used. Connection events are sent to reflect its connection status.

session

protectedSessionsession

The session from which this service was created.

url

protectedURLNameurl

TheURLName of this service.

debug

protected booleandebug

Debug flag for this service. Set from the session's debug flag when this service is created.

Service

protectedService(Session session,URLName urlname)

Constructor.

Parameters:

session - Session object for this service

url - URLName object to be used for this service

connect

public voidconnect()             throwsMessagingException

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 followingconnect(String, String, String) method with nulls.

Throws:

AuthenticationFailedException - for authentication failures

MessagingException - for other failures

java.lang.IllegalStateException - if the service is already connected

See Also:

ConnectionEvent

connect

public voidconnect(java.lang.String host,                    java.lang.String user,                    java.lang.String password)             throwsMessagingException

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 theURLName 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, thesetURLName 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. 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

user - the user name

password - this user's password

Throws:

AuthenticationFailedException - for authentication failures

MessagingException - for other failures

java.lang.IllegalStateException - if the service is already connected

See Also:

ConnectionEvent

connect

public voidconnect(java.lang.String host,                    int port,                    java.lang.String user,                    java.lang.String password)             throwsMessagingException

Similar to connect(host, user, password) except a specific port can be specified.

Parameters:

host - the host to connect to

port - the port to connect to (-1 means the default port)

user - the user name

password - this user's password

Throws:

AuthenticationFailedException - for authentication failures

MessagingException - for other failures

java.lang.IllegalStateException - if the service is already connected

See Also:

connect(java.lang.String, java.lang.String, java.lang.String),ConnectionEvent

protocolConnect

protected booleanprotocolConnect(java.lang.String host,                                  int port,                                  java.lang.String user,                                  java.lang.String password)                           throwsMessagingException

The service implementation should override this method to perform the actual protocol-specific connection attempt. The default implementation of theconnect method calls this method as needed.

TheprotocolConnect 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 should also returnfalse if authentication fails for the supplied user name or password.

TheprotocolConnect 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

port - the port to use (-1 means use default port)

user - the name of the user to login as

password - the user's password

Returns:

true if connection successful, false if authentication failed

Throws:

MessagingException - for non-authentication failures

isConnected

public booleanisConnected()

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

setConnected

protected voidsetConnected(boolean connected)

Set the connection state of this service. The connection state will automatically be set by the service implementation during theconnect 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 theisConnected method.

Parameters:

connected - true if the service is connected, false if it is not connected

close

public voidclose()           throwsMessagingException

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 usessetConnected(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

getURLName

publicURLNamegetURLName()

Return a URLName representing this service. The returned URLName doesnot 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) theurl field with the password and file information stripped out.

Returns:

the URLName representing this service

See Also:

URLName

setURLName

protected voidsetURLName(URLName url)

Set the URLName representing this service. Normally used to update theurl 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 byURLName; a newURLName should be constructed with any unneeded fields removed.

The implementation in the Service class simply sets theurl field.

See Also:

URLName

addConnectionListener

public voidaddConnectionListener(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 voidremoveConnectionListener(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)

notifyConnectionListeners

protected voidnotifyConnectionListeners(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.

toString

public java.lang.StringtoString()

ReturngetURLName.toString() if this service has a URLName, otherwise it will return the defaulttoString.

Overrides:

toString in classjava.lang.Object

queueEvent

protected voidqueueEvent(MailEvent event,                          java.util.Vector vector)

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

finalize

protected voidfinalize()                 throws java.lang.Throwable

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

Overrides:

finalize in classjava.lang.Object