Subversion Repositories javautils

                JavaMail 1.4
                ============

                (Updated August 15, 2005)

Following is a description of the new APIs that are being
introduced in JavaMail 1.4.  The numbers in parentheses
are bug numbers; you can find more information about the
bug reports at:

    http://bugs.sun.com/bugdatabase/index.jsp

Please send comments and feedback to javamail@sun.com.

Many of these changes expand JavaMail's conformance with Internet
standards, or make JavaMail more tolerant of messages that don't
quite conform to the standards.  "Be liberal in what you receive
and conservative in what you send."

JavaMail 1.4 will also require at least J2SE 1.4.  This allows
JavaMail to take advantage of features of more modern J2SE releases.


===================================================================

1. Add MimePart.setText(text, charset, subtype) method (6300765)
----------------------------------------------------------------

The setText method is a convenience method used to set the content
for a text/plain part.  With the increased use of HTML and XML in
mail messages, it would be useful to have a convenience method to
set content of those types as well.  To support this usage we add
a new method to the MimePart interface:

    /**
     * Convenience method that sets the given String as this part's
     * content, with a primary MIME type of "text" and the specified
     * MIME subtype.  The given Unicode string will be charset-encoded
     * using the specified charset. The charset is also used to set
     * the "charset" parameter.
     *
     * @param   text    the text content to set
     * @param   charset the charset to use for the text
     * @param   subtype the MIME subtype to use (e.g., "html")
     * @exception       MessagingException      if an error occurs
     * @since   JavaMail 1.4
     */
    public void setText(String text, String charset, String subtype)
                        throws MessagingException;

The MimeMessage and MimeBodyPart classes, which implement the
MimePart interface, will be updated to provide implementations
of the new method.


===================================================================

2. Add mail.mime.encodefilename and decodefilename properties (6300768)
-----------------------------------------------------------------------

According to the MIME spec (RFC 2047), filenames included in the
filename parameter of the Content-Disposition header may not
include MIME "encoded-words", and thus may contain only US-ASCII
characters.  However, many mailers violate this spec requirement
and use standard MIME encoding techniques to store non-ASCII
filenames in this filename parameter.

If the mail.mime.encodefilename System property is set to "true".
the MimeMessage and MimeBodyPart setFileName methods will use the
MimeUtility.encodeText method to encode the filename.

If the mail.mime.decodefilename System property is set to "true".
the MimeMessage and MimeBodyPart getFileName methods will use the
MimeUtility.decodeText method to decode the filename.

Both of these properties default to "false".

The following text is added to the MimeMessage and MimeBodyPart
setFileName methods:

     * If the <code>mail.mime.encodefilename</code> 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 <code>mail.mime.encodefilename</code> 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
     * <code>connect(host, user, password)</code> 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 <code>mail.mime.multipart.ignoremissingendboundary</code>
 * System property may be set to <code>false</code> to cause a
 * <code>MessagingException</code> to be thrown if the multipart
 * data does not end with the required end boundary line.  If this
 * property is set to <code>true</code> or not set, missing end
 * boundaries are not considered an error and the final body part
 * ends at the end of the data. <p>


===================================================================

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 <code>mail.mime.multipart.ignoremissingboundaryparameter</code>
 * System property may be set to <code>false</code> to cause a
 * <code>MessagingException</code> to be thrown if the Content-Type
 * of the MimeMultipart does not include a <code>boundary</code> parameter.
 * If this property is set to <code>true</code> 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 <code>updateHeaders</code> 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
 * <code>setText</code>, <code>setContent</code>, or
 * <code>setDataHandler</code> 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
     * <code>used</code> indicates how many characters have been used in
     * the current line; it is usually the length of the header name. <p>
     *
     * 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
     * <code>javamail.default.address.map</code> or
     * <code>javamail.address.map</code> 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
     * <code>mail.mime.encodeparameters</code> 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 <A HREF="http://www.ietf.org/rfc/rfc2087.txt">RFC 2087</A>
 * for more information. <p>
 *
 * @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
     * <code>getQuota</code> 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
 * <code>Quota.Resource</code> 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 <code>charset</code>
     * 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 <code>IOException</code>
     * 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 <code>offset</code> for <code>length</code>
     * 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 <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)
}


===================================================================

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 <code>SharedFileInputStream</code> is a
 * <code>BufferedInputStream</code> that buffers
 * data from the file and supports the <code>mark</code>
 * and <code>reset</code> methods.  It also supports the
 * <code>newStream</code> method that allows you to create
 * other streams that represent subsets of the file.
 * A <code>RandomAccessFile</code> 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 <code>SharedFileInputStream</code>
     * for the file.
     *
     * @param   file   the file
     */
    public SharedFileInputStream(File file) throws IOException

    /**
     * Creates a <code>SharedFileInputStream</code>
     * for the named file.
     *
     * @param   file   the file
     */
    public SharedFileInputStream(String file) throws IOException

    /**
     * Creates a <code>SharedFileInputStream</code>
     * 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 <code>SharedFileInputStream</code>
     * 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 <code>read</code>
     * method of <code>InputStream</code>.
     *
     * @return     the next byte of data, or <code>-1</code> 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.
     *
     * <p> This method implements the general contract of the corresponding
     * <code>{@link java.io.InputStream#read(byte[], int, int) read}</code>
     * method of the <code>{@link java.io.InputStream}</code> 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 <code>-1</code> 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 <code>skip</code>
     * method of <code>InputStream</code>.
     *
     * @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 <code>mark</code>
     * method of <code>InputStream</code>.
     *
     * @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 <code>reset</code>
     * method of <code>InputStream</code>.
     * <p>
     * If <code>markpos</code> is <code>-1</code>
     * (no mark has been set or the mark has been
     * invalidated), an <code>IOException</code>
     * is thrown. Otherwise, <code>pos</code> is
     * set equal to <code>markpos</code>.
     *
     * @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 <code>mark</code> 
     * and <code>reset</code> methods. The <code>markSupported</code> 
     * method of <code>SharedFileInputStream</code> returns 
     * <code>true</code>. 
     *
     * @return  a <code>boolean</code> indicating if this stream type supports
     *          the <code>mark</code> and <code>reset</code> 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 <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)

    /**
     * Force this stream to close.
     */
    protected void finalize() throws Throwable
}