Package org.apache.commons.net.imap

Class IMAPSClient

java.lang.Object

org.apache.commons.net.SocketClient

org.apache.commons.net.imap.IMAP

org.apache.commons.net.imap.IMAPClient

org.apache.commons.net.imap.IMAPSClient

Direct Known Subclasses:

AuthenticatingIMAPClient

public class IMAPSClient
extends IMAPClient

The IMAPSClient class provides SSL/TLS connection encryption to IMAPClient. Copied from FTPSClient and modified to suit IMAP. If implicit mode is selected (NOT the default), SSL/TLS negotiation starts right after the connection has been established. In explicit mode (the default), SSL/TLS negotiation starts when the user calls execTLS() and the server accepts the command.

 
 //Implicit usage:

               IMAPSClient c = new IMAPSClient(true);
               c.connect("127.0.0.1", 993);

 //Explicit usage:

               IMAPSClient c = new IMAPSClient();
               c.connect("127.0.0.1", 143);
               if (c.execTLS()) { /rest of the commands here/ }
 
 

Warning: the hostname is not verified against the certificate by default, use setHostnameVerifier(HostnameVerifier) or setEndpointCheckingEnabled(boolean) (on Java 1.7+) to enable verification.

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.commons.net.imap.IMAPClient

IMAPClient.FETCH_ITEM_NAMES, IMAPClient.SEARCH_CRITERIA, IMAPClient.STATUS_DATA_ITEMS

Nested classes/interfaces inherited from class org.apache.commons.net.imap.IMAP

IMAP.IMAPChunkListener, IMAP.IMAPState

Field Summary

Fields

Modifier and Type	Field	Description
static final int	DEFAULT_IMAPS_PORT	The default IMAP over SSL port.
static final String	DEFAULT_PROTOCOL	Default secure socket protocol name.

Fields inherited from class org.apache.commons.net.imap.IMAP

__DEFAULT_ENCODING, __writer, _reader, DEFAULT_PORT, TRUE_CHUNK_LISTENER

Fields inherited from class org.apache.commons.net.SocketClient

_defaultPort_, _hostname_, _input_, _output_, _serverSocketFactory_, _socket_, _socketFactory_, _timeout_, connectTimeout, NETASCII_EOL, remoteInetSocketAddress

Constructor Summary

Constructors

Constructor	Description
IMAPSClient()	Constructor for IMAPSClient.
IMAPSClient(boolean implicit)	Constructor for IMAPSClient.
IMAPSClient(boolean implicit, SSLContext ctx)	Constructor for IMAPSClient.
IMAPSClient(String proto)	Constructor for IMAPSClient.
IMAPSClient(String proto, boolean implicit)	Constructor for IMAPSClient.
IMAPSClient(String proto, boolean implicit, SSLContext ctx)	Constructor for IMAPSClient.
IMAPSClient(SSLContext context)	Constructor for IMAPSClient.

Method Summary

Modifier and Type	Method	Description
protected void	_connectAction_()	Because there are so many connect() methods, the _connectAction_() method is provided as a means of performing some action immediately after establishing a connection, rather than reimplementing all the connect() methods.
boolean	execTLS()	The TLS command execution.
String[]	getEnabledCipherSuites()	Returns the names of the cipher suites which could be enabled for use on this connection.
String[]	getEnabledProtocols()	Returns the names of the protocol versions which are currently enabled for use on this connection.
HostnameVerifier	getHostnameVerifier()	Gets the currently configured HostnameVerifier.
TrustManager	getTrustManager()	Gets the currently configured TrustManager.
boolean	isEndpointCheckingEnabled()	Return whether or not endpoint identification using the HTTPS algorithm on Java 1.7+ is enabled.
void	setEnabledCipherSuites(String[] cipherSuites)	Controls which particular cipher suites are enabled for use on this connection.
void	setEnabledProtocols(String[] protocolVersions)	Controls which particular protocol versions are enabled for use on this connection.
void	setEndpointCheckingEnabled(boolean enable)	Automatic endpoint identification checking using the HTTPS algorithm is supported on Java 1.7+.
void	setHostnameVerifier(HostnameVerifier newHostnameVerifier)	Override the default HostnameVerifier to use.
void	setKeyManager(KeyManager newKeyManager)	Sets a KeyManager to use.
void	setTrustManager(TrustManager newTrustManager)	Override the default TrustManager to use.

Methods inherited from class org.apache.commons.net.imap.IMAPClient

append, append, append, capability, check, close, copy, create, delete, examine, expunge, fetch, list, login, logout, lsub, noop, rename, search, search, select, status, store, subscribe, uid, unsubscribe

Methods inherited from class org.apache.commons.net.imap.IMAP

disconnect, doCommand, doCommand, fireReplyReceived, generateCommandID, getReplyString, getReplyStrings, getState, sendCommand, sendCommand, sendCommand, sendCommand, sendData, setChunkListener, setState

Methods inherited from class org.apache.commons.net.SocketClient

addProtocolCommandListener, applySocketAttributes, checkOpenOutputStream, connect, connect, connect, connect, connect, connect, createCommandSupport, fireCommandSent, getCharset, getCharsetName, getCommandSupport, getConnectTimeout, getDefaultPort, getDefaultTimeout, getKeepAlive, getLocalAddress, getLocalPort, getProxy, getReceiveBufferSize, getRemoteAddress, getRemoteInetSocketAddress, getRemotePort, getSendBufferSize, getServerSocketFactory, getSoLinger, getSoTimeout, getTcpNoDelay, isAvailable, isConnected, removeProtocolCommandListener, setCharset, setConnectTimeout, setDefaultPort, setDefaultTimeout, setKeepAlive, setProxy, setReceiveBufferSize, setSendBufferSize, setServerSocketFactory, setSocketFactory, setSoLinger, setSoTimeout, setTcpNoDelay, verifyRemote

Methods inherited from class java.lang.Object

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

Field Details

DEFAULT_IMAPS_PORT

public static final int DEFAULT_IMAPS_PORT

The default IMAP over SSL port.

See Also:

• Constant Field Values

DEFAULT_PROTOCOL

public static final String DEFAULT_PROTOCOL

Default secure socket protocol name.

See Also:

• Constant Field Values

Constructor Details

IMAPSClient

public IMAPSClient()

Constructor for IMAPSClient. Sets security mode to explicit (isImplicit = false).

IMAPSClient

public IMAPSClient(boolean implicit)

Constructor for IMAPSClient.

Parameters:

implicit - The security mode (Implicit/Explicit).

IMAPSClient

public IMAPSClient(boolean implicit,
 SSLContext ctx)

Constructor for IMAPSClient.

Parameters:

implicit - The security mode(Implicit/Explicit).

ctx - A pre-configured SSL Context.

IMAPSClient

public IMAPSClient(SSLContext context)

Constructor for IMAPSClient.

Parameters:

context - A pre-configured SSL Context.

IMAPSClient

public IMAPSClient(String proto)

Constructor for IMAPSClient.

Parameters:

proto - the protocol.

IMAPSClient

public IMAPSClient(String proto,
 boolean implicit)

Constructor for IMAPSClient.

Parameters:

proto - the protocol.

implicit - The security mode(Implicit/Explicit).

IMAPSClient

public IMAPSClient(String proto,
 boolean implicit,
 SSLContext ctx)

Constructor for IMAPSClient.

Parameters:

proto - the protocol.

implicit - The security mode(Implicit/Explicit).

ctx - the SSL context

Method Details

_connectAction_

protected void _connectAction_()
                        throws IOException

Because there are so many connect() methods, the _connectAction_() method is provided as a means of performing some action immediately after establishing a connection, rather than reimplementing all the connect() methods.

Overrides:

_connectAction_ in class IMAP

Throws:

IOException - If it is thrown by _connectAction_().

See Also:

• SocketClient._connectAction_()

execTLS

public boolean execTLS()
                throws SSLException,
IOException

The TLS command execution.

Returns:

TRUE if the command and negotiation succeeded.

Throws:

SSLException - If the server reply code is not positive.

IOException - If an I/O error occurs while sending the command or performing the negotiation.

getEnabledCipherSuites

public String[] getEnabledCipherSuites()

Returns the names of the cipher suites which could be enabled for use on this connection. When the underlying Socket is not an SSLSocket instance, returns null.

Returns:

An array of cipher suite names, or null.

getEnabledProtocols

public String[] getEnabledProtocols()

Returns the names of the protocol versions which are currently enabled for use on this connection. When the underlying Socket is not an SSLSocket instance, returns null.

Returns:

An array of protocols, or null.

getHostnameVerifier

public HostnameVerifier getHostnameVerifier()

Gets the currently configured HostnameVerifier.

Returns:

A HostnameVerifier instance.

Since:

3.4

getTrustManager

public TrustManager getTrustManager()

Gets the currently configured TrustManager.

Returns:

A TrustManager instance.

isEndpointCheckingEnabled

public boolean isEndpointCheckingEnabled()

Return whether or not endpoint identification using the HTTPS algorithm on Java 1.7+ is enabled. The default behavior is for this to be disabled.

Returns:

True if enabled, false if not.

Since:

3.4

setEnabledCipherSuites

public void setEnabledCipherSuites(String[] cipherSuites)

Controls which particular cipher suites are enabled for use on this connection. Called before server negotiation.

Parameters:

cipherSuites - The cipher suites.

setEnabledProtocols

public void setEnabledProtocols(String[] protocolVersions)

Controls which particular protocol versions are enabled for use on this connection. I perform setting before a server negotiation.

Parameters:

protocolVersions - The protocol versions.

setEndpointCheckingEnabled

public void setEndpointCheckingEnabled(boolean enable)

Automatic endpoint identification checking using the HTTPS algorithm is supported on Java 1.7+. The default behavior is for this to be disabled.

Parameters:

enable - Enable automatic endpoint identification checking using the HTTPS algorithm on Java 1.7+.

Since:

3.4

setHostnameVerifier

public void setHostnameVerifier(HostnameVerifier newHostnameVerifier)

Override the default HostnameVerifier to use.

Parameters:

newHostnameVerifier - The HostnameVerifier implementation to set or null to disable.

Since:

3.4

setKeyManager

public void setKeyManager(KeyManager newKeyManager)

Sets a KeyManager to use.

Parameters:

newKeyManager - The KeyManager implementation to set.

See Also:

• KeyManagerUtils

setTrustManager

public void setTrustManager(TrustManager newTrustManager)

Override the default TrustManager to use.

Parameters:

newTrustManager - The TrustManager implementation to set.

See Also:

• TrustManagerUtils