notes.txt

SUN的JAVA MAIL API

			     NOTES
			     =====

		    JavaMail(TM) API 1.1.3 release
		    ------------------------------

Welcome to the 1.1.3 release of the JavaMail API implementation. 

Please refer to CHANGES.txt for a list of the changes since the 
1.1.2 release.

Please see the FAQ at http://java.sun.com/products/javamail/FAQ.html


A list of the provider specific properties:
-------------------------------------------
The following properties are specified by the JavaMail API specification
(Appendix A).

 Name			 Type		Description
 ----			 ----		------------
 mail.imap.user		 String	  Default user name for IMAP.

 mail.imap.host		 String	  The IMAP server to connect to.

 mail.smtp.user		 String	  Default user name for SMTP Authentication.

 mail.smtp.host		 String	  The SMTP server to connect to.


The following properties are specific to our IMAP provider. These
properties are not part of the JavaMail API specification, so they may
change in future versions.

 Name			 Type		Description
 ----			 ----		------------
 mail.imap.port		 int	  The IMAP server port to connect to, if
				  the connect() method doesn't explicitly
				  specify one. Defaults to 143.

 mail.imap.partialfetch	 boolean  Controls whether the IMAP partial-fetch
				  capability should be used. Defaults to
				  true. 

 mail.imap.fetchsize	 int	  Partial fetch size in bytes. Defaults
				  to 16K.
 
 mail.imap.timeout	 int	  Socket timeout value in milliseconds.
				  Default is infinite timeout.

 mail.imap.statuscachetimeout int Timeout value in milliseconds for cache
				  of STATUS command response.  Default is
				  1000 (1 second).  Zero disables cache.


The following properties are specific to our SMTP provider. These
properties are not part of the JavaMail API specification, so they may
change in future versions.

The SMTP provider has been enhanced to support ESMTP (RFC1651).  It can
optionally use SMTP Authentication (RFC2554) using the LOGIN and PLAIN
mechanisms (Internet Draft draft-newman-tls-imappop-09.txt).  Note,
however, that SASL (RFC2222 and RFC2487) is NOT supported.

To use SMTP authentication you'll need to provide the SMTP Transport
with a username and password when connecting to the SMTP server.  You
can do this using one of the following approaches:

- Provide an Authenticator object when creating your mail Session
  and provide the username and password information during the
  Authenticator callback.

  Note that the mail.smtp.user property can be set to provide a default
  username for the callback, but the password will still need to be
  supplied explicitly.

  This approach allows you to use the static Transport.send method
  to send messages.

- Call the Transport connect method explicitly with username and
  password arguments.

  This approach requires you to explicitly manage a Transport object
  and use the Transport sendMessage method to send the message.  The
  transport.java demo program demonstrates how to manage a Transport
  object.  The following is roughly equivalent to the static
  Transport send method, but supplies the needed username and password:

	Transport tr = session.getTransport("smtp");
	tr.connect(smtphost, username, password);
	msg.saveChanges();	// don't forget this
	tr.sendMessage(msg);
	tr.close();

SMTP can also optionally request Delivery Status Notifications
(RFC1891).

See below for the properties to enable these features.  These new SMTP
features should be considered EXPERIMENTAL, and thus likely to change
in future releases.

Note also that THERE IS NOT SUFFICIENT DOCUMENTATION HERE TO USE THESE
FEATURES!!!  You will need to read the appropriate RFCs mentioned above
to understand what these features do and how to use them.  Don't just
start setting properties and then complain to us when it doesn't work
like you expect it to work.  READ THE RFCs FIRST!!!

 Name			 Type		Description
 ----			 ----		------------
 mail.smtp.port		 int	  The SMTP server port to connect to, if
				  the connect() method doesn't explicitly
				  specify one.  Defaults to 25.
 
 mail.smtp.from		 String	  Email address to use for SMTP 
				  MAIL command.  This sets the envelope
				  return address.  Defaults to msg.getFrom()
				  or InternetAddress.getLocalAddress().
				  NOTE: mail.smtp.user was previously
				  used for this.

 mail.smtp.localhost	 String	  Local host name.  Defaults to
				  InetAddress.getLocalHost().getHostName().
				  Should not normally need to be set if
				  your JDK and your name service are
				  configured properly.

 mail.smtp.timeout	 int	  Socket timeout value in milliseconds.
				  Default is infinite timeout.

 mail.stmp.ehlo		 boolean  If false, do not attempt to sign on
				  with the EHLO command.  Defaults to
				  true.  Normally failure of the EHLO
				  command will fallback to the HELO
				  command; this property exists only
				  for servers that don't fail EHLO
				  properly or don't implement EHLO
				  properly.

 mail.stmp.auth		 boolean  If true, attempt to authenticate the
				  user using the AUTH command.  Defaults
				  to false.

 mail.smtp.dsn.notify	 String	  The NOTIFY option to the RCPT command.
				  Either NEVER, or some combination of
				  SUCCESS, FAILURE, and DELAY (separated
				  by commas).

 mail.smtp.dsn.ret	 String	  The RET option to the MAIL command.
				  Either FULL or HDRS.



A list of the known limitations, bugs, issues:
----------------------------------------------

1. Unsigned applets that use this version of the JavaMail API will not
   work under the Netscape browser, due to security restrictions 
   that prevent the "provider" and "mailcap" related files from 
   being loaded from mail.jar and activation.jar. 
   	
   We have not explored yet whether signed applets will work.
   We are investigating this further and will attempt to make 
   the appropriate fixes in the next minor release.

   A possible solution is to use the Java(TM) Plug-in that isn't 
   affected by the restrictions that Netscape places on the 
   resource files. (http://java.sun.com/products/plugin)

2. Internationalization. Parameter encoding in MIME headers hasn't 
   yet been implemented. These will be provided in a later release.

3. We've received reports of problems using the JavaMail API in servlets
   driven by Netscape web servers. The error is that the Netscape
   servlet implementation doesn't support the 
   java.awt.datatransfer.Transferable class which is used by the JAF. 
   We recommend that you submit a bug report with Netscape.

4. We've received reports of IMAP authentication failures on the
   Microsoft Exchange Server 5.5, enterprise edition. This is due to
   a bug in the Microsoft server and the "Service Pack 1 for Exchange 
   Server 5.5" apparently fixes this server bug. The service pack can
   be downloaded from the Microsoft website.

5. Due to a problem in the Microsoft Exchange IMAP server, insufficient
   number of bytes may be retrieved when reading big messages. There
   are two ways to workaround this Exchange bug:

   (a) The Exchange IMAP server provides a configuration option called
       "fast message retrieval" to the UI.  Simply go to the site, server
       or recipient, click on the "IMAP4" tab, and one of the check boxes
       is "enable fast message retrieval".  Turn it off and the octet 
       counts will be exact. 

   (b) Set the "mail.imap.partialfetch" property to false. You'll have 
       to set this property in the Properties object that you provide to 
       your Session.

6. Certain IMAP servers do not implement the IMAP Partial FETCH 
   functionality properly. This problem typically manifests as corrupt
   email attachments when downloading large messages from the IMAP 
   server. To workaround this server bug, set the 
	"mail.imap.partialfetch" 
   property to false. You'll have to set this property in the Properties
   object that you provide to your Session.

Servers tested with:
--------------------

  The IMAP implementation works with IMAP4 and IMAP4rev1 servers.
  The current release has been tested with:
	Sun Internet Mail Server version 2.0 and 4.0
	Netscape Messaging Server version 4.0
	UW IMAP4 server version 4.7
	Cyrus IMAP4 server version 1.6.19

  Previous releases have been tested with:
	Sun Internet Mail Server version 2.0 and 3.2
	UW IMAP4rev1 server
	Netscape 3.01 Messaging Server
	beta version of the Netscape 4.0 Messaging Server
	Microsoft Exchange
	Microsoft MCIS Mail Server
	Lotus Notes
	Software.com IMAP server
	Qualcomm Worldmail
	Cyrus IMAP4 server

  The current release of the SMTP implementation has been tested with:
	Sendmail version 8.9.1
	Sun Internet Mail Server version 4.0
	Netscape Messaging Server version 4.0

  Previous releases have been tested with:
	Sendmail 8.6
	Sun Internet Mail Server 3.2
	Netscape 3.01 Messaging Server
	Microsoft Exchange
	Microsoft MCIS Mail Server
	Qualcomm Worldmail

JavaMail API 1.1.3 Y2K compliance
------------------------------

Summary: JavaMail API 1.1.3 is Option-3 compliant.

Sun's JavaMail API implementation uses the java.util.Date class to store
Date objects internally.

Dates can be introduced into the JavaMail API in the following ways:

1) When reading a MIME message from a MIME input stream.

The MimeMessage constructor parses the MIME stream. One of the RFC822
headers is the "Date" field. As per the RFC, this date field must
have 4-digit years.  However, older or non-compliant software may
generate 2-digit years. The JavaMail API follows the recommendations
from the IETF-DRUMS draft (http://www.imc.org/draft-ietf-drums-msg-fmt)
to parse such date strings:
        00 through 49 represents 2000 through 2049;
        50 through 99 represents 1950 through 1999

2) The IMAP provider deals with two kinds of dates:
        Received Date & Sent Date
   The Recieved Date is an IMAP data item (INTERNALDATE) and can
   contain only 4-digit years. The Sent Date is actually the "Date"
   RFC822 header. The IMAP provider follows the logic listed
   in the previous section to parse this header, thus it is
   compliant with the IETF-DRUMS draft.

3) Dates can be set externally by the client when creating a MimeMessage
   using the MimeMessage.setSentDate(java.util.Date) method. The Date
   class is defined in the java.util package; the JavaMail API has nothing
   to do with the interpretation of date strings by the Date class.
   The Y2K compliance of this class is defined by the particular JDK
   implementation. (Note that JDK1.1.6 is Option-3 compliant)

From (1) and (2), we can conclude that Sun's implementation of
the JavaMail API is Option-3 compliant.

For more information on compliance levels, refer:
http://www.sun.com/y2000

JavaMail API 100% Pure Java Certification
-----------------------------------------

Sun's JavaMail API implementation is 100% pure Java. Earlier versions
have been certified by KeyLabs. (See http://java.sun.com/100percent)
This latest release (1.1.3) has not yet been certified 100% pure Java,
but we anticipate that this will be done without any problems.
-------------------------------------------------------------------

How to give feedback
--------------------
	
Please send your feedback to this email-address:

	[e-mail]

Check out our website at http://java.sun.com/products/javamail

You can subscribe to our open discussion-list: 

	[e-mail].

Or you can subscribe to our low-volume mailing-list (where we announce
product updates and other relevant information):

	[e-mail]. 

Instructions on how to subscribe are on our website.


How to submit bug reports
-------------------------

If you've found a bug, or if you just need help figuring out how to use
the JavaMail API, please try to include the following information in
your message to us:

    - a program or code snippet that shows the problem
    - the platform you are using
    - the mail server (vendor name, version number) you are using
    - your environment variable settings
    - a stack trace, if appropriate
    - a protocol trace, after turning on session debugging, if appropriate

Most of the problems reported to us fail to include enough of the above
information to allow us to diagnose your problem.  It will save you and
us time if you include this information in your first message to us.

By far the most common problems we see are:

Your problem:	Something doesn't work right when talking to my mail server.
Our response:	Turn on session debugging and send us the protocol trace.
		See the demo program documentation and/or our FAQ for how
		to turn on session debugging.

Your problem:	javax.mail or javax.activation classes not found when compiling.
Our response:	You didn't set CLASSPATH correctly to find mail.jar and
		activation.jar.  See README.txt.

Your problem:	NoSuchProviderException - No such provider for RFC822.
Our response:	You unjar'ed mail.jar.  Don't.

Your problem:	How do I create a message with an attachment?
Our response:	Create a message with a MimeMultipart content.  See the
		sendfile.html and msgmultisendsample.java demo programs.

Please check the FAQ at http://java.sun.com/products/javamail/FAQ.html
before submitting bug reports.

Send your bug reports to:

	[e-mail]

------------------------------------------------------------------