IMAPClient.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  18. package org.apache.commons.net.imap;

  20. import java.io.IOException;

  22. /**
  23.  * The IMAPClient class provides the basic functionalities found in an IMAP client.
  24.  */
  25. public class IMAPClient extends IMAP {

  27.     /**
  28.      * The message data item names for the FETCH command defined in RFC 3501.
  29.      */
  30.     public enum FETCH_ITEM_NAMES {
  31.         /** Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE). */
  32.         ALL,
  33.         /** Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE). */
  34.         FAST,
  35.         /** Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE BODY). */
  36.         FULL,
  37.         /** Non-extensible form of BODYSTRUCTURE or the text of a particular body section. */
  38.         BODY,
  39.         /** The [MIME-IMB] body structure of the message. */
  40.         BODYSTRUCTURE,
  41.         /** The envelope structure of the message. */
  42.         ENVELOPE,
  43.         /** The flags that are set for this message. */
  44.         FLAGS,
  45.         /** The internal date of the message. */
  46.         INTERNALDATE,
  47.         /** A prefix for RFC-822 item names. */
  48.         RFC822,
  49.         /** The unique identifier for the message. */
  50.         UID
  51.     }

  53.     /**
  54.      * The search criteria defined in RFC 3501.
  55.      */
  56.     public enum SEARCH_CRITERIA {
  57.         /** All messages in the mailbox. */
  58.         ALL,
  59.         /** Messages with the \Answered flag set. */
  60.         ANSWERED,
  61.         /**
  62.          * Messages that contain the specified string in the envelope structure's BCC field.
  63.          */
  64.         BCC,
  65.         /**
  66.          * Messages whose internal date (disregarding time and time zone) is earlier than the specified date.
  67.          */
  68.         BEFORE,
  69.         /**
  70.          * Messages that contain the specified string in the body of the message.
  71.          */
  72.         BODY,
  73.         /**
  74.          * Messages that contain the specified string in the envelope structure's CC field.
  75.          */
  76.         CC,
  77.         /** Messages with the \Deleted flag set. */
  78.         DELETED,
  79.         /** Messages with the \Draft flag set. */
  80.         DRAFT,
  81.         /** Messages with the \Flagged flag set. */
  82.         FLAGGED,
  83.         /**
  84.          * Messages that contain the specified string in the envelope structure's FROM field.
  85.          */
  86.         FROM,
  87.         /**
  88.          * 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
  89.          * (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
  90.          * regardless of the contents.
  91.          */
  92.         HEADER,
  93.         /** Messages with the specified keyword flag set. */
  94.         KEYWORD,
  95.         /**
  96.          * Messages with an [RFC-2822] size larger than the specified number of octets.
  97.          */
  98.         LARGER,
  99.         /**
  100.          * Messages that have the \Recent flag set but not the \Seen flag. This is functionally equivalent to "(RECENT UNSEEN)".
  101.          */
  102.         NEW,
  103.         /** Messages that do not match the specified search key. */
  104.         NOT,
  105.         /**
  106.          * Messages that do not have the \Recent flag set. This is functionally equivalent to "NOT RECENT" (as opposed to "NOT NEW").
  107.          */
  108.         OLD,
  109.         /**
  110.          * Messages whose internal date (disregarding time and time zone) is within the specified date.
  111.          */
  112.         ON,
  113.         /** Messages that match either search key. */
  114.         OR,
  115.         /** Messages that have the \Recent flag set. */
  116.         RECENT,
  117.         /** Messages that have the \Seen flag set. */
  118.         SEEN,
  119.         /**
  120.          * Messages whose [RFC-2822] Date: header (disregarding time and time zone) is earlier than the specified date.
  121.          */
  122.         SENTBEFORE,
  123.         /**
  124.          * Messages whose [RFC-2822] Date: header (disregarding time and time zone) is within the specified date.
  125.          */
  126.         SENTON,
  127.         /**
  128.          * Messages whose [RFC-2822] Date: header (disregarding time and time zone) is within or later than the specified date.
  129.          */
  130.         SENTSINCE,
  131.         /**
  132.          * Messages whose internal date (disregarding time and time zone) is within or later than the specified date.
  133.          */
  134.         SINCE,
  135.         /**
  136.          * Messages with an [RFC-2822] size smaller than the specified number of octets.
  137.          */
  138.         SMALLER,
  139.         /**
  140.          * Messages that contain the specified string in the envelope structure's SUBJECT field.
  141.          */
  142.         SUBJECT,
  143.         /**
  144.          * Messages that contain the specified string in the header or body of the message.
  145.          */
  146.         TEXT,
  147.         /**
  148.          * Messages that contain the specified string in the envelope structure's TO field.
  149.          */
  150.         TO,
  151.         /**
  152.          * Messages with unique identifiers corresponding to the specified unique identifier set. Sequence set ranges are permitted.
  153.          */
  154.         UID,
  155.         /** Messages that do not have the \Answered flag set. */
  156.         UNANSWERED,
  157.         /** Messages that do not have the \Deleted flag set. */
  158.         UNDELETED,
  159.         /** Messages that do not have the \Draft flag set. */
  160.         UNDRAFT,
  161.         /** Messages that do not have the \Flagged flag set. */
  162.         UNFLAGGED,
  163.         /** Messages that do not have the specified keyword flag set. */
  164.         UNKEYWORD,
  165.         /** Messages that do not have the \Seen flag set. */
  166.         UNSEEN
  167.     }

  169.     // --------- commands available in all states

  171.     /**
  172.      * The status data items defined in RFC 3501.
  173.      */
  174.     public enum STATUS_DATA_ITEMS {
  175.         /** The number of messages in the mailbox. */
  176.         MESSAGES,
  177.         /** The number of messages with the \Recent flag set. */
  178.         RECENT,
  179.         /** The next unique identifier value of the mailbox. */
  180.         UIDNEXT,
  181.         /** The unique identifier validity value of the mailbox. */
  182.         UIDVALIDITY,
  183.         /** The number of messages which do not have the \Seen flag set. */
  184.         UNSEEN
  185.     }

  187.     private static final char DQUOTE = '"';

  189.     private static final String DQUOTE_S = "\"";

  191.     // --------- commands available in the not-authenticated state
  192.     // STARTTLS skipped - see IMAPSClient.
  193.     // AUTHENTICATE skipped - see AuthenticatingIMAPClient.

  195.     /**
  196.      * Send an APPEND command to the server.
  197.      *
  198.      * @param mailboxName The mailbox name.
  199.      * @return {@code true} if the command was successful,{@code false} if not.
  200.      * @throws IOException If a network I/O error occurs.
  201.      * @deprecated (3.4) Does not work; the message body is not optional. Use {@link #append(String, String, String, String)} instead.
  202.      */
  203.     @Deprecated
  204.     public boolean append(final String mailboxName) throws IOException {
  205.         return append(mailboxName, null, null);
  206.     }

  208.     // --------- commands available in the authenticated state

  210.     /**
  211.      * Send an APPEND command to the server.
  212.      *
  213.      * @param mailboxName The mailbox name.
  214.      * @param flags       The flag parenthesized list (optional).
  215.      * @param datetime    The date/time string (optional).
  216.      * @return {@code true} if the command was successful,{@code false} if not.
  217.      * @throws IOException If a network I/O error occurs.
  218.      * @deprecated (3.4) Does not work; the message body is not optional. Use {@link #append(String, String, String, String)} instead.
  219.      */
  220.     @Deprecated
  221.     public boolean append(final String mailboxName, final String flags, final String datetime) throws IOException {
  222.         final StringBuilder args = new StringBuilder().append(mailboxName);
  223.         if (flags != null) {
  224.             args.append(" ").append(flags);
  225.         }
  226.         if (datetime != null) {
  227.             if (datetime.charAt(0) == '{') {
  228.                 args.append(" ").append(datetime);
  229.             } else {
  230.                 args.append(" {").append(datetime).append("}");
  231.             }
  232.         }
  233.         return doCommand(IMAPCommand.APPEND, args.toString());
  234.     }

  236.     /**
  237.      * Send an APPEND command to the server.
  238.      *
  239.      * @param mailboxName The mailbox name.
  240.      * @param flags       The flag parenthesized list (optional).
  241.      * @param datetime    The date/time string (optional).
  242.      * @param message     The message to append.
  243.      * @return {@code true} if the command was successful,{@code false} if not.
  244.      * @throws IOException If a network I/O error occurs.
  245.      * @since 3.4
  246.      */
  247.     public boolean append(final String mailboxName, final String flags, final String datetime, final String message) throws IOException {
  248.         final StringBuilder args = new StringBuilder(quoteMailboxName(mailboxName));
  249.         if (flags != null) {
  250.             args.append(" ").append(flags);
  251.         }
  252.         if (datetime != null) {
  253.             args.append(" ");
  254.             if (datetime.charAt(0) == DQUOTE) {
  255.                 args.append(datetime);
  256.             } else {
  257.                 args.append(DQUOTE).append(datetime).append(DQUOTE);
  258.             }
  259.         }
  260.         args.append(" ");
  261.         // String literal (probably not used much - if at all)
  262.         if (message.startsWith(DQUOTE_S) && message.endsWith(DQUOTE_S)) {
  263.             args.append(message);
  264.             return doCommand(IMAPCommand.APPEND, args.toString());
  265.         }
  266.         args.append('{').append(message.getBytes(IMAP.__DEFAULT_ENCODING).length).append('}'); // length of message
  267.         final int status = sendCommand(IMAPCommand.APPEND, args.toString());
  268.         return IMAPReply.isContinuation(status) // expecting continuation response
  269.                 && IMAPReply.isSuccess(sendData(message)); // if so, send the data
  270.     }

  272.     /**
  273.      * Send a CAPABILITY command to the server.
  274.      *
  275.      * @return {@code true} if the command was successful,{@code false} if not.
  276.      * @throws IOException If a network I/O error occurs
  277.      */
  278.     public boolean capability() throws IOException {
  279.         return doCommand(IMAPCommand.CAPABILITY);
  280.     }

  282.     /**
  283.      * Send a CHECK command to the server.
  284.      *
  285.      * @return {@code true} if the command was successful,{@code false} if not.
  286.      * @throws IOException If a network I/O error occurs.
  287.      */
  288.     public boolean check() throws IOException {
  289.         return doCommand(IMAPCommand.CHECK);
  290.     }

  292.     /**
  293.      * Send a CLOSE command to the server.
  294.      *
  295.      * @return {@code true} if the command was successful,{@code false} if not.
  296.      * @throws IOException If a network I/O error occurs.
  297.      */
  298.     public boolean close() throws IOException {
  299.         return doCommand(IMAPCommand.CLOSE);
  300.     }

  302.     /**
  303.      * Send a COPY command to the server.
  304.      *
  305.      * @param sequenceSet The sequence set to fetch.
  306.      * @param mailboxName The mailbox name.
  307.      * @return {@code true} if the command was successful,{@code false} if not.
  308.      * @throws IOException If a network I/O error occurs.
  309.      */
  310.     public boolean copy(final String sequenceSet, final String mailboxName) throws IOException {
  311.         return doCommand(IMAPCommand.COPY, sequenceSet + " " + quoteMailboxName(mailboxName));
  312.     }

  314.     /**
  315.      * Send a CREATE command to the server.
  316.      *
  317.      * @param mailboxName The mailbox name to create.
  318.      * @return {@code true} if the command was successful,{@code false} if not.
  319.      * @throws IOException If a network I/O error occurs.
  320.      */
  321.     public boolean create(final String mailboxName) throws IOException {
  322.         return doCommand(IMAPCommand.CREATE, quoteMailboxName(mailboxName));
  323.     }

  325.     /**
  326.      * Send a DELETE command to the server.
  327.      *
  328.      * @param mailboxName The mailbox name to delete.
  329.      * @return {@code true} if the command was successful,{@code false} if not.
  330.      * @throws IOException If a network I/O error occurs.
  331.      */
  332.     public boolean delete(final String mailboxName) throws IOException {
  333.         return doCommand(IMAPCommand.DELETE, quoteMailboxName(mailboxName));
  334.     }

  336.     /**
  337.      * Send an EXAMINE command to the server.
  338.      *
  339.      * @param mailboxName The mailbox name to examine.
  340.      * @return {@code true} if the command was successful,{@code false} if not.
  341.      * @throws IOException If a network I/O error occurs.
  342.      */
  343.     public boolean examine(final String mailboxName) throws IOException {
  344.         return doCommand(IMAPCommand.EXAMINE, quoteMailboxName(mailboxName));
  345.     }

  347.     /**
  348.      * Send an EXPUNGE command to the server.
  349.      *
  350.      * @return {@code true} if the command was successful,{@code false} if not.
  351.      * @throws IOException If a network I/O error occurs.
  352.      */
  353.     public boolean expunge() throws IOException {
  354.         return doCommand(IMAPCommand.EXPUNGE);
  355.     }

  357.     /**
  358.      * Send a FETCH command to the server.
  359.      *
  360.      * @param sequenceSet The sequence set to fetch (e.g. 1:4,6,11,100:*)
  361.      * @param itemNames   The item names for the FETCH command. (e.g. BODY.PEEK[HEADER.FIELDS (SUBJECT)]) If multiple item names are requested, these must be
  362.      *                    enclosed in parentheses, e.g. "(UID FLAGS BODY.PEEK[])"
  363.      * @return {@code true} if the command was successful,{@code false} if not.
  364.      * @throws IOException If a network I/O error occurs.
  365.      * @see #getReplyString()
  366.      * @see #getReplyStrings()
  367.      */
  368.     public boolean fetch(final String sequenceSet, final String itemNames) throws IOException {
  369.         return doCommand(IMAPCommand.FETCH, sequenceSet + " " + itemNames);
  370.     }

  372.     /**
  373.      * Send a LIST command to the server. Quotes the parameters if necessary.
  374.      *
  375.      * @param refName     The reference name If empty, indicates that the mailbox name is interpreted as by SELECT.
  376.      * @param mailboxName The mailbox name. If empty, this is a special request to return the hierarchy delimiter and the root name of the name given in the
  377.      *                    reference
  378.      * @return {@code true} if the command was successful,{@code false} if not.
  379.      * @throws IOException If a network I/O error occurs.
  380.      */
  381.     public boolean list(final String refName, final String mailboxName) throws IOException {
  382.         return doCommand(IMAPCommand.LIST, quoteMailboxName(refName) + " " + quoteMailboxName(mailboxName));
  383.     }

  385.     /**
  386.      * Login to the IMAP server with the given user and password. You must first connect to the server with
  387.      * {@link org.apache.commons.net.SocketClient#connect connect } before attempting to log in. A login attempt is only valid if the client is in the
  388.      * NOT_AUTH_STATE. After logging in, the client enters the AUTH_STATE.
  389.      *
  390.      * @param user The account name being logged in to.
  391.      * @param password The plain text password of the account.
  392.      * @return True if the login attempt was successful, false if not.
  393.      * @throws IOException If a network I/O error occurs in the process of logging in.
  394.      */
  395.     public boolean login(final String user, final String password) throws IOException {
  396.         if (getState() != IMAP.IMAPState.NOT_AUTH_STATE) {
  397.             return false;
  398.         }

  400.         if (!doCommand(IMAPCommand.LOGIN, user + " " + password)) {
  401.             return false;
  402.         }

  404.         setState(IMAP.IMAPState.AUTH_STATE);

  406.         return true;
  407.     }

  409.     // --------- commands available in the selected state

  411.     /**
  412.      * 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
  413.      * client is in the not authenticated or authenticated state, it enters the logout on a successful logout.
  414.      *
  415.      * @return {@code true} if the command was successful,{@code false} if not.
  416.      * @throws IOException If a network I/O error occurs.
  417.      */
  418.     public boolean logout() throws IOException {
  419.         return doCommand(IMAPCommand.LOGOUT);
  420.     }

  422.     /**
  423.      * Send an LSUB command to the server. Quotes the parameters if necessary.
  424.      *
  425.      * @param refName     The reference name.
  426.      * @param mailboxName The mailbox name.
  427.      * @return {@code true} if the command was successful,{@code false} if not.
  428.      * @throws IOException If a network I/O error occurs.
  429.      */
  430.     public boolean lsub(final String refName, final String mailboxName) throws IOException {
  431.         return doCommand(IMAPCommand.LSUB, quoteMailboxName(refName) + " " + quoteMailboxName(mailboxName));
  432.     }

  434.     /**
  435.      * Send a NOOP command to the server. This is useful for keeping a connection alive since most IMAP servers will time out after 10 minutes of inactivity.
  436.      *
  437.      * @return {@code true} if the command was successful,{@code false} if not.
  438.      * @throws IOException If a network I/O error occurs.
  439.      */
  440.     public boolean noop() throws IOException {
  441.         return doCommand(IMAPCommand.NOOP);
  442.     }

  444.     /**
  445.      * Send a RENAME command to the server.
  446.      *
  447.      * @param oldMailboxName The existing mailbox name to rename.
  448.      * @param newMailboxName The new mailbox name.
  449.      * @return {@code true} if the command was successful,{@code false} if not.
  450.      * @throws IOException If a network I/O error occurs.
  451.      */
  452.     public boolean rename(final String oldMailboxName, final String newMailboxName) throws IOException {
  453.         return doCommand(IMAPCommand.RENAME, quoteMailboxName(oldMailboxName) + " " + quoteMailboxName(newMailboxName));
  454.     }

  456.     /**
  457.      * Send a SEARCH command to the server.
  458.      *
  459.      * @param criteria The search criteria.
  460.      * @return {@code true} if the command was successful,{@code false} if not.
  461.      * @throws IOException If a network I/O error occurs.
  462.      */
  463.     public boolean search(final String criteria) throws IOException {
  464.         return search(null, criteria);
  465.     }

  467.     /**
  468.      * Send a SEARCH command to the server.
  469.      *
  470.      * @param charset  The charset (optional).
  471.      * @param criteria The search criteria.
  472.      * @return {@code true} if the command was successful,{@code false} if not.
  473.      * @throws IOException If a network I/O error occurs.
  474.      */
  475.     public boolean search(final String charset, final String criteria) throws IOException {
  476.         final StringBuilder args = new StringBuilder();
  477.         if (charset != null) {
  478.             args.append("CHARSET ").append(charset);
  479.         }
  480.         args.append(criteria);
  481.         return doCommand(IMAPCommand.SEARCH, args.toString());
  482.     }

  484.     /**
  485.      * Send a SELECT command to the server.
  486.      *
  487.      * @param mailboxName The mailbox name to select.
  488.      * @return {@code true} if the command was successful,{@code false} if not.
  489.      * @throws IOException If a network I/O error occurs.
  490.      */
  491.     public boolean select(final String mailboxName) throws IOException {
  492.         return doCommand(IMAPCommand.SELECT, quoteMailboxName(mailboxName));
  493.     }

  495.     /**
  496.      * Send a STATUS command to the server.
  497.      *
  498.      * @param mailboxName The reference name.
  499.      * @param itemNames   The status data item names.
  500.      * @return {@code true} if the command was successful,{@code false} if not.
  501.      * @throws IOException If a network I/O error occurs.
  502.      */
  503.     public boolean status(final String mailboxName, final String[] itemNames) throws IOException {
  504.         if (itemNames == null || itemNames.length < 1) {
  505.             throw new IllegalArgumentException("STATUS command requires at least one data item name");
  506.         }

  508.         final StringBuilder sb = new StringBuilder();
  509.         sb.append(quoteMailboxName(mailboxName));

  511.         sb.append(" (");
  512.         for (int i = 0; i < itemNames.length; i++) {
  513.             if (i > 0) {
  514.                 sb.append(" ");
  515.             }
  516.             sb.append(itemNames[i]);
  517.         }
  518.         sb.append(")");

  520.         return doCommand(IMAPCommand.STATUS, sb.toString());
  521.     }

  523.     /**
  524.      * Send a STORE command to the server.
  525.      *
  526.      * @param sequenceSet The sequence set to update (e.g. 2:5)
  527.      * @param itemNames   The item name for the STORE command (i.e. [+|-]FLAGS[.SILENT])
  528.      * @param itemValues  The item values for the STORE command. (e.g. (\Deleted) )
  529.      * @return {@code true} if the command was successful,{@code false} if not.
  530.      * @throws IOException If a network I/O error occurs.
  531.      */
  532.     public boolean store(final String sequenceSet, final String itemNames, final String itemValues) throws IOException {
  533.         return doCommand(IMAPCommand.STORE, sequenceSet + " " + itemNames + " " + itemValues);
  534.     }

  536.     /**
  537.      * Send a SUBSCRIBE command to the server.
  538.      *
  539.      * @param mailboxName The mailbox name to subscribe to.
  540.      * @return {@code true} if the command was successful,{@code false} if not.
  541.      * @throws IOException If a network I/O error occurs.
  542.      */
  543.     public boolean subscribe(final String mailboxName) throws IOException {
  544.         return doCommand(IMAPCommand.SUBSCRIBE, quoteMailboxName(mailboxName));
  545.     }

  547.     /**
  548.      * Send a UID command to the server.
  549.      *
  550.      * @param command     The command for UID.
  551.      * @param commandArgs The arguments for the command.
  552.      * @return {@code true} if the command was successful,{@code false} if not.
  553.      * @throws IOException If a network I/O error occurs.
  554.      */
  555.     public boolean uid(final String command, final String commandArgs) throws IOException {
  556.         return doCommand(IMAPCommand.UID, command + " " + commandArgs);
  557.     }

  559.     /**
  560.      * Send a UNSUBSCRIBE command to the server.
  561.      *
  562.      * @param mailboxName The mailbox name to unsubscribe from.
  563.      * @return {@code true} if the command was successful,{@code false} if not.
  564.      * @throws IOException If a network I/O error occurs.
  565.      */
  566.     public boolean unsubscribe(final String mailboxName) throws IOException {
  567.         return doCommand(IMAPCommand.UNSUBSCRIBE, quoteMailboxName(mailboxName));
  568.     }

  570. }
Created with JaCoCo 0.8.12.202403310830