Class Service

protected Session session

The session from which this service was created.

protected URLName url

The URLName of this service.

protected Service(Session session,
                  URLName url)

Constructor.

Parameters:

session - Session object for this service

url - URLName object to be used for this service

public void addConnectionListener(ConnectionListener l)

Add a listener for Connection events on this service.

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

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.

Throws:

MessagingException - for other failures

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

Parameters:

host - the host to connect to

user - the user name

password - this user's password

Throws:

MessagingException - for other failures

public 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 - the host to connect to

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

user - the user name

password - this user's password

Throws:

MessagingException - for other failures

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.

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

public void removeConnectionListener(ConnectionListener l)

Remove a Connection event listener.

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.