jakarta.mail.internet.package-info Maven / Gradle / Ivy
/*
* Copyright (c) 2021 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
*/
/**
* Classes specific to Internet mail systems.
* This package supports features that are specific to Internet mail systems
* based on the MIME standard
* (RFC 2045,
* RFC 2046, and
* RFC 2047).
* The IMAP, SMTP, and POP3 protocols use
* {@link jakarta.mail.internet.MimeMessage MimeMessages}.
*
* Properties
*
* The Jakarta Mail API supports the following standard properties,
* which may be set in the Session object, or in the
* Properties object used to create the Session object.
* The properties are always set as strings; the Type column describes
* how the string is interpreted. For example, use
*
*
* session.setProperty("mail.mime.address.strict", "false");
*
*
* to set the mail.mime.address.strict property,
* which is of type boolean.
*
*
* Jakarta Mail properties
*
* Name
* Type
* Description
*
*
*
* mail.mime.address.strict
* boolean
*
* The mail.mime.address.strict session property controls
* the parsing of address headers. By default, strict parsing of address
* headers is done. If this property is set to "false",
* strict parsing is not done and many illegal addresses that sometimes
* occur in real messages are allowed. See the InternetAddress
* class for details.
*
*
*
*
* mail.mime.allowutf8
* boolean
*
* If set to "true", UTF-8 strings are allowed in message headers,
* e.g., in addresses. This should only be set if the mail server also
* supports UTF-8.
*
*
*
*
* The Jakarta Mail API specification requires support for the following properties,
* which must be set in the System properties.
* The properties are always set as strings; the Type column describes
* how the string is interpreted. For example, use
*
*
* System.setProperty("mail.mime.decodetext.strict", "false");
*
*
* to set the mail.mime.decodetext.strict property,
* which is of type boolean.
*
*
* Jakarta Mail System properties
*
* Name
* Type
* Description
*
*
*
* mail.mime.charset
* String
*
* The mail.mime.charset System property can
* be used to specify the default MIME charset to use for encoded words
* and text parts that don't otherwise specify a charset. Normally, the
* default MIME charset is derived from the default Java charset, as
* specified in the file.encoding System property. Most
* applications will have no need to explicitly set the default MIME
* charset. In cases where the default MIME charset to be used for
* mail messages is different than the charset used for files stored on
* the system, this property should be set.
*
*
*
*
* mail.mime.decodetext.strict
* boolean
*
* The mail.mime.decodetext.strict property controls
* decoding of MIME encoded words. The MIME spec requires that encoded
* words start at the beginning of a whitespace separated word. Some
* mailers incorrectly include encoded words in the middle of a word.
* If the mail.mime.decodetext.strict System property is
* set to "false", an attempt will be made to decode these
* illegal encoded words. The default is true.
*
*
*
*
* mail.mime.encodeeol.strict
* boolean
*
* The mail.mime.encodeeol.strict property controls the
* choice of Content-Transfer-Encoding for MIME parts that are not of
* type "text". Often such parts will contain textual data for which
* an encoding that allows normal end of line conventions is appropriate.
* In rare cases, such a part will appear to contain entirely textual
* data, but will require an encoding that preserves CR and LF characters
* without change. If the mail.mime.encodeeol.strict
* System property is set to "true", such an encoding will
* be used when necessary. The default is false.
*
*
*
*
* mail.mime.decodefilename
* boolean
*
* If set to "true", the getFileName method
* uses the MimeUtility
* method decodeText to decode any
* non-ASCII characters in the filename. Note that this decoding
* violates the MIME specification, but is useful for interoperating
* with some mail clients that use this convention.
* The default is false.
*
*
*
*
* mail.mime.encodefilename
* boolean
*
* If set to "true", the setFileName method
* uses the MimeUtility
* method encodeText to encode any
* non-ASCII characters in the filename. Note that this encoding
* violates the MIME specification, but is useful for interoperating
* with some mail clients that use this convention.
* The default is false.
*
*
*
*
* mail.mime.decodeparameters
* boolean
*
* If set to "false", non-ASCII parameters in a
* ParameterList, e.g., in a Content-Type header,
* will not be decoded as specified by
* RFC 2231.
* The default is true.
*
*
*
*
* mail.mime.encodeparameters
* boolean
*
* If set to "false", non-ASCII parameters in a
* ParameterList, e.g., in a Content-Type header,
* will not be encoded as specified by
* RFC 2231.
* The default is true.
*
*
*
*
* mail.mime.multipart. ignoremissingendboundary
* boolean
*
* Normally, when parsing a multipart MIME message, a message that is
* missing the final end boundary line is not considered an error.
* The data simply ends at the end of the input. Note that messages
* of this form violate the MIME specification. If the property
* mail.mime.multipart.ignoremissingendboundary is set
* to false, such messages are considered an error and a
* MesagingException will be thrown when parsing such a
* message.
*
*
*
*
* mail.mime.multipart. ignoremissingboundaryparameter
* boolean
*
* If the Content-Type header for a multipart content does not have
* a boundary parameter, the multipart parsing code
* will look for the first line in the content that looks like a
* boundary line and extract the boundary parameter from the line.
* If this property is set to "false", a
* MessagingException will be thrown if the Content-Type
* header doesn't specify a boundary parameter.
* The default is true.
*
*
*
*
* mail.mime.multipart. ignoreexistingboundaryparameter
* boolean
*
* Normally the boundary parameter in the Content-Type header of a multipart
* body part is used to specify the separator between parts of the multipart
* body. This System property may be set to "true" to cause
* the parser to look for a line in the multipart body that looks like a
* boundary line and use that value as the separator between subsequent parts.
* This may be useful in cases where a broken anti-virus product has rewritten
* the message incorrectly such that the boundary parameter and the actual
* boundary value no longer match.
* The default value of this property is false.
*
*
*
*
* mail.mime.multipart. allowempty
* boolean
*
* Normally, when writing out a MimeMultipart that contains no body
* parts, or when trying to parse a multipart message with no body parts,
* a MessagingException is thrown. The MIME spec does not allow
* multipart content with no body parts. This
* System property may be set to "true" to override this behavior.
* When writing out such a MimeMultipart, a single empty part will be
* included. When reading such a multipart, a MimeMultipart will be created
* with no body parts.
* The default value of this property is false.
*
*
*
*
*
*
*
* The following properties are supported by the EE4J implementation of
* Jakarta Mail, but are not currently a required part of the specification.
* These must be set as Session properties.
* The names, types, defaults, and semantics of these properties may
* change in future releases.
*
*
* Jakarta Mail implementation properties
*
* Name
* Type
* Description
*
*
*
* mail.alternates
* String
*
* A string containing other email addresses that the current user is known by.
* The MimeMessage reply method will eliminate any
* of these addresses from the recipient list in the message it constructs,
* to avoid sending the reply back to the sender.
*
*
*
*
* mail.replyallcc
* boolean
*
* If set to "true", the MimeMessage
* reply method will put all recipients except the original
* sender in the Cc list of the newly constructed message.
* Normally, recipients in the To header of the original
* message will also appear in the To list of the newly
* constructed message.
*
*
*
*
*
* The following properties are supported by the EE4J implementation of
* Jakarta Mail, but are not currently a required part of the specification.
* These must be set as System properties.
* The names, types, defaults, and semantics of these properties may
* change in future releases.
*
*
* Jakarta Mail implementation System properties
*
* Name
* Type
* Description
*
*
*
* mail.mime.base64.ignoreerrors
* boolean
*
* If set to "true", the BASE64 decoder will ignore errors
* in the encoded data, returning EOF. This may be useful when dealing
* with improperly encoded messages that contain extraneous data at the
* end of the encoded stream. Note however that errors anywhere in the
* stream will cause the decoder to stop decoding so this should be used
* with extreme caution. The default is false.
*
*
*
*
* mail.mime.foldtext
* boolean
*
* If set to "true", header fields containing just text
* such as the Subject and Content-Description
* header fields, and long parameter values in structured headers such
* as Content-Type will be folded (broken into 76 character lines)
* when set and unfolded when read. The default is true.
*
*
*
*
* mail.mime.setcontenttypefilename
* boolean
*
* If set to "true", the setFileName method
* will also set the name parameter on the Content-Type
* header to the specified filename. This supports interoperability with
* some old mail clients. The default is true.
*
*
*
*
* mail.mime.setdefaulttextcharset
* boolean
*
* When updating the headers of a message, a body
* part with a text content type but no charset
* parameter will have a charset parameter added to it
* if this property is set to "true".
* The default is true.
*
*
*
*
* mail.mime.parameters.strict
* boolean
*
* If set to false, when reading a message, parameter values in header fields
* such as Content-Type and Content-Disposition
* are allowed to contain whitespace and other special characters without
* being quoted; the parameter value ends at the next semicolon.
* If set to true (the default), parameter values are required to conform
* to the MIME specification and must be quoted if they contain whitespace
* or special characters.
*
*
*
*
* mail.mime.applefilenames
* boolean
*
* Apple Mail incorrectly encodes filenames that contain spaces,
* forgetting to quote the parameter value. If this property is
* set to "true", Jakarta Mail will try to detect this
* situation when parsing parameters and work around it.
* The default is false.
* Note that this property handles a subset of the cases handled
* by setting the mail.mime.parameters.strict property to false.
* This property will likely be removed in a future release.
*
*
*
*
* mail.mime.windowsfilenames
* boolean
*
* Internet Explorer 6 incorrectly includes a complete pathname
* in the filename parameter of the Content-Disposition header
* for uploaded files, and fails to properly escape the backslashes
* in the pathname. If this property is
* set to "true", Jakarta Mail will preserve all backslashes
* in the "filename" and "name" parameters of any MIME header.
* The default is false.
* Note that this is a violation of the MIME specification but may
* be useful when using Jakarta Mail to parse HTTP messages for uploaded
* files sent by IE6.
*
*
*
*
* mail.mime. ignoreunknownencoding
* boolean
*
* If set to "true", an unknown value in the
* Content-Transfer-Encoding header will be ignored
* when reading a message and an encoding of "8bit" will be assumed.
* If set to "false", an exception is thrown for an
* unknown encoding value. The default is false.
*
*
*
*
* mail.mime.uudecode. ignoreerrors
* boolean
*
* If set to "true", errors in the encoded format of a
* uuencoded document will be ignored when reading a message part.
* If set to "false", an exception is thrown for an
* incorrectly encoded message part. The default is false.
*
*
*
*
* mail.mime.uudecode. ignoremissingbeginend
* boolean
*
* If set to "true", a missing "being" or "end" line in a
* uuencoded document will be ignored when reading a message part.
* If set to "false", an exception is thrown for a
* uuencoded message part without the required "begin" and "end" lines.
* The default is false.
*
*
*
*
* mail.mime. ignorewhitespacelines
* boolean
*
* Normally the header of a MIME part is separated from the body by an empty
* line. This System property may be set to "true" to cause
* the parser to consider a line containing only whitespace to be an empty
* line. The default value of this property is false.
*
*
*
*
* mail.mime. ignoremultipartencoding
* boolean
*
* The MIME spec does not allow body parts of type multipart/* to be encoded.
* The Content-Transfer-Encoding header is ignored in this case.
* Setting this System property to "false" will
* cause the Content-Transfer-Encoding header to be honored for multipart
* content.
* The default value of this property is true.
*
*
*
*
* mail.mime.allowencodedmessages
* boolean
*
* The MIME spec does not allow body parts of type message/* to be encoded.
* The Content-Transfer-Encoding header is ignored in this case.
* Some versions of Microsoft Outlook will incorrectly encode message
* attachments. Setting this System property to "true" will
* cause the Content-Transfer-Encoding header to be honored for message
* attachments.
* The default value of this property is false.
*
*
*
*
* mail.mime.contenttypehandler
* String
*
* In some cases Jakarta Mail is unable to process messages with an invalid
* Content-Type header. The header may have incorrect syntax or other
* problems. This property specifies the name of a class that will be
* used to clean up the Content-Type header value before Jakarta Mail uses it.
* The class must have a method with this signature:
* public static String cleanContentType(MimePart mp, String contentType)
* Whenever Jakarta Mail accesses the Content-Type header of a message, it
* will pass the value to this method and use the returned value instead.
* The value may be null if the Content-Type header isn't present.
* Returning null will cause the default Content-Type to be used.
* The MimePart may be used to access other headers of the message part
* to determine how to correct the Content-Type.
* Note that the Content-Type handler doesn't affect the
* getHeader method, which still returns the raw header value.
* Note also that the handler doesn't affect the IMAP provider; the IMAP
* server is responsible for returning pre-parsed, syntactically correct
* Content-Type information.
*
*
*
*
* mail.mime.address.usecanonicalhostname
* boolean
*
* Use the
* {@link java.net.InetAddress#getCanonicalHostName InetAddress.getCanonicalHostName}
* method to determine the host name in the
* {@link jakarta.mail.internet.InternetAddress#getLocalAddress InternetAddress.getLocalAddress}
* method.
* With some network configurations, InetAddress.getCanonicalHostName may be
* slow or may return an address instead of a host name.
* In that case, setting this System property to false will cause the
* {@link java.net.InetAddress#getHostName InetAddress.getHostName}
* method to be used instead.
* The default is true.
*
*
*
*
*
* The current
* implementation of classes in this package log debugging information using
* {@link java.util.logging.Logger} as described in the following table:
*
*
* Jakarta Mail Loggers
*
* Logger Name
* Logging Level
* Purpose
*
*
*
* jakarta.mail.internet
* FINE
* General debugging output
*
*
*/
package jakarta.mail.internet;