Package org.apache.commons.net.imap
Class IMAP
- java.lang.Object
-
- org.apache.commons.net.SocketClient
-
- org.apache.commons.net.imap.IMAP
-
- Direct Known Subclasses:
IMAPClient
public class IMAP extends SocketClient
The IMAP class provides the basic the functionality necessary to implement your own IMAP client.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
IMAP.IMAPChunkListener
Implement this interface and register it viasetChunkListener(IMAPChunkListener)
in order to get access to multi-line partial command responses.static class
IMAP.IMAPState
-
Field Summary
Fields Modifier and Type Field Description protected static java.lang.String
__DEFAULT_ENCODING
The default control socket encoding.protected java.io.BufferedWriter
__writer
protected java.io.BufferedReader
_reader
private IMAP.IMAPChunkListener
chunkListener
static int
DEFAULT_PORT
The default IMAP port (RFC 3501).private char[]
initialID
private int
replyCode
private java.util.List<java.lang.String>
replyLines
private IMAP.IMAPState
state
static IMAP.IMAPChunkListener
TRUE_CHUNK_LISTENER
Implementation of IMAPChunkListener that returnstrue
but otherwise does nothing.-
Fields inherited from class org.apache.commons.net.SocketClient
_defaultPort_, _hostname_, _input_, _output_, _serverSocketFactory_, _socket_, _socketFactory_, _timeout_, connectTimeout, NETASCII_EOL
-
-
Constructor Summary
Constructors Constructor Description IMAP()
The default IMAPClient constructor.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description protected void
_connectAction_()
Performs connection initialization and sets state toIMAP.IMAPState.NOT_AUTH_STATE
.void
disconnect()
Disconnects the client from the server, and sets the state toDISCONNECTED_STATE
.boolean
doCommand(IMAPCommand command)
Sends a command to the server and return whether successful.boolean
doCommand(IMAPCommand command, java.lang.String args)
Sends a command and arguments to the server and return whether successful.protected void
fireReplyReceived(int replyCode, java.lang.String ignored)
OverridesSocketClient.fireReplyReceived(int, String)
so as to avoid creating the reply string if there are no listeners to invoke.protected java.lang.String
generateCommandID()
Generates a new command ID (tag) for a command.private void
getReply()
Get the reply for a command that expects a tagged response.private void
getReply(boolean wantTag)
Get the reply for a command, reading the response until the reply is found.java.lang.String
getReplyString()
Returns the reply to the last command sent to the server.java.lang.String[]
getReplyStrings()
Returns an array of lines received as a reply to the last command sent to the server.IMAP.IMAPState
getState()
Returns the current IMAP client state.(package private) static java.lang.String
quoteMailboxName(java.lang.String input)
Quote an input string if necessary.int
sendCommand(java.lang.String command)
Sends a command with no arguments to the server and returns the reply code.int
sendCommand(java.lang.String command, java.lang.String args)
Sends a command an arguments to the server and returns the reply code.int
sendCommand(IMAPCommand command)
Sends a command with no arguments to the server and returns the reply code.int
sendCommand(IMAPCommand command, java.lang.String args)
Sends a command and arguments to the server and returns the reply code.private int
sendCommandWithID(java.lang.String commandID, java.lang.String command, java.lang.String args)
Sends a command an arguments to the server and returns the reply code.int
sendData(java.lang.String command)
Sends data to the server and returns the reply code.void
setChunkListener(IMAP.IMAPChunkListener listener)
Sets the current chunk listener.protected void
setState(IMAP.IMAPState state)
Sets IMAP client state.-
Methods inherited from class org.apache.commons.net.SocketClient
addProtocolCommandListener, applySocketAttributes, connect, connect, connect, connect, connect, connect, createCommandSupport, fireCommandSent, getCharset, getCharsetName, getCommandSupport, getConnectTimeout, getDefaultPort, getDefaultTimeout, getKeepAlive, getLocalAddress, getLocalPort, getProxy, getReceiveBufferSize, getRemoteAddress, getRemotePort, getSendBufferSize, getServerSocketFactory, getSoLinger, getSoTimeout, getTcpNoDelay, isAvailable, isConnected, removeProtocolCommandListener, setCharset, setConnectTimeout, setDefaultPort, setDefaultTimeout, setKeepAlive, setProxy, setReceiveBufferSize, setSendBufferSize, setServerSocketFactory, setSocketFactory, setSoLinger, setSoTimeout, setTcpNoDelay, verifyRemote
-
-
-
-
Field Detail
-
DEFAULT_PORT
public static final int DEFAULT_PORT
The default IMAP port (RFC 3501).- See Also:
- Constant Field Values
-
__DEFAULT_ENCODING
protected static final java.lang.String __DEFAULT_ENCODING
The default control socket encoding.- See Also:
- Constant Field Values
-
TRUE_CHUNK_LISTENER
public static final IMAP.IMAPChunkListener TRUE_CHUNK_LISTENER
Implementation of IMAPChunkListener that returns
true
but otherwise does nothing.This is intended for use with a suitable ProtocolCommandListener. If the IMAP response contains multiple-line data, the protocol listener will be called for each multi-line chunk. The accumulated reply data will be cleared after calling the listener. If the response is very long, this can significantly reduce memory requirements. The listener will also start receiving response data earlier, as it does not have to wait for the entire response to be read.
The ProtocolCommandListener must be prepared to accept partial responses. This should not be a problem for listeners that just log the input.
- Since:
- 3.4
- See Also:
setChunkListener(IMAPChunkListener)
-
state
private IMAP.IMAPState state
-
__writer
protected java.io.BufferedWriter __writer
-
_reader
protected java.io.BufferedReader _reader
-
replyCode
private int replyCode
-
replyLines
private final java.util.List<java.lang.String> replyLines
-
chunkListener
private volatile IMAP.IMAPChunkListener chunkListener
-
initialID
private final char[] initialID
-
-
Method Detail
-
quoteMailboxName
static java.lang.String quoteMailboxName(java.lang.String input)
Quote an input string if necessary. If the string is enclosed in double-quotes it is assumed to be quoted already and is returned unchanged. If it is the empty string, "" is returned. If it contains a space then it is enclosed in double quotes, escaping the characters backslash and double-quote.- Parameters:
input
- the value to be quoted, may be null- Returns:
- the quoted value
-
_connectAction_
protected void _connectAction_() throws java.io.IOException
Performs connection initialization and sets state toIMAP.IMAPState.NOT_AUTH_STATE
.- Overrides:
_connectAction_
in classSocketClient
- Throws:
java.io.IOException
- (SocketException) if a problem occurs with the socket
-
disconnect
public void disconnect() throws java.io.IOException
Disconnects the client from the server, and sets the state toDISCONNECTED_STATE
. The reply text information from the last issued command is voided to allow garbage collection of the memory used to store that information.- Overrides:
disconnect
in classSocketClient
- Throws:
java.io.IOException
- If there is an error in disconnecting.
-
doCommand
public boolean doCommand(IMAPCommand command) throws java.io.IOException
Sends a command to the server and return whether successful.- Parameters:
command
- The IMAP command to send (one of the IMAPCommand constants).- Returns:
true
if the command was successful- Throws:
java.io.IOException
- on error
-
doCommand
public boolean doCommand(IMAPCommand command, java.lang.String args) throws java.io.IOException
Sends a command and arguments to the server and return whether successful.- Parameters:
command
- The IMAP command to send (one of the IMAPCommand constants).args
- The command arguments.- Returns:
true
if the command was successful- Throws:
java.io.IOException
- on error
-
fireReplyReceived
protected void fireReplyReceived(int replyCode, java.lang.String ignored)
OverridesSocketClient.fireReplyReceived(int, String)
so as to avoid creating the reply string if there are no listeners to invoke.- Overrides:
fireReplyReceived
in classSocketClient
- Parameters:
replyCode
- passed to the listenersignored
- the string is only created if there are listeners defined.- Since:
- 3.4
- See Also:
getReplyString()
-
generateCommandID
protected java.lang.String generateCommandID()
Generates a new command ID (tag) for a command.- Returns:
- a new command ID (tag) for an IMAP command.
-
getReply
private void getReply() throws java.io.IOException
Get the reply for a command that expects a tagged response.- Throws:
java.io.IOException
-
getReply
private void getReply(boolean wantTag) throws java.io.IOException
Get the reply for a command, reading the response until the reply is found.- Parameters:
wantTag
-true
if the command expects a tagged response.- Throws:
java.io.IOException
-
getReplyString
public java.lang.String getReplyString()
Returns the reply to the last command sent to the server. The value is a single string containing all the reply lines including newlines.- Returns:
- The last server response.
-
getReplyStrings
public java.lang.String[] getReplyStrings()
Returns an array of lines received as a reply to the last command sent to the server. The lines have end of lines truncated.- Returns:
- The last server response.
-
getState
public IMAP.IMAPState getState()
Returns the current IMAP client state.- Returns:
- The current IMAP client state.
-
sendCommand
public int sendCommand(IMAPCommand command) throws java.io.IOException
Sends a command with no arguments to the server and returns the reply code.- Parameters:
command
- The IMAP command to send (one of the IMAPCommand constants).- Returns:
- The server reply code (see IMAPReply).
- Throws:
java.io.IOException
- on error
-
sendCommand
public int sendCommand(IMAPCommand command, java.lang.String args) throws java.io.IOException
Sends a command and arguments to the server and returns the reply code.- Parameters:
command
- The IMAP command to send (one of the IMAPCommand constants).args
- The command arguments.- Returns:
- The server reply code (see IMAPReply).
- Throws:
java.io.IOException
- on error
-
sendCommand
public int sendCommand(java.lang.String command) throws java.io.IOException
Sends a command with no arguments to the server and returns the reply code.- Parameters:
command
- The IMAP command to send.- Returns:
- The server reply code (see IMAPReply).
- Throws:
java.io.IOException
- on error
-
sendCommand
public int sendCommand(java.lang.String command, java.lang.String args) throws java.io.IOException
Sends a command an arguments to the server and returns the reply code.- Parameters:
command
- The IMAP command to send.args
- The command arguments.- Returns:
- The server reply code (see IMAPReply).
- Throws:
java.io.IOException
- on error
-
sendCommandWithID
private int sendCommandWithID(java.lang.String commandID, java.lang.String command, java.lang.String args) throws java.io.IOException
Sends a command an arguments to the server and returns the reply code.- Parameters:
commandID
- The ID (tag) of the command.command
- The IMAP command to send.args
- The command arguments.- Returns:
- The server reply code (either IMAPReply.OK, IMAPReply.NO or IMAPReply.BAD).
- Throws:
java.io.IOException
-
sendData
public int sendData(java.lang.String command) throws java.io.IOException
Sends data to the server and returns the reply code.- Parameters:
command
- The IMAP command to send.- Returns:
- The server reply code (see IMAPReply).
- Throws:
java.io.IOException
- on error
-
setChunkListener
public void setChunkListener(IMAP.IMAPChunkListener listener)
Sets the current chunk listener. If a listener is registered and the implementation returns true, then any registeredPrintCommandListener
instances will be invoked with the partial response and a status ofIMAPReply.PARTIAL
to indicate that the final reply code is not yet known.- Parameters:
listener
- the class to use, ornull
to disable- Since:
- 3.4
- See Also:
TRUE_CHUNK_LISTENER
-
setState
protected void setState(IMAP.IMAPState state)
Sets IMAP client state. This must be one of the_STATE
constants.- Parameters:
state
- The new state.
-
-