如何自学JavaMail 1.4.3

解压下载的zip文件得到一个文件夹，在文件夹根目录下的问价结构如下：

首先用写字板打开README.txt。如所有java文档一样，首先介绍jdk版本的问题：

JDK Version notes
-----------------

While JavaMail will work with JAF 1.0.2, we recommend the use of JAF 1.1
or newer.  JAF 1.1.1 is currently the newest version.  Note that JAF 1.1
is included in JDK 1.6 and JAF 1.1.1 is included in JDK 1.6.0_10 and
later.

注：安装jdk1.6的用户可以不用安装JAF，否则需要安装JAF。

Protocols supported
-------------------

The following table lists the names of the supported protocols (as used
in the JavaMail API) and their capabilities:

    Protocol    Store or        Uses    Supports
    Name      Transport?      SSL?    STARTTLS?
    -------------------------------------------------
    imap          Store          No          Yes
    imaps        Store          Yes         Yes
    pop3          Store          No           No
    pop3s        Store          Yes          No
    smtp        Transport       No         Yes
    smtps      Transport       Yes        Yes

注：可以看出smtp需要Transport这个类来进行通信，多组smtp是需要ssl进行验证的，smtp需要tls认证。

Contents
--------

这里是详细描述文件夹目录结构及内容的文件。重要的有如下几个：

NOTES.txt        Notes, issues and known bugs

内容介绍：（这里我只挑重要的说，后面也是如此）

——————————————————————————————————————————————                               

The JavaMail API jar file "mail.jar" includes the full JavaMail API
implementation and *all* the Sun protocol providers - IMAP, SMTP, and
POP3.  The simplest way to use the JavaMail API is to just use the
mail.jar file and ignore the other jar files in this package.

可以只把mail.jar引入到类库就可以进行所有开发。

An important note when using the separate protocol provider jar files:

You can't mix and match the Sun protocol providers between different
releases of the JavaMail API. 

不能用不同版本的api。

SASL Support。此处我并不知道sasl是什么，很简单，去google，只是简单了解下，然后我发现这个词的解释还是不太清楚，没关系，忽略它，只是有个印象就行。

DSN Support。To make use of this support you need to include dsn.jar
in your CLASSPATH along with mail.jar.  See the javadocs for the
com.sun.mail.dsn package for more details.很清楚的给出了要支持DSN就要在lib中加dsn.jar，还有他的使用文档的位置。

How to submit bug reports。介绍了如何提交bug和一些常见的bug的解决。比较重要的如下：

1.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.

2.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.

3.Your problem:Internationalization.  Parameter encoding in MIME headers, as
   specified by RFC2231, *has* been implemented.  Note that
   this covers only certain special cases not covered by the MIME
   specification.  MIME specifies encoding of text in the Subject
   and address headers, and JavaMail fully supports such encoding.
   Most mailers don't support RFC2231.

   Our response:To enable RFC2231 support in parameter lists, set the System
   properties mail.mime.encodeparameters and mail.mime.decodeparameters
   to "true".

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.(这个对我们其实不怎么重要，因为比较流行的邮箱都提供了smtp和pop3，我们不一定要用imap，不过既然和微软沾边我就顺带记下来，到时候来查究行)

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.  This is fully described at
http://support.microsoft.com/default.aspx?scid=kb;EN-US;Q191504

   (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.

How to give feedback。给出了解决问题和反馈的具体方法，如邮件和论坛上。

——————————————————————————————————————————————

SSLNOTES.txt    Notes on using SSL/TLS with JavaMail

内容介绍 ：         Notes for use of SSL with JavaMail（这里我只挑重要的说，后面也是如此）

there are two alternative approaches to enable use of SSL.

First, and perhaps the simplest, is to set a property to enable use
of SSL.  For example, to enable use of SSL for SMTP connections, set
the property "mail.smtp.ssl.enable" to "true".

当我打开这个文档读到此处时，我解决了连接gmail出现“isSSL false”错误信息的问题。

Alternatively, you can configure JavaMail to use one of the SSL-enabled
protocol names.  In addition to the non-SSL JavaMail protocols "imap",
"pop3", and "smtp", the protocols "imaps", "pop3s", and "smtps" can
be used to connect to the corresponding services using an SSL
connection.

读到此处我知道我可以用smtps代替smtp来解决如上问题。我用“props.setProperty("mail.transport.protocol", "smtps");”这段代码代替了原代码，并且没有用第一种方法果然生效了。

-- STARTTLS support

The STARTTLS support is available in the standard "imap" and "smtp"
protocols, but must be enabled by setting the appropriate property,
mail.imap.starttls.enable or mail.smtp.starttls.enable, to "true".
When set, if the server supports the STARTTLS command, it will be
used after making the connection and before sending any login
information.

设置mail.imap.starttls.enable 或者 mail.smtp.starttls.enable为 "true"就可以提供这种支持。

-- Server Identity Check

RFC 2595 specifies addition checks that must be performed on the
server's certificate to ensure that the server you connected to is
the server you intended to connect to.  This reduces the risk of
"man in the middle" attacks.  For compatibility with earlier releases
of JavaMail, these additional checks are disabled by default.  We
strongly recommend that you enable these checks when using SSL.  To
enable these checks, set the "mail. .ssl.checkserveridentity"
property to "true".

主要是减少黑客的攻击。

-- Socket Factories

In earlier releases it was necessary to explicitly set a socket
factory property to enable use of SSL.  In almost all cases, this
is no longer necessary.  SSL support is built in.  However, there
is one case where a special socket factory may be needed.

JavaMail now includes a special SSL socket factory that can simplify
dealing with servers with self-signed certificates.  While the
recommended approach is to include the certificate in your keystore
as described above, the following approach may be simpler in some cases.

The class com.sun.mail.util.MailSSLSocketFactory can be used as a
simple socket factory that allows trusting all hosts or a specific set
of hosts.  For example:

    MailSSLSocketFactory sf = new MailSSLSocketFactory();
    sf.setTrustAllHosts(true);
    // or
    // sf.setTrustedHosts(new String[] { "my-server" });
    props.put("mail.smtp.ssl.enable", "true");
    // also use following for additional safety
    //props.put("mail.smtp.ssl.checkserveridentity", "true");
    props.put("mail.smtp.ssl.socketFactory", sf);

Use of MailSSLSocketFactory avoids the need to add the certificate to
your keystore as described above, or configure your own TrustManager
as described below.

避免添加认证或者配置你自己的可信任管理。（解释可能不到位，不过只要了解下邮箱运营就能了解基本意思）

-- keytool Usage

Given a certificate for the server as used in case #2 above, you can
import this certificate into your Java keystore file using a command
such as:

    keytool -import -alias imap-server -file imap.cer

The keytool command can also be used to generate a self-signed certificate
that can be used by your mail server, if you're setting up your own server.
Other utilities, such as those included with the OpenSSL package, can also
be used to generate such certificates, and they can be imported into the
Java keystore using keytool.

-- Configuring Your Own Trust Manager

When using SSL/TLS, it's important to ensure that the server you connect
to is actually the server you expected to connect to, to prevent "man in
the middle" attacks on your communication.  The recommended technique is
to configure the Java keystore using one of the methods described above.
If, for some reason, that approach is not workable, it's also possible
to configure the SSL/TLS implementation to use your own TrustManager
class to evaluate whether to trust the server you've connected to.

The following "dummy" classes illustrate the framework necessary to create
your own TrustManager implementation.

First, a replacement for the standard SSLSocketFactory is needed, to allow
you to specify which TrustManager to use:

==> DummySSLSocketFactory.java <==

import java.io.IOException;
import java.net.InetAddress;
import java.net.Socket;

import javax.net.SocketFactory;
import javax.net.ssl.*;

/**
* DummySSLSocketFactory
*/
public class DummySSLSocketFactory extends SSLSocketFactory {
    private SSLSocketFactory factory;

    public DummySSLSocketFactory() {
    try {
        SSLContext sslcontext = SSLContext.getInstance("TLS");
        sslcontext.init(null,
                 new TrustManager[] { new DummyTrustManager()},
                 null);
        factory = (SSLSocketFactory)sslcontext.getSocketFactory();
    } catch(Exception ex) {
        // ignore
    }
    }

    public static SocketFactory getDefault() {
    return new DummySSLSocketFactory();
    }

    public Socket createSocket() throws IOException {
    return factory.createSocket();
    }

    public Socket createSocket(Socket socket, String s, int i, boolean flag)
                throws IOException {
    return factory.createSocket(socket, s, i, flag);
    }

    public Socket createSocket(InetAddress inaddr, int i,
                InetAddress inaddr1, int j) throws IOException {
    return factory.createSocket(inaddr, i, inaddr1, j);
    }

    public Socket createSocket(InetAddress inaddr, int i)
                throws IOException {
    return factory.createSocket(inaddr, i);
    }

    public Socket createSocket(String s, int i, InetAddress inaddr, int j)
                throws IOException {
    return factory.createSocket(s, i, inaddr, j);
    }

    public Socket createSocket(String s, int i) throws IOException {
    return factory.createSocket(s, i);
    }

    public String[] getDefaultCipherSuites() {
    return factory.getDefaultCipherSuites();
    }

    public String[] getSupportedCipherSuites() {
    return factory.getSupportedCipherSuites();
    }
}

Next you need the actual implementation of the TrustManager.  This dummy
trust manager trusts anything.  THIS IS NOT SECURE!!!

==> DummyTrustManager.java <==

import javax.net.ssl.X509TrustManager;
import java.security.cert.X509Certificate;

/**
* DummyTrustManager - NOT SECURE
*/
public class DummyTrustManager implements X509TrustManager {

    public void checkClientTrusted(X509Certificate[] cert, String authType) {
    // everything is trusted
    }

    public void checkServerTrusted(X509Certificate[] cert, String authType) {
    // everything is trusted
    }

    public X509Certificate[] getAcceptedIssuers() {
    return new X509Certificate[0];
    }
}

Finally, you need to configure JavaMail to use your SSLSocketFactory.
Set the appropriate protocol-specific property, e.g.,

    props.setProperty("mail.imap.ssl.enable", "true");
    props.setProperty("mail.imap.ssl.socketFactory.class",
                    "DummySSLSocketFactory");
    props.setProperty("mail.imap.ssl.socketFactory.fallback", "false");
    Session session = Session.getInstance(props, null);

Similar properties would need to be set to use other protocols.

教你如何添加自己的可信任管理，其实就是处理那些垃圾邮件。

——————————————————————————————————————————————

NTLMNOTES.txt 有关ntlm的相关内容（基本上用不到）。  

——————————————————————————————————————————————

javamail-1.4.3/docs/JavaMail-1.4.pdf详细介绍了各种指令，还有properties的各种值的介绍。demo是其中例子的代码。

——————————————————————————————————————————————

javamail-1.4.3/docs/javadocs/index.html是javamail api的起始页，方法可以去那里找。

——————————————————————————————————————————————

现在我们通过阅读readme.txt知道我们最终要阅读 JavaMail-1.4.pdf来了解编程。当我们读完pdf后，我们就可以自如的编写javamail了。