0,0 → 1,1022 |
|
JavaMail 1.2 |
============ |
|
Following is a description of the new APIs that are being |
introduced in JavaMail 1.2. The numbers in parentheses |
are bug numbers; you can find more information about the |
bug reports at: |
|
http://developer.java.sun.com/developer/bugParade/index.html |
|
Please send comments and feedback to javamail@sun.com. |
|
|
=================================================================== |
|
1. New protected field and methods (4129743) |
-------------------------------------------- |
|
To simplify creating subclasses of MimeMessage, the following |
field and method that were previously private are now protected: |
|
/** |
* A flag indicating whether the message has been modified. |
* If the message has not been modified, any data in the |
* <code>content</code> array is assumed to be valid and is used |
* directly in the <code>writeTo</code> method. This flag is |
* set to true when an empty message is created or when the |
* <code>saveChanges</code> method is called. |
*/ |
protected boolean modified = false; |
|
/** |
* Parse the InputStream setting the <code>headers</code> and |
* <code>content</code> fields appropriately. Also resets the |
* <code>modified</code> flag. <p> |
* |
* This method is intended for use by subclasses that need to |
* control when the InputStream is parsed. |
* |
* @param is The message input stream |
* @exception MessagingException |
*/ |
protected void parse(InputStream is) throws MessagingException |
|
|
The javadocs for the following exsting methods have been updated to |
describe the use of the modified flag: |
|
/** |
* Default constructor. An empty message object is created. |
* The <code>headers</code> field is set to an empty InternetHeaders |
* object. The <code>flags</code> field is set to an empty Flags |
* object. The <code>modified</code> flag is set to true. |
*/ |
public MimeMessage(Session session) |
|
/** |
* Output the message as an RFC 822 format stream, without |
* specified headers. If the <code>modified</code> flag is not |
* set and the <code>content</code> array is not null, the |
* <code>content</code> array is written directly, after |
* writing the appropriate message headers. |
* |
* @exception javax.mail.MessagingException |
* @exception IOException if an error occurs writing to the stream |
* or if an error is generated by the |
* javax.activation layer. |
* @see javax.activation.DataHandler#writeTo |
*/ |
public void writeTo(OutputStream os, String[] ignoreList) |
throws IOException, MessagingException |
|
/** |
* Updates the appropriate header fields of this message to be |
* consistent with the message's contents. If this message is |
* contained in a Folder, any changes made to this message are |
* committed to the containing folder. <p> |
* |
* If any part of a message's headers or contents are changed, |
* <code>saveChanges</code> must be called to ensure that those |
* changes are permanent. Otherwise, any such modifications may or |
* may not be saved, depending on the folder implementation. <p> |
* |
* Messages obtained from folders opened READ_ONLY should not be |
* modified and saveChanges should not be called on such messages. <p> |
* |
* This method sets the <code>modified</code> flag to true and then |
* calls the <code>updateHeaders<code> method. |
* |
* @exception IllegalWriteException if the underlying |
* implementation does not support modification |
* @exception IllegalStateException if this message is |
* obtained from a READ_ONLY folder. |
* @exception MessagingException |
*/ |
public void saveChanges() throws MessagingException |
|
The following method is added to MimeMessage: |
|
/** |
* Create and return an InternetHeaders object that loads the |
* headers from the given InputStream. Subclasses can override |
* this method to return a subclass of InternetHeaders, if |
* necessary. This implementation simply constructs and returns |
* an InternetHeaders object. |
* |
* @param is the InputStream to read the headers from |
* @exception MessagingException |
*/ |
protected InternetHeaders createInternetHeaders(InputStream is) |
throws MessagingException |
|
Likewise, to simplify creating subclasses of MimeMultipart, the parse |
method is made protected: |
|
/** |
* Parse the InputStream from our DataSource, constructing the |
* appropriate MimeBodyParts. The <code>parsed</code> flag is |
* set to true, and if true on entry nothing is done. This |
* method is called by all other methods that need data for |
* the body parts, to make sure the data has been parsed. |
*/ |
protected synchronized void parse() throws MessagingException |
|
and the following protected methods are added: |
|
/** |
* Create and return an InternetHeaders object that loads the |
* headers from the given InputStream. Subclasses can override |
* this method to return a subclass of InternetHeaders, if |
* necessary. This implementation simply constructs and returns |
* an InternetHeaders object. |
* |
* @param is the InputStream to read the headers from |
* @exception MessagingException |
*/ |
protected InternetHeaders createInternetHeaders(InputStream is) |
throws MessagingException |
|
/** |
* Create and return a MimeBodyPart object to represent a |
* body part parsed from the InputStream. Subclasses can override |
* this method to return a subclass of MimeBodyPart, if |
* necessary. This implementation simply constructs and returns |
* a MimeBodyPart object. |
* |
* @param headers the headers for the body part |
* @param content the content ofthe body part |
* @exception MessagingException |
*/ |
protected MimeBodyPart createMimeBodyPart(InternetHeaders headers, |
byte[] content) throws MessagingException |
|
/** |
* Create and return a MimeBodyPart object to represent a |
* body part parsed from the InputStream. Subclasses can override |
* this method to return a subclass of MimeBodyPart, if |
* necessary. This implementation simply constructs and returns |
* a MimeBodyPart object. |
* |
* @param is InputStream containing the body part |
* @exception MessagingException |
*/ |
protected MimeBodyPart createMimeBodyPart(InputStream is) |
throws MessagingException |
|
=================================================================== |
|
2. MimeMessage and MimeBodyPart getRawInputStream method (4124840) |
------------------------------------------------------------------ |
|
In some cases it is desirable to get the data for a body part |
before JavaMail attempts to decode it. This is particularly important |
if the Content-Transfer-Encoding header is incorrect. (For example, |
some mail software is known to use "7-bit" instead of the MIME |
defined "7bit".) Access to this data is currently provided |
through the protected getContentStream method. Since simply |
making this method public has the potential to cause a source |
incompatibility for any subclasses that declare this method as |
protected, we instead add a new public method that calls this |
protected method: |
|
/** |
* Return an InputStream to the raw data with any Content-Transfer-Encoding |
* intact. This method is useful if the "Content-Transfer-Encoding" |
* header is incorrect or corrupt, which would prevent the |
* <code>getInputStream</code> method or <code>getContent</code> method |
* from returning the correct data. In such a case the application may |
* use this method and attempt to decode the raw data itself. <p> |
* |
* This implementation simply calls the <code>getContentStream</code> |
* method. |
* |
* @see #getInputStream |
* @see #getContentStream |
*/ |
public InputStream getRawInputStream() throws MessagingException |
|
|
=================================================================== |
|
3. ReadOnlyFolderException (4163360) |
------------------------------------ |
|
A new MessagingException subclass to indicate a read-only folder |
is needed. |
|
Currently, if a client attempts to open a folder in read-write mode |
and the folder is read-only, a MessagingException is thrown. This |
exception type does not indicate that the anomaly was caused due to |
the lack of write-permissions. |
|
/** |
* This exception is thrown when an attempt is made to open a folder |
* with read-write access when the folder is marked read-only. <p> |
*/ |
|
public class ReadOnlyFolderException extends MessagingException { |
|
/** |
* Constructor. |
* @param folder the Folder |
*/ |
public ReadOnlyFolderException(Folder folder) |
|
/** |
* Constructor. |
* @param folder the Folder |
* @param message the detailed error message |
*/ |
public ReadOnlyFolderException(Folder folder, String message) |
|
/** |
* Returns the Folder object. |
*/ |
public Folder getFolder() |
} |
|
=================================================================== |
|
4. InternetAddress implements Cloneable (4181144) |
------------------------------------------------- |
|
To simplify copying of InternetAddress objects, the InternetAddress |
class will implement the Cloneable interface and will provide a |
public clone method. |
|
public class InternetAddress extends Address implements Cloneable { |
|
/** |
* Return a copy of this InternetAddress object. |
*/ |
public Object clone() |
} |
|
=================================================================== |
|
5. MimeMessage copy constructor (4107752) |
----------------------------------------- |
|
When forwarding or saving a message retrieved from a Store, it is |
sometimes desirable to be able to modify the message first. Since |
most Stores do not allow their Message objects to be modified, the |
message must first be copied. To simplify copying a MimeMessage, |
we introduce a copy constructor that allows a new MimeMessage to |
be created and initialized with a copy of another MimeMessage. |
|
/** |
* Constructs a new MimeMessage with content initialized form the |
* <code>source</code> MimeMessage. The new message is independent |
* of the original. <p> |
* |
* @param source the message to copy content from |
* @exception MessagingException |
*/ |
public MimeMessage(MimeMessage source) throws MessagingException |
|
=================================================================== |
|
6. AuthenticationFailedException includes server message (4230553) |
------------------------------------------------------------------ |
|
When authentication with a server fails, the server often supplies |
some information in its protocol message that indicates the reason |
for the failure. To allow a service provider to return this information |
to the user, we now allow the Service.protocolConnect() method to |
throw an AuthenticationFailedException in this case. The exception |
may contain a string message that includes the additional information |
from the server. |
|
/** |
* The service implementation should override this method to |
* perform the actual protocol-specific connection attempt. |
* The default implementation of the <code>connect</code> method |
* calls this method as needed. <p> |
* |
* The <code>protocolConnect</code> method should return |
* <code>false</code> if a user name or password is required |
* for authentication but the corresponding parameter is null; |
* the <code>connect</code> method will prompt the user when |
* needed to supply missing information. This method may |
* also return <code>false</code> if authentication fails for |
* the supplied user name or password. Alternatively, this method |
* may throw an AuthenticationFailedException when authentication |
* fails. This exception may include a String message with more |
* detail about the failure. <p> |
* |
* The <code>protocolConnect</code> method should throw an |
* exception to report failures not related to authentication, |
* such as an invalid host name or port number, loss of a |
* connection during the authentication process, unavailability |
* of the server, etc. |
* |
* @param host the name of the host to connect to |
* @param port the port to use (-1 means use default port) |
* @param user the name of the user to login as |
* @param password the user's password |
* @return true if connection successful, false if authentication failed |
* @exception AuthenticationFailedException for authentication failures |
* @exception MessagingException for non-authentication failures |
*/ |
protected boolean protocolConnect(String host, int port, String user, |
String password) throws MessagingException |
|
=================================================================== |
|
7. Support ESMTP 8BITMIME extension (4132029) |
--------------------------------------------- |
|
JavaMail chooses the encoding for body parts when the Message.saveChanges() |
method is called. At the time this method is called, JavaMail has no |
information about the Transport that might be used to send the message. |
Thus, communicating the Transport's capabilities to the part of JavaMail |
that chooses body part encodings is problematic. |
|
To provide some minimal support for the 8BITMIME extension, the SMTP |
protocol provider is extended in the following way. Note that this |
capability is part of Sun's SMTP protocol provider, and is *not* a |
part of the JavaMail API spec. We include it here for convenience only. |
|
If the property "mail.smtp.allow8bitmime" is set to "true", and the |
SMTP server supports the 8BITMIME extension, the SMTP Transport will |
traverse the message and adjust the Content-Transfer-Encoding of text |
body parts from "quoted-printable" or "base64" to "8bit" as appropriate. |
|
Note that if the same message is subsequently sent over a Transport |
or to a server that does not support 8bit MIME, the message will *not* |
be converted back to a non-8bit encoding. Normally this will not be a |
problem. Note also that a message using "8bit" encoding can be safely |
appended to an IMAP folder. |
|
=================================================================== |
|
8. Make MailDateFormat class public (4266390) |
--------------------------------------------- |
|
It would be useful to have the MailDateFormat class available as part |
of the javax.mail.internet package to allow parsing and formatting |
dates in other MIME headers. |
|
/** |
* Formats and parses date specification based on the |
* draft-ietf-drums-msg-fmt-08 dated January 26, 2000. This is a followup |
* spec to RFC822.<p> |
* |
* This class does not take pattern strings. It always formats the |
* date based on the specification below.<p> |
* |
* 3.3 Date and Time Specification<p> |
* |
* Date and time occur in several header fields of a message. This section |
* specifies the syntax for a full date and time specification. Though folding |
* whitespace is permitted throughout the date-time specification, it is |
* recommended that only a single space be used where FWS is required and no |
* space be used where FWS is optional in the date-time specification; some |
* older implementations may not interpret other occurrences of folding |
* whitespace correctly.<p> |
* |
* date-time = [ day-of-week "," ] date FWS time [CFWS]<p> |
* |
* day-of-week = ([FWS] day-name) / obs-day-of-week<p> |
* |
* day-name = "Mon" / "Tue" / "Wed" / "Thu" / "Fri" / "Sat" / "Sun"<p> |
* |
* date = day month year<p> |
* |
* year = 4*DIGIT / obs-year<p> |
* |
* month = (FWS month-name FWS) / obs-month<p> |
* |
*<pre>month-name = "Jan" / "Feb" / "Mar" / "Apr" / |
* "May" / "Jun" / "Jul" / "Aug" / |
* "Sep" / "Oct" / "Nov" / "Dec" |
* </pre><p> |
* day = ([FWS] 1*2DIGIT) / obs-day<p> |
* |
* time = time-of-day FWS zone<p> |
* |
* time-of-day = hour ":" minute [ ":" second ]<p> |
* |
* hour = 2DIGIT / obs-hour<p> |
* |
* minute = 2DIGIT / obs-minute<p> |
* |
* second = 2DIGIT / obs-second<p> |
* |
* zone = (( "+" / "-" ) 4DIGIT) / obs-zone<p> |
* |
* |
* The day is the numeric day of the month. The year is any numeric year in |
* the common era.<p> |
* |
* The time-of-day specifies the number of hours, minutes, and optionally |
* seconds since midnight of the date indicated.<p> |
* |
* The date and time-of-day SHOULD express local time.<p> |
* |
* The zone specifies the offset from Coordinated Universal Time (UTC, |
* formerly referred to as "Greenwich Mean Time") that the date and |
* time-of-day represent. The "+" or "-" indicates whether the time-of-day is |
* ahead of or behind Universal Time. The first two digits indicate the number |
* of hours difference from Universal Time, and the last two digits indicate |
* the number of minutes difference from Universal Time. (Hence, +hhmm means |
* +(hh * 60 + mm) minutes, and -hhmm means -(hh * 60 + mm) minutes). The form |
* "+0000" SHOULD be used to indicate a time zone at Universal Time. Though |
* "-0000" also indicates Universal Time, it is used to indicate that the time |
* was generated on a system that may be in a local time zone other than |
* Universal Time.<p> |
* |
* A date-time specification MUST be semantically valid. That is, the |
* day-of-the week (if included) MUST be the day implied by the date, the |
* numeric day-of-month MUST be between 1 and the number of days allowed for |
* the specified month (in the specified year), the time-of-day MUST be in the |
* range 00:00:00 through 23:59:60 (the number of seconds allowing for a leap |
* second; see [STD-12]), and the zone MUST be within the range -9959 through |
* +9959.<p> |
* |
*/ |
public class MailDateFormat extends SimpleDateFormat { |
|
public MailDateFormat() |
|
/** |
* Formats the given date in the format specified by |
* draft-ietf-drums-msg-fmt-08 in the current TimeZone |
* |
* @param date the Date object |
* @param dateStrBuf the formatted string |
* @param fieldPosition the current field position |
* @returns StringBuffer the formatted String |
*/ |
public StringBuffer format(Date date, StringBuffer dateStrBuf, |
FieldPosition fieldPosition) |
|
/** |
* Parses the given date in the format specified by |
* draft-ietf-drums-msg-fmt-08 in the current TimeZone |
* |
* @param text the formatted date to be parsed |
* @param pos the current parse position |
* @returns Date the parsed date in a Date object |
*/ |
public Date parse(String text, ParsePosition pos) |
} |
|
=================================================================== |
|
9. String-based MimeMessage setRecipients and addRecipients methods (4328824) |
----------------------------------------------------------------------------- |
The following convenience methods will be added to MimeMessage. They take a |
String for setting/adding a recipient (instead of javax.mail.Address objects). |
|
/** |
* Set the specified recipient type to the given addresses. |
* If the address parameter is <code>null</code>, the corresponding |
* recipient field is removed. |
* |
* @param type Recipient type |
* @param addresses Addresses |
* @exception IllegalWriteException if the underlying |
* implementation does not support modification |
* of existing values |
* @exception IllegalStateException if this message is |
* obtained from a READ_ONLY folder. |
* @exception MessagingException |
* @see #getRecipients |
*/ |
public void setRecipients(Message.RecipientType type, String addresses) |
throws MessagingException |
|
/** |
* Add the given addresses to the specified recipient type. |
* |
* @param type Recipient type |
* @param addresses Addresses |
* @exception IllegalWriteException if the underlying |
* implementation does not support modification |
* of existing values. |
* @exception IllegalStateException if this message is |
* obtained from a READ_ONLY folder. |
* @exception MessagingException |
*/ |
public void addRecipients(Message.RecipientType type, String addresses) |
throws MessagingException |
|
=================================================================== |
|
10. Add Session.getDefaultInstance(Properties props) and |
Session.getInstance(Properties props) methods (4328826) |
--------------------------------------------------------------- |
|
These are convenience methods for retrieving the default Session or a new |
Session object which does not require an Authenticator parameter |
(it is assumed to be null). |
|
/** |
* Get the default Session object. If a default has not yet been |
* setup, a new Session object is created and installed as the |
* default.<p> |
* |
* Note that a default session created with no Authenticator is |
* available to all code executing in the same Java virtual |
* machine, and the session can contain security sensitive |
* information such as user names and passwords. |
* |
* @param props Properties object. Used only if a new Session |
* object is created.<br> |
* It is expected that the client supplies values |
* for the properties listed in Appendix A of the |
* JavaMail spec (particularly mail.store.protocol, |
* mail.transport.protocol, mail.host, mail.user, |
* and mail.from) as the defaults are unlikely to |
* work in all cases. |
* @return the default Session object |
*/ |
public static Session getDefaultInstance(Properties props) |
|
/** |
* Get a new Session object. |
* |
* @param props Properties object that hold relevant properties.<br> |
* It is expected that the client supplies values |
* for the properties listed in Appendix A of the |
* JavaMail spec (particularly mail.store.protocol, |
* mail.transport.protocol, mail.host, mail.user, |
* and mail.from) as the defaults are unlikely to |
* work in all cases. |
* @return a new Session object |
* @see javax.mail.Authenticator |
*/ |
public static Session getInstance(Properties props) |
|
=================================================================== |
|
11. Allow for providing a filename when using MimeUtility.encode() (4140579) |
---------------------------------------------------------------------------- |
|
The UUEncode encoder requires the filename to be inserted into the encoded |
stream. The public access point to the encoder is thru the MimeUtility.encode() |
method, which does not have any parameter that can provide the filename. |
Hence the uuencoded stream always has "encode.buf" as filename. This new |
method allows the setting of the filename. |
|
/** |
* Wrap an encoder around the given output stream. |
* All the encodings defined in RFC 2045 are supported here. |
* They include "base64", "quoted-printable", "7bit", "8bit" and |
* "binary". In addition, "uuencode" is also supported. |
* The <code>filename</code> parameter is used with the "uuencode" |
* encoding and is included in the encoded output. |
* |
* @param os output stream |
* @param encoding the encoding of the stream. |
* @param filename name for the file being encoded |
* @exception MessagingException |
* @return output stream that applies the |
* specified encoding. |
*/ |
public static OutputStream encode(OutputStream os, String encoding, |
String filename) |
throws MessagingException |
|
=================================================================== |
|
12. New exception constructors (4259211) |
---------------------------------------- |
|
The FolderNotFoundException constructors are not consistant with other |
exceptions defined in the API. New constructors are needed to eliminate |
these inconsistencies. |
|
/** |
* Constructs a MessagingException with the specified folder |
* @param folder the Folder |
*/ |
public FolderNotFoundException(Folder folder) |
|
/** |
* Constructs a MessagingException with the specified detail message |
* and the specified folder. |
* @param folder the Folder |
* @param s the detail message |
*/ |
public FolderNotFoundException(Folder folder, String s) |
|
=================================================================== |
|
13. InternetAddress.toUnicodeString() method (4281729) |
------------------------------------------------------- |
|
Problem: AddressStringTerm.match does not return the correct results |
in some situations. |
|
AddressStringTerm wants to do the match against the formatted address |
string in Unicode, not the ASCII version that might include charset |
encoding information. To do this it attempts to format the address |
itself, but it's not smart enough to know all the rules about |
formatting an address (e.g., when to quote the personal name) so it |
does this formatting differently than InternetAddress.toString does. |
When the address contains only ASCII characters, the formatting should |
be identical. |
|
/** |
* Returns a properly formatted address (RFC 822 syntax) of |
* Unicode characters. |
* |
* @return Unicode address string |
*/ |
public String toUnicodeString() |
|
=================================================================== |
|
14. Call saveChanges automatically on newly constructed message (4339203) |
------------------------------------------------------------------------- |
|
One of the most common errors when constructing new messages is forgetting |
to call the saveChanges() method before writing out the message or calling |
the Transport.sendMessage() method. To solve this problem we add a flag |
to MimeMessage and change the writeTo() method accordingly: |
|
/** |
* Does the <code>saveChanges</code> method need to be called on |
* this message? This flag is set to false by the public constructor |
* and set to true by the <code>saveChanges</code> method. The |
* <code>writeTo</code> method checks this flag and calls the |
* <code>saveChanges</code> method as necessary. This avoids the |
* common mistake of forgetting to call the <code>saveChanges</code> |
* method on a newly constructed message. |
*/ |
protected boolean saved = false; |
|
/** |
* Updates the appropriate header fields of this message to be |
* consistent with the message's contents. If this message is |
* contained in a Folder, any changes made to this message are |
* committed to the containing folder. <p> |
* |
* If any part of a message's headers or contents are changed, |
* <code>saveChanges</code> must be called to ensure that those |
* changes are permanent. Otherwise, any such modifications may or |
* may not be saved, depending on the folder implementation. <p> |
* |
* Messages obtained from folders opened READ_ONLY should not be |
* modified and saveChanges should not be called on such messages. <p> |
* |
* This method sets the <code>modified</code> flag to true, the |
* <code>save</code> flag to true, and then calls the |
* <code>updateHeaders<code> method. |
* |
* @exception IllegalWriteException if the underlying |
* implementation does not support modification |
* @exception IllegalStateException if this message is |
* obtained from a READ_ONLY folder. |
* @exception MessagingException |
*/ |
public void saveChanges() throws MessagingException |
|
/** |
* Output the message as an RFC 822 format stream, without |
* specified headers. If the <code>saved</code> flag is not set, |
* the <code>saveChanges</code> method is called. |
* If the <code>modified</code> flag is not |
* set and the <code>content</code> array is not null, the |
* <code>content</code> array is written directly, after |
* writing the appropriate message headers. |
* |
* @exception javax.mail.MessagingException |
* @exception IOException if an error occurs writing to the stream |
* or if an error is generated by the |
* javax.activation layer. |
* @see javax.activation.DataHandler#writeTo |
*/ |
public void writeTo(OutputStream os, String[] ignoreList) |
throws IOException, MessagingException |
|
=================================================================== |
|
15. New MimeUtility.getEncoding(DataHandler) method (4340648) |
------------------------------------------------------------- |
|
To improve the performance of JavaMail, we previously added a (package |
private) getEncoding() method to MimeUtility. This method is now public: |
|
/** |
* Same as <code>getEncoding(DataSource)</code> except that instead |
* of reading the data from an <code>InputStream</code> it uses the |
* <code>writeTo</code> method to examine the data. This is more |
* efficient in the common case of a <code>DataHandler</code> |
* created with an object and a MIME type (for example, a |
* "text/plain" String) because all the I/O is done in this |
* thread. In the case requiring an <code>InputStream</code> the |
* <code>DataHandler</code> uses a thread, a pair of pipe streams, |
* and the <code>writeTo</code> method to produce the data. <p> |
*/ |
public static String getEncoding(DataHandler dh) |
|
=================================================================== |
|
16. New TransportEvent.getMessage() method (4331674) |
----------------------------------------------------- |
|
The TransportEvent class saves the message that caused the error, |
but provides no getMessage method for the listener to retrieve the |
Message object. The following method will be added: |
|
/** |
* Get the Message object associated with this Transport Event. |
* |
* @return the Message object |
*/ |
public Message getMessage() |
|
|
=================================================================== |
|
17. javax.mail.search terms should be serializable (4126013) |
------------------------------------------------------------ |
|
The javax.mail.search package allows you to programmatically construct |
a search term. It would be convenient if those terms could be saved |
in persistent storage and restored in a later session. Using |
serialization to store these expressions is the simplest approach. |
|
Many of the search terms reference other objects that must also be |
serializable. The most problematic such objects are of the class |
Message.RecipientType. This class uses the java "type-safe enum" |
idiom, which involves a number of static final instances of the class. |
Applications are allowed to test for equivalence with these "constants" |
by using the "==" equality operator. Thus, it's critical that only a |
single instance of each constant exist in the Java virtual machine. |
To ensure that this constraint is met when deserializing an object |
of this class, we must take advantage of the JDK 1.2 readReplace() |
method. Since this method is not available on JDK 1.1, objects of |
this class, and thus search terms that reference them, can not be |
correctly deserialized on JDK 1.1. This is a limitation of this |
new capability. |
|
To provide this support, the following classes and all their subclasses |
now implement the Serializable interface: |
|
javax.mail.search.SearchTerm |
javax.mail.Address |
javax.mail.Flags |
javax.mail.Message.RecipientType |
|
In addition, to allow comparison between search terms, the equals |
and hashCode methods on SearchTerm (and all subclasses) now implement |
"value" equivalence rather than identity equivalence. |
|
|
=================================================================== |
|
18. Support IMAP NAMESPACE extension (4364827) |
------------------------------------------------------------ |
|
We propose the following new APIs to be added to javax.mail.Store to |
provide namespace information. If the IMAP server supports the |
NAMESPACE extension, it will be used to return this information. |
|
/** |
* Return a set of folders representing the <i>personal</i> namespaces |
* for the current user. A personal namespace is a set of names that |
* is considered within the personal scope of the authenticated user. |
* Typically, only the authenticated user has access to mail folders |
* in their personal namespace. If an INBOX exists for a user, it |
* must appear within the user's personal namespace. In the |
* typical case, there should be only one personal namespace for each |
* user in each Store. <p> |
* |
* This implementation returns an array with a single entry containing |
* the return value of the <code>getDefaultFolder</code> method. |
* Subclasses should override this method to return appropriate information. |
* |
* @exception IllegalStateException if this Store is not connected. |
* @return array of Folder objects |
*/ |
public Folder[] getPersonalNamespaces() throws MessagingException |
|
/** |
* Return a set of folders representing the namespaces for |
* <code>user</code>. The namespaces returned represent the |
* personal namespaces for the user. To access mail folders in the |
* other user's namespace, the currently authenticated user must be |
* explicitly granted access rights. For example, it is common for |
* a manager to grant to their secretary access rights to their |
* mail folders. <p> |
* |
* This implementation returns an empty array. Subclasses should |
* override this method to return appropriate information. |
* |
* @exception IllegalStateException if this Store is not connected. |
* @return array of Folder objects |
*/ |
public Folder[] getUserNamespaces(String user) throws MessagingException |
|
/** |
* Return a set of folders representing the <i>shared</i> namespaces. |
* A shared namespace is a namespace that consists of mail folders |
* that are intended to be shared amongst users and do not exist |
* within a user's personal namespace. <p> |
* |
* This implementation returns an empty array. Subclasses should |
* override this method to return appropriate information. |
* |
* @exception IllegalStateException if this Store is not connected. |
* @return array of Folder objects |
*/ |
public Folder[] getSharedNamespaces() throws MessagingException |
|
|
=================================================================== |
|
19. Make ContentDisposition class public (4366373) |
-------------------------------------------------- |
|
The javax.mail.internet.ContentDisposition class is package private |
and should be made public. The API is: |
|
/** |
* This class represents a MIME ContentDisposition value. It provides |
* methods to parse a ContentDisposition string into individual components |
* and to generate a MIME style ContentDisposition string. |
*/ |
|
public class ContentDisposition |
|
/** |
* No-arg Constructor. |
*/ |
public ContentDisposition() |
|
/** |
* Constructor. |
* |
* @param disposition disposition |
* @param list ParameterList |
*/ |
public ContentDisposition(String disposition, ParameterList list) |
|
/** |
* Constructor that takes a ContentDisposition string. The String |
* is parsed into its constituents: dispostion and parameters. |
* A ParseException is thrown if the parse fails. |
* |
* @param s the ContentDisposition string. |
* @exception ParseException if the parse fails. |
*/ |
public ContentDisposition(String s) throws ParseException |
|
/** |
* Return the disposition value. |
* @return the disposition |
*/ |
public String getDisposition() |
|
/** |
* Return the specified parameter value. Returns <code>null</code> |
* if this parameter is absent. |
* @return parameter value |
*/ |
public String getParameter(String name) |
|
/** |
* Return a ParameterList object that holds all the available |
* parameters. Returns null if no parameters are available. |
* |
* @return ParameterList |
*/ |
public ParameterList getParameterList() |
|
/** |
* Set the primary type. Overrides existing primary type. |
* @param primaryType primary type |
*/ |
public void setDisposition(String disposition) |
|
/** |
* Set the specified parameter. If this parameter already exists, |
* it is replaced by this new value. |
* |
* @param name parameter name |
* @param value parameter value |
*/ |
public void setParameter(String name, String value) |
|
/** |
* Set a new ParameterList. |
* @param list ParameterList |
*/ |
public void setParameterList(ParameterList list) |
|
/** |
* Retrieve a RFC2045 style string representation of |
* this ContentDisposition. Returns <code>null</code> if |
* the conversion failed. |
* |
* @return RFC2045 style string |
*/ |
public String toString() |
} |
|
=================================================================== |
|
20. Improve performance of MimeMessage (4371862) |
-------------------------------------------------- |
|
To allow us to improve the performance of the MimeMessage and MimeMultipart |
classes when parsing data from an InputStream, we introduce a new |
interface that allows the data in the InputStream to be shared instead |
of copied, and we use this new interface in key parts of the implementation. |
|
The following field is added to MimeMessage: |
|
/** |
* If the data for this message was supplied by an |
* InputStream that implements the SharedInputStream interface, |
* <code>contentStream</code> is another such stream representing |
* the content of this message. In this case, <code>content</code> |
* will be null. |
*/ |
protected InputStream contentStream; |
|
The following field is added to MimeBodyPart: |
|
/** |
* If the data for this body part was supplied by an |
* InputStream that implements the SharedInputStream interface, |
* <code>contentStream</code> is another such stream representing |
* the content of this body part. In this case, <code>content</code> |
* will be null. |
*/ |
protected InputStream contentStream; |
|
The following interface is added: |
|
package javax.mail.internet; |
|
/** |
* An InputStream that is backed by data that can be shared by multiple |
* readers may implement this interface. This allows users of such an |
* InputStream to determine the current positionin the InputStream, and |
* to create new InputStreams representing a subset of the data in the |
* original InputStream. The new InputStream will access the same |
* underlying data as the original, without copying the data. |
*/ |
|
public interface SharedInputStream { |
/** |
* 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 <code>start</code> (inclusive) |
* up to <code>end</code> (exclusive). <code>start</code> must be |
* non-negative. If <code>end</code> 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); |
} |
|
=================================================================== |
|
21. New ParameterList.toString(int used) method. |
-------------------------------------------------- |
|
The ParameterList.toString() method returns its results "unfolded". It |
would be useful to have the results "folded" in certain situations. A |
new method will be added to the ParamterList class which will return |
"folded" results. Folding is defined by RFC 822 as the process of splitting |
a header field into multiple lines. "The general rule is that wherever there |
may be linear-white-space (NOT simply LWSP-chars), a CRLF immediately |
followed by AT LEAST one LWSP-char may instead be inserted." Unfolding is |
the process of returning to a single line representation. "Unfolding is |
accomplished by regarding CRLF immediately followed by a LWSP-char as |
equivalent to the LWSP-char." |
|
/** |
* Convert this ParameterList into a MIME String. If this is |
* an empty list, an empty string is returned. |
* |
* The 'used' parameter specifies the number of character positions |
* already taken up in the field into which the resulting address |
* sequence string is to be inserted. It's used to determine where |
* to "fold" the resulting parameter list. |
* |
* @param used number of character positions already used, in |
* the field into which the parameter list is to |
* be inserted. |
* @return String |
*/ |
public String toString(int used) |