You are viewing a plain text version of this content. The canonical link for it is here.
Posted to scm@geronimo.apache.org by ri...@apache.org on 2007/09/24 15:16:46 UTC
svn commit: r578802 - in
/geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail:
Message.java MessageContext.java Part.java Quota.java QuotaAwareStore.java
Store.java Transport.java
Author: rickmcguire
Date: Mon Sep 24 06:16:44 2007
New Revision: 578802
URL: http://svn.apache.org/viewvc?rev=578802&view=rev
Log:
More javadoc comment improvements.
Modified:
geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Message.java
geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/MessageContext.java
geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Part.java
geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Quota.java
geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/QuotaAwareStore.java
geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Store.java
geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Transport.java
Modified: geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Message.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Message.java?rev=578802&r1=578801&r2=578802&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Message.java (original)
+++ geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Message.java Mon Sep 24 06:16:44 2007
@@ -69,7 +69,7 @@
}
/**
- * The index of a message withing its folder, or zero if the message was not retrieved from a folder.
+ * The index of a message within its folder, or zero if the message was not retrieved from a folder.
*/
protected int msgnum;
/**
@@ -114,28 +114,28 @@
}
/**
- * Return the "From" header indicating the identity of the person who the message is from;
- * in some circumstances this may be different to the actual sender.
+ * Return the "From" header indicating the identity of the person the message is from;
+ * in some circumstances this may be different than the actual sender.
*
* @return a list of addresses this message is from; may be empty if the header is present but empty, or null
* if the header is not present
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public abstract Address[] getFrom() throws MessagingException;
/**
* Set the "From" header for this message to the value of the "mail.user" property,
- * of if that property is not set, to the value of the system property "user.name"
+ * or if that property is not set, to the value of the system property "user.name"
*
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public abstract void setFrom() throws MessagingException;
/**
* Set the "From" header to the supplied address.
*
- * @param address the address of the person who the message is from
- * @throws MessagingException if there was a problem accessing the store
+ * @param address the address of the person the message is from
+ * @throws MessagingException if there was a problem accessing the Store
*/
public abstract void setFrom(Address address) throws MessagingException;
@@ -143,7 +143,7 @@
* Add multiple addresses to the "From" header.
*
* @param addresses the addresses to add
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public abstract void addFrom(Address[] addresses) throws MessagingException;
@@ -153,7 +153,7 @@
* @param type the type of recipient to get
* @return a list of addresses; may be empty if the header is present but empty,
* or null if the header is not present
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
* @see RecipientType
*/
public abstract Address[] getRecipients(RecipientType type) throws MessagingException;
@@ -164,7 +164,7 @@
* and then concatentates the results into a single array; it returns null if no headers are defined.
*
* @return an array containing all recipients
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public Address[] getAllRecipients() throws MessagingException {
Address[] to = getRecipients(RecipientType.TO);
@@ -199,7 +199,7 @@
*
* @param type the type of recipient
* @param addresses the new addresses
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public abstract void setRecipients(RecipientType type, Address[] addresses) throws MessagingException;
@@ -208,7 +208,7 @@
*
* @param type the type of recipient
* @param address the new address
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public void setRecipient(RecipientType type, Address address) throws MessagingException {
setRecipients(type, new Address[]{address});
@@ -219,7 +219,7 @@
*
* @param type the type of recipient
* @param addresses the addresses to add
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public abstract void addRecipients(RecipientType type, Address[] addresses) throws MessagingException;
@@ -228,7 +228,7 @@
*
* @param type the type of recipient
* @param address the address to add
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public void addRecipient(RecipientType type, Address address) throws MessagingException {
addRecipients(type, new Address[]{address});
@@ -241,7 +241,7 @@
* simply calls {@link #getFrom()}.
*
* @return a list of addresses to which replies should be directed
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public Address[] getReplyTo() throws MessagingException {
return getFrom();
@@ -253,7 +253,7 @@
* The default implementation throws a MethodNotSupportedException.
*
* @param addresses to which replies should be directed
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public void setReplyTo(Address[] addresses) throws MessagingException {
throw new MethodNotSupportedException("setReplyTo not supported");
@@ -263,7 +263,7 @@
* Get the subject for this message.
*
* @return the subject
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public abstract String getSubject() throws MessagingException;
@@ -271,7 +271,7 @@
* Set the subject of this message
*
* @param subject the subject
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public abstract void setSubject(String subject) throws MessagingException;
@@ -279,7 +279,7 @@
* Return the date that this message was sent.
*
* @return the date this message was sent
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public abstract Date getSentDate() throws MessagingException;
@@ -287,7 +287,7 @@
* Set the date this message was sent.
*
* @param sent the date when this message was sent
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public abstract void setSentDate(Date sent) throws MessagingException;
@@ -295,7 +295,7 @@
* Return the date this message was received.
*
* @return the date this message was received
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public abstract Date getReceivedDate() throws MessagingException;
@@ -303,7 +303,7 @@
* Return a copy the flags associated with this message.
*
* @return a copy of the flags for this message
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public abstract Flags getFlags() throws MessagingException;
@@ -313,7 +313,7 @@
*
* @param flag the flags to check for
* @return true if the flags is set
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public boolean isSet(Flags.Flag flag) throws MessagingException {
return getFlags().contains(flag);
@@ -325,7 +325,7 @@
*
* @param flags the flags to modify
* @param set the new value of those flags
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public abstract void setFlags(Flags flags, boolean set) throws MessagingException;
@@ -335,7 +335,7 @@
*
* @param flag the flag to set
* @param set the value for that flag
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public void setFlag(Flags.Flag flag, boolean set) throws MessagingException {
setFlags(new Flags(flag), set);
@@ -344,7 +344,7 @@
/**
* Return the message number for this Message.
* This number refers to the relative position of this message in a Folder; the message
- * number for any given message can change during a seesion if the Folder is expunged.
+ * number for any given message can change during a session if the Folder is expunged.
* Message numbers for messages in a folder start at one; the value zero indicates that
* this message does not belong to a folder.
*
@@ -406,18 +406,18 @@
*
* @param replyToAll if true, indciates the message should be addressed to all recipients not just the sender
* @return a new message suitable as a reply to this message
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public abstract Message reply(boolean replyToAll) throws MessagingException;
/**
- * To ensure changes are saved to the store, this message should be invoked
- * before its containing folder is closed. Implementations may save modifications
+ * To ensure changes are saved to the Store, this message should be invoked
+ * before its containing Folder is closed. Implementations may save modifications
* immediately but are free to defer such updates to they may be sent to the server
* in one batch; if saveChanges is not called then such changes may not be made
* permanent.
*
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public abstract void saveChanges() throws MessagingException;
@@ -426,7 +426,7 @@
*
* @param term the search criteria
* @return true if this message matches the search criteria.
- * @throws MessagingException if there was a problem accessing the store
+ * @throws MessagingException if there was a problem accessing the Store
*/
public boolean match(SearchTerm term) throws MessagingException {
return term.match(this);
Modified: geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/MessageContext.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/MessageContext.java?rev=578802&r1=578801&r2=578802&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/MessageContext.java (original)
+++ geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/MessageContext.java Mon Sep 24 06:16:44 2007
@@ -69,7 +69,14 @@
}
}
- // recurse up the chain of MultiPart/BodyPart paris until we hit a message
+ /**
+ * recurse up the chain of MultiPart/BodyPart parts until we hit a message
+ *
+ * @param p The starting part.
+ *
+ * @return The encountered Message or null if no Message parts
+ * are found.
+ */
private Message getMessageFrom(Part p) {
while (p != null) {
if (p instanceof Message) {
Modified: geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Part.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Part.java?rev=578802&r1=578801&r2=578802&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Part.java (original)
+++ geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Part.java Mon Sep 24 06:16:44 2007
@@ -32,56 +32,284 @@
* @version $Rev$ $Date$
*/
public interface Part {
+ /**
+ * This part should be presented as an attachment.
+ */
public static final String ATTACHMENT = "attachment";
+ /**
+ * This part should be presented or rendered inline.
+ */
public static final String INLINE = "inline";
+ /**
+ * Add this value to the existing headers with the given name. This method
+ * does not replace any headers that may already exist.
+ *
+ * @param name The name of the target header.
+ * @param value The value to be added to the header set.
+ *
+ * @exception MessagingException
+ */
public abstract void addHeader(String name, String value) throws MessagingException;
+ /**
+ * Return all headers as an Enumeration of Header objects.
+ *
+ * @return An Enumeration containing all of the current Header objects.
+ * @exception MessagingException
+ */
public abstract Enumeration getAllHeaders() throws MessagingException;
+ /**
+ * Return a content object for this Part. The
+ * content object type is dependent upon the
+ * DataHandler for the Part.
+ *
+ * @return A content object for this Part.
+ * @exception IOException
+ * @exception MessagingException
+ */
public abstract Object getContent() throws IOException, MessagingException;
+ /**
+ * Get the ContentType for this part, or null if the
+ * ContentType has not been set. The ContentType
+ * is expressed using the MIME typing system.
+ *
+ * @return The ContentType for this part.
+ * @exception MessagingException
+ */
public abstract String getContentType() throws MessagingException;
+ /**
+ * Returns a DataHandler instance for the content
+ * with in the Part.
+ *
+ * @return A DataHandler appropriate for the Part content.
+ * @exception MessagingException
+ */
public abstract DataHandler getDataHandler() throws MessagingException;
+ /**
+ * Returns a description string for this Part. Returns
+ * null if a description has not been set.
+ *
+ * @return The description string.
+ * @exception MessagingException
+ */
public abstract String getDescription() throws MessagingException;
+ /**
+ * Return the disposition of the part. The disposition
+ * determines how the part should be presented to the
+ * user. Two common disposition values are ATTACHMENT
+ * and INLINE.
+ *
+ * @return The current disposition value.
+ * @exception MessagingException
+ */
public abstract String getDisposition() throws MessagingException;
+ /**
+ * Get a file name associated with this part. The
+ * file name is useful for presenting attachment
+ * parts as their original source. The file names
+ * are generally simple names without containing
+ * any directory information. Returns null if the
+ * filename has not been set.
+ *
+ * @return The string filename, if any.
+ * @exception MessagingException
+ */
public abstract String getFileName() throws MessagingException;
+ /**
+ * Get all Headers for this header name. Returns null if no headers with
+ * the given name exist.
+ *
+ * @param name The target header name.
+ *
+ * @return An array of all matching header values, or null if the given header
+ * does not exist.
+ * @exception MessagingException
+ */
public abstract String[] getHeader(String name) throws MessagingException;
+ /**
+ * Return an InputStream for accessing the Part
+ * content. Any mail-related transfer encodings
+ * will be removed, so the data presented with
+ * be the actual part content.
+ *
+ * @return An InputStream for accessing the part content.
+ * @exception IOException
+ * @exception MessagingException
+ */
public abstract InputStream getInputStream() throws IOException, MessagingException;
+ /**
+ * Return the number of lines in the content, or
+ * -1 if the line count cannot be determined.
+ *
+ * @return The estimated number of lines in the content.
+ * @exception MessagingException
+ */
public abstract int getLineCount() throws MessagingException;
+ /**
+ * Return all headers that match the list of names as an Enumeration of
+ * Header objects.
+ *
+ * @param names An array of names of the desired headers.
+ *
+ * @return An Enumeration of Header objects containing the matching headers.
+ * @exception MessagingException
+ */
public abstract Enumeration getMatchingHeaders(String[] names) throws MessagingException;
+ /**
+ * Return an Enumeration of all Headers except those that match the names
+ * given in the exclusion list.
+ *
+ * @param names An array of String header names that will be excluded from the return
+ * Enumeration set.
+ *
+ * @return An Enumeration of Headers containing all headers except for those named
+ * in the exclusion list.
+ * @exception MessagingException
+ */
public abstract Enumeration getNonMatchingHeaders(String[] names) throws MessagingException;
+ /**
+ * Return the size of this part, or -1 if the size
+ * cannot be reliably determined.
+ *
+ * Note: the returned size does not take into account
+ * internal encodings, nor is it an estimate of
+ * how many bytes are required to transfer this
+ * part across a network. This value is intended
+ * to give email clients a rough idea of the amount
+ * of space that might be required to present the
+ * item.
+ *
+ * @return The estimated part size, or -1 if the size
+ * information cannot be determined.
+ * @exception MessagingException
+ */
public abstract int getSize() throws MessagingException;
+ /**
+ * Tests if the part is of the specified MIME type.
+ * Only the primaryPart and subPart of the MIME
+ * type are used for the comparison; arguments are
+ * ignored. The wildcard value of "*" may be used
+ * to match all subTypes.
+ *
+ * @param mimeType The target MIME type.
+ *
+ * @return true if the part matches the input MIME type,
+ * false if it is not of the requested type.
+ * @exception MessagingException
+ */
public abstract boolean isMimeType(String mimeType) throws MessagingException;
+ /**
+ * Remove all headers with the given name from the Part.
+ *
+ * @param name The target header name used for removal.
+ *
+ * @exception MessagingException
+ */
public abstract void removeHeader(String name) throws MessagingException;
public abstract void setContent(Multipart content) throws MessagingException;
+ /**
+ * Set a content object for this part. Internally,
+ * the Part will use the MIME type encoded in the
+ * type argument to wrap the provided content object.
+ * In order for this to work properly, an appropriate
+ * DataHandler must be installed in the Java Activation
+ * Framework.
+ *
+ * @param content The content object.
+ * @param type The MIME type for the inserted content Object.
+ *
+ * @exception MessagingException
+ */
public abstract void setContent(Object content, String type) throws MessagingException;
+ /**
+ * Set a DataHandler for this part that defines the
+ * Part content. The DataHandler is used to access
+ * all Part content.
+ *
+ * @param handler The DataHandler instance.
+ *
+ * @exception MessagingException
+ */
public abstract void setDataHandler(DataHandler handler) throws MessagingException;
+ /**
+ * Set a descriptive string for this part.
+ *
+ * @param description
+ * The new description.
+ *
+ * @exception MessagingException
+ */
public abstract void setDescription(String description) throws MessagingException;
+ /**
+ * Set the disposition for this Part.
+ *
+ * @param disposition
+ * The disposition string.
+ *
+ * @exception MessagingException
+ */
public abstract void setDisposition(String disposition) throws MessagingException;
+ /**
+ * Set a descriptive file name for this part. The
+ * name should be a simple name that does not include
+ * directory information.
+ *
+ * @param name The new name value.
+ *
+ * @exception MessagingException
+ */
public abstract void setFileName(String name) throws MessagingException;
+ /**
+ * Sets a value for the given header. This operation will replace all
+ * existing headers with the given name.
+ *
+ * @param name The name of the target header.
+ * @param value The new value for the indicated header.
+ *
+ * @exception MessagingException
+ */
public abstract void setHeader(String name, String value) throws MessagingException;
+ /**
+ * Set the Part content as text. This is a convenience method that sets
+ * the content to a MIME type of "text/plain".
+ *
+ * @param content The new text content, as a String object.
+ *
+ * @exception MessagingException
+ */
public abstract void setText(String content) throws MessagingException;
+ /**
+ * Write the Part content out to the provided OutputStream as a byte
+ * stream using an encoding appropriate to the Part content.
+ *
+ * @param out The target OutputStream.
+ *
+ * @exception IOException
+ * @exception MessagingException
+ */
public abstract void writeTo(OutputStream out) throws IOException, MessagingException;
}
Modified: geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Quota.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Quota.java?rev=578802&r1=578801&r2=578802&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Quota.java (original)
+++ geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Quota.java Mon Sep 24 06:16:44 2007
@@ -37,7 +37,7 @@
/**
- * Create a Quota with the given name and not resources.
+ * Create a Quota with the given name and no resources.
*
* @param quotaRoot The quota root name.
*/
@@ -47,7 +47,7 @@
/**
* Set a limit value for a resource. If the resource is not
- * current associated with this Quota, a new Resource item is
+ * currently associated with this Quota, a new Resource item is
* added to the resources list.
*
* @param name The target resource name.
Modified: geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/QuotaAwareStore.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/QuotaAwareStore.java?rev=578802&r1=578801&r2=578802&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/QuotaAwareStore.java (original)
+++ geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/QuotaAwareStore.java Mon Sep 24 06:16:44 2007
@@ -36,7 +36,7 @@
public Quota[] getQuota(String root) throws javax.mail.MessagingException;
/**
- * Set a quota item. The root contained in the Quota item identies
+ * Set a quota item. The root contained in the Quota item identifies
* the quota target.
*
* @param quota The source quota item.
Modified: geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Store.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Store.java?rev=578802&r1=578801&r2=578802&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Store.java (original)
+++ geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Store.java Mon Sep 24 06:16:44 2007
@@ -47,9 +47,9 @@
}
/**
- * Retutn a Folder object that represents the root of the namespace for the current user.
+ * Return a Folder object that represents the root of the namespace for the current user.
*
- * Note that in some store configurations (such as IMAP4) then the root folder may
+ * Note that in some store configurations (such as IMAP4) the root folder might
* not be the INBOX folder.
*
* @return the root Folder
@@ -59,7 +59,7 @@
/**
* Return the Folder corresponding to the given name.
- * The folder may not physically exist; the {@link Folder#exists()} method can be used
+ * The folder might not physically exist; the {@link Folder#exists()} method can be used
* to determine if it is real.
* @param name the name of the Folder to return
* @return the corresponding folder
Modified: geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Transport.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Transport.java?rev=578802&r1=578801&r2=578802&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Transport.java (original)
+++ geronimo/specs/trunk/geronimo-javamail_1.4_spec/src/main/java/javax/mail/Transport.java Mon Sep 24 06:16:44 2007
@@ -35,7 +35,7 @@
*/
public abstract class Transport extends Service {
/**
- * Send a message to all recipient addresses it contains (as returned by {@link Message#getAllRecipients()})
+ * Send a message to all recipient addresses the message contains (as returned by {@link Message#getAllRecipients()})
* using message transports appropriate for each address. Message addresses are checked during submission,
* but there is no guarantee that the ultimate address is valid or that the message will ever be delivered.
* <p/>
@@ -49,7 +49,7 @@
}
/**
- * Send a message to all addresses provided irrespective of any recipients contained in the message itself
+ * Send a message to all addresses provided irrespective of any recipients contained in the message,
* using message transports appropriate for each address. Message addresses are checked during submission,
* but there is no guarantee that the ultimate address is valid or that the message will ever be delivered.
* <p/>