mail.mime.encodefilename System property
* is set to true, the {@link MimeUtility#encodeText
* MimeUtility.encodeText method will be used to encode the
* filename. While such encoding is not supported by the MIME
* spec, many mailers use this technique to support non-ASCII
* characters in filenames. The default value of this property
* is false.
The following text is added to the MimeMessage and MimeBodyPart
getFileName methods:
* If the mail.mime.encodefilename System property
* is set to true, the {@link MimeUtility#decodeText
* MimeUtility.decodeText method will be used to decode the
* filename. While such encoding is not supported by the MIME
* spec, many mailers use this technique to support non-ASCII
* characters in filenames. The default value of this property
* is false.
===================================================================
3. Add Service.connect(user, password) (6300771)
------------------------------------------------
This convenience method uses the host already known to the Service
(Transport or Store). Equivalent to connect(null, user, password).
/**
* Connect to the current host using the specified username
* and password. This method is equivalent to calling the
* connect(host, user, password) method with null
* for the host name.
*
* @param user the user name
* @param password this user's password
* @exception AuthenticationFailedException for authentication failures
* @exception MessagingException for other failures
* @exception IllegalStateException if the service is already connected
* @see javax.mail.event.ConnectionEvent
* @see javax.mail.Session#setPasswordAuthentication
* @see #connect(java.lang.String, java.lang.String, java.lang.String)
* @since JavaMail 1.4
*/
public void connect(String user, String password) throws MessagingException
===================================================================
4. Add mail.mime.multipart.ignoremissingendboundary System property (4971381)
-----------------------------------------------------------------------------
The current implementation of the MimeMultipart class will
ignore a missing end boundary line; if EOF is reached when
parsing the content before seeing an end boundary line, the
last part of the multipart is terminated and no error is
returned.
Some users have requested a way to force the multipart
parsing to more strictly enforce the MIME specification.
To support this we we introduce a new System property:
mail.mime.multipart.ignoremissingendboundary
If this property is set to "false" MimeMultipart will throw a
MessagingException when parsing a multipart that does not
include the proper end boundary line.
This property is already supported as part of the JavaMail
implementation. This change makes the property a part of the
standard API.
* The mail.mime.multipart.ignoremissingendboundary
* System property may be set to false to cause a
* MessagingException to be thrown if the multipart
* data does not end with the required end boundary line. If this
* property is set to true or not set, missing end
* boundaries are not considered an error and the final body part
* ends at the end of the data.
===================================================================
5. Add MimeMultipart.isComplete() method (6300811)
--------------------------------------------------
As described above, parsing of a MIME multipart may terminate
without an error, even though no final boundary line was seen.
This method will return true if the final boundary line was
seen. This will allow applications to successfully parse
mal-formed messages, while also being able to tell that they
were mal-formed.
/**
* Return true if the final boundary line for this
* multipart was seen. When parsing multipart content,
* this class will (by default) terminate parsing with
* no error if the end of input is reached before seeing
* the final multipart boundary line. In such a case,
* this method will return false. (If the System property
* "mail.mime.multipart.ignoremissingendboundary" is set to
* false, parsing such a message will instead throw a
* MessagingException.)
*
* @return true if the final boundary line was seen
* @since JavaMail 1.4
*/
public boolean isComplete() throws MessagingException
===================================================================
6. Add mail.mime.multipart.ignoremissingboundaryparameter property (6300814)
----------------------------------------------------------------------------
The following property is already supported as part of the JavaMail
implementation. This change makes the property a part of the
standard API.
* The mail.mime.multipart.ignoremissingboundaryparameter
* System property may be set to false to cause a
* MessagingException to be thrown if the Content-Type
* of the MimeMultipart does not include a boundary parameter.
* If this property is set to true or not set, the multipart
* parsing code will look for a line that looks like a bounary line and
* use that as the boundary separating the parts.
===================================================================
7. Add MimeMultipart getPreamble and setPreamble methods (6300828)
------------------------------------------------------------------
In a MIME multipart message, it's possible to include text between
the headers and the first boundary line. This text is called the
preamble. It may include instructions for users of non-MIME
compliant software. The getPreamble method allows access to this
text when available. (Note that IMAP servers provide no convenient
access to this text.) The setPreamble method allows an application
to set the preamble for a message being constructed.
/**
* Get the preamble text, if any, that appears before the
* first body part of this multipart. Some protocols,
* such as IMAP, will not allow access to the preamble text.
*
* @return the preamble text, or null if no preamble
* @since JavaMail 1.4
*/
public String getPreamble() throws MessagingException
/**
* Set the preamble text to be included before the first
* body part. Applications should generally not include
* any preamble text. In some cases it may be helpful to
* include preamble text with instructions for users of
* pre-MIME software.
*
* @param preamble the preamble text
* @since JavaMail 1.4
*/
public void setPreamble(String preamble) throws MessagingException
===================================================================
8. Add MimeMessage.updateMessageID() protected method (6300831)
---------------------------------------------------------------
Some applications want more control over the data that's used
to create the Message-ID for a message. This method allows
an application to provide a simple subclass of MimeMessage
that overrides the Message-ID algorithm.
/**
* Update the Message-ID header. This method is called
* by the updateHeaders and allows a subclass
* to override only the algorithm for choosing a Message-ID.
*
* @since JavaMail 1.4
*/
protected void updateMessageID() throws MessagingException
===================================================================
9. Add MimeMessage.createMimeMessage() protected method (6300833)
-----------------------------------------------------------------
The MimeMessage.reply method creates and returns a new MimeMessage.
Subclasses of MimeMessage may need the reply method to create a new
message of the appropriate subclass. This method allows subclasses
to control the class created in this case.
/**
* Create and return a MimeMessage object. The reply method
* uses this method to create the MimeMessage object that it
* will return. Subclasses can override this method to return
* a subclass of MimeMessage. This implementation simply constructs
* and returns a MimeMessage object using the supplied Session.
*
* @param session the Session to use for the new message
* @return the new MimeMessage object
* @since JavaMail 1.4
*/
protected MimeMessage createMimeMessage(Session session)
throws MessagingException
===================================================================
10. Make the "part" field of MimePartDataSource protected (6300834)
-------------------------------------------------------------------
Subclasses of MimePartDataSource may need access to the "part"
field in order to implement the getInputStream method. The
part field is currently private, this change will make it protected.
/**
* The MimePart that provides the data for this DataSource.
*
* @since JavaMail 1.4
*/
protected MimePart part;
===================================================================
11. Folder.getSeparator should not require the folder to exist (6301381)
------------------------------------------------------------------------
IMAP folders are able to determine the separator character without
knowing whether the folder exists. Checking whether the folder
exists in order to throw FolderNotFoundException introduces additional
overhead. Because other methods often need to know the separator
character, this overhead can be noticable. The specification of this
method is changed as follows:
/**
* Return the delimiter character that separates this Folder's pathname
* from the names of immediate subfolders. This method can be invoked
* on a closed Folder.
*
* @exception FolderNotFoundException if the implementation
* requires the folder to exist, but it does not
* @return Hierarchy separator character
*/
public abstract char getSeparator() throws MessagingException;
===================================================================
12. Add PreencodedMimeBodyPart class (6301386)
----------------------------------------------
In some cases an application will have data that has already
been encoded using (for example) base64 encoding. There should
be an easy way to attach such data to a message without the need
to decode it and reencode it. This class provides such support.
/**
* A MimeBodyPart that handles data that has already been encoded.
* This class is useful when constructing a message and attaching
* data that has already been encoded (for example, using base64
* encoding). The data may have been encoded by the application,
* or may have been stored in a file or database in encoded form.
* The encoding is supplied when this object is created. The data
* is attached to this object in the usual fashion, by using the
* setText, setContent, or
* setDataHandler methods.
*
* @since JavaMail 1.4
*/
public class PreencodedMimeBodyPart extends MimeBodyPart {
/**
* Create a PreencodedMimeBodyPart that assumes the data is
* encoded using the specified encoding. The encoding must
* be a MIME supported Content-Transfer-Encoding.
*/
public PreencodedMimeBodyPart(String encoding)
}
===================================================================
13. Add MimeBodyPart attachFile and saveFile methods (6301390)
--------------------------------------------------------------
It's very common for applications to create messages with files
as attachments, and to receive attachments and save them in files.
To simplify this usable, we add several convenience methods to the
MimeBodyPart class:
/**
* Use the specified file to provide the data for this part.
* The simple file name is used as the file name for this
* part and the data in the file is used as the data for this
* part. The encoding will be chosen appropriately for the
* file data.
*
* @param file the File object to attach
* @exception IOException errors related to accessing the file
* @exception MessagingException message related errors
* @since JavaMail 1.4
*/
public void attachFile(File file) throws IOException, MessagingException
/**
* Use the specified file to provide the data for this part.
* The simple file name is used as the file name for this
* part and the data in the file is used as the data for this
* part. The encoding will be chosen appropriately for the
* file data.
*
* @param file the name of the file to attach
* @exception IOException errors related to accessing the file
* @exception MessagingException message related errors
* @since JavaMail 1.4
*/
public void attachFile(String file) throws IOException, MessagingException
/**
* Save the contents of this part in the specified file. The content
* is decoded and saved, without any of the MIME headers.
*
* @param file the File object to write to
* @exception IOException errors related to accessing the file
* @exception MessagingException message related errors
* @since JavaMail 1.4
*/
public void saveFile(File file) throws IOException, MessagingException
/**
* Save the contents of this part in the specified file. The content
* is decoded and saved, without any of the MIME headers.
*
* @param file the name of the file to write to
* @exception IOException errors related to accessing the file
* @exception MessagingException message related errors
* @since JavaMail 1.4
*/
public void saveFile(String file) throws IOException, MessagingException
===================================================================
14. Add MimeUtility fold and unfold methods (6302118)
--------------------------------------------------------------
When dealing with long header lines, it's often necessary to fold
the lines to avoid exceeding line length limitations. When retrieving
the data from such headers, the folding needs to be undone. The JavaMail
implementation includes private fold and unfold methods for this purpose.
These methods should be made public.
/**
* Fold a string at linear whitespace so that each line is no longer
* than 76 characters, if possible. If there are more than 76
* non-whitespace characters consecutively, the string is folded at
* the first whitespace after that sequence. The parameter
* used indicates how many characters have been used in
* the current line; it is usually the length of the header name.
*
* Note that line breaks in the string aren't escaped; they probably
* should be.
*
* @param used characters used in line so far
* @param s the string to fold
* @return the folded string
*/
public static String fold(int used, String s)
/**
* Unfold a folded header. Any line breaks that aren't escaped and
* are followed by whitespace are removed.
*
* @param s the string to unfold
* @return the unfolded string
*/
public static String unfold(String s)
===================================================================
15. Allow more control over headers in InternetHeaders object (6302832)
-----------------------------------------------------------------------
Some applications, such as mail server applications, need more control
over the order of headers in the InternetHeaders class. To support
such usage, we allow such applications to subclass InternetHeaders
and access the List of headers directly. InternetHeaders exposes a
protected field:
protected List headers;
The elements of the list are objects of a new protected final class
InternetHeaders.InternetHeader that extends the javax.mail.Header class.
To allow the InternetHeader class to make use of the Header class, we
make the following fields of Header protected:
/**
* The name of the header.
*
* @since JavaMail 1.4
*/
protected String name;
/**
* The value of the header.
*
* @since JavaMail 1.4
*/
protected String value;
===================================================================
16. Allow applications to dynamically register new protocol providers (6302835)
-----------------------------------------------------------------------
Some applications would like to register new protocol providers at runtime
rather than depending on the JavaMail configuration files and resources.
To support such usage we make the constructor for the Provider class
public:
/**
* Create a new provider of the specified type for the specified
* protocol. The specified class implements the provider.
*
* @param type Type.STORE or Type.TRANSPORT
* @param protocol valid protocol for the type
* @param classname class name that implements this protocol
* @param vendor optional string identifying the vendor (may be null)
* @param version optional implementation version string (may be null)
* @since JavaMail 1.4
*/
public Provider(Type type, String protocol, String classname,
String vendor, String version)
We also add a new method to Session to allow registering such Providers:
/**
* Add a provider to the session.
*
* @param provider the provider to add
* @since JavaMail 1.4
*/
public void addProvider(Provider provider)
===================================================================
17. Allow applications to dynamically register address type mappings (4377727)
------------------------------------------------------------------------------
Along with the above item, some applications will want to dynamically
control the mapping from address type to protocol. This could also
be used to change the default internet protocol from "smtp" to "smtps".
We add the following method to Session:
/**
* Set the default transport protocol to use for addresses of
* the specified type. Normally the default is set by the
* javamail.default.address.map or
* javamail.address.map files or resources.
*
* @param addresstype type of address
* @param protocol name of protocol
* @see #getTransport(Address)
* @since JavaMail 1.4
*/
public void setProtocolForAddress(String addresstype, String protocol)
===================================================================
18. ParameterList class should support non US-ASCII parameters (4107342)
------------------------------------------------------------------------
RFC 2231 describes a method for encoding non-ASCII parameters in MIME
headers. We introduce the following System properties to control
encoding and decoding such parameters.
If the mail.mime.encodeparameters System property is set to "true".
non-ASCII parameters will be encoded per RFC 2231.
If the mail.mime.decodeparameters System property is set to "true".
parameters encoded per RFC 2231 will be decoded.
Both of these properties default to "false".
Note that RFC 2231 also describes a technique for splitting long
parameter values across multiple parameters. We do not plan to
support such parameter continuations.
To allow specifying the charset to use for a parameter, we add
the following method to ParameterList:
/**
* Set a parameter. If this parameter already exists, it is
* replaced by this new value. If the
* mail.mime.encodeparameters System property
* is true, and the parameter value is non-ASCII, it will be
* encoded with the specified charset.
*
* @param name name of the parameter.
* @param value value of the parameter.
* @param charset charset of the parameter value.
* @since JavaMail 1.4
*/
public void set(String name, String value, String charset)
===================================================================
19. Standard interface for Stores that support quotas (6304051)
---------------------------------------------------------------
Some IMAP stores support quotas. To allow applications to make
use of quota support without depending on IMAP-specific APIs,
we provide a QuotaAwareStore interface that Stores, such as the
IMAP Store, can implement. We also provide a Quota class to
represent a set of quotas for a quota root.
package javax.mail;
/**
* An interrface implemented by Stores that support quotas.
* The {@link #getQuota getQuota} and {@link #setQuota setQuota} methods
* support the quota model defined by the IMAP QUOTA extension.
* Refer to RFC 2087
* for more information.
*
* @since JavaMail 1.4
*/
public interface QuotaAwareStore {
/**
* Get the quotas for the named quota root.
* Quotas are controlled on the basis of a quota root, not
* (necessarily) a folder. The relationship between folders
* and quota roots depends on the server. Some servers
* might implement a single quota root for all folders owned by
* a user. Other servers might implement a separate quota root
* for each folder. A single folder can even have multiple
* quota roots, perhaps controlling quotas for different
* resources.
*
* @param root the name of the quota root
* @return array of Quota objects
* @exception MessagingException if the server doesn't support the
* QUOTA extension
*/
Quota[] getQuota(String root) throws MessagingException;
/**
* Set the quotas for the quota root specified in the quota argument.
* Typically this will be one of the quota roots obtained from the
* getQuota method, but it need not be.
*
* @param quota the quota to set
* @exception MessagingException if the server doesn't support the
* QUOTA extension
*/
void setQuota(Quota quota) throws MessagingException;
}
package javax.mail;
/**
* This class represents a set of quotas for a given quota root.
* Each quota root has a set of resources, represented by the
* Quota.Resource class. Each resource has a name
* (for example, "STORAGE"), a current usage, and a usage limit.
* See RFC 2087.
*
* @since JavaMail 1.4
*/
public class Quota {
/**
* An individual resource in a quota root.
*
* @since JavaMail 1.4
*/
public static class Resource {
/** The name of the resource. */
public String name;
/** The current usage of the resource. */
public long usage;
/** The usage limit for the resource. */
public long limit;
/**
* Construct a Resource object with the given name,
* usage, and limit.
*
* @param name the resource name
* @param usage the current usage of the resource
* @param limit the usage limit for the resource
*/
public Resource(String name, long usage, long limit)
}
/**
* The name of the quota root.
*/
public String quotaRoot;
/**
* The set of resources associated with this quota root.
*/
public Quota.Resource[] resources;
/**
* Create a Quota object for the named quotaroot with no associated
* resources.
*
* @param quotaRoot the name of the quota root
*/
public Quota(String quotaRoot)
/**
* Set a resource limit for this quota root.
*
* @param name the name of the resource
* @param limit the resource limit
*/
public void setResourceLimit(String name, long limit)
}
===================================================================
20. Add ByteArrayDataSource class (4623517)
-------------------------------------------
The ByteArrayDataSource has been included in the JavaMail demo
source code for quite some time. Quite a few applications need
a class of this sort. It's time to add it as a standard API.
To avoid conflicting with applications that have used the demo
version, we put this version in a new javax.mail.util package.
package javax.mail.util;
/**
* A DataSource backed by a byte array. The byte array may be
* passed in directly, or may be initialized from an InputStream
* or a String.
*
* @since JavaMail 1.4
*/
public class ByteArrayDataSource implements DataSource {
/**
* Create a ByteArrayDataSource with data from the
* specified byte array and with the specified MIME type.
*/
public ByteArrayDataSource(byte[] data, String type)
/**
* Create a ByteArrayDataSource with data from the
* specified InputStream and with the specified MIME type.
* The InputStream is read completely and the data is
* stored in a byte array.
*/
public ByteArrayDataSource(InputStream is, String type) throws IOException
/**
* Create a ByteArrayDataSource with data from the
* specified String and with the specified MIME type.
* The MIME type should include a charset
* parameter specifying the charset to be used for the
* string. If the parameter is not included, the
* default charset is used.
*/
public ByteArrayDataSource(String data, String type) throws IOException
/**
* Return an InputStream for the data.
* Note that a new stream is returned each time
* this method is called.
*/
public InputStream getInputStream() throws IOException
/**
* Return an OutputStream for the data.
* Writing the data is not supported; an IOException
* is always thrown.
*/
public OutputStream getOutputStream() throws IOException
/**
* Get the MIME content type of the data.
*/
public String getContentType()
/**
* Get the name of the data.
* By default, an empty string ("") is returned.
*/
public String getName()
/**
* Set the name of the data.
*/
public void setName(String name)
}
===================================================================
21. Add SharedByteArrayInputStream class (6304189)
--------------------------------------------------
The SharedInputStream interface allows the JavaMail implementation to
efficiently process data when parsing messages, without needing to
make many copies of the data. This class is an implementation of the
SharedInputStream interface that uses a byte array as the backing store.
package javax.mail.util;
/**
* A ByteArrayInputStream that implements the SharedInputStream interface,
* allowing the underlying byte array to be shared between multiple readers.
*
* @since JavaMail 1.4
*/
public class SharedByteArrayInputStream extends ByteArrayInputStream
implements SharedInputStream {
/**
* Position within shared buffer that this stream starts at.
*/
protected int start;
/**
* Create a SharedByteArrayInputStream representing the entire
* byte array.
*/
public SharedByteArrayInputStream(byte[] buf)
/**
* Create a SharedByteArrayInputStream representing the part
* of the byte array from offset for length
* bytes.
*/
public SharedByteArrayInputStream(byte[] buf, int offset, int length)
/**
* Return the current position in the InputStream, as an
* offset from the beginning of the InputStream.
*
* @return the current position
*/
public long getPosition()
/**
* Return a new InputStream representing a subset of the data
* from this InputStream, starting at start (inclusive)
* up to end (exclusive). start must be
* non-negative. If end is -1, the new stream ends
* at the same place as this stream. The returned InputStream
* will also implement the SharedInputStream interface.
*
* @param start the starting position
* @param end the ending position + 1
* @return the new stream
*/
public InputStream newStream(long start, long end)
}
===================================================================
22. Add SharedFileInputStream class (6304193)
---------------------------------------------
Finally, SharedFileInputStream is an implementation of the
SharedInputStream interface that uses a file as the backing store.
package javax.mail.util;
/**
* A SharedFileInputStream is a
* BufferedInputStream that buffers
* data from the file and supports the mark
* and reset methods. It also supports the
* newStream method that allows you to create
* other streams that represent subsets of the file.
* A RandomAccessFile object is used to
* access the file data.
*
* @since JavaMail 1.4
*/
public class SharedFileInputStream extends BufferedInputStream
implements SharedInputStream {
/**
* The file containing the data.
* Shared by all related SharedFileInputStream instances.
*/
protected RandomAccessFile in;
/**
* The normal size of the read buffer.
*/
protected int bufsize;
/**
* The file offset that corresponds to the first byte in
* the read buffer.
*/
protected long bufpos;
/**
* The file offset of the start of data in this subset of the file.
*/
protected long start = 0;
/**
* The amount of data in this subset of the file.
*/
protected long datalen;
/**
* Creates a SharedFileInputStream
* for the file.
*
* @param file the file
*/
public SharedFileInputStream(File file) throws IOException
/**
* Creates a SharedFileInputStream
* for the named file.
*
* @param file the file
*/
public SharedFileInputStream(String file) throws IOException
/**
* Creates a SharedFileInputStream
* with the specified buffer size.
*
* @param file the file
* @param size the buffer size.
* @exception IllegalArgumentException if size <= 0.
*/
public SharedFileInputStream(File file, int size) throws IOException
/**
* Creates a SharedFileInputStream
* with the specified buffer size.
*
* @param file the file
* @param size the buffer size.
* @exception IllegalArgumentException if size <= 0.
*/
public SharedFileInputStream(String file, int size) throws IOException
/**
* See the general contract of the read
* method of InputStream.
*
* @return the next byte of data, or -1 if the end of the
* stream is reached.
* @exception IOException if an I/O error occurs.
*/
public int read() throws IOException
/**
* Reads bytes from this stream into the specified byte array,
* starting at the given offset.
*
*
This method implements the general contract of the corresponding
* {@link java.io.InputStream#read(byte[], int, int) read}
* method of the {@link java.io.InputStream} class.
*
* @param b destination buffer.
* @param off offset at which to start storing bytes.
* @param len maximum number of bytes to read.
* @return the number of bytes read, or -1 if the end of
* the stream has been reached.
* @exception IOException if an I/O error occurs.
*/
public int read(byte b[], int off, int len) throws IOException
/**
* See the general contract of the skip
* method of InputStream.
*
* @param n the number of bytes to be skipped.
* @return the actual number of bytes skipped.
* @exception IOException if an I/O error occurs.
*/
public long skip(long n) throws IOException
/**
* Returns the number of bytes that can be read from this input
* stream without blocking.
*
* @return the number of bytes that can be read from this input
* stream without blocking.
* @exception IOException if an I/O error occurs.
*/
public int available() throws IOException
/**
* See the general contract of the mark
* method of InputStream.
*
* @param readlimit the maximum limit of bytes that can be read before
* the mark position becomes invalid.
* @see #reset()
*/
public void mark(int readlimit)
/**
* See the general contract of the reset
* method of InputStream.
*
* If markpos is -1
* (no mark has been set or the mark has been
* invalidated), an IOException
* is thrown. Otherwise, pos is
* set equal to markpos.
*
* @exception IOException if this stream has not been marked or
* if the mark has been invalidated.
* @see #mark(int)
*/
public void reset() throws IOException
/**
* Tests if this input stream supports the mark
* and reset methods. The markSupported
* method of SharedFileInputStream returns
* true.
*
* @return a boolean indicating if this stream type supports
* the mark and reset methods.
* @see java.io.InputStream#mark(int)
* @see java.io.InputStream#reset()
*/
public boolean markSupported()
/**
* Closes this input stream and releases any system resources
* associated with the stream.
*
* @exception IOException if an I/O error occurs.
*/
public void close() throws IOException
/**
* Return the current position in the InputStream, as an
* offset from the beginning of the InputStream.
*
* @return the current position
*/
public long getPosition()
/**
* Return a new InputStream representing a subset of the data
* from this InputStream, starting at start (inclusive)
* up to end (exclusive). start must be
* non-negative. If end is -1, the new stream ends
* at the same place as this stream. The returned InputStream
* will also implement the SharedInputStream interface.
*
* @param start the starting position
* @param end the ending position + 1
* @return the new stream
*/
public InputStream newStream(long start, long end)
/**
* Force this stream to close.
*/
protected void finalize() throws Throwable
}