de.trantor.mail
Class Connection

java.lang.Object
  |
  +--de.trantor.mail.Connection

Direct Known Subclasses:

ConnectionImpl, ConnectionImpl, ConnectionImpl

public abstract class Connection

extends java.lang.Object

Is the abstract base class for socket connections used inside the SMTP, POP3 and IMAP protocols of the mail package. The rationale for using this class is the difference in how networking is handled in J2ME and J2SE: While J2SE has java.net.Socket, J2ME uses the Generic Connection Framework with its javax.io.Connector class as a central means to open sockets or HTTP connection. Unfortunately, both methods are totally incompatible with each other, so a common abstraction has to be found to make the mail package work in both environments.

The Connection class is such an abstraction. It provides abstract versions of methods that open and close sockets, read from them and write to them. It also provides a static factory method that is able to instantiate one of several sub-classes of Connection that match the different run-time environments. These sub-classes are all called ConnectionImpl, and they are loaded "by name" from the j2me, j2se, or http packages, respectively. This is the only way to get rid of compile-time dependencies on these classes.

Constructor Summary

Connection()

Method Summary

abstract void	close() Closes a connection.
abstract boolean	connected() Queries the current status of the connection.
boolean	getDebug() Queries the current value of the debugging flag.
static Connection	getInstance() Creates a new, concrete connection object for either J2SE or J2SE, depending on the current run-time environment.
abstract void	open(java.lang.String host, int port, boolean ssl) Opens a connection.
protected abstract int	read(byte[] buffer, int offset, int count) Reads from the socket.
java.lang.String	receive() Receives a string from the server.
void	send(java.lang.String s) Sends a string to the server.
void	setDebug(boolean debug) Controls the output of debugging information to standard output.
protected abstract void	write(byte[] buffer, int offset, int count) Writes to the socket.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Connection

public Connection()

Method Detail

open

public abstract void open(java.lang.String host,
                          int port,
                          boolean ssl)
                   throws java.io.IOException

Opens a connection. Concrete descendents of Connection override this method to actually do something useful.

java.io.IOException

close

public abstract void close()
                    throws java.io.IOException

Closes a connection. Concrete descendents of Connection override this method to actually do something useful.

java.io.IOException

write

protected abstract void write(byte[] buffer,
                              int offset,
                              int count)
                       throws java.io.IOException

Writes to the socket.

java.io.IOException

read

protected abstract int read(byte[] buffer,
                            int offset,
                            int count)
                     throws java.io.IOException

Reads from the socket.

java.io.IOException

connected

public abstract boolean connected()

Queries the current status of the connection.

getInstance

public static Connection getInstance()

Creates a new, concrete connection object for either J2SE or J2SE, depending on the current run-time environment.

send

public void send(java.lang.String s)
          throws java.io.IOException

Sends a string to the server. This method is used internally for all outgoing communication to the server. The main thing it does it terminate the line with a CR/LF. If there are occurences of CR or LF inside the string, the method ensures that proper CR/LF sequences are sent for them, since this is what most internet protocols expect.

java.io.IOException

See Also:

receive()

receive

public java.lang.String receive()
                         throws java.io.IOException

Receives a string from the server. This method is used internally for incoming communication from the server. The main thing it does is ensuring that only complete lines are returned to the application, that is, lines that were terminated at least by a CR. LFs are ignored completely. Neither CRs nor LFs are returned as part of the result.

java.io.IOException

See Also:

send(java.lang.String)

setDebug

public void setDebug(boolean debug)

Controls the output of debugging information to standard output. Set it to true to see all protocol information exchanged.

See Also:

getDebug()

getDebug

public boolean getDebug()

Queries the current value of the debugging flag.

See Also:

setDebug(boolean)