Package org.bluezoo.gumdrop.imap.client

Class IMAPClientProtocolHandler

java.lang.Object

org.bluezoo.gumdrop.imap.client.IMAPClientProtocolHandler

All Implemented Interfaces:

ClientAppendState, ClientAuthenticatedState, ClientAuthExchange, ClientIdleState, ClientNotAuthenticatedState, ClientPostStarttls, ClientSelectedState, LineParser.Callback, ProtocolHandler

public class IMAPClientProtocolHandler
extends Object
implements ProtocolHandler, LineParser.Callback, ClientNotAuthenticatedState, ClientPostStarttls, ClientAuthExchange, ClientAuthenticatedState, ClientSelectedState, ClientIdleState, ClientAppendState

IMAP4rev2 client protocol handler (RFC 9051).

Implements a type-safe IMAP client state machine with staged callback interfaces constraining which operations are valid at each protocol stage. Tagged command tracking ensures exactly one command is in-flight at a time (RFC 9051 section 5.5).

Line parsing is handled by the composable LineParser utility. Incoming literal data (FETCH body sections) is tracked by LiteralTracker and streamed as ByteBuffer chunks.

Supported features:

• STARTTLS — RFC 9051 section 6.2.1
• SASL AUTHENTICATE with initial response — RFC 4959
• IDLE — RFC 2177
• NAMESPACE — RFC 2342
• MOVE — RFC 6851
• APPEND with literal streaming

Author:

Chris Burdess

See Also:

• ProtocolHandler
• ServerGreeting
• RFC 9051 — IMAP4rev2

Constructor Summary

Constructors

Constructor	Description
IMAPClientProtocolHandler(ServerGreeting handler)	Creates an IMAP client protocol handler.

Method Summary

Modifier and Type	Method	Description
void	abort(ServerAuthAbortHandler callback)
void	append(String mailbox, String[] flags, String date, long size, ServerAppendReplyHandler callback)
void	authenticate(String mechanism, byte[] initialResponse, ServerAuthReplyHandler callback)
void	capability(ServerCapabilityReplyHandler callback)
void	close()
void	close(ServerCloseReplyHandler callback)
void	connected(Endpoint ep)	Called when the endpoint is established and ready for protocol traffic.
boolean	continueLineProcessing()	Called after each line to determine whether parsing should continue.
void	copy(String sequenceSet, String mailbox, ServerCopyReplyHandler callback)
void	create(String mailbox, ServerMailboxReplyHandler callback)
void	delete(String mailbox, ServerMailboxReplyHandler callback)
void	disconnected()	Called when the peer has closed the connection or stream.
void	done()
void	endAppend()
void	error(Exception cause)	Called when an unrecoverable error occurs on the endpoint.
void	examine(String mailbox, ServerSelectReplyHandler callback)
void	expunge(ServerExpungeReplyHandler callback)
void	fetch(String sequenceSet, String dataItems, ServerFetchReplyHandler callback)
void	getQuota(String quotaRoot, ServerQuotaReplyHandler callback)
void	getQuotaRoot(String mailbox, ServerQuotaReplyHandler callback)
void	idle(ServerIdleEventHandler callback)
boolean	isOpen()
void	lineReceived(ByteBuffer line)	Called when a complete CRLF-terminated line has been parsed.
void	list(String reference, String pattern, ServerListReplyHandler callback)
void	literalComplete()
void	literalContent(ByteBuffer data)
void	login(String username, String password, ServerLoginReplyHandler callback)
void	logout()
void	lsub(String reference, String pattern, ServerListReplyHandler callback)
void	move(String sequenceSet, String mailbox, ServerCopyReplyHandler callback)
void	namespace(ServerNamespaceReplyHandler callback)
void	noop(ServerNoopReplyHandler callback)
void	onWriteReady(Runnable callback)	Registers a one-shot callback invoked when the transport is ready for more data.
void	receive(ByteBuffer data)	Called when plaintext application data is received from the peer.
void	rename(String from, String to, ServerMailboxReplyHandler callback)
void	respond(byte[] response, ServerAuthReplyHandler callback)
void	search(String criteria, ServerSearchReplyHandler callback)
void	securityEstablished(SecurityInfo info)	Called when the security layer becomes active.
void	select(String mailbox, ServerSelectReplyHandler callback)
void	setMailboxEventListener(MailboxEventListener listener)	Sets the listener for unsolicited mailbox events.
void	setSecure(boolean secure)	Sets whether this connection started in secure mode.
void	starttls(ServerStarttlsReplyHandler callback)
void	status(String mailbox, String[] items, ServerStatusReplyHandler callback)
void	store(String sequenceSet, String action, String[] flags, ServerStoreReplyHandler callback)
void	subscribe(String mailbox, ServerMailboxReplyHandler callback)
void	uidCopy(String sequenceSet, String mailbox, ServerCopyReplyHandler callback)
void	uidFetch(String sequenceSet, String dataItems, ServerFetchReplyHandler callback)
void	uidMove(String sequenceSet, String mailbox, ServerCopyReplyHandler callback)
void	uidSearch(String criteria, ServerSearchReplyHandler callback)
void	uidStore(String sequenceSet, String action, String[] flags, ServerStoreReplyHandler callback)
void	unselect(ServerCloseReplyHandler callback)
void	unsubscribe(String mailbox, ServerMailboxReplyHandler callback)
void	writeContent(ByteBuffer data)

Methods inherited from class java.lang.Object

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

Constructor Details

IMAPClientProtocolHandler

public IMAPClientProtocolHandler(ServerGreeting handler)

Creates an IMAP client protocol handler.

Parameters:

handler - the server greeting handler

Method Details

setSecure

public void setSecure(boolean secure)

Sets whether this connection started in secure mode.

Parameters:

secure - true for implicit TLS (IMAPS port 993)

setMailboxEventListener

public void setMailboxEventListener(MailboxEventListener listener)

Sets the listener for unsolicited mailbox events.

Parameters:

listener - the event listener, or null to clear

connected

public void connected(Endpoint ep)

Description copied from interface: ProtocolHandler

Called when the endpoint is established and ready for protocol traffic.

The endpoint reference passed here should be stored by the handler for sending data and querying connection state.

Specified by:

connected in interface ProtocolHandler

Parameters:

ep - the endpoint that is now connected

receive

public void receive(ByteBuffer data)

Description copied from interface: ProtocolHandler

Called when plaintext application data is received from the peer.

The buffer is in read mode (position at data start, limit at data end). The handler should consume as much data as it can. After this method returns, any unconsumed data (between the buffer's position and limit) will be preserved for the next call.

Specified by:

receive in interface ProtocolHandler

Parameters:

data - the application data received

disconnected

public void disconnected()

Description copied from interface: ProtocolHandler

Called when the peer has closed the connection or stream.

After this method returns, the endpoint is no longer usable. Protocol handlers should perform any cleanup here.

Specified by:

disconnected in interface ProtocolHandler

securityEstablished

public void securityEstablished(SecurityInfo info)

Description copied from interface: ProtocolHandler

Called when the security layer becomes active.

For TCP with STARTTLS, this is called after the TLS handshake completes. For QUIC (always secure), this is called before ProtocolHandler.connected(Endpoint). For initially-secure TCP, this is also called before ProtocolHandler.connected(Endpoint).

Protocol handlers that need to reset state after STARTTLS (e.g., SMTP EHLO re-issue) should do so here.

Specified by:

securityEstablished in interface ProtocolHandler

Parameters:

info - details about the negotiated security parameters

error

public void error(Exception cause)

Description copied from interface: ProtocolHandler

Called when an unrecoverable error occurs on the endpoint.

This covers I/O errors, TLS handshake failures, and connection failures for client-initiated endpoints. The endpoint may or may not be usable after this call.

Specified by:

error in interface ProtocolHandler

Parameters:

cause - the exception that caused the error

lineReceived

public void lineReceived(ByteBuffer line)

Description copied from interface: LineParser.Callback

Called when a complete CRLF-terminated line has been parsed.

The buffer contains exactly one line including its CRLF terminator, with position at the start of the line and limit immediately after the terminating LF.

Specified by:

lineReceived in interface LineParser.Callback

Parameters:

line - a buffer containing the complete line including CRLF

continueLineProcessing

public boolean continueLineProcessing()

Description copied from interface: LineParser.Callback

Called after each line to determine whether parsing should continue.

Return false when the protocol transitions out of line-based mode (e.g., SMTP DATA, IMAP APPEND). When this returns false, LineParser.parse(ByteBuffer, Callback) stops and returns, leaving remaining data unconsumed in the buffer.

Specified by:

continueLineProcessing in interface LineParser.Callback

Returns:

true to continue parsing lines, false to stop

literalContent

public void literalContent(ByteBuffer data)

literalComplete

public void literalComplete()

isOpen

public boolean isOpen()

close

public void close()

capability

public void capability(ServerCapabilityReplyHandler callback)

Specified by:

capability in interface ClientNotAuthenticatedState

Specified by:

capability in interface ClientPostStarttls

login

public void login(String username,
 String password,
 ServerLoginReplyHandler callback)

Specified by:

login in interface ClientNotAuthenticatedState

Specified by:

login in interface ClientPostStarttls

authenticate

public void authenticate(String mechanism,
 byte[] initialResponse,
 ServerAuthReplyHandler callback)

Specified by:

authenticate in interface ClientNotAuthenticatedState

Specified by:

authenticate in interface ClientPostStarttls

starttls

public void starttls(ServerStarttlsReplyHandler callback)

Specified by:

starttls in interface ClientNotAuthenticatedState

logout

public void logout()

Specified by:

logout in interface ClientAuthenticatedState

Specified by:

logout in interface ClientNotAuthenticatedState

Specified by:

logout in interface ClientPostStarttls

respond

public void respond(byte[] response,
 ServerAuthReplyHandler callback)

Specified by:

respond in interface ClientAuthExchange

abort

public void abort(ServerAuthAbortHandler callback)

Specified by:

abort in interface ClientAuthExchange

select

public void select(String mailbox,
 ServerSelectReplyHandler callback)

Specified by:

select in interface ClientAuthenticatedState

examine

public void examine(String mailbox,
 ServerSelectReplyHandler callback)

Specified by:

examine in interface ClientAuthenticatedState

create

public void create(String mailbox,
 ServerMailboxReplyHandler callback)

Specified by:

create in interface ClientAuthenticatedState

delete

public void delete(String mailbox,
 ServerMailboxReplyHandler callback)

Specified by:

delete in interface ClientAuthenticatedState

rename

public void rename(String from,
 String to,
 ServerMailboxReplyHandler callback)

Specified by:

rename in interface ClientAuthenticatedState

subscribe

public void subscribe(String mailbox,
 ServerMailboxReplyHandler callback)

Specified by:

subscribe in interface ClientAuthenticatedState

unsubscribe

public void unsubscribe(String mailbox,
 ServerMailboxReplyHandler callback)

Specified by:

unsubscribe in interface ClientAuthenticatedState

list

public void list(String reference,
 String pattern,
 ServerListReplyHandler callback)

Specified by:

list in interface ClientAuthenticatedState

lsub

public void lsub(String reference,
 String pattern,
 ServerListReplyHandler callback)

Specified by:

lsub in interface ClientAuthenticatedState

status

public void status(String mailbox,
 String[] items,
 ServerStatusReplyHandler callback)

Specified by:

status in interface ClientAuthenticatedState

namespace

public void namespace(ServerNamespaceReplyHandler callback)

Specified by:

namespace in interface ClientAuthenticatedState

getQuota

public void getQuota(String quotaRoot,
 ServerQuotaReplyHandler callback)

Specified by:

getQuota in interface ClientAuthenticatedState

getQuotaRoot

public void getQuotaRoot(String mailbox,
 ServerQuotaReplyHandler callback)

Specified by:

getQuotaRoot in interface ClientAuthenticatedState

append

public void append(String mailbox,
 String[] flags,
 String date,
 long size,
 ServerAppendReplyHandler callback)

Specified by:

append in interface ClientAuthenticatedState

idle

public void idle(ServerIdleEventHandler callback)

Specified by:

idle in interface ClientAuthenticatedState

noop

public void noop(ServerNoopReplyHandler callback)

Specified by:

noop in interface ClientAuthenticatedState

close

public void close(ServerCloseReplyHandler callback)

Specified by:

close in interface ClientSelectedState

unselect

public void unselect(ServerCloseReplyHandler callback)

Specified by:

unselect in interface ClientSelectedState

expunge

public void expunge(ServerExpungeReplyHandler callback)

Specified by:

expunge in interface ClientSelectedState

search

public void search(String criteria,
 ServerSearchReplyHandler callback)

Specified by:

search in interface ClientSelectedState

uidSearch

public void uidSearch(String criteria,
 ServerSearchReplyHandler callback)

Specified by:

uidSearch in interface ClientSelectedState

fetch

public void fetch(String sequenceSet,
 String dataItems,
 ServerFetchReplyHandler callback)

Specified by:

fetch in interface ClientSelectedState

uidFetch

public void uidFetch(String sequenceSet,
 String dataItems,
 ServerFetchReplyHandler callback)

Specified by:

uidFetch in interface ClientSelectedState

store

public void store(String sequenceSet,
 String action,
 String[] flags,
 ServerStoreReplyHandler callback)

Specified by:

store in interface ClientSelectedState

uidStore

public void uidStore(String sequenceSet,
 String action,
 String[] flags,
 ServerStoreReplyHandler callback)

Specified by:

uidStore in interface ClientSelectedState

copy

public void copy(String sequenceSet,
 String mailbox,
 ServerCopyReplyHandler callback)

Specified by:

copy in interface ClientSelectedState

uidCopy

public void uidCopy(String sequenceSet,
 String mailbox,
 ServerCopyReplyHandler callback)

Specified by:

uidCopy in interface ClientSelectedState

move

public void move(String sequenceSet,
 String mailbox,
 ServerCopyReplyHandler callback)

Specified by:

move in interface ClientSelectedState

uidMove

public void uidMove(String sequenceSet,
 String mailbox,
 ServerCopyReplyHandler callback)

Specified by:

uidMove in interface ClientSelectedState

done

public void done()

Specified by:

done in interface ClientIdleState

writeContent

public void writeContent(ByteBuffer data)

Specified by:

writeContent in interface ClientAppendState

onWriteReady

public void onWriteReady(Runnable callback)

Description copied from interface: ClientAppendState

Registers a one-shot callback invoked when the transport is ready for more data. Use this to pace large APPEND uploads: send a chunk, register a callback, and send the next chunk from the callback.

Specified by:

onWriteReady in interface ClientAppendState

Parameters:

callback - the callback, or null to clear

endAppend

public void endAppend()

Specified by:

endAppend in interface ClientAppendState