Commons Net example source code file (IMAPClient.java)
The Commons Net IMAPClient.java source code/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.net.imap;
import java.io.IOException;
/**
* The IMAPClient class provides the basic functionalities found in an
* IMAP client.
*/
public class IMAPClient extends IMAP
{
// --------- commands available in all states
/**
* Send a CAPABILITY command to the server.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs
*/
public boolean capability() throws IOException
{
return doCommand (IMAPCommand.CAPABILITY);
}
/**
* Send a NOOP command to the server. This is useful for keeping
* a connection alive since most IMAP servers will timeout after 10
* minutes of inactivity.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean noop() throws IOException
{
return doCommand (IMAPCommand.NOOP);
}
/**
* Send a LOGOUT command to the server. To fully disconnect from the server
* you must call disconnect().
* A logout attempt is valid in any state. If
* the client is in the not authenticated or authenticated state, it enters the
* logout on a successful logout.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean logout() throws IOException
{
return doCommand (IMAPCommand.LOGOUT);
}
// --------- commands available in the not-authenticated state
// STARTTLS skipped - see IMAPSClient.
// AUTHENTICATE skipped - see AuthenticatingIMAPClient.
/**
* Login to the IMAP server with the given username and password. You
* must first connect to the server with
* {@link org.apache.commons.net.SocketClient#connect connect }
* before attempting to login. A login attempt is only valid if
* the client is in the NOT_AUTH_STATE.
* After logging in, the client enters the AUTH_STATE.
* <p>
* @param username The account name being logged in to.
* @param password The plain text password of the account.
* @return True if the login attempt was successful, false if not.
* @exception IOException If a network I/O error occurs in the process of
* logging in.
*/
public boolean login(String username, String password) throws IOException
{
if (getState() != IMAP.IMAPState.NOT_AUTH_STATE)
{
return false;
}
if (!doCommand(IMAPCommand.LOGIN, username + " " + password))
{
return false;
}
setState(IMAP.IMAPState.AUTH_STATE);
return true;
}
// --------- commands available in the authenticated state
/**
* Send a SELECT command to the server.
* @param mailboxName The mailbox name to select.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean select(String mailboxName) throws IOException
{
return doCommand (IMAPCommand.SELECT, mailboxName);
}
/**
* Send an EXAMINE command to the server.
* @param mailboxName The mailbox name to examine.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean examine(String mailboxName) throws IOException
{
return doCommand (IMAPCommand.EXAMINE, mailboxName);
}
/**
* Send a CREATE command to the server.
* @param mailboxName The mailbox name to create.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean create(String mailboxName) throws IOException
{
return doCommand (IMAPCommand.CREATE, mailboxName);
}
/**
* Send a DELETE command to the server.
* @param mailboxName The mailbox name to delete.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean delete(String mailboxName) throws IOException
{
return doCommand (IMAPCommand.DELETE, mailboxName);
}
/**
* Send a RENAME command to the server.
* @param oldMailboxName The existing mailbox name to rename.
* @param newMailboxName The new mailbox name.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean rename(String oldMailboxName, String newMailboxName) throws IOException
{
return doCommand (IMAPCommand.RENAME, oldMailboxName + " " + newMailboxName);
}
/**
* Send a SUBSCRIBE command to the server.
* @param mailboxName The mailbox name to subscribe to.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean subscribe(String mailboxName) throws IOException
{
return doCommand (IMAPCommand.SUBSCRIBE, mailboxName);
}
/**
* Send a UNSUBSCRIBE command to the server.
* @param mailboxName The mailbox name to unsubscribe from.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean unsubscribe(String mailboxName) throws IOException
{
return doCommand (IMAPCommand.UNSUBSCRIBE, mailboxName);
}
/**
* Send a LIST command to the server.
* @param refName The reference name.
* @param mailboxName The mailbox name.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean list(String refName, String mailboxName) throws IOException
{
return doCommand (IMAPCommand.LIST, refName + " " + mailboxName);
}
/**
* Send an LSUB command to the server.
* @param refName The reference name.
* @param mailboxName The mailbox name.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean lsub(String refName, String mailboxName) throws IOException
{
return doCommand (IMAPCommand.LSUB, refName + " " + mailboxName);
}
/**
* Send a STATUS command to the server.
* @param mailboxName The reference name.
* @param itemNames The status data item names.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean status(String mailboxName, String[] itemNames) throws IOException
{
if (itemNames == null || itemNames.length < 1) {
throw new IllegalArgumentException("STATUS command requires at least one data item name");
}
StringBuilder sb = new StringBuilder();
sb.append(mailboxName);
sb.append(" (");
for ( int i = 0; i < itemNames.length; i++ )
{
if (i > 0) {
sb.append(" ");
}
sb.append(itemNames[i]);
}
sb.append(")");
return doCommand (IMAPCommand.STATUS, sb.toString());
}
/**
* Send an APPEND command to the server.
* @param mailboxName The mailbox name.
* @param flags The flag parenthesized list (optional).
* @param datetime The date/time string (optional).
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean append(String mailboxName, String flags, String datetime) throws IOException
{
String args = mailboxName;
if (flags != null) args += " " + flags;
if (datetime != null)
{
if (datetime.charAt(0) == '{') args += " " + datetime;
else args += " {" + datetime + "}";
}
return doCommand (IMAPCommand.APPEND, args);
}
/**
* Send an APPEND command to the server.
* @param mailboxName The mailbox name.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean append(String mailboxName) throws IOException
{
return append(mailboxName, null, null);
}
// --------- commands available in the selected state
/**
* Send a CHECK command to the server.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean check() throws IOException
{
return doCommand (IMAPCommand.CHECK);
}
/**
* Send a CLOSE command to the server.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean close() throws IOException
{
return doCommand (IMAPCommand.CLOSE);
}
/**
* Send an EXPUNGE command to the server.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean expunge() throws IOException
{
return doCommand (IMAPCommand.EXPUNGE);
}
/**
* Send a SEARCH command to the server.
* @param charset The charset (optional).
* @param criteria The search criteria.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean search(String charset, String criteria) throws IOException
{
String args = "";
if (charset != null) args += "CHARSET " + charset;
args += criteria;
return doCommand (IMAPCommand.SEARCH, args);
}
/**
* Send a SEARCH command to the server.
* @param criteria The search criteria.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean search(String criteria) throws IOException
{
return search(null, criteria);
}
/**
* Send a FETCH command to the server.
* @param sequenceSet The sequence set to fetch.
* @param itemNames The item names for the FETCH command.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean fetch(String sequenceSet, String itemNames) throws IOException
{
return doCommand (IMAPCommand.FETCH, sequenceSet + " " + itemNames);
}
/**
* Send a STORE command to the server.
* @param sequenceSet The sequence set to store.
* @param itemNames The item names for the STORE command.
* @param itemValues The item values for the STORE command.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean store(String sequenceSet, String itemNames, String itemValues)
throws IOException
{
return doCommand (IMAPCommand.STORE, sequenceSet + " " + itemNames + " " + itemValues);
}
/**
* Send a COPY command to the server.
* @param sequenceSet The sequence set to fetch.
* @param mailboxName The mailbox name.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean copy(String sequenceSet, String mailboxName) throws IOException
{
return doCommand (IMAPCommand.COPY, sequenceSet + " " + mailboxName);
}
/**
* Send a UID command to the server.
* @param command The command for UID.
* @param commandArgs The arguments for the command.
* @return {@code true} if the command was successful,{@code false} if not.
* @exception IOException If a network I/O error occurs.
*/
public boolean uid(String command, String commandArgs) throws IOException
{
return doCommand (IMAPCommand.UID, command + " " + commandArgs);
}
/**
* The status data items defined in RFC 3501.
*/
public enum STATUS_DATA_ITEMS
{
/** The number of messages in the mailbox. */
MESSAGES,
/** The number of messages with the \Recent flag set. */
RECENT,
/** The next unique identifier value of the mailbox. */
UIDNEXT,
/** The unique identifier validity value of the mailbox. */
UIDVALIDITY,
/** The number of messages which do not have the \Seen flag set. */
UNSEEN;
}
/**
* The search criteria defined in RFC 3501.
*/
public enum SEARCH_CRITERIA
{
/** All messages in the mailbox. */
ALL,
/** Messages with the \Answered flag set. */
ANSWERED,
/**
* Messages that contain the specified string in the envelope
* structure's BCC field.
*/
BCC,
/**
* Messages whose internal date (disregarding time and timezone)
* is earlier than the specified date.
*/
BEFORE,
/**
* Messages that contain the specified string in the body of the
* message.
*/
BODY,
/**
* Messages that contain the specified string in the envelope
* structure's CC field.
*/
CC,
/** Messages with the \Deleted flag set. */
DELETED,
/** Messages with the \Draft flag set. */
DRAFT,
/** Messages with the \Flagged flag set. */
FLAGGED,
/**
* Messages that contain the specified string in the envelope
* structure's FROM field.
*/
FROM,
/**
* Messages that have a header with the specified field-name (as
* defined in [RFC-2822]) and that contains the specified string
* in the text of the header (what comes after the colon). If the
* string to search is zero-length, this matches all messages that
* have a header line with the specified field-name regardless of
* the contents.
*/
HEADER,
/** Messages with the specified keyword flag set. */
KEYWORD,
/**
* Messages with an [RFC-2822] size larger than the specified
* number of octets.
*/
LARGER,
/**
* Messages that have the \Recent flag set but not the \Seen flag.
* This is functionally equivalent to "(RECENT UNSEEN)".
*/
NEW,
/** Messages that do not match the specified search key. */
NOT,
/**
* Messages that do not have the \Recent flag set. This is
* functionally equivalent to "NOT RECENT" (as opposed to "NOT
* NEW").
*/
OLD,
/**
* Messages whose internal date (disregarding time and timezone)
* is within the specified date.
*/
ON,
/** Messages that match either search key. */
OR,
/** Messages that have the \Recent flag set. */
RECENT,
/** Messages that have the \Seen flag set. */
SEEN,
/**
* Messages whose [RFC-2822] Date: header (disregarding time and
* timezone) is earlier than the specified date.
*/
SENTBEFORE,
/**
* Messages whose [RFC-2822] Date: header (disregarding time and
* timezone) is within the specified date.
*/
SENTON,
/**
* Messages whose [RFC-2822] Date: header (disregarding time and
* timezone) is within or later than the specified date.
*/
SENTSINCE,
/**
* Messages whose internal date (disregarding time and timezone)
* is within or later than the specified date.
*/
SINCE,
/**
* Messages with an [RFC-2822] size smaller than the specified
* number of octets.
*/
SMALLER,
/**
* Messages that contain the specified string in the envelope
* structure's SUBJECT field.
*/
SUBJECT,
/**
* Messages that contain the specified string in the header or
* body of the message.
*/
TEXT,
/**
* Messages that contain the specified string in the envelope
* structure's TO field.
*/
TO,
/**
* Messages with unique identifiers corresponding to the specified
* unique identifier set. Sequence set ranges are permitted.
*/
UID,
/** Messages that do not have the \Answered flag set. */
UNANSWERED,
/** Messages that do not have the \Deleted flag set. */
UNDELETED,
/** Messages that do not have the \Draft flag set. */
UNDRAFT,
/** Messages that do not have the \Flagged flag set. */
UNFLAGGED,
/** Messages that do not have the specified keyword flag set. */
UNKEYWORD,
/** Messages that do not have the \Seen flag set. */
UNSEEN;
}
/**
* The message data item names for the FETCH command defined in RFC 3501.
*/
public enum FETCH_ITEM_NAMES
{
/** Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE). */
ALL,
/** Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE). */
FAST,
/** Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE BODY). */
FULL,
/** Non-extensible form of BODYSTRUCTURE or the text of a particular body section. */
BODY,
/** The [MIME-IMB] body structure of the message. */
BODYSTRUCTURE,
/** The envelope structure of the message. */
ENVELOPE,
/** The flags that are set for this message. */
FLAGS,
/** The internal date of the message. */
INTERNALDATE,
/** A prefix for RFC-822 item names. */
RFC822,
/** The unique identifier for the message. */
UID;
}
}
/* kate: indent-width 4; replace-tabs on; */
Other Commons Net examples (source code examples)Here is a short list of links related to this Commons Net IMAPClient.java source code file: |
The search page
Other Commons Net source code examples at this package level
Click here to learn more about this project
