org.eclipse.angus.mail.pop3.package-info Maven / Gradle / Ivy
/*
* Copyright (c) 2021, 2024 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
/**
* A POP3 protocol provider for the Jakarta Mail API
* that provides access to a POP3 message store.
* Refer to
* RFC 1939
* for more information.
*
* The POP3 provider provides a Store object that contains a single Folder
* named "INBOX". Due to the limitations of the POP3 protocol, many of
* the Jakarta Mail API capabilities like event notification, folder management,
* flag management, etc. are not allowed. The corresponding methods throw
* the MethodNotSupportedException exception; see below for details.
*
*
* Note that Jakarta Mail does not include a local store into
* which messages can be downloaded and stored. See our
*
* Third Party Products
* web page for availability of "mbox" and "MH" local store providers.
*
*
* The POP3 provider is accessed through the Jakarta Mail APIs by using the protocol
* name "pop3" or a URL of the form "pop3://user:password@host:port/INBOX".
*
*
* POP3 supports only a single folder named "INBOX".
*
*
* POP3 supports no permanent flags (see
* {@link jakarta.mail.Folder#getPermanentFlags Folder.getPermanentFlags()}).
* In particular, the Flags.Flag.RECENT
flag will never be set
* for POP3
* messages. It's up to the application to determine which messages in a
* POP3 mailbox are "new". There are several strategies to accomplish
* this, depending on the needs of the application and the environment:
*
*
* -
* A simple approach would be to keep track of the newest
* message seen by the application.
*
* -
* An alternative would be to keep track of the UIDs (see below)
* of all messages that have been seen.
*
* -
* Another approach is to download all messages into a local
* mailbox, so that all messages in the POP3 mailbox are, by
* definition, new.
*
*
*
* All approaches will require some permanent storage associated with the client.
*
*
* POP3 does not support the Folder.expunge()
method. To delete and
* expunge messages, set the Flags.Flag.DELETED
flag on the messages
* and close the folder using the Folder.close(true)
method. You
* cannot expunge without closing the folder.
*
*
* POP3 does not provide a "received date", so the getReceivedDate
* method will return null.
* It may be possible to examine other message headers (e.g., the
* "Received" headers) to estimate the received date, but these techniques
* are error-prone at best.
*
*
* The POP3 provider supports the POP3 UIDL command, see
* {@link org.eclipse.angus.mail.pop3.POP3Folder#getUID POP3Folder.getUID()}.
* You can use it as follows:
*
*
* if (folder instanceof org.eclipse.angus.mail.pop3.POP3Folder) {
* org.eclipse.angus.mail.pop3.POP3Folder pf =
* (org.eclipse.angus.mail.pop3.POP3Folder)folder;
* String uid = pf.getUID(msg);
* if (uid != null)
* ... // use it
* }
*
*
* You can also pre-fetch all the UIDs for all messages like this:
*
*
* FetchProfile fp = new FetchProfile();
* fp.add(UIDFolder.FetchProfileItem.UID);
* folder.fetch(folder.getMessages(), fp);
*
*
* Then use the technique above to get the UID for each message. This is
* similar to the technique used with the UIDFolder interface supported by
* IMAP, but note that POP3 UIDs are strings, not integers like IMAP
* UIDs. See the POP3 spec for details.
*
*
* When the headers of a POP3 message are accessed, the POP3 provider uses
* the TOP command to fetch all headers, which are then cached. Use of the
* TOP command can be disabled with the mail.pop3.disabletop
* property, in which case the entire message content is fetched with the
* RETR command.
*
*
* When the content of a POP3 message is accessed, the POP3 provider uses
* the RETR command to fetch the entire message. Normally the message
* content is cached in memory. By setting the
* mail.pop3.filecache.enable
property, the message content
* will instead be cached in a temporary file. The file will be removed
* when the folder is closed. Caching message content in a file is generally
* slower, but uses substantially less memory and may be helpful when dealing
* with very large messages.
*
*
* The {@link org.eclipse.angus.mail.pop3.POP3Message#invalidate POP3Message.invalidate}
* method can be used to invalidate cached data without closing the folder.
* Note that if the file cache is being used the data in the file will be
* forgotten and fetched from the server if it's needed again, and stored again
* in the file cache.
*
*
* The POP3 CAPA command (defined by
* RFC 2449)
* will be used to determine the capabilities supported by the server.
* Some servers don't implement the CAPA command, and some servers don't
* return correct information, so various properties are available to
* disable use of certain POP3 commands, including CAPA.
*
*
* If the server advertises the PIPELINING capability (defined by
* RFC 2449),
* or the mail.pop3.pipelining
property is set, the POP3
* provider will send some commands in batches, which can significantly
* improve performance and memory use.
* Some servers that don't support the CAPA command or don't advertise
* PIPELINING may still support pipelining; experimentation may be required.
*
*
* If pipelining is supported and the connection is using
* SSL, the USER and PASS commands will be sent as a batch.
* (If SSL is not being used, the PASS command isn't sent
* until the user is verified to avoid exposing the password
* if the user name is bad.)
*
*
* If pipelining is supported, when fetching a message with the RETR command,
* the LIST command will be sent as well, and the result will be used to size
* the I/O buffer, greatly reducing memory usage when fetching messages.
*
* Properties
*
* The POP3 protocol provider supports the following properties,
* which may be set in the Jakarta Mail Session
object.
* The properties are always set as strings; the Type column describes
* how the string is interpreted. For example, use
*
*
* props.put("mail.pop3.port", "888");
*
*
* to set the mail.pop3.port
property, which is of type int.
*
*
* Note that if you're using the "pop3s" protocol to access POP3 over SSL,
* all the properties would be named "mail.pop3s.*".
*
*
* POP3 properties
*
* Name
* Type
* Description
*
*
*
* mail.pop3.user
* String
* Default user name for POP3.
*
*
*
* mail.pop3.host
* String
* The POP3 server to connect to.
*
*
*
* mail.pop3.port
* int
* The POP3 server port to connect to, if the connect() method doesn't
* explicitly specify one. Defaults to 110.
*
*
*
* mail.pop3.connectiontimeout
* int
* Socket connection timeout value in milliseconds.
* This timeout is implemented by java.net.Socket.
* Default is infinite timeout.
*
*
*
* mail.pop3.timeout
* int
* Socket read timeout value in milliseconds.
* This timeout is implemented by java.net.Socket.
* Default is infinite timeout.
*
*
*
* mail.pop3.writetimeout
* int
* Socket write timeout value in milliseconds.
* This timeout is implemented by using a
* java.util.concurrent.ScheduledExecutorService per connection
* that schedules a thread to close the socket if the timeout expires.
* Thus, the overhead of using this timeout is one thread per connection.
* Default is infinite timeout.
*
*
*
* mail.pop3.executor.writetimeout
* java.util.concurrent.ScheduledExecutorService
* Provides specific ScheduledExecutorService for mail.pop3.writetimeout option.
* The value of mail.pop3.writetimeout shouldn't be a null.
* For provided executor pool it is highly recommended to have set up in true
* {@link java.util.concurrent.ScheduledThreadPoolExecutor#setRemoveOnCancelPolicy(boolean)}.
* Without it, write methods will create garbage that would only be reclaimed after the timeout.
* Be careful with calling {@link java.util.concurrent.ScheduledThreadPoolExecutor#shutdownNow()} in your executor,
* it can kill the running tasks. It would be ok to use shutdownNow only when JavaMail sockets are closed.
* This would be all service subclasses ({@link jakarta.mail.Store}/{@link jakarta.mail.Transport})
* Invoking run {@link java.lang.Runnable#run()} on the returned {@link java.util.concurrent.Future} objects
* would force close the open connections.
* Instead of shutdownNow you can use {@link java.util.concurrent.ScheduledThreadPoolExecutor#shutdown()} ()}
* and
* {@link java.util.concurrent.ScheduledThreadPoolExecutor#awaitTermination(long, java.util.concurrent.TimeUnit)} ()}.
*
*
*
*
* mail.pop3.rsetbeforequit
* boolean
*
* Send a POP3 RSET command when closing the folder, before sending the
* QUIT command. Useful with POP3 servers that implicitly mark all
* messages that are read as "deleted"; this will prevent such messages
* from being deleted and expunged unless the client requests so. Default
* is false.
*
*
*
*
* mail.pop3.message.class
* String
*
* Class name of a subclass of org.eclipse.angus.mail.pop3.POP3Message
.
* The subclass can be used to handle (for example) non-standard
* Content-Type headers. The subclass must have a public constructor
* of the form MyPOP3Message(Folder f, int msgno)
* throws MessagingException
.
*
*
*
*
* mail.pop3.localaddress
* String
*
* Local address (host name) to bind to when creating the POP3 socket.
* Defaults to the address picked by the Socket class.
* Should not normally need to be set, but useful with multi-homed hosts
* where it's important to pick a particular local address to bind to.
*
*
*
*
* mail.pop3.localport
* int
*
* Local port number to bind to when creating the POP3 socket.
* Defaults to the port number picked by the Socket class.
*
*
*
*
* mail.pop3.apop.enable
* boolean
*
* If set to true, use APOP instead of USER/PASS to login to the
* POP3 server, if the POP3 server supports APOP. APOP sends a
* digest of the password rather than the clear text password.
* Defaults to false.
*
*
*
*
* mail.pop3.auth.mechanisms
* String
*
* If set, lists the authentication mechanisms to consider, and the order
* in which to consider them. Only mechanisms supported by the server and
* supported by the current implementation will be used.
* The default is "LOGIN PLAIN DIGEST-MD5 NTLM"
, which includes all
* the authentication mechanisms supported by the current implementation
* except XOAUTH2.
*
*
*
*
* mail.pop3.auth.login.disable
* boolean
* If true, prevents use of the USER
and PASS
* commands.
* Default is false.
*
*
*
* mail.pop3.auth.plain.disable
* boolean
* If true, prevents use of the AUTH PLAIN
command.
* Default is false.
*
*
*
* mail.pop3.auth.digest-md5.disable
* boolean
* If true, prevents use of the AUTH DIGEST-MD5
command.
* Default is false.
*
*
*
* mail.pop3.auth.ntlm.disable
* boolean
* If true, prevents use of the AUTH NTLM
command.
* Default is false.
*
*
*
* mail.pop3.auth.ntlm.domain
* String
*
* The NTLM authentication domain.
*
*
*
*
* mail.pop3.auth.ntlm.flags
* int
*
* NTLM protocol-specific flags.
* See
* http://curl.haxx.se/rfc/ntlm.html#theNtlmFlags for details.
*
*
*
*
*
*
* mail.pop3.auth.xoauth2.disable
* boolean
* If true, prevents use of the AUTHENTICATE XOAUTH2
command.
* Because the OAuth 2.0 protocol requires a special access token instead of
* a password, this mechanism is disabled by default. Enable it by explicitly
* setting this property to "false" or by setting the "mail.pop3.auth.mechanisms"
* property to "XOAUTH2".
*
*
*
* mail.pop3.auth.xoauth2.two.line.authentication.format
* boolean
* If true, splits authentication command on two lines.
* Default is false.
*
*
*
* mail.pop3.socketFactory
* SocketFactory
*
* If set to a class that implements the
* javax.net.SocketFactory
interface, this class
* will be used to create POP3 sockets. Note that this is an
* instance of a class, not a name, and must be set using the
* put
method, not the setProperty
method.
*
*
*
*
* mail.pop3.socketFactory.class
* String
*
* If set, specifies the name of a class that implements the
* javax.net.SocketFactory
interface. This class
* will be used to create POP3 sockets.
*
*
*
*
* mail.pop3.socketFactory.fallback
* boolean
*
* If set to true, failure to create a socket using the specified
* socket factory class will cause the socket to be created using
* the java.net.Socket
class.
* Defaults to true.
*
*
*
*
* mail.pop3.socketFactory.port
* int
*
* Specifies the port to connect to when using the specified socket
* factory.
* If not set, the default port will be used.
*
*
*
*
* mail.pop3.ssl.enable
* boolean
*
* If set to true, use SSL to connect and use the SSL port by default.
* Defaults to false for the "pop3" protocol and true for the "pop3s" protocol.
*
*
*
*
* mail.pop3.ssl.checkserveridentity
* boolean
*
* If set to false, it does not check the server identity as specified by
* RFC 2595,
* RFC 2830, and
* RFC 6125.
* These additional checks based on the content of the server's certificate
* are intended to prevent man-in-the-middle attacks.
* Defaults to true.
*
*
*
*
* mail.pop3.ssl.hostnameverifier
* javax.net.ssl.HostnameVerifier
*
* If set to an object that implements the
* javax.net.ssl.HostnameVerifier
interface then, this object
* will be used to verify the hostname against the certificate. Note that this
* is an instance of a class, not a name, and must be set using the
* put
method, not the setProperty
method. The given
* object will provide additional checks based on the content of the server's
* certificate are intended to prevent man-in-the-middle attacks. Defaults to
* null.
*
*
*
*
* mail.pop3.ssl.hostnameverifier.class
* String
*
* If set, specifies the name of a class that implements the
* javax.net.ssl.HostnameVerifier
interface or an alias name
* assigned to a built in hostname verifier. A class name will be instantiated
* using the default constructor and that instance will be used to verify the
* hostname against the certificate. The alias name "legacy"
will
* enable the "sun.security.util.HostnameChecker"
with fail over to
* the "MailHostnameVerifier"
. The alias name
* "sun.security.util.HostnameChecker"
or
* "JdkHostnameChecker"
will attempt to access the
* sun.security.util.HostnameChecker
via reflection. The alias name
* "MailHostnameVerifier"
will check server identity as specified
* by RFC 2595.
* The instantiated object will provide additional checks based on the content
* of the server's certificate are intended to prevent man-in-the-middle
* attacks. Defaults to null.
*
*
*
*
* mail.pop3.ssl.trust
* String
*
* If set, and a socket factory hasn't been specified, enables use of a
* {@link org.eclipse.angus.mail.util.MailSSLSocketFactory MailSSLSocketFactory}.
* If set to "*", all hosts are trusted.
* If set to a whitespace separated list of hosts, those hosts are trusted.
* Otherwise, trust depends on the certificate the server presents.
*
*
*
*
* mail.pop3.ssl.socketFactory
* SSLSocketFactory
*
* If set to a class that extends the
* javax.net.ssl.SSLSocketFactory
class, this class
* will be used to create POP3 SSL sockets. Note that this is an
* instance of a class, not a name, and must be set using the
* put
method, not the setProperty
method.
*
*
*
*
* mail.pop3.ssl.socketFactory.class
* String
*
* If set, specifies the name of a class that extends the
* javax.net.ssl.SSLSocketFactory
class. This class
* will be used to create POP3 SSL sockets.
*
*
*
*
* mail.pop3.ssl.socketFactory.port
* int
*
* Specifies the port to connect to when using the specified socket
* factory.
* If not set, the default port will be used.
*
*
*
*
* mail.pop3.ssl.protocols
* string
*
* Specifies the SSL protocols that will be enabled for SSL connections.
* The property value is a whitespace separated list of tokens acceptable
* to the javax.net.ssl.SSLSocket.setEnabledProtocols
method.
*
*
*
*
* mail.pop3.ssl.ciphersuites
* string
*
* Specifies the SSL cipher suites that will be enabled for SSL connections.
* The property value is a whitespace separated list of tokens acceptable
* to the javax.net.ssl.SSLSocket.setEnabledCipherSuites
method.
*
*
*
*
* mail.pop3.starttls.enable
* boolean
*
* If true, enables the use of the STLS
command (if
* supported by the server) to switch the connection to a TLS-protected
* connection before issuing any login commands.
* If the server does not support STARTTLS, the connection continues without
* the use of TLS; see the
* mail.pop3.starttls.required
* property to fail if STARTTLS isn't supported.
* Note that an appropriate trust store must configured so that the client
* will trust the server's certificate.
* Defaults to false.
*
*
*
*
* mail.pop3.starttls.required
* boolean
*
* If true, requires the use of the STLS
command.
* If the server doesn't support the STLS command, or the command
* fails, the connect method will fail.
* Defaults to false.
*
*
*
*
* mail.pop3.proxy.host
* string
*
* Specifies the host name of an HTTP web proxy server that will be used for
* connections to the mail server.
*
*
*
*
* mail.pop3.proxy.port
* string
*
* Specifies the port number for the HTTP web proxy server.
* Defaults to port 80.
*
*
*
*
* mail.pop3.proxy.user
* string
*
* Specifies the user name to use to authenticate with the HTTP web proxy server.
* By default, no authentication is done.
*
*
*
*
* mail.pop3.proxy.password
* string
*
* Specifies the password to use to authenticate with the HTTP web proxy server.
* By default, no authentication is done.
*
*
*
*
* mail.pop3.socks.host
* string
*
* Specifies the host name of a SOCKS5 proxy server that will be used for
* connections to the mail server.
*
*
*
*
* mail.pop3.socks.port
* string
*
* Specifies the port number for the SOCKS5 proxy server.
* This should only need to be used if the proxy server is not using
* the standard port number of 1080.
*
*
*
*
* mail.pop3.disabletop
* boolean
*
* If set to true, the POP3 TOP command will not be used to fetch
* message headers. This is useful for POP3 servers that don't
* properly implement the TOP command, or that provide incorrect
* information in the TOP command results.
* Defaults to false.
*
*
*
*
* mail.pop3.disablecapa
* boolean
*
* If set to true, the POP3 CAPA command will not be used to fetch
* server capabilities. This is useful for POP3 servers that don't
* properly implement the CAPA command, or that provide incorrect
* information in the CAPA command results.
* Defaults to false.
*
*
*
*
* mail.pop3.forgettopheaders
* boolean
*
* If set to true, the headers that might have been retrieved using
* the POP3 TOP command will be forgotten and replaced by headers
* retrieved as part of the POP3 RETR command. Some servers, such
* as some versions of Microsft Exchange and IBM Lotus Notes,
* will return slightly different
* headers each time the TOP or RETR command is used. To allow the
* POP3 provider to properly parse the message content returned from
* the RETR command, the headers also returned by the RETR command
* must be used. Setting this property to true will cause these
* headers to be used, even if they differ from the headers returned
* previously as a result of using the TOP command.
* Defaults to false.
*
*
*
*
* mail.pop3.filecache.enable
* boolean
*
* If set to true, the POP3 provider will cache message data in a temporary
* file rather than in memory. Messages are only added to the cache when
* accessing the message content. Message headers are always cached in
* memory (on demand). The file cache is removed when the folder is closed
* or the JVM terminates.
* Defaults to false.
*
*
*
*
* mail.pop3.filecache.dir
* String
*
* If the file cache is enabled, this property can be used to override the
* default directory used by the JDK for temporary files.
*
*
*
*
* mail.pop3.cachewriteto
* boolean
*
* Controls the behavior of the
* {@link org.eclipse.angus.mail.pop3.POP3Message#writeTo writeTo} method
* on a POP3 message object.
* If set to true, and the message content hasn't yet been cached,
* and ignoreList is null, the message is cached before being written.
* Otherwise, the message is streamed directly
* to the output stream without being cached.
* Defaults to false.
*
*
*
*
* mail.pop3.keepmessagecontent
* boolean
*
* The content of a message is cached when it is first fetched.
* Normally this cache uses a {@link java.lang.ref.SoftReference SoftReference}
* to refer to the cached content. This allows the cached content to be purged
* if memory is low, in which case the content will be fetched again if it's
* needed.
* If this property is set to true, a hard reference to the cached content
* will be kept, preventing the memory from being reused until the folder
* is closed or the cached content is explicitly invalidated (using the
* {@link org.eclipse.angus.mail.pop3.POP3Message#invalidate invalidate} method).
* (This was the behavior in previous versions of Jakarta Mail.)
* Defaults to false.
*
*
*
*
* mail.pop3.finalizecleanclose
* boolean
*
* When the finalizer for POP3Store or POP3Folder is called,
* should the connection to the server be closed cleanly, as if the
* application called the close method?
* Or should the connection to the server be closed without sending
* any commands to the server?
* Defaults to false, the connection is not closed cleanly.
*
*
*
*
*
* In general, applications should not need to use the classes in this
* package directly. Instead, they should use the APIs defined by
* jakarta.mail
package (and subpackages). Applications should
* never construct instances of POP3Store
or
* POP3Folder
directly. Instead, they should use the
* Session
method getStore
to acquire an
* appropriate Store
object, and from that acquire
* Folder
objects.
*
*
* In addition to printing debugging output as controlled by the
* {@link jakarta.mail.Session Session} configuration,
* the org.eclipse.angus.mail.pop3 provider logs the same information using
* {@link java.util.logging.Logger} as described in the following table:
*
*
* POP3 Loggers
*
* Logger Name
* Logging Level
* Purpose
*
*
*
* org.eclipse.angus.mail.pop3
* CONFIG
* Configuration of the POP3Store
*
*
*
* org.eclipse.angus.mail.pop3
* FINE
* General debugging output
*
*
*
* org.eclipse.angus.mail.pop3.protocol
* FINEST
* Complete protocol trace
*
*
*
*
* WARNING: The APIs unique to this package should be
* considered EXPERIMENTAL. They may be changed in the
* future in ways that are incompatible with applications using the
* current APIs.
*/
package org.eclipse.angus.mail.pop3;