diff --git a/.github/workflows/maven.yml b/.github/workflows/maven.yml index 7932af22..77a33121 100644 --- a/.github/workflows/maven.yml +++ b/.github/workflows/maven.yml @@ -14,7 +14,13 @@ name: Jakarta Mail API CI on: pull_request: + paths: + - '!doc/**' + - '!www/**' push: + paths: + - '!doc/**' + - '!www/**' jobs: build: @@ -23,7 +29,7 @@ jobs: strategy: matrix: - java_version: [ 11, 17-ea ] + java_version: [ 11, 17 ] steps: - name: Checkout for build diff --git a/.github/workflows/web.yml b/.github/workflows/web.yml new file mode 100644 index 00000000..327f0fd4 --- /dev/null +++ b/.github/workflows/web.yml @@ -0,0 +1,74 @@ +# +# Copyright (c) 2022 Contributors to the Eclipse Foundation +# +# This program and the accompanying materials are made available under the +# terms of the Eclipse Public License v. 2.0 which is available at +# http://www.eclipse.org/legal/epl-2.0, +# or the Eclipse Distribution License v. 1.0 which is available at +# http://www.eclipse.org/org/documents/edl-v10.php. +# +# SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause +# + +name: Update web site + +on: + # Runs on pushes targeting the default branch + push: + branches: ["master"] + paths: + - 'doc/**' + - 'www/**' + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + - name: Add static content + run: | + export VERSION=`curl -s https://repo1.maven.org/maven2/jakarta/mail/jakarta.mail-api/maven-metadata.xml | tac | grep -o -m 1 "[[:digit:]]\.[[:digit:]]\.[[:digit:]]" | cut -f 1 -d "<"` + echo Getting javadoc for version: $VERSION + rm -rf ./www/docs/api || true + wget -q -O jakarta.mail-api-javadoc.zip https://repo1.maven.org/maven2/jakarta/mail/jakarta.mail-api/$VERSION/jakarta.mail-api-$VERSION-javadoc.jar + mkdir -p ./www/docs/api + unzip -q -d ./www/docs/api jakarta.mail-api-javadoc.zip -x "META-INF/*" + cp -Rfv doc/spec/* doc/release/* ./www/docs/ + cp -Rfv CONTRIBUTING.md ./www/ + - name: Setup Pages + uses: actions/configure-pages@v2 + - name: Build with Jekyll + uses: actions/jekyll-build-pages@v1 + with: + source: ./www/ + destination: ./_site + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v1 diff --git a/.gitignore b/.gitignore index 6ce558bc..f2246727 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,12 @@ webrev .project .settings/ *.iml + +_site +www/CONTRIBUTING.md +www/docs/api +www/docs/CHANGES.txt +www/vendor +www/.sass-cache +www/.jekyll-cache +www/.jekyll-metadata diff --git a/README.md b/README.md index 6deca00a..6bf8792b 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,8 @@ framework to build mail and messaging applications. **IMPORTANT:** The implementation of the Jakarta Mail API, aka JakartaMail (formerly JavaMail), is no longer part of this repository. As part of breaking tight integration between Jakarta Mail API and the implementation, -its sources were moved to the new project - [Eclipse Angus](https://github.com/eclipse-ee4j/angus-mail) - -and further development continues there. [Eclipse Angus](https://github.com/eclipse-ee4j/angus-mail) +its sources were moved to the new project - [Eclipse Angus](https://eclipse-ee4j.github.io/angus-mail) - +and further development continues there. [Eclipse Angus](https://eclipse-ee4j.github.io/angus-mail) is the direct successor of JavaMail/JakartaMail. See the [Jakarta Mail web site](https://jakartaee.github.io/mail-api/). @@ -42,4 +42,5 @@ the terms of [Eclipse Contributor Agreement](http://www.eclipse.org/legal/ECA.ph * [Jakarta Mail Specification project](https://github.com/jakartaee/mail-spec) * [Jakarta Mail TCK project](https://github.com/jakartaee/mail-tck) * [Jakarta Mail API nightly build job](https://ci.eclipse.org/mail/job/mail-api-build/) -* [Eclipse Angus project](https://github.com/eclipse-ee4j/angus-mail) +* [Mailing list](https://accounts.eclipse.org/mailing-list/mail-dev) +* [Eclipse Angus project](https://eclipse-ee4j.github.io/angus-mail) diff --git a/www/Android.md b/www/Android.md new file mode 100644 index 00000000..fd4e46aa --- /dev/null +++ b/www/Android.md @@ -0,0 +1,54 @@ +Jakarta Mail for Android +======================== + +Jakarta Mail for Android is now available! + +As of Jakarta Mail 2.0.0, standard Jakarta Mail distribution can run on Android. + +This version is available from the maven central repository. +You can try out this version by adding the following to your +build.gradle file for your Android application: + + android { + packagingOptions { + pickFirst 'META-INF/LICENSE.md' // picks the Jakarta Mail license file + pickFirst 'META-INF/NOTICE.md' // picks the Jakarta Mail notice file + } + } + + dependencies { + // use whatever the current 2.x version is... + compile 'com.sun.mail:jakarta.mail:2.0.0' + compile 'com.sun.activation:jakarta.activation:2.0.0' + } + +Previous versions of Jakarta Mail, ie 1.6.5, do not run on Android `as is`, therefore, +a special version of Jakarta Mail is available. This special version of Jakarta +Mail depends on a special version of Jakarta Activation. + + android { + packagingOptions { + pickFirst 'META-INF/LICENSE.md' // picks the Jakarta Mail license file + pickFirst 'META-INF/NOTICE.md' // picks the Jakarta Mail notice file + } + } + + dependencies { + // use whatever the current 1.x version is... + compile 'com.sun.mail:android-mail:1.6.5' + compile 'com.sun.mail:android-activation:1.6.5' + } + +One of the standard Java features not supported on Android is SASL. That means +none of the "mail._protocol_.sasl.*" properties will have any effect. One of +the main uses of SASL was to enable OAuth2 support. The latest version +of Jakarta Mail includes built-in OAuth2 support that doesn't require SASL. +See the [OAuth2](OAuth2) page for more details. + +Jakarta Mail for Android requires at least Android API level 19, +which corresponds to +[Android KitKat](https://en.wikipedia.org/wiki/Android_version_history#Android_4.4_KitKat_.28API_19.29), +currently the oldest supported version of Android. + +If you discover problems, please report them to +[mail-dev@eclipse.org](https://accounts.eclipse.org/mailing-list/mail-dev). diff --git a/www/Books.md b/www/Books.md new file mode 100644 index 00000000..e58693ed --- /dev/null +++ b/www/Books.md @@ -0,0 +1,46 @@ +# Books on the Jakarta Mail API and Internet Mail + +You might find these books useful. +If you know of other books we should list, please let us know at +mai-dev@eclipse.org. + +* + JavaMail API, by Elliotte Rusty Harold. + +* + Internet Email, by David Wood. + +* + Programmer's Guide to Internet Mail, by John Rhoton. + +* + Internet Email Protocols: A Developer's Guide, by Kevin Johnson. + +* + Java Network Programming, 2nd Edition, by Elliotte Rusty Harold. + +* + Essential Email Standards: RFCs and Protocols Made Practical, + by Pete Loshin. + +* + Internet Messaging: From the Desktop to the Enterprise, + by Marshall T. Rose and David Strom. + +* + Internet E-Mail: Protocols, Standards, & Implementation, + by Lawrence Hughes. + +* + Managing IMAP, by Dianna Mullet and Kevin Mullet. + +* + Professional Java Server Programming J2EE Edition. + +* + Java Cookbook: Solutions and Examples for Java Developers, + by Ian F. Darwin. + +* + JavaServer Pages (JSP) Fast & Easy Web Development, + by Aneesha Bakharia. diff --git a/www/Build-Instructions.md b/www/Build-Instructions.md new file mode 100644 index 00000000..b57e1f44 --- /dev/null +++ b/www/Build-Instructions.md @@ -0,0 +1,27 @@ +Jakarta Mail Build Instructions +=============================== + +To download the most recent Jakarta Mail source code you'll need +[git](https://git-scm.com/downloads). + +Once you've installed git, the following command will check out a copy +of the source code: + + % git clone git@github.com:eclipse-ee4j/mail.git + +Or, to check out the version corresponding to a particular release, use +a tag. For example, to check out the 1.6.4 version: + + % git clone -b 1.6.4 git@github.com:eclipse-ee4j/mail.git + +To build Jakarta Mail you'll need [Maven](http://maven.apache.org/). + +To simply build everything, use: + + % cd mail + % mvn install + +You'll find the jakarta.mail.jar file in mail/target/jakarta.mail.jar. + +See [Workspace Structure](Workspace-Structure) for a description of the +workspace. diff --git a/www/Contributions.md b/www/Contributions.md new file mode 100644 index 00000000..0fb45c06 --- /dev/null +++ b/www/Contributions.md @@ -0,0 +1,86 @@ +How to Contribute to Jakarta Mail +================================= + +If you're interested in contributing fixes, enhancements, etc. to +Jakarta Mail, please contact us at [mail-dev@eclipse.org](https://accounts.eclipse.org/mailing-list/mail-dev) +before you start. We can give you advice you might need to make it easier to +contribute, and we can better coordinate contributions with other +planned or ongoing work on Jakarta Mail. + +Contributions to Jakarta Mail follow the same rules and process as +contributions to other Eclipse projects. + +See [CONTRIBUTING](CONTRIBUTING.md) for the legal details. + +## Coding Style + +Modifications to existing Jakarta Mail source files, and contributions of +new source files, should use the standard Java coding style as +originally described +[here](http://www.oracle.com/technetwork/java/codeconvtoc-136057.html) +and unofficially updated +[here](http://cr.openjdk.java.net/~alundblad/styleguide/index-v6.html). +The most important points are summarized below: + +- Indentation should be in units of 4 spaces, preferably with every 8 + spaces replaced with a tab character. (If using vi, set tabstop=8, + not 4.) + +- Braces should be at the end of the line they apply to, rather than + all alone at the beginning of the next line, i.e., + +```java + if (foo instanceof bar) { + foobar(); + barfoo(); + } +``` + +- Methods should have doc comments of the form: + +```java + \/** + \* comments here + \*/ +``` + +- All keywords should have a space after them, before any paren + (e.g., "if (", "while (", "for (", etc.) + +- The "comment to end of line" characters (//) should be followed by a space. + +- The start of a multiline comment (/\* or /\*\*) should be alone on a line. + +- No space after left paren or before right paren (e.g., "foo(x)", + not "foo( x )") + +- There should be no whitespace characters after the last printing + characters on a line. + +- In method signatures, start with the access-control keyword, then + the return-type, i.e., + +```java + public int foobar() { + ... + } +``` + +- When in doubt, copy the style used in existing Jakarta Mail code. + +* * * * * + +If using vi, try the following: + +1. Either set up your EXINIT variable or a $HOME/.exrc file with: + 
+    set autoindent
+    set tabstop=8
+    set shiftwidth=4
+
+2. Use Ctrl-t to indent forward one level +3. Use Ctrl-d to indent backwards one level +4. To indent a range like 10 lines starting at the current line use "10\>\>" +5. To indent backwards use "\<\<" instead of "\>\>" + +Using the actual tab key and spacing over will work, but it slows you down. diff --git a/www/Exchange.md b/www/Exchange.md new file mode 100644 index 00000000..e92d8774 --- /dev/null +++ b/www/Exchange.md @@ -0,0 +1,101 @@ +Microsoft Exchange and Office 365 +================================= + +*This page should have a lot more information about Exchange. For now +it's just a collection of notes.* + +My understanding is that Office 365 (and Exchange Online) is largely +just a version of Exchange hosted by Microsoft. Many of the issues +listed here that apply to newer versions of Exchange may also apply to +Office 365 and vice versa. + +Exchange +-------- + +Exchange 2016 returns incorrect BODYSTRUCTURE data for an S/MIME +encrypted message. Use the workaround described in the +[Jakarta Mail FAQ](FAQ.html#imapserverbug). + +Exchange fails to find an email address using FromTerm, FromStringTerm, +RecipientTerm, or RecipientStringTerm. As described in +(this blog entry)[https://blogs.technet.microsoft.com/dkhrebin/2013/10/04/how-exchange-imap-search-in-message-header/], +Exchange will only find a personal name using these search terms. +Instead, use a HeaderTerm to search for the email address. + +Exchange 2010 has a bug where it returns NIL instead of "" for empty +parameter values, causing a NullPointerException. A +[workaround](https://github.com/eclipse-ee4j/javamail/issues/203) +was added to JavaMail 1.5.5. + +Searching for an address in Exchange 2010 matches only the "personal +name" field of the address, not the email address itself. (Reported +12/8/2015) + +Exchange 365 returns an incorrect BODYSTRUCTURE response for single +part messages, failing to include the message disposition value in +parentheses as required by the IMAP spec. See +[this bug report](https://github.com/eclipse-ee4j/javamail/issues/31). +This causes a MessagingException with the message "Unable to load +BODYSTRUCTURE". Use the workaround described in the +[Jakarta Mail FAQ](FAQ.html#imapserverbug). + +Exchange 2010 has a bug where it fails to quote the encoding value in a +BODYSTRUCTURE response. This causes a MessagingException with the +message "Unable to load BODYSTRUCTURE". As of 1/10/2011, a customer +reported that Microsoft expects to fix this bug in "Roll Up 3" for +Exchange 2010. JavaMail 1.4.4 includes a workaround for this Exchange +bug. + +Exchange 2007 has a bug where it returns "-1" as the size of a +multipart/signed body part (at least) in the BODYSTRUCTURE response.. +This causes a MessagingException with the message "Unable to load +BODYSTRUCTURE". Use the workaround described in the +[Jakarta Mail FAQ](FAQ.html#imapserverbug). + +Exchange 2007 has a bug where it advertises that it supports +AUTH=PLAIN, even though +[this Exchange documentation](http://technet.microsoft.com/en-us/library/cc540463.aspx) +claims that it's not supported. This causes Jakarta Mail to choose PLAIN +authentication, which will always fail. To work around this Exchange +bug, set the session property "mail.imap.auth.plain.disable" to "true". +(Change "imap" to "imaps" if you're using the "imaps" protocol.) + +On Aug 6, 2012, a customer reported that Exchange 2010 has a similar +problem where both PLAIN and NTLM authentication fail for shared +mailboxes (with user names of the form user1@domain.com/sharedMB), even +though they work for regular user mailboxes. Disabling all +authentication types and falling back to IMAP LOGIN support seemed to +work. + +Exchange 2007 through SP3 has a +[bug](https://github.com/eclipse-ee4j/javamail/issues/86) +where, at least in some circumstances, it will report a message as a +result of an IMAP SEARCH command that it had not previously notified +the client of via an EXISTS response, causing an exception such as +"java.lang.ArrayIndexOutOfBoundsException: message number (1) out of +bounds (0)" from the Folder.search() method. A workaround for this bug +was included in JavaMail 1.5.1. (Reported by a user on 6/18/2012) + +To access a shared mailbox in Exchange, you need to login using the +"alias" name and password for the shared mailbox, which you can get +from your Exchange server administrator. +[This article](http://social.technet.microsoft.com/Forums/bg-BG/exchangesvrgeneral/thread/8c8b4605-efae-49eb-a118-54aa418de6c2) +has more information. + +Here's another article that discusses +[the use of shared mailboxes with Exchange 2013/2016](https://ingogegenwarth.wordpress.com/2016/04/11/exchange-20132016-imapews-and-service-accounts/). + +In Exchange 2007 Microsoft removed the ability to access public +folders, and they have no plans to restore it. + +Office 365 +---------- + +To access a shared mailbox using Office 365, see +[this article](https://social.technet.microsoft.com/Forums/msonline/en-US/6369118f-7dee-4728-ac1c-a0c706b3d290/office-365-exchange-online-how-to-access-a-shared-mailbox-using-thunderbird-or-other-imap-client?forum=onlineservicesexchange). + +In some cases, +[Office 365 will accept a bad password for a correct user name](http://unix.stackexchange.com/questions/164823/user-is-authenticated-but-not-connected-after-changing-my-exchange-password) +and then later return the error "BAD User is authenticated but not +connected" for subsequent IMAP commands, resulting in a +MessagingException. diff --git a/www/FAQ.html b/www/FAQ.html new file mode 100644 index 00000000..3a3706bd --- /dev/null +++ b/www/FAQ.html @@ -0,0 +1,3509 @@ +--- +layout: default +title: Jakarta Mail FAQ +--- +

Jakarta Mail FAQ

+ + + +

General

+ +
+
+

Installation and Configuration

+ +
+
+

Programming

+ +
+
+

Debugging

+ +
+
+

Reading mail, IMAP

+ +
+
+

Sending mail, SMTP

+ +
+
+

POP3

+ +
+
+

Jakarta Mail in servlets

+ +
+
+

Jakarta Mail in applets

+ + +

+ +
+ +

+
+
+

General

+
+
+

+ +Q: What is the Jakarta Mail API?
+A: The Jakarta Mail API is a set of +abstract APIs that model a mail system. +(Jakarta Mail was previously known as JavaMail.) +The API provides a platform independent and protocol independent framework +to build Java technology based email client applications. +The Jakarta Mail API provides facilities for reading and sending email. +Service providers implement particular protocols. +Several service providers are included with the Jakarta Mail API package; +others are available separately. +The Jakarta Mail API is implemented as a Java optional package that can be +used on JDK 1.4 and later on any operating system. +The Jakarta Mail API is also a required part of the +Jakarta EE Platform and the + +Java Platform, +Enterprise Edition (Java EE). +

+ +

+ +Q: How do I get an implementation of the Jakarta Mail API?
+A: Eclipse provides an open source +implementation that developers may use and ship. +The implementation +includes the core Jakarta Mail packages and IMAP, POP3, and SMTP service providers. +The implementation may be downloaded +here. +

+ +

+ +Q: How do I send feedback or comments? +
+A: Send email to +mail-dev@eclipse.org. +

+ +

+ +Q: Where is javax.activation?
+A: javax.activation is part of the + +JavaBeans Activation Framework (JAF) +and is included in Java SE 6 through Java SE 10. +The Jakarta Mail API uses JAF for data content handling. +

+ +

+ +Q: What JDK does the Jakarta Mail API need?
+A: The Jakarta Mail API requires JDK/JRE 1.7 or higher. +The Jakarta Mail API is a Java +optional package, it is not part of the core +Java SE +but is included in +Java EE +and +Jakarta EE. +

+ +

+ +Q: Where can I find a version of Jakarta Mail for my favorite +operating system? +
+A: Jakarta Mail is completely written in Java and will run on +any operating system that supports the required version of the JDK. +No special version is needed for different operating systems. +

+ +

+ +Q: Do the Jakarta Mail APIs work in web browsers?
+A: Jakarta Mail will work in any browser that supports the +required JDK version. +The +Java Plug-in may be required to provide such support. +

+ +

+ +Q: Can I use Jakarta Mail to read mail from my web mail account +(such as Yahoo or Hotmail)? + +
+A: It depends. Many web-based email services provide access only +using a browser with HTTP. These services cannot be accessed using Jakarta Mail. +If the service also provides POP3 or IMAP access, Jakarta Mail can probably +be used to access it. +Contact your web email service provider for details. +Another helpful tool is MrPostman, a proxy server that provides POP3 access +to Hotmail and Yahoo! Mail, available at +http://sourceforge.net/projects/mrpostman/ +

+ +

+ +Q: What is IMAP?
+A: IMAP stands for Internet Message Access Protocol. It is a +method of accessing electronic mail messages stored on a (possibly shared) +mail server. In other words, it permits a "client" email program to +access remote message stores as if they were local. IMAP is defined +by RFC2060. +

+ +

+ +Q: What is SMTP?
+A: SMTP stands for Simple Mail Transfer Protocol. It is used +to transfer RFC822-style messages between different mail hosts as +well as to submit new messages to a host for delivery. SMTP is in +very wide use (it originated in 1982) and is defined by +RFC821. +

+ +

+ +Q: What is MIME?
+A: MIME and +RFC822 +are the standards for describing email +messages that are sent across the Internet. The javax.mail.internet +subpackage (which is part of the Jakarta Mail APIs) provides a complete +implementation of these two packages. MIME is specified by the +following RFCs: RFC2045, +RFC2046, +RFC2047. +

+ +

+ +Q: What is POP3?
+A: POP3 stands for Post Office Protocol version 3. +POP3 is a very limited protocol for accessing a single mailbox. +It is much less capable than IMAP. +POP3 is very widely used and is defined by +RFC1939. +

+ +

+ +Q: What about support for MAPI, NNTP, Lotus Notes, +and other service providers?
+A: We have no current plans to implement any of these +providers. However, the architecture of the Jakarta Mail APIs provides +for being able to easily plug-in third-party service providers. It is +our hope that third-parties will embrace the Jakarta Mail APIs by writing +providers for other standard and proprietary protocols. +See our Third Party Products page +for the latest list of such providers. +

+ +

+ +Q: How do I store mail messages on my local disk? +
+A: A "local store provider" can be used to store mail messages +on a local disk. The Jakarta Mail API download does not include such a provider +but a provider that supports the Unix mbox format is available in the Jakarta Mail +source repository that you can build yourself. See +this page +for details. +In addition, several local store providers are available from third parties +for different local store formats such as MH and Mbox. +See our Third Party Products page +for the latest list of such providers. +

+ +

+ +Q: Where do I find documentation on the protocol providers? +
+A: The protocol providers for IMAP, POP3, and SMTP support +many features that are not part of the Jakarta Mail API specification. The +documentation for these protocol providers is included in the Jakarta Mail +javadocs. The package level documentation for each protocol provider +package describes the properties that are supported by the protocol +proivder. In addition, the protocol providers include some classes and +methods that applications can use to take advantage of +provider-specific features. Note that use of these properties, +classes, and methods renders a program non-portable; it may +only work with Oracle's implementation of the Jakarta Mail API. +See the +IMAP, +POP3, and +SMTP package +javadocs for details. +

+ +

+ +Q: Is the Jakarta Mail API implementation completely free? +Can I ship it along with my product?
+A: Yes. The Jakarta Mail API implementation +is completely free and open source and you can include it in your product. +This release includes IMAP, POP3, and SMTP providers as well. Please do +read the license and ensure that you understand it. +The Jakarta Mail license is described +here. +

+ +

+ +Q: Can I get the source code for the Jakarta Mail API +implementation? +
+A: Starting with Jakarta Mail 1.4.2, the source code for the +Jakarta Mail API +Reference Implementation is available under the CDDL or GPL open source licenses +in the Jakarta Mail project. +

+ +

+ +Q: Is Jakarta Mail Y2K compliant?
+A: Yes. Oracle's Jakarta Mail implementation is Option-3 Y2K compliant. Please +see the NOTES.txt +file in the Jakarta Mail package for more information. +

+ +

+ +Q: The answer to my question isn't here, where else should I look? + +
+A: In addition to the Jakarta Mail API spec and javadocs +(available from +our main web page), +don't forget to check the +README.txt and +NOTES.txt files +for additional important information. +

+

+You can reach the Jakarta Mail team directly at +mail-dev@eclipse.org. +You can use this address to report bugs. +Bugs can also be reported using the Issue Tracker at the +Jakarta Mail project. +

+

+The Oracle Technology Network maintains a Jakarta Mail forum, see the + +Jakarta Mail Forum. +

+

+jGuru also maintains a Jakarta Mail FAQ, which you'll find at + +http://www.jguru.com/faq/Jakarta Mail, +although it hasn't been updated in several years. +

+ +
+
+

Installation and Configuration

+
+
+ +

+ +Q: How do I install the Jakarta Mail API implementation? +
+A: Download the +[Jakarta Mail jar file](https://github.com/eclipse-ee4j/mail/releases/download/1.6.4/jakarta.mail.jar) +and edit your CLASSPATH environment variable to include the jakarta.mail.jar file. +You will also need an implementation of the +JavaBeans Activation Framework (see below) unless you're using JDK 1.6 +through JDK 10 (which includes JAF). +See the README.txt file +for additional details and examples, +as well as the following FAQ entry. +

+ +

+ +Q: I get a ClassNotFoundException when I run my program. +
+A: You haven't set CLASSPATH properly. See + +Setting the class path (Windows) or + +Setting the class path (Solaris/Linux) in the JDK documentation. +Note that if you're running your program using "java -jar", the CLASSPATH +environment variable setting is ignored. In that case you'll need to +add the "-classpath" argument to the java command, or add the +Class-Path header to the manifest file of your jar file. +See the +Java Tutorial +and this +Wikipedia article +for more information. +

+ +

+ +Q: I get a ClassNotFoundException for a javax.activation class +when I run my program on JDK 9 or 10. +[new!] +
+A: JDK 9 and 10 hide many of the javax.* classes by default. +You need to use the java command line option +--add-modules java.activation +to enable access the the javax.activation (JAF) classes. +(Note that there's no "x" in the module name.) +Or, you need to include the +jakarta.activation.jar +file in your CLASSPATH. +

+ +

+ +Q: How do I set my CLASSPATH on Windows? + +
+A: Detailed instructions are available +here +

+ +

+ +Q: How do I add the Jakarta Mail library to my NetBeans Java Project? + +
+A: +Use the Library Manager to create a library and add a reference to that library +to your project. +

    +
  1. Inside Netbeans, open the Library Manager (Tools > Libraries from the + main menu bar).
    2. +
  2. Select <New Library...>
    3. +
  3. Enter a library name, e.g., "Jakarta Mail", and hit <OK>. Do not + check server library.
    4. +
  4. Make sure the new library is selected under "Libraries" on the left.
    5. +
  5. Select the "Classpath" tab on the right and choose + <Add Jar/Folder...>
    6. +
  6. Using the file browser, select the jakarta.mail.jar that you downloaded, + and hit <Add Jar/Folder> to accept.
    7. +
  7. Select the "Javadoc" tab and choose <Add ZIP/Folder...>
    8. +
  8. Using the file browser, select the folder where the Jakarta Mail javadoc + index files are, and hit <Add ZIP/Folder> to accept.
    9. +
  9. If you downloaded the Jakarta Mail source code, you + can set the source code reference on the "Sources" tab. This can be helpful + for debugging. Using the file browser, select the source root for the + Jakarta Mail sources and hit <Add Jar/Folder> to accept.
    10. +
+

+

+Note: If you are using JDK 1.5.0 or earlier you will need to add the + +JavaBeans Activation Framework +library as well. You can create a separate library in a manner similar to +the above, or just add activation.jar (and javadoc/source references +if desired) to this library definition. +

+

Now add a reference to this library to your project. +

+
    +
  1. Open your project in NetBeans and make sure the "Projects" tab is + visible.
    2. +
  2. Right click your project in the project explorer and select + "Properties"
    3. +
  3. In the Properties dialog, select "Libraries" in the tree on the left + and make sure the "Compile" tab is selected.
    4. +
  4. Click <Add Library...>
    5. +
  5. Locate and select the library you created above and + click "Add Library". It should be added to the list of compile-time + libraries.
    6. +
  6. Click "OK" and you're done.
    7. +
+

+ +

+ +Q: How do I add the Jakarta Mail library to my Eclipse Java Project? + +
+A: +Create a "user library" for Jakarta Mail and add a reference to that library to +your project. +

    +
  1. From the Eclipse main menu, open Window > Preferences
    2. +
  2. Open the tree to Java > Build Path > User Libraries and select + the <User Libraries> node.
    3. +
  3. Choose <New...> from the panel on the right
    4. +
  4. In the new library dialog, enter a user library name, e.g. "Jakarta Mail", + and hit <OK>. Do not check system library.
    5. +
  5. Make sure the new library is selected and choose <Add Jars...>
    6. +
  6. Browse to where Jakarta Mail is installed and select jakarta.mail.jar
    7. +
  7. Select <Javadoc location: (None)> and hit <Edit...> to + add a reference to the javadoc location. This can be found at docs/javadocs + under the same folder where you installed Jakarta Mail.
    8. +
  8. You can also set the source code reference here if you downloaded the + Jakarta Mail source code. Use + ".../jakartamail-1.6.4/mail/src/main/java" as the source root for 1.6.4.
    9. +
  9. Choose <OK> to close the Preferences dialog. Jakarta Mail is now + installed as a Library in Eclipse.
    10. +
+

+

+Note: If you are using JDK 1.5.0 or earlier you will need to add the + +JavaBeans Activation Framework +library as well. You can create a separate library in a manner similar to +the above, or just add activation.jar (and javadoc/source references +if desired) to this library definition. +

+

Now use the Jakarta Mail library in your Eclipse Java Project (Eclipse 3.4) +

+
    +
  1. Open your project in Eclipse and be in the Java Perspective
    2. +
  2. Right click your project in the project explorer and select + "Build Path > Configure Build Path..."
    3. +
  3. In the Properties dialog that opens, ensure Java Build Path is selected + in the tree on the left and select the Libraries tab on the right
    4. +
  4. Click <Add Library...>
    5. +
  5. Select "User Library", then click <Next>
    6. +
  6. Locate and select the Jakarta Mail library added in the previous step, + click "Finish", and you're done.
    7. +
+

+

+ +This article +explains how to make the Jakarta Mail source code available to your Eclipse project. +

+ +

+ +Q: Does Jakarta Mail include all the necessary mail servers? +
+A: No, the Jakarta Mail API package does not include any mail servers. +To use the Jakarta Mail API package, you'll need to have access to an IMAP +or POP3 mail server (for reading mail) and/or an SMTP mail server (for +sending mail). +These mail servers are usually provided by your Internet Service Provider +or are a part of your organization's networking infrastructure. +If you don't have access to such a mail server, see below. +

+ +

+ +Q: Where can I get the necessary mail servers? +
+A: +The University of Washington IMAP server supports multiple platforms +(UNIX, Windows 32bit, etc). +Get the source code from +http://www.washington.edu/imap/. +There are several free, all Java mail servers available, including +Apache James and +Java Email Server. +Sendmail is a popular (non-Java) SMTP server. +SubEthaSMTP +is a Java library for implementing SMTP server functionality; +their web page also references other mail servers. +Many other vendors provide mail servers supporting Internet standards. +There are also many free, public mail servers that support the required +mail protocols such as Gmail, Yahoo! Mail, Hotmail, etc. +

+ +

+ +Q: What host name, user name, or password should I use? +
+A: We do not provide a mail server for you to use. You must use your +own mail server, or one provided by your Internet Service Provider +or the company you work for. Your network administrator can give you +the information necessary to configure Jakarta Mail to work with your mail server. +

+ +

+ +Q: How do I configure Jakarta Mail to work through my proxy server? +[updated!] +
+A: Starting with Jakarta Mail 1.6.0, Jakarta Mail supports accessing +mail servers through a web proxy server. +Set the "mail.protocol.proxy.host" and "mail.protocol.proxy.port" +properties for the proxy server. +Proxy server BASIC authentication is supported by setting the +"mail.protocol.proxy.user" and "mail.protocol.proxy.password" +properties. +

+

+In addition, if your proxy server supports the SOCKS V4 or V5 protocol +(http://www.socks.nec.com/aboutsocks.html, +RFC1928) +and allows anonymous connections, and +you're using JDK 1.5 or newer and Jakarta Mail 1.4.5 or newer, you can +configure a SOCKS proxy on a per-session, per-protocol basis by setting the +"mail.smtp.socks.host" property as described in the javadocs for the + +com.sun.mail.smtp package. +Similar properties exist for the "imap" and "pop3" protocols. +Authentication for SOCKS servers is supported by the JDK by setting the +"java.net.socks.username" and "java.net.socks.password" System properties +(and thus apply to all SOCKS connections) as describe in the +JDK Networking Properties documentation. +

+

+If you're using older versions of the JDK or Jakarta Mail, you can tell the Java +runtime to direct all TCP socket connections to the SOCKS server. +See the +Networking Properties guide +for the latest documentation of the socksProxyHost and +socksProxyPort properties. These are system-level properties, +not Jakarta Mail session properties. They can be set from the command line +when the application is invoked, for example: +java -DsocksProxyHost=myproxy .... +This facility can be used to direct the SMTP, IMAP, and POP3 +communication from Jakarta Mail to the SOCKS proxy server. Note that +setting these properties directs all TCP sockets to the SOCKS +proxy, which may have negative impact on other aspects of your +application. +

+

+When using older versions of Jakarta Mail, and without such a SOCKS server, +if you want to use Jakarta Mail to access mail servers +outside the firewall indirectly, you might be able to use a program such as +connect +to tunnel TCP connections through an HTTP proxy server. +Configure Jakarta Mail to use the connect instance as the SOCKS server. +

+ +

+ +Q: When connecting to my mail server over SSL I get an exception like +"unable to find valid certification path to requested target". + +
+A: +The full exception might look like: +javax.net.ssl.SSLHandshakeException: +sun.security.validator.ValidatorException: PKIX path building failed: +sun.security.provider.certpath.SunCertPathBuilderException: +unable to find valid certification path to requested target. +Your server is probably using a test certificate or self-signed +certificate instead of a certificate signed by a commercial Certificate +Authority. +You'll need to install the server's certificate into your trust store. +The +InstallCert program will help. +A + +newer version of InstallCert is available here. +

+

+Alternatively, you can set the "mail.protocol.ssl.trust" property +to the host name of your mail server. See the javadocs for the protocol +provider packages for details. +

+

+Other common causes of this problem are: +

+

+

+ +Q: While trying to run my program on Linux I get a very strange +error message and the program fails. What did I do wrong?
+A: The error message often looks something like this: +

+

+

+Exception in thread "main"
+java.lang.VerifyError:(Class:com/sun/mail/pop3/POP3Store,
+method: finalize Signature :()V)
+Illegal use of nonvirtual function call
+
+
+

+

+The problem is due to a buggy version of the unzip command used to unzip +the Jakarta Mail download package on Linux. The unzip command corrupts the +jakarta.mail.jar file. Get a newer version of the unzip command, or use the +JDK's jar command to unzip the package. +

+ +

+ +Q: How do I use Jakarta Mail in an application run under a SecurityManager; +what permissions must I grant to the application and to Jakarta Mail? + +
+A: When using Jakarta Mail in an environment with a +SecurityManager, Jakarta Mail will sometimes fail to read the configuration +files in the jakarta.mail.jar file. The JavaBeans Activation Framework may +have the same problem reading configuration files from the jakarta.activation.jar +file. These default configuration files are stored as "resource" files +in the META-INF directory in the jar file. +

+

+There are a number of debugging techniques that can be used to determine +if this is the problem. Setting the Session property "mail.debug" to +true (or calling session.setDebug(true)) will cause Jakarta Mail +to print debugging messages as it attempts to load each configuration +file. A message of the form "DEBUG: can't load default providers file" +indicates that this problem might exist. Similarly, setting the System +property "javax.activation.debug" to "true" (e.g., by running the +program using "java -Djavax.activation.debug=true ...") will cause JAF +to print debugging messages as it attempts to load each resource file. +Finally, the JDK can produce helpful debugging output by setting the +system property "java.security.debug" to "access:failure" (e.g., by +running the program using "java -Djava.security.debug=access:failure ..."). +The command java -Djava.security.debug=help will display +other security debugging options. +

+

+In addition to the permissions necessary to read the configuration files, +the application (and Jakarta Mail) will also need permission to connect to the +mail servers it uses. If the application uses System properties to +configure Jakarta Mail (e.g., by passing the Properties object returned from +System.getProperties() to the Session constructor, as many +of the Jakarta Mail demo programs do), it will also need permission to use +the System Properties object. Alternatively, the application can use +its own Properties object and be sure to set the "mail.from" property +or the "mail.user" and "mail.host" properties (see the +InternetAddress.getLocalAddress() method). +

+

+To allow an application to use Jakarta Mail under a SecurityManager, +the application, Jakarta Mail, and JAF will need permissions such as the +following (be sure to replace the host and path names with appropriate +values); add these to the security policy file used by the application: +

+

+ +

+grant {
+    // following two permissions allow
+    // access to default config files
+    permission java.io.FilePermission
+		"/path/to/jakarta.mail.jar", "read";
+    permission java.io.FilePermission
+		"/path/to/activation.jar", "read";
+    // following to use SMTP
+    permission java.net.SocketPermission
+		"SMTPHOST:25", "connect,resolve";
+    // following to use IMAP
+    permission java.net.SocketPermission
+		"IMAPHOST:143", "connect,resolve";
+    // following to use POP3
+    permission java.net.SocketPermission
+		"POP3HOST:110", "connect,resolve";
+    // following needed if System.getProperties() is used
+    permission java.util.PropertyPermission
+		"*", "read,write";
+};
+
+
+
+

+

+If you don't want to give the application read/write permission to +System properties, but you still want to be able to use System properties +to configure the application, you can give the application only "read" +permission to System properties and use the following approach: +

+

+ +

+    Properties props = (Properties)System.getProperties().clone();
+    props.put("mail.smtp.host", "whatever");
+    // set as properties as needed
+    Session session = Session.getInstance(props, null);
+
+
+
+

+ +

+ +Q: How do I configure Tomcat to allow me to use Jakarta Mail in my +web application? + +
+A: +To run a web application using Jakarta Mail, you can add the Jakarta Mail +jakarta.mail.jar file and, if you're not using JDK 1.6 or newer, the JavaBeans +Activation Framework +jakarta.activation.jar +file to the lib directory under the +directory in which you installed Tomcat. This will cause Tomcat to +include these jar files in its classpath automatically. +For details, see + +JNDI Resources HOW-TO in the Tomcat documentation. +

+

+Alternatively, you can package the jakarta.mail.jar file and jakarta.activation.jar +files in the lib directory of your web application package (war file). +

+ +

+ +Q: When using Jakarta Mail in my servlet, it is unable to find any of +the Jakarta Mail classes. I've added jakarta.mail.jar to the server's CLASSPATH. + +
+A: It is often necessary to completely restart the web server +when changing the CLASSPATH. +

+ +

+ +Q: I'm sure I've set my CLASSPATH correctly, but I'm still getting +complaints about classes that can't be found, such as com.sun.mail +classes. + +
+A: The most common cause of problems like this is having more than +one copy of jakarta.mail.jar in your CLASSPATH or available to your application. +In addition to checking your CLASSPATH setting, also look for copies in +the jre/lib/ext directory of your JDK installation. +If you're running in a web server or application server, it may be +providing its own version of jakarta.mail.jar in one of its directories. +You should only have one version of jakarta.mail.jar available to your +application. +

+ +

+ +Q: My servlet can find the Jakarta Mail classes, but Jakarta Mail complains +that it can't find a service provider for "smtp" or "imap" or address +type "rfc822". + +
+A: Usually this is because Jakarta Mail can't access the configuration +files in jakarta.mail.jar, possibly because of a security permission problem; +see this item for more details. +Also, make sure that you haven't extracted the jakarta.mail.jar contents; +you should include the unmodified jakarta.mail.jar file in the server's CLASSPATH. +

+ +

+ +Q: How do I access Gmail with Jakarta Mail? +
+A: +Jakarta Mail is capable of sending and reading messages using Gmail. +All that's required is to properly configure Jakarta Mail. I'll +illustrate the proper configuration using the +demo programs that come with Jakarta Mail - +msgshow.java and smtpsend.java. +You can use these programs for basic testing to ensure that +your networking is working properly, that you can connect to +the servers, that your username and password are correct, etc. +This is important when debugging problems to determine whether +the bug is in your code or is elsewhere. +

+

+Note that you'll need to configure your Gmail account to + +enable less secure apps, or you'll need to use + +OAuth2 authentication +(which is somewhat more complex). +

+

+Let's assume your Gmail username is "user@gmail.com" and your +password is "passwd". +

+

+To read mail from your Gmail Inbox, invoke msgshow as follows: +

+

+

+java msgshow -D -T imaps -H imap.gmail.com -U user -P passwd
+
+

+

+By reading the msgshow.java source code, you can see how these +command line arguments are used in the Jakarta Mail API. You should +first try using msgshow as shown above, and once that's working +move on to writing and configuring your own program to use Gmail. +The following code fragment shows a simple way to incorporate the +needed configuration in your application: +

+    String host = "imap.gmail.com";
+    String username = "user";
+    String password = "passwd";
+    Properties props = new Properties();
+    props.setProperty("mail.imap.ssl.enable", "true");
+    // set any other needed mail.imap.* properties here
+    Session session = Session.getInstance(props);
+    Store store = session.getStore("imap");
+    store.connect(host, username, password);
+
+
+
+

+

+To connect to Gmail using the POP3 protocol instead of the IMAP protocol, +simply change the host name "imap.gmail.com" to "pop.gmail.com" and change +"imap" to "pop3" in the property name and protocol name in the above +instructions. +

+

+To send a message through Gmail, invoke smtpsend as follows: +

+

+

+java smtpsend -d -S -A -M smtp.gmail.com -U user -P passwd someone@example.com
+
+
+

+

+The smtpsend program will prompt for a subject and message body text. +End the message body with ^D on UNIX or ^Z on Windows. +

+

+Again, you can read the smtpsend.java source code to see how the +command line arguments are used in the Jakarta Mail API. +The following code fragment shows a simple way to incorporate the +needed configuration in your application: +

+    String host = "smtp.gmail.com";
+    String username = "user";
+    String password = "passwd";
+    Properties props = new Properties();
+    props.setProperty("mail.smtp.host", host);
+    props.setProperty("mail.smtp.ssl.enable", "true");
+    // set any other needed mail.smtp.* properties here
+    Session session = Session.getInstance(props);
+    MimeMessage msg = new MimeMessage(session);
+    // set the message content here
+    Transport.send(msg, username, password);
+
+
+

+

+There is, of course, more than one way to use the Jakarta Mail API to accomplish +the same goal. This should help you understand the essential +configuration parameters necessary to use Gmail. +

+ +

+ +Q: Why do I get AuthenticationFailedException when +accessing Gmail? +[new!] +
+A: +Most likely you failed to + +enable less secure apps. +

+ +

+ +Q: Why don't I see all my messages when accessing Gmail with POP3? +
+A: +Gmail has settings that control which of your messages are available via +the POP3 protocol. See the + +Gmail settings page to change the configuration of your Gmail account. +

+ +

+ +Q: Why doesn't search find all the messages I expect when accessing +Gmail with IMAP? +
+A: +Gmail does not fully support all IMAP features. For details see + +this Gmail Help page. +

+ +

+ +Q: How do I delete a message in Gmail? + +[new!] +
+A: +Gmail does not follow the normal IMAP conventions for deleting messages. +Marking a message as deleted and then expunging the folder simply removes +the current folder's "label" from the message. The message will still +appear in the "[Gmail]/All Mail" folder. +To delete a message, copy the message to the "[Gmail]/Trash" folder, +which will immediately remove the message from the current folder. +To permanently remove a message, open the "[Gmail]/Trash" folder, +mark the message deleted (msg.setFlag(Flags.Flag.DELETED, true);), +and expunge the folder (folder.close(true);). +

+ +

+ +Q: How do I access Yahoo! Mail with Jakarta Mail? +
+A: +Jakarta Mail is capable of sending and reading messages using Yahoo! Mail. +All that's required is to properly configure Jakarta Mail. I'll +illustrate the proper configuration using the +demo programs that come with Jakarta Mail - +msgshow.java and smtpsend.java. +

+

+Let's assume your Yahoo! Mail username is "user@yahoo.com" and your +password is "passwd". +

+

+To read mail from your Yahoo! Mail Inbox, invoke msgshow as follows: +

+

+

+java msgshow -D -T imaps -H imap.mail.yahoo.com -U user@yahoo.com -P passwd
+
+
+

+

+By reading the msgshow.java source code, you can see how these +command line arguments are used in the Jakarta Mail API. You should +first try using msgshow as shown above, and once that's working +move on to writing and configuring your own program to use Yahoo! Mail. +The code fragment shown above for connecting to Gmail will also work for +connecting to Yahoo! Mail by simply changing the host name. +

+

+To send a message through Yahoo! Mail, invoke smtpsend as follows: +

+

+

+java smtpsend -d -S -A -M smtp.mail.yahoo.com -U user@yahoo.com -P passwd someone@example.com
+
+
+

+

+The smtpsend program will prompt for a subject and message body text. +End the message body with ^D on UNIX or ^Z on Windows. +

+

+Again, you can read the smtpsend.java source code to see how the +command line arguments are used in the Jakarta Mail API. The code fragment shown +above for connecting to Gmail will also work for connecting to Yahoo! Mail +by simply changing the host name. +There is, of course, more than one way to use the Jakarta Mail API to accomplish +the same goal. This should help you understand the essential +configuration parameters necessary to use Yahoo! Mail. +

+

+Also see the Yahoo! Mail help page + +POP server settings for Yahoo Mail +

+ +

+ +Q: How do I access Hotmail (Windows Live mail) with Jakarta Mail? +
+A: +Jakarta Mail is capable of sending and reading messages using Hotmail. +All that's required is to properly configure Jakarta Mail. I'll +illustrate the proper configuration using the +demo programs that come with Jakarta Mail - +msgshow.java and smtpsend.java. +

+

+Let's assume your Hotmail username is "user@hotmail.com" and your +password is "passwd". +

+

+To read mail from your Hotmail Inbox, invoke msgshow as follows: +

+

+

+java msgshow -D -T pop3s -H pop3.live.com -U user@hotmail.com -P passwd
+
+
+

+

+By reading the msgshow.java source code, you can see how these +command line arguments are used in the Jakarta Mail API. You should +first try using msgshow as shown above, and once that's working +move on to writing and configuring your own program to use Hotmail. +The code fragment shown above for connecting to Gmail will also work for +connecting to Hotmail by simply changing the host name. +

+

+To send a message through Hotmail, invoke smtpsend as follows: +

+

+

+java -Dmail.smtp.starttls.enable=true -Dmail.smtp.port=587
+	smtpsend -d -A -M smtp.live.com
+	-U user@hotmail.com -P passwd someone@example.com
+
+
+

+

+(Note that I split the command over three lines for display, but you +should type it on one line.) +

+

+The smtpsend program uses the System properties +when creating the Jakarta Mail Session, so the properties set on the +command line will be available to the Jakarta Mail Session. +

+

+The smtpsend program will prompt for a subject and message body text. +End the message body with ^D on UNIX or ^Z on Windows. +

+

+Again, you can read the smtpsend.java source code to see how the +command line arguments are used in the Jakarta Mail API. The code fragment shown +above for connecting to Gmail will also work for connecting to Hotmail +by simply changing the host name and changing the connect call to +t.connect(host, 587, username, password). +There is, of course, more than one way to use the Jakarta Mail API to accomplish +the same goal. This should help you understand the essential +configuration parameters necessary to use Hotmail. +

+

+For more details, search + +Windows Live Hotmail help for "POP3". +

+ +

+ +Q: How do I access Outlook.com with Jakarta Mail? +
+A: +Jakarta Mail is capable of sending and reading messages using Outlook.com. +All that's required is to properly configure Jakarta Mail. I'll +illustrate the proper configuration using the +demo programs that come with Jakarta Mail - +msgshow.java and smtpsend.java. +

+

+Let's assume your Outlook.com username is "user@outlook.com" and your +password is "passwd". +

+

+To read mail from your Outlook.com Inbox, invoke msgshow as follows: +

+

+

+java msgshow -D -T imaps -H imap-mail.outlook.com -U user@outlook.com -P passwd
+
+
+

+

+By reading the msgshow.java source code, you can see how these +command line arguments are used in the Jakarta Mail API. You should +first try using msgshow as shown above, and once that's working +move on to writing and configuring your own program to use Outlook.com. +The code fragment shown above for connecting to Gmail will also work for +connecting to Outlook.com by simply changing the host name. +

+

+To connect to Outlook.com using the POP3 protocol instead of the IMAP protocol, +simply change the host name "imap-mail.outlook.com" to "pop-mail.outlook.com" +and change the protocol name "imaps" to "pop3s" in the above instructions. +

+

+To send a message through Outlook.com, invoke smtpsend as follows: +

+

+

+java -Dmail.smtp.starttls.enable=true
+	smtpsend -d -A -M smtp-mail.outlook.com
+	-U user@outlook.com -P passwd someone@example.com
+
+
+

+

+(Note that I split the command over three lines for display, but you +should type it on one line.) +

+

+The smtpsend program uses the System properties +when creating the Jakarta Mail Session, so the properties set on the +command line will be available to the Jakarta Mail Session. +

+

+The smtpsend program will prompt for a subject and message body text. +End the message body with ^D on UNIX or ^Z on Windows. +

+

+Again, you can read the smtpsend.java source code to see how the +command line arguments are used in the Jakarta Mail API. +The following code fragment shows a simple way to incorporate the +needed configuration in your application: +

+    String host = "smtp-mail.outlook.com";
+    String username = "user@outlook.com";
+    String password = "passwd";
+    Properties props = new Properties();
+    props.setProperty("mail.smtp.host", host);
+    props.setProperty("mail.smtp.starttls.enable", "true");
+    Session session = Session.getInstance(props);
+    MimeMessage msg = new MimeMessage(session);
+    // set the message content here
+    Transport.send(msg, username, password);
+
+
+

+

+There is, of course, more than one way to use the Jakarta Mail API to accomplish +the same goal. This should help you understand the essential +configuration parameters necessary to use Outlook.com. +For more details, see the + +Outlook Blog. +

+ +
+
+

Programming

+
+
+ +

+ +Q: Where can I learn the basics about Internet email that +I'll need to know to program Jakarta Mail effectively? +
+A: See one of the +books +referenced on our web page for a good background on Internet email, MIME, +SMTP, IMAP, POP3, etc. +

+ +

+ +Q: Where can I find some example programs that show how to use Jakarta Mail? +
+A: There are many example programs available for download +on the +Jakarta Mail project page, +including simple command line programs illustrating various aspects of +the Jakarta Mail API, a Swing-based GUI application, a simple servlet-based +application, and a complete web application using JSP pages and a tag +library. +

+ +

+ +Q: What are some of the most common mistakes people make +when using Jakarta Mail? +
+A: Unfortunately, the internet is full of copy and paste +programmers who don't understand the code they're using, which has resulted +in a lot of unnecessarily complex and often incorrect examples. +The most common mistakes are: +

+

+ +

+ +Q: How do I send a message with an attachment? +
+A: A message with attachments is represented as a +MIME multipart message where the first part is the main body of the +message and the other parts are the attachments. +There are numerous examples showing how to construct such a message +in the demo programs included in the Jakarta Mail download package. +To attach a file use the +attachFile method of MimeBodyPart. +

+ +

+ +Q: How do I tell if a message has attachments? +
+A: In the simplest case, a message of MIME type +multipart/mixed with more than one body part is likely +a message with attachments. As described above, there are more complex +cases to consider as well. In particular, messages may have arbitrary +nesting of multipart/mixed and multipart/alternative +parts and may include multipart/related parts for embedded +HTML and multipart/signed and/or multipart/encrypted +parts for secure messages. It's up to you to decide how many of these +cases you want to handle in your application before deciding that a +message has an attachment. Most applications take a very simple approach +to this and handle only a few of the most commonly seen cases. +

+

+Note that while it's recommended that attachments have a Content-Disposition +of "ATTACHMENT", and will usually have a file name, these are not requirements. +Some messages with attachments will have only one or none of these. Looking +for attachments by looking for a body part with these set will fail in some +cases. +

+

+In the simplest case, here's how to tell if a message has attachments: +

+    boolean hasAttachments(Message msg) throws MessagingException {
+	if (msg.isMimeType("multipart/mixed")) {
+	    Multipart mp = (Multipart)msg.getContent();
+	    if (mp.getCount() > 1)
+		return true;
+	}
+	return false;
+    }
+
+
+

+ +

+ +Q: How do I read a message with an attachment and save the +attachment? +
+A: As described above, a message with an attachment is +represented in +MIME as a multipart message. In the simple case, the results of the +Message object's getContent method will be a +MimeMultipart object. The first body part of the multipart +object wil be the main text of the message. The other body parts will +be attachments. The msgshow.java demo program shows how +to traverse all the multipart objects in a message and extract the data +of each of the body parts. The getDisposition method will +give you a hint as to whether the body part should be displayed inline +or should be considered an attachment (but note that not all mailers +provide this information). So to save the contents of a body part in a file, +use the saveFile method of MimeBodyPart. +

+

+To save the data in a body part into a file (for example), use the +getInputStream method to access the attachment content and +copy the data to a FileOutputStream. +Note that when copying the data you can not use the +available method to determine how much data is in the +attachment. Instead, you must read the data until EOF. +The saveFile method of MimeBodyPart will +do this for you. +However, you should not use the results of the getFileName +method directly to name the file to be saved; doing so could cause you +to overwrite files unintentionally, including system files. +

+

+Note that there are also more complicated cases to be handled as well. +For example, some mailers send the main body as both plain text and +html. This will typically appear as a multipart/alternative +content (and a MimeMultipart object) in place of a simple +text body part. Also, messages that are digitally signed or encrypted +are even more complex. Handling all these cases can be challenging. +Please refer to the various MIME specifications and other +resources listed on our main page. +

+ +

+ +Q: How do I find the main message body in a message that has +attachments? +
+A: The following approach will handle the most common cases. +Handling improperly formatted messages, messages with unknown charsets, +and signed or encrypted messages, can make this much more complex. +

+

+ +

+    private boolean textIsHtml = false;
+
+    /**
+     * Return the primary text content of the message.
+     */
+    private String getText(Part p) throws
+                MessagingException, IOException {
+        if (p.isMimeType("text/*")) {
+            String s = (String)p.getContent();
+            textIsHtml = p.isMimeType("text/html");
+            return s;
+        }
+
+        if (p.isMimeType("multipart/alternative")) {
+            // prefer html text over plain text
+            Multipart mp = (Multipart)p.getContent();
+            String text = null;
+            for (int i = 0; i < mp.getCount(); i++) {
+                Part bp = mp.getBodyPart(i);
+                if (bp.isMimeType("text/plain")) {
+                    if (text == null)
+                        text = getText(bp);
+                    continue;
+                } else if (bp.isMimeType("text/html")) {
+                    String s = getText(bp);
+                    if (s != null)
+                        return s;
+                } else {
+                    return getText(bp);
+                }
+            }
+            return text;
+        } else if (p.isMimeType("multipart/*")) {
+            Multipart mp = (Multipart)p.getContent();
+            for (int i = 0; i < mp.getCount(); i++) {
+                String s = getText(mp.getBodyPart(i));
+                if (s != null)
+                    return s;
+            }
+        }
+
+        return null;
+    }
+
+
+
+

+

+You can call the getText method with a Message +object (which is a Part). +

+ +

+ +Q: How do I find the attachments in a message? +[new!] +
+A: +There's a wide variety of possible MIME structures for email. A general +solution can be quite complex since it would need to take into account +signed and encrypted messages, among other issues. Different mailers +will use different MIME structure, and of course some mailers will have +bugs in how they use MIME. You need to decide which cases you need to +support. +

+

+In general, multipart/alternative is used to contain different versions +of the main message body, and so can be skipped because it doesn't +contain any attachments. Typically, a message with attachments will +have a top level multipart/mixed content with the first body part +containing the main message body. The first part may be a simple text +part, a multipart/alternative with text/plain and text/html parts, or a +multipart/related with a text/html part and associated images. +

+

+Attachments will usually, but not always, have a Content-Disposition of +attachment. Attachments will usually, but not always, have a file +name. +

+

+So, a good approach to start with is to only consider messages with a +top level multipart/mixed content and then consider the parts after the +first part to be attachments whether they say so or not. And as I said +above, signed and encrypted messages will make this more complex. +

+ +

+ +Q: How do I get all the unread messages in a folder? +
+A: Search for all messages with the SEEN flag not set: +

+ +

+	Message[] unreadMessages = folder.search(
+		new FlagTerm(new Flags(Flags.Flag.SEEN), false));
+
+
+
+

+ +

+ +Q: Should I use the isMimeType method, +or should I use instanceof on the object returned by the +getContent method, when deciding how to process a message +part? +
+A: It is almost always more efficient to use the +isMimeType method. +The msgshow.java demo program shows how to use the +isMimeType method when traversing the parts of a message. +

+ +

+ +Q: When reading a multipart message, why is the getContent +method returning an IMAPInputStream (or SharedByteArrayInputStream) instead +of a MimeMultipart object? +
+A: This usually happens because the JavaBeans Activation +Framework (JAF) can't find the mailcap configuration file included in the +jakarta.mail.jar file. +JAF uses the thread's context class loader to look for the configuration file. +If the context class loader is not set properly, this can fail. +Most application servers should set the context class loader properly, but +at least some versions of Tomcat do not. +One workaround is to put the jakarta.mail.jar file in Tomcat's lib directory +instead of including it in the war file. +Another workaround is to add code such as the following to the beginning of +your application: + +

+Thread.currentThread().setContextClassLoader(this.getClass().getClassLoader());
+
+
+ +

+

+And of course you should always make sure the message you're dealing with is +a multipart message before calling the getContent method, using something like +if (msg.isMimeType("multipart/*")), as described +above and in this example. +

+ +

+ +Q: When I attach a file it gets a MIME type of +application/octet-stream instead of the correct MIME type. +
+A: The FileDataSource class uses the JavaBeans Activation +Framework (JAF) class MimetypesFileTypeMap to determine the +MIME type of a file based on the extension of the filename. +The default mapping knows about only a few extensions. +You can add support for more extensions either programmatically +or by adding a META-INF/mime.types configuration file +to your application. +For example, to map the .doc extension to the MIME type +application/msword, create a META-INF/mime.types +file with the single line: +

+

+ +

+application/msword doc
+
+ +
+

+

+See the javadocs for the MimetypesFileTypeMap class for details. +

+ +

+ +Q: How do I manually set the MIME type for an attached file, +for example in the case where the filename doesn't have an obvious extension? + +
+A: Subclass the FileDataSource class and override +the getContentType method. +(Note that with this approach you can't use the attachFile method.) +

+

+ +

+    File file = new File("filename");
+    DataSource ds = new FileDataSource(file) {
+	public String getContentType() {
+	    return "mytype/mysubtype";
+	}
+    };
+    MimeBodyPart mbp = new MimeBodyPart();
+    mbp.setDataHandler(new DataHandler(ds));
+    mbp.setFileName(file.getName());
+    mbp.setDisposition(Part.ATTACHMENT);
+
+
+
+

+ +

+ +Q: How do I create a multipart message with a part of any +MIME type I choose? +
+A: The Jakarta Mail API includes builtin support for the most +common MIME types, but to create a message that includes data in +a MIME type that Jakarta Mail does not already understand, you'll +need to supply that data to Jakarta Mail in a byte stream format. +The ByteArrayDataSource class in the javax.mail.util +pacakge in Jakarta Mail 1.4 and later, or included in source code in the demo +directory of older versions of the Jakarta Mail download package, can help. +This class +will take a String, byte array, or InputStream +and create a DataSource object that you can use as follows: +

+

+ +

+    MimeBodyPart mbp = new MimeBodyPart();
+    String data = "any ASCII data";
+    DataSource ds = new ByteArrayDataSource(data, "application/x-any");
+    mbp.setDataHandler(new DataHandler(ds));
+
+
+
+

+

+You can specify any MIME type that you want. The MimeBodyPart +object can then be added to a MimeMultipart object in the +usual way. +

+

+Note that if you create a ByteArrayDataSource with an +InputStream, it first copies all of the data in the stream +into memory. This is necessary because a DataSource needs +to be able to supply multiple InputStream objects so that +Jakarta Mail can read the data once to determine what +Content-Transfer-Encoding is appropriate, and then read the data again +to include the data in the message. +

+ +

+ +Q: Can I read or send a Microsoft Office document using +Jakarta Mail? +
+A: Jakarta Mail can read a Microsoft Office document as an +attachment and save that document in a file. Likewise, Jakarta Mail can attach a +Microsoft Office document to a message and send it as an attachment. +Use the MimeBodyPart +saveFile and +attachFile methods. +To process the content of a Microsoft Office document you'll need a +separate library such as +Apache POI. +

+ +

+ +Q: How do I create or process calendar appointments? +
+A: The iCal4j project +provides an API that might be useful. +More information about how different products, such as Microsoft Outlook, +support calendar appointments is available +here. +This blog entry might also be helpful. +

+ +

+ +Q: When should I use Session.getDefaultInstance +and when should I use Session.getInstance? +
+A: Almost all code should use Session.getInstance. +The Session.getDefaultInstance method creates a new Session the +first time it's called, using the Properties that are passed. +Subsequent calls will return that original Session and ignore any +Properties you pass in. +If you want to create different Sessions with different properties, +Session.getDefaultInstance won't do that. +If some other code in the same JVM (e.g., in the same app server) has already +created the default Session with their properties, you may end up using their +Session and your properties will be ignored. +This often explains why your property settings seem to be ignored. +Always use Session.getInstance to avoid this problem. +

+ +

+ +Q: What is "disconnected support"? +
+A: A mail client supporting disconnected operation will allow +the user to access messages in a remote message store (e.g., +IMAP), cache (parts of) some of those messages locally, and +break the connection to the server. While in this disconnected +state, the mail client can access the messages that have been +cached, possibly deleting them or saving them to other folders. +When the mail client next connects to the remote message store, +the changes made locally will be synchronized with the remote +store. Similarly, disconnected support may allow the client +to "send" messages when there is no connection to the server, with +the messages being queued until a connection to the server is +available. See also +RFC 1733 and +RFC 4549. +

+ +

+ +Q: How do I support disconnected operation using the +Jakarta Mail APIs?
+A: The Jakarta Mail API specification defines interfaces that can +be used by a mail client to support disconnected operation. +Our IMAP provider implements these interfaces (the UIDFolder interfaces). +

+ +

+ +Q: How do I send secure email using the Jakarta Mail APIs? +
+A: The Jakarta Mail APIs currently have no support for sending +or receiving secure email. The architecture of the +Jakarta Mail APIs allows such support to be easily added later, +by us or by third parties. +Please browse our +Third Party Products +page for solutions from other vendors. +The most popular third party solution is the +Bouncy Castle library. +

+ +

+ +Q: The writeTo() method generates message text +with lines that are neither the canonical MIME representation of the data +(i.e., using CRLF to terminate lines), nor using the canonical line +separator of my platform (e.g., "\n" on UNIX). How do I get either +of these representations if I need them?
+A: In either case you'll need to create an appropriate +FilterOutputStream to hand to writeTo(). The +FilterOutputStream will need to accept lines with any of the common +line terminators and write out lines with only the desired line +terminator. The following are examples of such filters. +NewlineOutputStream +converts to the local platform's line terminator and is useful when +writing a message to a file. +CRLFOutputStream +converts to the MIME canonical CRLF line terminator and is useful +when the canonical MIME format is needed (e.g., to compute a digital +signature). +

+ +

+ +Q: Can I use the Jakarta Mail APIs to implement a +mail server?
+A: The Jakarta Mail APIs were not intended to help you implement a +mail server. +Nonetheless, some of the utility classes, such as the MIME +message parsing classes, might be of use to you. +In general you'll find that the Jakarta Mail API errs on the side +of "simple" instead of "robust". That's appropriate for a mail +client, but a mail server would likely make different tradeoffs. +

+ +

+ +Q: Can I use the Jakarta Mail APIs to add new user accounts to my +mail server, remove user accounts from my mail server, or change the passwords +for user accounts on my mail server? +
+A: The Jakarta Mail API does not include any facilities for adding, +removing, or changing user accounts. There are no standards in this area; +every mail server handles this differently. +

+ +

+ +Q: Can I use the Jakarta Mail APIs to access my address book +on my mail server? +
+A: The Jakarta Mail API does not include any facilities for accessing +an address book. There are no standards in this area; +every mail server handles this differently. +If you can figure out how your server does it, you might be able +to find a Java API to access it. For example, if your server stores +address books in LDAP, you could use the JNDI API to access it. +

+ +

+ +Q: Why doesn't the MimeMessage class implement Serializable +so that I can serialize a message to disk and read it back later? + +
+A: +The Jakarta Mail API was designed to layer on top of existing email systems, +using existing message formats. The ability to use Java serialization +was neither essential nor useful for such implementations, and thus was +not considered a goal of the Jakarta Mail API. +

+

+The hard part about serializing a Message is retaining the pointers to +the Folder, Store, and Session. If you only want to save the content +of the message, and not the object itself, the writeTo +method of a message gives you everything you need. +If you want to create an entire email system based on serialized messages, +you should be able to subclass Message et. al. and implement Serializable +in your subclass. +

+

+If you want to serialize other objects of your own that reference +MimeMessages, the writeObject method of your object can use the +writeTo method of MimeMessage, and the readObject +method of your object can use the MimeMessage constructor that takes an +InputStream. Your class will need to provide a Session when constructing +the MimeMessage. +

+ +

+ +Q: How do I write a Service Provider?
+A: Please read the Service Provider documentation for details. +In general, if you want to write a Store provider, you subclass +javax.mail.Store, javax.mail.Folder, possibly +javax.mail.Message and a few others. For a Transport +provider, you subclass javax.mail.Transport, possibly +javax.mail.Message and a few others. Then you add +the entry describing your provider to the javamail.providers +registry. If you're interested in writing a service provider for a protocol +or messaging system not currently supported by the Jakarta Mail API +implementation, please contact us at +mail-dev@eclipse.org. +

+ +

+ +Q: I'm having trouble logging into my Microsoft Exchange server, +even though I'm sure I'm using the correct username and password, what +could I be doing wrong? + +
+A: When logging in to Exchange you need to use a username that's +more than your simple login name. For example, if your email address +is "J.User@server.com", your Windows NT login name is "juser", your +NT domain name is "dom", and your Exchange mailbox name is "Joe User", +then you would need to use a username of "dom\juser\J.User" when logging +in using Jakarta Mail. +

+

+Note also that there's a bug in Exchange 2007. The Exchange server +advertises that it supports AUTH=PLAIN, even though + +this Exchange documentation claims that it's not supported. +This causes Jakarta Mail to choose PLAIN authentication, which will always fail. +To work around this Exchange bug, set the session property +"mail.imap.auth.plain.disable" to "true". (Change "imap" to "imaps" if +you're using the "imaps" protocol.) +

+ +

+ +Q: How do I encode a binary file before sending it and how do I +decode it when I receive it? + +
+A: You don't need to! Jakarta Mail will automatically determine an +appropriate encoding to use for your message parts before sending the +message, and will automatically decode message parts when reading them. +The getInputStream method will return the decoded +data. +

+ +

+ +Q: If I don't need to encode and decode attachments myself, +when should I use the MimeUtility methods? + +
+A: The MimeUtility methods are useful in cases that +Jakarta Mail doesn't handle automatically for you. One such case that +occurs frequently is encoding of filenames. The base MIME spec does not +allow header parameter values (such as the filename parameter) to be +encoded in the same way that (e.g.) the Subject header may be encoded. +This restricts parameter values, and thus filenames, to ASCII. However, +some mailers actually do encode non-ASCII filenames using the MIME text +encoding. Applications that wish to interoperate with such non-standard +mailers can use the encodeText method to encode filenames +before calling the MimeBodyPartsetFileName method, +and can use the decodeText method to decode returned filenames. +See also this entry below if you need to +encode filenames. +

+ +

+ +Q: I have data that's already encoded in (e.g.) base64, how do I +tell Jakarta Mail to send this data without re-encoding it? + +
+A: Use the PreencodedMimeBodyPart class, +new in Jakarta Mail 1.4. +

+ +

+ +Q: Even though Jakarta Mail does all the encoding and decoding for me, +I need to manually control the encoding for some body parts. + +
+A: In the rare case that you need to control the encoding, there +are several ways to override Jakarta Mail's default behavior. A simple +approach is as follows. After creating the entire message, call +msg.saveChanges() and then use something like +mbp.setHeader("Content-Transfer-Encoding", "base64") +to force base64 encoding for the given body part. +

+

+Another approach is to subclass MimeBodyPart and override +the updateHeaders method so that it first calls +super.updateHeaders() and then sets the +Content-Transfer-Encoding header as above. +

+ +

+ +Q: Why doesn't Jakarta Mail properly encode and decode filenames in +non-ASCII character sets? + +
+A: The filename is stored as a parameter in MIME headers. +Encoded filenames of the form =?ISO-8859-15?B?5OTkLUluZm8ucGRm?= +are not part of the MIME spec. A filename of +the form =?A?B?C?= is a perfectly valid filename, +not an incorrectly encoded filename. Jakarta Mail does +not encode and decode filenames by default because doing so +would violate the MIME spec. +

+

+The base MIME spec does not allow for encoding parameters. +RFC 2231 defines a new way to include encoded paramters, +including filenames, in MIME headers. It is not +compatible with the de facto way that many older applications +illegally encode filenames. Even though Jakarta Mail supports RFC 2231, that +alone does not allow Jakarta Mail to interoperate with these older +programs. Most recent email programs support RFC 2231 and Jakarta Mail +enables support for it by default starting in Jakarta Mail 1.5. +To enable RFC 2231 support in older Jakarta Mail releases for encoded parameters, +set the System properties "mail.mime.encodeparameters" and +"mail.mime.decodeparameters" to "true". +

+

+If you choose to violate the MIME spec, in order to +interoperate with other programs that also violate the +MIME spec, Jakarta Mail gives you all the tools you need to +do so. Starting with Jakarta Mail 1.4, setting the System properties +"mail.mime.encodefilename" and "mail.mime.decodefilename" to "true" +will cause Jakarta Mail to encode and decode the filename parameter +using the non-RFC 2231 MIME encoding. +

+

+Applications using earlier versions of Jakarta Mail can use the following +workaround to encode a filename: +

+

+mbp.setFileName(MimeUtility.encodeText(filename)); +

+

+The workaround for decoding a filename is equally simple: +

+

+String filename = MimeUtility.decodeText(part.getFileName()); +

+

+Again, this is primarily for applications using old versions of Jakarta Mail. +Most applications should never need to use these methods. +

+ +

+ +Q: Why do I get an error such as +java.net.SocketException: Permission denied: connect +when connecting to my mail server using JDK7? +
+A: You may be running into an issue with support for IPv6. +You can work around this problem by setting the System property +"java.net.preferIPv4Stack" to "true". +You can do this when starting your program using +"java -Djava.net.preferIPv4Stack=true ..." +

+ + +
+
+

Debugging

+
+
+ +

+ +Q: How do I debug my application that uses Jakarta Mail APIs?
+A: Turn on session debugging by invoking the method +setDebug(true) +on the Session object in your code. That will cause debug information to +be printed to the console, including a protocol trace. +If you passed the System properties to the Session when you created it, +you can simply run your program with java -Dmail.debug=true ... +
+If you think that you found a bug in Jakarta Mail, +send us this trace along with a test case that reproduces the problem, +the platform you are using, the version of the JDK you are using, and +the name and version of the mail servers (IMAP, SMTP) that you are using. +

+ +

+ +Q: How do I debug problems connecting to my mail server? +
+A: The first thing to do when debugging such problems is to +determine whether it's a Java problem or a networking problem. +Use telnet to try to connect to the remote system. For +example, if you're having trouble connecting to the POP3 server named +mail.example.com, you would use: +

+

+telnet mail.example.com 110 +

+

+If you're trying to connect to an SMTP server, use 25 instead of 110 +for the port number. If you're trying to connect to an IMAP server +use 143 for the port number. +

+

+If you get a greeting banner you can simply disconnect. +If this works, your +networking, name service, firewall, etc. are all set up +correctly and your problem is most likely in your Java +program. +

+

+If it doesn't work, you'll need to check your networking +configuration or talk to your network administrator for help. +Sometimes a firewall installed on your local machine or on +your network will prevent you from connecting to the server. +If telnet complains that it doesn't know the host name that +you're using, most likely your name service (e.g., DNS) isn't +properly configured to resolve internet host names. +None of these problems are Jakarta Mail or Java problems. +

+

+Usually, when you get a low level SocketException +when connecting, the problem is due to your networking +configuration. Usually it's not a Java problem. +

+

+If you've succeeded in connecting with telnet, the next thing +to do is to turn on Session debugging and get the protocol +trace when Jakarta Mail tries to connect to the remote machine, +as described above. +This will often include more detailed error messages from the +server that will indicate the real source of the problem. +

+ +

+ +Q: How do I debug problems connecting to my mail server using SSL? +
+A: Debugging SSL problems, and in particular certificate problems, +can be difficult. The file +SSLNOTES.txt +includes some useful information. Jakarta Mail uses the JDK's JSSE +API to provide SSL support. You can find information about debugging +JSSE problems in the + +JSSE Reference Guide. +

+ +

+ +Q: How do I debug problems with Java security permissions? +
+A: You can set the java.security.debug System property +to debug problems with Java security permissions. +To get the possible values for setting that property, the following command +will print a help message: java -Djava.security.debug=help MyClass +

+ + +
+
+

Reading mail, IMAP

+
+
+ +

+ +Q: I tried running your demos against my IMAP server, +but I get an error. +
+A: First verify that you indeed have an email account on the IMAP +server. Check with your system administrator about it. +Turn debug mode on, by invoking the method setDebug(true) on +the session object in your code. This will cause the IMAP +protocol trace to be dumped on your screen. Send us this trace. +The trace will be very useful to us for identifying the problem. +If you can, please send us vendor information about your IMAP +server. +

+ +

+ +Q: I can read messages from my IMAP server with other mail clients, +but even though I can connect to the server using Jakarta Mail, when I use +Jakarta Mail to read some messages it fails. Doesn't that mean there's a bug +in Jakarta Mail? + +
+A: No, not usually. Most other mail clients make very little +use of the rich IMAP protocol. They use the IMAP protocol as little +more than a variant of the POP3 protocol, typically downloading the +entire message to the client and parsing it in the client. This allows +them to avoid all sorts of parsing and protocol bugs in many IMAP +servers, but of course it comes at the cost of being less efficient +because they don't take advantage of the IMAP protocol's ability to +fetch only the parts of the message that are needed. These server bugs +often manifest themselves as the following exception on the client: +javax.mail.MessagingException: Unable to load BODYSTRUCTURE +

+

+The best approach when running into server bugs of this sort is to contact +the vendor of the server and get them to fix their product. Contact +mail-dev@eclipse.org and we'll help you +pinpoint the problem so that you can report it to the server vendor. +If you can't get a fix from the server vendor, the following technique +will often allow you to work around these server bugs: + +

+    // Get the message object from the folder in the
+    // usual way, for example:
+    MimeMessage msg = (MimeMessage)folder.getMessage(n);
+
+    // Use the MimeMessage copy constructor to make a copy
+    // of the entire message, which will fetch the entire
+    // message from the server and parse it on the client:
+    MimeMessage cmsg = new MimeMessage(msg);
+
+    // The cmsg object is disconnected from the server so
+    // setFlags will have no effect (for example).  Use
+    // the original msg object for such operations.  Use
+    // the cmsg object to access the content of the message.
+
+
+

+

+In some cases, the server may be so badly broken that loading the envelope +data is not possible, which can cause the above workaround to fail because +internally it first fetches the message flags and message size from the server. +In that case, the following approach will usually work: + +

+    // Get the message object from the folder in the
+    // usual way, for example:
+    MimeMessage msg = (MimeMessage)folder.getMessage(n);
+
+    // Copy the message by writing into a byte array and
+    // creating a new MimeMessage object based on the contents
+    // of the byte array:
+    ByteArrayOutputStream bos = new ByteArrayOutputStream();
+    msg.writeTo(bos);
+    bos.close();
+    SharedByteArrayInputStream bis =
+		    new SharedByteArrayInputStream(bos.toByteArray());
+    MimeMessage cmsg = new MimeMessage(session, bis);
+    bis.close();
+
+    // The cmsg object is disconnected from the server so
+    // setFlags will have no effect (for example).  Use
+    // the original msg object for such operations.  Use
+    // the cmsg object to access the content of the message.
+
+
+
+

+ +

+ +Q: The IMAP provider seems to lose data when I fetch messages with large +attachments.
+A: This is due to bugs in the partial fetch implementation of your +IMAP server. To workaround this server bug, set the +"mail.imap.partialfetch" property to "false". +Refer to NOTES.txt from +the Jakarta Mail package for more information. +

+ +

+ +Q: Does the IMAP provider cache the retrieved data?
+A: The IMAP provider fetches the data for a message from the server only +when necessary. (The javax.mail.FetchProfile can be used +to optimize this). +The header and bodystructure information, once fetched, is always +cached within the Message object. However, the content of a bodypart +is not cached. So each time the content is +requested by the client (either using getContent() or +using getInputStream()), a new FETCH request is issued +to the server. +The reason for this is that the content of a message could be +potentially large, and if we cache this content for a large number +of messages, there is the possibility that the system may +run out of memory soon since the garbage collector cannot free +the referenced objects. +Clients should be aware of this and must hold on to the retrieved +content themselves if needed. +

+ +

+ +Q: I want to move messages between folders. Should I use +appendMessages() or copyMessages()?
+A: Use copyMessages() if the messages to be copied/moved +belong to the folder on which this method is being invoked. This is because +some implementations can optimize this operation if the source +and destination folder belong to the same backend Store. +Otherwise, use appendMessages(). +

+ +

+ +Q: Retrieving large message bodies seems inefficient at times.
+A: If you are using the IMAP provider, you could try increasing +the mail.imap.fetchsize property (the current default is 16k). +This will cause data to be fetched from the server in larger chunks. +Note that you risk the possibility of the JVM running out of memory +when you do this. +

+ +

+ +Q: I get OutOfMemory errors when loading this large binary attachement. +
+A: Increase the maximum JVM heapsize at startup. Use the "-mx" option +if using the standard JVM from Oracle. +Don't keep references to the "content" of messages not being used. +In certain cases, you could try streaming the message content +(using getInputStream()) as raw bytes, use and then discard the +used data chunks. +

+ +

+ +Q: Why do I get the UnsupportedDataTypeException when I invoke +getContent() on a bodypart?
+A: The getContent() method returns a Java object that +represents +the bodypart content. For this to work, a JAF DataContentHandler +corresponding to the content's MIME type must be registered. Otherwise, the +UnsupportedDataTypeException will be thrown. In this case, you +can use the getInputStream() method to retrieve the content as +a stream of bytes. See the JAF docs for details on how to create +and register your own DataContentHandlers. +

+ +

+ +Q: Why do I get the UnsupportedEncodingException when I invoke +getContent() on a bodypart that contains text data? +
+A: Textual bodyparts (i.e., bodyparts whose type is "text/plain", +"text/html", or "text/xml") +return Unicode String objects when getContent() is used. +Typically, +such bodyparts internally hold their textual data in some non Unicode +charset. Jakarta Mail (through the corresponding DataContentHandler) +attempts to convert that data into a Unicode string. +The underlying JDK's charset converters are used to do this. +If the JDK does not support a particular charset, then the +UnsupportedEncodingException is thrown. +In this case, you can use the getInputStream() method to retrieve +the content as a stream of bytes. +For example: + +

+    String s;
+    if (part.isMimeType("text/plain")) {
+	try {
+	    s = part.getContent();
+	} catch (UnsupportedEncodingException uex) {
+	    InputStream is = part.getInputStream();
+	    /*
+	     * Read the input stream into a byte array.
+	     * Choose a charset in some heuristic manner, use
+	     * that charset in the java.lang.String constructor
+	     * to convert the byte array into a String.
+	     */
+	    s = convert_to_string(is);
+	} catch (Exception ex) {
+	    // Handle other exceptions appropriately
+	}
+    }
+
+
+

+

+There are some commonly used charsets that the JDK does not yet support. +You can find support for some of these additional charsets in the JCharset +package at + +http://www.freeutils.net/source/jcharset/. +

+

+You can also add an alias for an existing charset already supported +by the JDK so that it will be known by an additional name. +You can create +a charset provider for the "bad" charset name that simply redirects to +an existing charset provider; see the following code. +Create an appropriate CharsetProvider subclass and include it along with the +META-INF/services file and the JDK will find it. +Obviously you could get significantly more clever and redirect all +unknown charsets to "us-ascii", for instance. + +

+==> UnknownCharsetProvider.java <==
+import java.nio.charset.*;
+import java.nio.charset.spi.*;
+import java.util.*;
+
+public class UnknownCharsetProvider extends CharsetProvider {
+     private static final String badCharset = "x-unknown";
+     private static final String goodCharset = "iso-8859-1";
+
+     public Charset charsetForName(String charset) {
+         if (charset.equalsIgnoreCase(badCharset))
+             return Charset.forName(goodCharset);
+         return null;
+     }
+
+     public Iterator<Charset> charsets() {
+         return Collections.emptyIterator();
+     }
+}
+
+==> META-INF/services/java.nio.charset.spi.CharsetProvider <==
+UnknownCharsetProvider
+
+
+
+

+ +

+ +Q: How do I process all the messages in an IMAP folder +and add a listener to wait for the arrival of new messages? + +[new!] +
+A: +Open the folder, process all the messages in the folder, and check +whether new messages have arrived (the message count has increased). +If so, loop. If not, add the listener, then wait for new messages +(e.g., by calling the idle method). +

+

+Part of the key to understanding how this works is understanding when +the server is allowed to notify the client of new messages, and when +Jakarta Mail will see those notifications. Between getting the number of +messages and adding the listener, Jakarta Mail won't see any notifications +of new messages. By the time you do an operation that will allow +Jakarta Mail to see the notification, the listener will be in place. +

+

+The following code illustrates the general approach. Many details have +been omitted. + +

+    folder.open(Folder.READ_WRITE); // or READ_ONLY
+
+    // first batch of messages
+    int start = 1;
+    int end = folder.getMessageCount();
+    while (start <= end) {
+	Message[] msgs = folder.getMessages(start, end);
+	for (Message msg : msgs)
+	    processMessage(msg);
+	// new messages that have arrived
+	start = end + 1;
+	end = folder.getMessageCount();
+    }
+    // processed all messages
+
+    // add MessageCountListener to listen for new messages
+    folder.addMessageCountListener(new MessageCountAdapter() {
+	public void messagesAdded(MessageCountEvent ev) {
+	    Message[] msgs = ev.getMessages();
+	    for (Message msg : msgs)
+		processMessage(msg);
+	}
+    });
+
+    // wait for new messages
+    for (;;)
+	((IMAPFolder)folder).idle();
+
+

+ + +
+
+

Sending mail, SMTP

+
+
+ +

+ +Q: How do I reply to a message? + +
+A: To reply to a message, use the reply method +on the Message object. This method will return a new object with the +headers set appropriately for a reply. You'll need to supply the content +of the message yourself. +If you have the content of the original message as a String, you can use +a simple method such as the following to create the prototypical reply +text, which inserts "> " in front of each line: +

+    String text = (String)msg.getContent();
+    Message reply = msg.reply();
+    String replyText = text.replaceAll("(?m)^", "> ");
+    // allow user to edit replyText,
+    // e.g., using a Swing GUI or a web form
+    reply.setText(replyText);
+
+
+
+

+ +

+ +Q: How do I forward a message? + +
+A: The approach used to forward a message depends on how you want +to present the forwarded message. +It's straightforward to create a new MimeMessage, address it appropriately, +and attach an existing message as an attachment to the new message. +To attach the original message to the new message, use code such as: +

+    MimeMessage msg = new MimeMessage(session);
+    // set To, From, Subject, Date, etc.
+    MimeMultipart mp = new MimeMultipart();
+    // create a body part to contain whatever text you want to include
+    MimeBodyPart mbp = new MimeBodyPart();
+    mbp.setText("Here's the forwarded message\n");
+    mp.addPart(mbp);
+    // create another body part to contain the message to be forwarded
+    MimeBodyPart fmbp = new MimeBodyPart();
+    // forwardedMsg is the MimeMessage object you want to forward
+    // as an attachment
+    fmbp.setContent(forwardedMsg, "message/rfc822");
+    fmbp.setDisposition(Part.ATTACHMENT);
+    mp.addPart(fmbp);
+    msg.setContent(mp);
+
+
+

+

+If instead you want to create the new message with the text of the +original message included in the new message, to forward the message +"inline", you can use an approach such as the following: +

+    String text = (String)forwardedMsg.getContent();
+    String forwardedText = String.format(
+	"\n\n-------- Original Message --------\n" +
+	"Subject: %s\nDate: %s\nFrom: %s\nTo: %s\n",
+	forwardedMsg.getSubject(),
+	forwardedMsg.getSentDate(),
+	forwardedMsg.getFrom()[0],
+	formatAddressList(
+	  forwardedMsg.getRecipients(Message.RecipientType.TO)));
+    // allow user to edit forwardedText,
+    // e.g., using a Swing GUI or a web form
+    msg.setText(forwardedText);
+
+
+

+

+(You'll have to write the formatAddressList method using +the toUnicodeString method of InternetAddress. +You'll also want to include appropriate error checking and test for null +values.) +

+ +

+ +Q: How do I send HTML mail?
+A: There are a number of demo programs included with the +distribution that show how to send HTML mail. If you want to +send a simple message that has HTML instead of plain text, see +the sendhtml.java program in the demo directory. +If you want to send an HTML file as an attachment, see the +sendfile.java example that shows how to send any file +as an attachment. +

+ +

+ +Q: How do I send mail with formatted text using different fonts +and colors? +
+A: The simplest approach is to send a message using HTML text. +See above. +

+ +

+ +Q: How do I send mail with both plain text as well as HTML text +so that each mail reader can choose the format appropriate for it? +
+A: You'll want to send a MIME multipart/alternative +message. You construct such a message essentially the same way you +construct a multipart/mixed message, using a MimeMultipart +object constructed using new MimeMultipart("alternative"). +You then insert the text/plain body part as the first part +in the multpart and insert the text/html body part as the +second part in the multipart. +You'll need to construct the plain and html parts yourself to have +appropriate content. +See RFC2046 +for details of the structure of such a message. +

+ +

+ +Q: How do I send HTML mail that includes images? + +[updated!] +
+A: The simplest approach is to send HTML text with image tags +that reference images on a public web site. In this approach the +images aren't actually included in the message, and so won't be visible +if the user is not connected to the Internet when they read the message. +Note also that some mailers will refuse to display images that are on +remote sites. +

+

+Another approach is to include the image data inline in the html content +of the message, for example: +

+
+	<img src="data:image/jpeg;base64,base64-encoded-data-here" />
+
+

+This works best for relatively small images. +

+

+Alternatively, you can construct a MIME multipart/related +message. See RFC2387 +for details of the structure of such a message. +A simple example follows: +

+
+        Multipart multipart = new MimeMultipart("related");
+
+        MimeBodyPart htmlPart = new MimeBodyPart();
+        // messageBody contains html that references image
+        // using something like <img src="cid:XXX"> where
+        // "XXX" is an identifier that you make up to refer
+        // to the image
+        htmlPart.setText(messageBody, "utf-8", "html");
+        multipart.addBodyPart(htmlPart);
+
+        MimeBodyPart imgPart = new MimeBodyPart();
+        // imageFile is the file containing the image
+        imgPart.attachFile(imageFile);
+        // or, if the image is in a byte array in memory, use
+        // imgPart.setDataHandler(new DataHandler(
+        //      new ByteArrayDataSource(bytes, "image/whatever")));
+
+        // "XXX" below matches "XXX" above in html code
+        imgPart.setContentID("<XXX>");
+        multipart.addBodyPart(imgPart);
+
+        message.setContent(multipart);
+
+

+For more advice, see + +How to Embed Images in Your Emails: The Facts +

+ +

+ +Q: What's the difference between the Transport methods +send and sendMessage? + +
+A: The send() method is a static method and can be +used without needing an instance of a Transport object. It is intended +for the common, simple case of sending a single message using the +default transport. Internally, the send() method will +first call the saveChanges() method on the message. +It will then create an appropriate new Transport object, call the Transport's +connect() method, call the Transport's sendMessage() +method to actually send the message, call the Transport's close() +method, and finally abandon the new instance of the Transport object to be +collected by the garbage collector. +(Actually, it's rather more complicated than that, but that's the general +idea.) +

+

+As you can see, the static send() convenience method is +built on the more general per-instance sendMessage() +method. There are a number of reasons for an application to use the +sendMessage() method directly. The most common reasons are +to improve performance by sending more than one message during a single +connection, or to manually manage the connection so as to provide +authentication information. +

+ +

+ +Q: When I try to send a message I get an error like +SMTPSendFailedException: 530, Address requires authentication. + +[updated!] +
+A: You need to authenticate to your SMTP server. The package +javadocs for the + +com.sun.mail.smtp package describe several methods to do this. +The easiest is to replace the call Transport.send(msg); with +Transport.send(msg, username, password);. +

+

+You'll have to supply the appropriate username and password +needed by your mail server. +

+ +

+ +Q: How do I use SSL or TLS when connecting to my mail server? + +[new!] +
+A: +To use SMTP over SSL, set the mail.smtp.ssl.enable property +in the Session properties. +To use the STARTTLS command set the mail.smtp.starttls.enable +property in the Session properties. +For example: +

+    Properties props = new Properties();
+    props.setProperty("mail.smtp.host", host);
+    props.setProperty("mail.smtp.ssl.enable", "true");
+    // or: props.put("mail.smtp.starttls.enable", "true");
+    Session session = Session.getInstance(props);
+    MimeMessage msg = new MimeMessage(session);
+    // set message content here
+    Transport.send(msg, username, password);
+
+
+

+ +

+ +Q: I need to authenticate to my SMTP server so I call +trans.connect(host, user, password) and then +trans.send(msg) to send the message, but it's not working. + +
+A: You should call +trans.sendMessage(msg, addrs) to send the message. As described +above, the send method is a static +convenience method that acquires its own Transport object and creates +its own connection to use for sending; it does not use the connection +associated with any Transport object through which it is invoked. +

+ +

+ +Q: I modified this message, but the headers do not reflect the changes. +
+A: You should call saveChanges() after you create a +new message or modify an existing message. This will cause the headers to be +reset and reflect your changes. +Note that the Transport.send(Message) method calls this implicitly. +So if all you are doing is sending the modified message, you can +skip calling saveChanges() yourself. +saveChanges() is a potentially expensive operation (especially for +large or deeply nested messages), so call it only when needed. +

+ +

+ +Q: I set a particular value for the Message-ID header of my +new message, but when I send this message that header is rewritten. + +
+A: +A new value for the Message-ID field is set when the saveChanges +method is called (usually implicitly when a message is sent), +overwriting any value you set yourself. If you need +to set your own Message-ID and have it retained, you will have to create +your own MimeMessage subclass, override the updateMessageID method +and use an instance of this subclass. + +

+class MyMessage extends MimeMessage {
+    ...
+
+    protected void updateMessageID() throws MessagingException {
+	setHeader("Message-ID", "my-message-id");
+    }
+    ...
+}
+
+
+
+

+ +

+ +Q: Why do I get an UnsupportedDataTypeException when sending this +new message that I created?
+A: You probably set some content for your message using the +setContent(Object o, String type) method. For this to work, there +must be a JAF DataContentHandler registered for the given "type". +If not, you will get the UnsupportedDataTypeException. See the + +JAF documents +for more information. +In most cases the simplest workaround is to use a +ByteArrayDataSource as described +above. +

+ +

+ +Q: How can I explicitly set the SMTP FROM: attribute when sending a +message? +
+A: The mail.smtp.from property can be used to set the +SMTP FROM: attribute. If this property if absent, the message's From +attribute is used. +If multiple threads need to send mail simultaneously, and each needs +to set the From attribute, each thread should use its own Session object +with its own Properties object. The mail.smtp.from property +can then be set on each Properties object for each Session (and thus +each thread) independently. +Alternatively, each thread can use the com.sun.mail.SMTPMessage +class. The setEnvelopeFrom method on that class can be used +to set this value. With this approach, all threads can use the same Session. +

+ +

+ +Q: I want to repeatedly send messages, to a different set of +recipients each time. But invoking Transport.send(Message) causes +a new Transport session to be established each time. This is +suboptimal in this case, so how do I get around this?
+A: Create an instance of the appropriate Transport object, connect +to it and invoke the sendMessage() method repeatedly. For example: + +

+    MimeMessage msg = ...;
+    // construct message
+    msg.saveChanges();
+    Transport t = session.getTransport("smtp");
+    t.connect();
+
+    for (int i = 0; .....) {
+	t.sendMessage(msg, new Address[] { recipients[i] });
+    }
+
+    t.close();
+
+
+
+

+ +

+ +Q: I get "MessagingException: 501 HELO requires domain address" +when trying to send a message. +
+A: The SMTP provider uses the results of +InetAddress.getLocalHost().getHostName() +in the SMTP HELO command. If that call fails to return any data, no +name is sent in the HELO command. Check your JDK and name server +configuration to ensure that that call returns the correct data. +You may also set the "mail.smtp.localhost" +property to the name you want to use for the HELO command. +

+ +

+ +Q: I get "Must issue a STARTTLS command first" +when trying to send a message. +
+A: Your SMTP server wants you to switch from a plain text connection +to a secure connection using the STARTTLS command. +You can enable use of this command by setting the Session property +"mail.smtp.starttls.enable" to "true". +This will cause the SMTP protocol provider to issue the STARTTLS +command after connecting to the server. +See the file +SSLNOTES.txt +for additional information. +Also, the javadocs for the +com.sun.mail.smtp +package has more information on the properties that can be set. +

+

+Note that your server is most likely also going to want you to authenticate, +as described in this entry. +

+ +

+ +Q: If I send a message to a bad address, why don't I get a +SendFailedException or TransportEvent indicating that the address is +bad?
+A: There is no end-to-end address verification on the Internet. +Often a message will need to be forwarded to several mail servers before +reaching one that can determine whether or not it can deliver the message. +If a failure occurs in one of these later steps, the message will +typically be returned to the sender as undeliverable. A successful +"send" indicates only that the mail server has accepted the message +and will try to deliver it. +

+ +

+ +Q: When a message can't be delivered, a failure message is returned. +How can I detect these "bounced" messages? +
+A: While there is an Internet standard for reporting such errors +(the multipart/report MIME type, see +RFC1892), +it is not widely implemented yet. +RFC1211 +discusses this problem in depth, including numerous examples. +

+

+In Internet email, the existence of a particular mailbox or user +name can only be determined by the ultimate server that would deliver the +message. The message may pass through several relay servers (that are not +able to detect the error) before reaching the end server. Typically, when +the end server detects such an error, it will return a message indicating +the reason for the failure to the sender of the original message. There +are many Internet standards covering such Delivery Status Notifications +but a large number of servers don't support these new standards, instead +using ad hoc techniques for returning such failure messages. This makes +it very difficult to correlate a "bounced" message with the original message +that caused the problem. (Note that this problem is completely independent +of Jakarta Mail.) +Jakarta Mail now includes support for parsing Delivery Status Notifications; +see the NOTES.txt +file in the Jakarta Mail package for details. +

+

+There are a number of techniques and heuristics for dealing with this +problem - none of them perfect. One technique is Variable Envelope +Return Paths, described at +http://cr.yp.to/proto/verp.txt. +The use of VERP with Jakarta Mail and Apache James is described +here. +

+ +

+ +Q: When I construct an InternetAddress object, why don't I get an +exception if the address is illegal? + +
+A: The InternetAddress class only checks the syntax of the address. +As discussed above, the InternetAddress class is not +able to determine whether the address actually exists as a legal address. +It is not even possible to verify the host name if the application is +running behind a firewall or isn't currently connected to the Internet. +

+ +

+ +Q: When I try to send a message, why do I get +javax.mail.SendFailedException: 550 Unable to relay for +my-address? +
+A: This is not a Jakarta Mail problem. This is an error reply from +your SMTP mail server. It indicates that your mail server is not +configured to allow you to send mail through it. Typically, mail servers +for an organization will be configured to allow mail from within the +organization to be sent to other addresses within the organization, +or to addresses external to the organization. It will also typically allow +mail coming from an address external to an organization to be sent to +addresses within the orgnaization. What it will typically not +allow is mail coming from an address external to the organization to be +sent (relayed) to another address also external to the organization. +The configuration of the mail server determines whether such relaying is +allowed, and which addresses are considered internal vs. external. +Often mail servers will require you to +authenticate before they will +relay messages. +

+ +

+ +Q: When I try to send a message to (for example) Yahoo, +why do I get an error that says "connection refused"? +
+A: The host you're trying to connect to is most likely not +running a mail server. If you're trying to connect to a web mail +service such as Yahoo, you can't usually use the web host name +(e.g., "yahoo.com") since this host doesn't run the required +mail server. Instead, you'll need to learn the name of the host +running the required mail server; contact your web mail provider for +this information. You can find this information for Yahoo at + +http://help.yahoo.com/help/us/mail/pop/pop-02.html. +Note that some web mail providers don't offer this service, instead +allowing you to access your mail only through a browser. +

+

+If you're not trying to connect to a web mail account, but instead are +trying to connect to a host on your local network, then most likely the +host you're trying to connect to is not running a mail server. Sometimes +this will occur if you forget to set (for example) the "mail.smtp.host" +property, which will cause you to try to connect to "localhost". Most +Windows machines do not run a mail server, although many UNIX (Solaris, +Linux, etc.) machines do. Thus, attempts to connect to "localhost" on +Windows machines will usually fail with a "connection refused" error. +

+ +

+ +Q: When sending mail, why does it fail with an exception that includes a +message something like +553 To send mail, first check your mail with a valid POP account? + +
+A: In order to prevent their use to send spam, some mail servers +will require you to have a valid POP3 account and require you to login +to that account before they'll let you send mail through that mail server. +This is simple to handle in Jakarta Mail. When you know that you're dealing +with such a mail server, make sure you connect to your POP3 Store on that +mail server before sending mail. +

+ +
+
+

POP3

+
+
+ +

+ +Q: I want to delete messages on a POP3 server. I set the +DELETED flag +on those messages. Then I call the expunge() method, but I get a +MethodNotSupportedException. +How do I delete messages when I use the POP3 provider?
+A: The expunge() method is not supported by the +POP3 provider. Instead, after marking the messages to be deleted +by setting the DELETED flag on those messages, close the folder with +the expunge flag set to true. That is, invoke folder.close(true). +

+ +

+ +Q: How can I retrieve POP3 UIDLs in messages obtained from the POP3 +provider?
+A: This is possible with the POP3 provider. See +the com.sun.mail.pop3 package documentation for details. +

+ +

+ +Q: How can I tell which messages are new with POP3?
+A: The POP3 protocol doesn't provide support for any permanent flags +so the RECENT flag is of no use. The com.sun.mail.pop3 package +documentation discusses several strategies for dealing with this problem. +

+ +

+ +Q: Why does hasNewMessages() always return false when using +POP3?
+A: The POP3 protocol provides no way to determine whether a folder +has new messages. +

+ +

+ +Q: I set up a MessageCountListener (as demonstrated in the +monitor program) but I'm never notified +of new mail in my POP3 INBOX.
+A: The POP3 protocol does not allow the client to see new messages +delivered to the INBOX while the INBOX is open. +The application must close the INBOX and reopen it in order to see any +new messages. You will never be notified of new mail using the +MessageCountListener interface with POP3. See the +com.sun.mail.pop3 package documentation +for more information. +

+ +

+ +Q: Why does getReceivedDate() return null when using +POP3?
+A: The POP3 protocol does not provide information about when a +message was received. It may be possible to guess at the received date +by looking at some message headers such as the Received +header, but this is not very reliable. +

+ +

+ +Q: When using POP3 I get complaints about the SocketFetcher class. + +
+A: Most likely you +have more than one version of pop3.jar or jakarta.mail.jar in your CLASSPATH. +Check the setting of CLASSPATH and +check the "jre/lib/ext" directory in the JDK. +

+ +

+ +Q: When using POP3 I get complaints about the contentStream field. + +
+A: The error usually looks like: +

+

+

+java.lang.NoSuchFieldError: contentStream at
+com.sun.mail.pop3.POP3Message.getContentStream(POP3Message.java:115)
+
+
+

+

+As above, you've mixed versions of the POP3 +provider and jakarta.mail.jar. You probably have an older version of +jakarta.mail.jar in your CLASSPATH before the newer version that includes +the POP3 provider. +

+ +

+ +Q: How do I access or create folders other than INBOX on my POP3 server? + +
+A: You can't. POP3 servers only support a single mailbox per user. +Most mail readers that use POP3 also maintain a local message store into +which they copy incoming messages (from the POP3 INBOX) and allow you to +file messages in other folders. See this item +for more information about local store providers. +

+ +

+ +Q: Why does the getSize method return a negative number +when using POP3? + +
+A: Your POP3 server is broken. The POP3 provider uses the +TOP command to fetch the headers for the message +and the LIST command to determine the size of the +entire message. It then subtracts the two values to determine +the size of the message body. If the server reports the size of +the entire message incorrectly, you may get a negative number. +You can set the property "mail.pop3.disabletop" to "true" to +disable the use of the TOP command, but note that +this will cause any access to the message headers to fetch the +entire message. +

+ +

+ +Q: I'm having problems using POP3 with Microsoft Exchange. + +
+A: Some versions of Microsoft Exchange do not implement the +POP3 protocol properly. They return different headers from the +TOP command than they do from the RETR +command. This can cause all sorts of strange failures in Jakarta Mail. +One solution is to disable use of the TOP command, +as described above. Another approach +that works in some cases os to tell Jakarta Mail to forget about the +headers it retrieved using the TOP command after +retrieving the entire message using the RETR command. +To do this, set the property "mail.pop3.forgettopheaders" to "true". +

+ +
+
+

Jakarta Mail in servlets

+
+
+ +

+ +Q: Can I use Jakarta Mail in servlets? + +
+A: +Yes, see the Installation and Configuration section above for more details. +The Jakarta Mail API is also a required part of the + +Java Platform, Enterprise Edition (Java EE). +No installation or configuration is necessary when using Jakarta Mail +in a Java EE product, it's just there! +

+ +

+ +Q: My web application uses Jakarta Mail to attach and send a file that +the user specifies, but my application can't find the file. + +
+A: If the user species the filename in an HTML form in the browser, +the filename is normally the name of a file on the user's machine, not on +the server. The file will need to be uploaded to the server before +Jakarta Mail can access it. +The +Apache Jakarta Commons FileUpload package can help. +

+ +
+
+

Jakarta Mail in applets

+
+
+ +

+ +Q: Can I use Jakarta Mail in applets? + +
+A: +Yes, Jakarta Mail will work in applets in browsers that support the +required JDK version. +The +Java Plug-in may be required to provide such support. +

+ +

+ +Q: What are the security implications of using Jakarta Mail in an applet? + +
+A: One of the biggest +issues with using Jakarta Mail in applets is the default applet security +restrictions. These restrictions only allow applets to connect to the +host from which they were loaded. Thus, for such applets to use Jakarta Mail, +the mail server will need to be located on the same machine as the web +server from which the applet is loaded. You can find more information +on the applet security model + +here. +

+ +

+ +Q: Ok, maybe I really don't want to use an applet, what should I +do instead? + +
+A: In general, we recommend use of a web application to collect +a mail message and send it using Jakarta Mail. The demo servlet included in +the Jakarta Mail download package illustrates this approach. The + +Email Web Application demo program on the Oracle Technology Network +illustrates another approach using JavaServer Pages. +

diff --git a/www/Gemfile b/www/Gemfile new file mode 100644 index 00000000..4477acdc --- /dev/null +++ b/www/Gemfile @@ -0,0 +1,7 @@ +source "https://rubygems.org" + +gem 'github-pages', group: :jekyll_plugins +#gem 'jekyll-theme-eclipsefdn' +gem 'jekyll-theme-jakarta-ee' + +gem "webrick", "~> 1.7" diff --git a/www/Gemfile.lock b/www/Gemfile.lock new file mode 100644 index 00000000..ed19d90a --- /dev/null +++ b/www/Gemfile.lock @@ -0,0 +1,266 @@ +GEM + remote: https://rubygems.org/ + specs: + activesupport (6.0.6) + concurrent-ruby (~> 1.0, >= 1.0.2) + i18n (>= 0.7, < 2) + minitest (~> 5.1) + tzinfo (~> 1.1) + zeitwerk (~> 2.2, >= 2.2.2) + addressable (2.8.1) + public_suffix (>= 2.0.2, < 6.0) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.11.1) + colorator (1.1.0) + commonmarker (0.23.6) + concurrent-ruby (1.1.10) + dnsruby (1.61.9) + simpleidn (~> 0.1) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + ethon (0.16.0) + ffi (>= 1.15.0) + eventmachine (1.2.7) + execjs (2.8.1) + faraday (2.7.1) + faraday-net_http (>= 2.0, < 3.1) + ruby2_keywords (>= 0.0.4) + faraday-net_http (3.0.2) + ffi (1.15.5) + forwardable-extended (2.6.0) + gemoji (3.0.1) + github-pages (227) + github-pages-health-check (= 1.17.9) + jekyll (= 3.9.2) + jekyll-avatar (= 0.7.0) + jekyll-coffeescript (= 1.1.1) + jekyll-commonmark-ghpages (= 0.2.0) + jekyll-default-layout (= 0.1.4) + jekyll-feed (= 0.15.1) + jekyll-gist (= 1.5.0) + jekyll-github-metadata (= 2.13.0) + jekyll-include-cache (= 0.2.1) + jekyll-mentions (= 1.6.0) + jekyll-optional-front-matter (= 0.3.2) + jekyll-paginate (= 1.1.0) + jekyll-readme-index (= 0.3.0) + jekyll-redirect-from (= 0.16.0) + jekyll-relative-links (= 0.6.1) + jekyll-remote-theme (= 0.4.3) + jekyll-sass-converter (= 1.5.2) + jekyll-seo-tag (= 2.8.0) + jekyll-sitemap (= 1.4.0) + jekyll-swiss (= 1.0.0) + jekyll-theme-architect (= 0.2.0) + jekyll-theme-cayman (= 0.2.0) + jekyll-theme-dinky (= 0.2.0) + jekyll-theme-hacker (= 0.2.0) + jekyll-theme-leap-day (= 0.2.0) + jekyll-theme-merlot (= 0.2.0) + jekyll-theme-midnight (= 0.2.0) + jekyll-theme-minimal (= 0.2.0) + jekyll-theme-modernist (= 0.2.0) + jekyll-theme-primer (= 0.6.0) + jekyll-theme-slate (= 0.2.0) + jekyll-theme-tactile (= 0.2.0) + jekyll-theme-time-machine (= 0.2.0) + jekyll-titles-from-headings (= 0.5.3) + jemoji (= 0.12.0) + kramdown (= 2.3.2) + kramdown-parser-gfm (= 1.1.0) + liquid (= 4.0.3) + mercenary (~> 0.3) + minima (= 2.5.1) + nokogiri (>= 1.13.6, < 2.0) + rouge (= 3.26.0) + terminal-table (~> 1.4) + github-pages-health-check (1.17.9) + addressable (~> 2.3) + dnsruby (~> 1.60) + octokit (~> 4.0) + public_suffix (>= 3.0, < 5.0) + typhoeus (~> 1.3) + html-pipeline (2.14.3) + activesupport (>= 2) + nokogiri (>= 1.4) + http_parser.rb (0.8.0) + i18n (0.9.5) + concurrent-ruby (~> 1.0) + jekyll (3.9.2) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 0.7) + jekyll-sass-converter (~> 1.0) + jekyll-watch (~> 2.0) + kramdown (>= 1.17, < 3) + liquid (~> 4.0) + mercenary (~> 0.3.3) + pathutil (~> 0.9) + rouge (>= 1.7, < 4) + safe_yaml (~> 1.0) + jekyll-avatar (0.7.0) + jekyll (>= 3.0, < 5.0) + jekyll-coffeescript (1.1.1) + coffee-script (~> 2.2) + coffee-script-source (~> 1.11.1) + jekyll-commonmark (1.4.0) + commonmarker (~> 0.22) + jekyll-commonmark-ghpages (0.2.0) + commonmarker (~> 0.23.4) + jekyll (~> 3.9.0) + jekyll-commonmark (~> 1.4.0) + rouge (>= 2.0, < 4.0) + jekyll-default-layout (0.1.4) + jekyll (~> 3.0) + jekyll-feed (0.15.1) + jekyll (>= 3.7, < 5.0) + jekyll-gist (1.5.0) + octokit (~> 4.2) + jekyll-github-metadata (2.13.0) + jekyll (>= 3.4, < 5.0) + octokit (~> 4.0, != 4.4.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-mentions (1.6.0) + html-pipeline (~> 2.3) + jekyll (>= 3.7, < 5.0) + jekyll-optional-front-matter (0.3.2) + jekyll (>= 3.0, < 5.0) + jekyll-paginate (1.1.0) + jekyll-readme-index (0.3.0) + jekyll (>= 3.0, < 5.0) + jekyll-redirect-from (0.16.0) + jekyll (>= 3.3, < 5.0) + jekyll-relative-links (0.6.1) + jekyll (>= 3.3, < 5.0) + jekyll-remote-theme (0.4.3) + addressable (~> 2.0) + jekyll (>= 3.5, < 5.0) + jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) + rubyzip (>= 1.3.0, < 3.0) + jekyll-sass-converter (1.5.2) + sass (~> 3.4) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-sitemap (1.4.0) + jekyll (>= 3.7, < 5.0) + jekyll-swiss (1.0.0) + jekyll-theme-architect (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-cayman (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-dinky (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-hacker (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-jakarta-ee (0.1.4) + jekyll (~> 3.7) + jekyll-theme-leap-day (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-merlot (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-midnight (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-minimal (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-modernist (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-primer (0.6.0) + jekyll (> 3.5, < 5.0) + jekyll-github-metadata (~> 2.9) + jekyll-seo-tag (~> 2.0) + jekyll-theme-slate (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-tactile (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-time-machine (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-titles-from-headings (0.5.3) + jekyll (>= 3.3, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + jemoji (0.12.0) + gemoji (~> 3.0) + html-pipeline (~> 2.2) + jekyll (>= 3.0, < 5.0) + kramdown (2.3.2) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.3) + listen (3.7.1) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.3.6) + minima (2.5.1) + jekyll (>= 3.5, < 5.0) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + minitest (5.16.3) + nokogiri (1.13.9-x86_64-darwin) + racc (~> 1.4) + octokit (4.25.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (4.0.7) + racc (1.6.0) + rb-fsevent (0.11.2) + rb-inotify (0.10.1) + ffi (~> 1.0) + rexml (3.2.5) + rouge (3.26.0) + ruby2_keywords (0.0.5) + rubyzip (2.3.2) + safe_yaml (1.0.5) + sass (3.7.4) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + sawyer (0.9.2) + addressable (>= 2.3.5) + faraday (>= 0.17.3, < 3) + simpleidn (0.2.1) + unf (~> 0.1.4) + terminal-table (1.8.0) + unicode-display_width (~> 1.1, >= 1.1.1) + thread_safe (0.3.6) + typhoeus (1.4.0) + ethon (>= 0.9.0) + tzinfo (1.2.10) + thread_safe (~> 0.1) + unf (0.1.4) + unf_ext + unf_ext (0.0.8.2) + unicode-display_width (1.8.0) + webrick (1.7.0) + zeitwerk (2.6.6) + +PLATFORMS + x86_64-darwin-21 + +DEPENDENCIES + github-pages + jekyll-theme-jakarta-ee + webrick (~> 1.7) + +BUNDLED WITH + 2.3.26 diff --git a/www/Gmail.md b/www/Gmail.md new file mode 100644 index 00000000..3c27ac05 --- /dev/null +++ b/www/Gmail.md @@ -0,0 +1,73 @@ +Gmail +===== + +This page describes hints and tips for using Jakarta Mail with Gmail. Basic +Gmail usage information can be found in the +[Jakarta Mail FAQ](FAQ.html#gmail). + +Gmail users might want to read the +[Gmail Help page](https://support.google.com/mail/topic/7280141?hl=en). +The IMAP features page in Gmail Help no longer exists. +Previous versions (as viewable on the +[Wayback Machine](https://web.archive.org/web/20140918045327/https://support.google.com/mail/answer/78761?hl=en&ref_topic=3397501)) +indicated that Gmail does not support the following IMAP features. +(This list may no longer be accurate.) + +* \Recent flags on messages. +* untagged FETCH responses. +* Substring search. All searches are assumed to be words. +* There is no SIEVE interface to Gmail filters. +* Only AUTH=XOAUTH and plain-text LOGIN over SSL tunneled connections are supported. +* ENVELOPE responses for email addresses in group syntax (RFC 5322 3.4) +* The \Answered flag is not preserved when a message is moved or a label is added to the message. + +To send email using Gmail with a different address than the one you +signed in with, see this +[Gmail help page](https://support.google.com/mail/bin/answer.py?hl=en&answer=22370). + +You may need to enable +[less secure apps](https://www.google.com/settings/security/lesssecureapps) +to use Jakarta Mail with Gmail. + +If the Gmail Auto-Expunge setting is turned on (the default), +when setting the \Deleted flag on a message, Gmail will expunge +the message, causing it to disappear from the mailbox. + +Gmail also includes a setting to control what happens to deleted +and expunged messages (including auto-expunged messages). They +can be archived (left in the [Gmail]/All Mail folder), moved to +the [Gmail]/Trash folder, or removed completely. The default is +to archive the message. + +As of Mar 21, 2011, an old Gmail bug has returned. When reading an +attachment, Gmail fails to return all of the data. This occurs because +Gmail reports the wrong size for the attachment in the BODYSTRUCTURE +response. It reports the size using Unix line terminators instead of +the required MIME line terminators. The bug has been reported to +Google. + +As of Dec 2011, several users have reported an +ArrayIndexOutOfBoundsException when accessing some messages in Gmail. +This is a bug in Gmail involving Subject headers with embedded +newlines. Google expects a fix to be available in mid March 2012. + +As of Jan 2012, Gmail has a bug that causes it to fail to return a +valid IMAP BODYSTRUCTURE response for messages that include another +message as an attachment. Applications may see an exception with a +message of "ENVELOPE parse error". The +[workaround described in the Jakarta Mail FAQ](FAQ.html#imapserverbug) +can be helpful for dealing with such messages. JavaMail 1.4.5 includes +a workaround for this Gmail bug. + +As of Dec 2012, Gmail has a bug that causes it to return a different +value for the getMessageID method than is in the Message-Id header of a +message. The returned Message-Id is "canonicalized". If you need the +actual value in the header, use the getHeader method instead. Google +has no current plans to fix this bug. + +As of Jan 2014, Gmail still only notifies clients of new messages and +expunged messages when using IMAP IDLE. Other flag changes are not +notified. + +As of Aug 2014, Gmail moves expunged messages to the Trash folder. +They're only really removed if expunged from Trash. diff --git a/www/Google-App-Engine.md b/www/Google-App-Engine.md new file mode 100644 index 00000000..24069161 --- /dev/null +++ b/www/Google-App-Engine.md @@ -0,0 +1,9 @@ +Google App Engine +================= + +Google's documentation is +[here](https://developers.google.com/appengine/docs/java/mail). + +Note that GAE limits the headers and attachment types you can use, +as described in the +[Google Cloud documentation](https://cloud.google.com/appengine/docs/standard/java/mail/mail-with-headers-attachments). diff --git a/www/IMAP-Store.md b/www/IMAP-Store.md new file mode 100644 index 00000000..c3fb9a07 --- /dev/null +++ b/www/IMAP-Store.md @@ -0,0 +1,12 @@ +IMAP Store +========== + +The IMAP Store supports reading mail from mail servers using the IMAP +protocol. The primary documentation for the IMAP Store is in the +javadocs for the +[com.sun.mail.imap package](docs/api/com/sun/mail/imap/package-summary.html). +Be sure to read the package level javadocs, which describe the +properties you can set, as well as the javadocs for the individual +classes in the package. + +This page is currently a placeholder for more information about the IMAP Store. diff --git a/www/InstallCert.java b/www/InstallCert.java new file mode 100644 index 00000000..eab76033 --- /dev/null +++ b/www/InstallCert.java @@ -0,0 +1,167 @@ +/* + * Copyright (c) 1997-2017 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Distribution License v. 1.0, which is available at + * http://www.eclipse.org/org/documents/edl-v10.php. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +import java.io.*; +import java.net.URL; + +import java.security.*; +import java.security.cert.*; + +import javax.net.ssl.*; + +public class InstallCert { + + public static void main(String[] args) throws Exception { + String host; + int port; + char[] passphrase; + if ((args.length == 1) || (args.length == 2)) { + String[] c = args[0].split(":"); + host = c[0]; + port = (c.length == 1) ? 443 : Integer.parseInt(c[1]); + String p = (args.length == 1) ? "changeit" : args[1]; + passphrase = p.toCharArray(); + } else { + System.out.println("Usage: java InstallCert [:port] [passphrase]"); + return; + } + + String ksName = + System.getProperty("javax.net.ssl.trustStore", "jssecacerts"); + File file = new File(ksName); + if (file.isFile() == false) { + char SEP = File.separatorChar; + File dir = new File(System.getProperty("java.home") + SEP + + "lib" + SEP + "security"); + file = new File(dir, "jssecacerts"); + if (file.isFile() == false) { + file = new File(dir, "cacerts"); + } + } + System.out.println("Loading KeyStore " + file + "..."); + InputStream in = new FileInputStream(file); + KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType()); + ks.load(in, passphrase); + in.close(); + + SSLContext context = SSLContext.getInstance("TLS"); + TrustManagerFactory tmf = + TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()); + tmf.init(ks); + X509TrustManager defaultTrustManager = (X509TrustManager)tmf.getTrustManagers()[0]; + SavingTrustManager tm = new SavingTrustManager(defaultTrustManager); + context.init(null, new TrustManager[] {tm}, null); + SSLSocketFactory factory = context.getSocketFactory(); + + System.out.println("Opening connection to " + host + ":" + port + "..."); + SSLSocket socket = (SSLSocket)factory.createSocket(host, port); + socket.setSoTimeout(10000); + try { + System.out.println("Starting SSL handshake..."); + socket.startHandshake(); + socket.close(); + System.out.println(); + System.out.println("No errors, certificate is already trusted"); + } catch (SSLException e) { + System.out.println(); + e.printStackTrace(System.out); + } + + X509Certificate[] chain = tm.chain; + if (chain == null) { + System.out.println("Could not obtain server certificate chain"); + return; + } + + BufferedReader reader = + new BufferedReader(new InputStreamReader(System.in)); + + System.out.println(); + System.out.println("Server sent " + chain.length + " certificate(s):"); + System.out.println(); + MessageDigest sha1 = MessageDigest.getInstance("SHA1"); + MessageDigest md5 = MessageDigest.getInstance("MD5"); + for (int i = 0; i < chain.length; i++) { + X509Certificate cert = chain[i]; + System.out.println + (" " + (i + 1) + " Subject " + cert.getSubjectDN()); + System.out.println(" Issuer " + cert.getIssuerDN()); + sha1.update(cert.getEncoded()); + System.out.println(" sha1 " + toHexString(sha1.digest())); + md5.update(cert.getEncoded()); + System.out.println(" md5 " + toHexString(md5.digest())); + System.out.println(); + } + + System.out.println("Enter certificate to add to trusted keystore or 'q' to quit: [1]"); + String line = reader.readLine().trim(); + int k; + try { + k = (line.length() == 0) ? 0 : Integer.parseInt(line) - 1; + } catch (NumberFormatException e) { + System.out.println("KeyStore not changed"); + return; + } + + X509Certificate cert = chain[k]; + String alias = host + "-" + (k + 1); + ks.setCertificateEntry(alias, cert); + + OutputStream out = new FileOutputStream(ksName); + ks.store(out, passphrase); + out.close(); + + System.out.println(); + System.out.println(cert); + System.out.println(); + System.out.println + ("Added certificate to keystore '" + ksName + "' using alias '" + + alias + "'"); + } + + private static final char[] HEXDIGITS = "0123456789abcdef".toCharArray(); + + private static String toHexString(byte[] bytes) { + StringBuilder sb = new StringBuilder(bytes.length * 3); + for (int b : bytes) { + b &= 0xff; + sb.append(HEXDIGITS[b >> 4]); + sb.append(HEXDIGITS[b & 15]); + sb.append(' '); + } + return sb.toString(); + } + + private static class SavingTrustManager implements X509TrustManager { + + private final X509TrustManager tm; + private X509Certificate[] chain; + + SavingTrustManager(X509TrustManager tm) { + this.tm = tm; + } + + public X509Certificate[] getAcceptedIssuers() { + throw new UnsupportedOperationException(); + } + + public void checkClientTrusted(X509Certificate[] chain, String authType) + throws CertificateException { + throw new UnsupportedOperationException(); + } + + public void checkServerTrusted(X509Certificate[] chain, String authType) + throws CertificateException { + this.chain = chain; + tm.checkServerTrusted(chain, authType); + } + } + +} diff --git a/www/InstallCert.md b/www/InstallCert.md new file mode 100644 index 00000000..d2f9bdb4 --- /dev/null +++ b/www/InstallCert.md @@ -0,0 +1,182 @@ +No more 'unable to find valid certification path to requested target' +===================================================================== + +(This page was rescued from Andreas Sterbenz's blog on blogs.sun.com, +which no longer exists.) + +Monday Oct 09, 2006 + +No more 'unable to find valid certification path to requested target' + +Some of you may be familiar with the (not very user friendly) exception +message javax.net.ssl.SSLHandshakeException: +sun.security.validator.ValidatorException: PKIX path building failed: +sun.security.provider.certpath.SunCertPathBuilderException: unable to +find valid certification path to requested target when trying to open +an SSL connection to a host using JSSE. What this usually means is that +the server is using a test certificate (possibly generated using +keytool) rather than a certificate from a well known commercial +Certification Authority such as Verisign or GoDaddy. Web browsers +display warning dialogs in this case, but since JSSE cannot assume an +interactive user is present it just throws an exception by default. + +Certificate validation is a very important part of SSL security, but I +am not writing this entry to explain the details. If you are +interested, you can start by reading the Wikipedia blurb. I am writing +this entry to show a simple way to talk to that host with the test +certificate, if you really want to. + +Basically, you want to add the server's certificate to the KeyStore +with your trusted certificates. There are any number of ways to achieve +that, but a simple solution is to compile and run +[this program](InstallCert.java) +as java InstallCert hostname, for example + + % java InstallCert ecc.fedora.redhat.com + Loading KeyStore /usr/jdk/instances/jdk1.5.0/jre/lib/security/cacerts... + Opening connection to ecc.fedora.redhat.com:443... + Starting SSL handshake... + + javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target + at com.sun.net.ssl.internal.ssl.Alerts.getSSLException(Alerts.java:150) + at com.sun.net.ssl.internal.ssl.SSLSocketImpl.fatal(SSLSocketImpl.java:1476) + at com.sun.net.ssl.internal.ssl.Handshaker.fatalSE(Handshaker.java:174) + at com.sun.net.ssl.internal.ssl.Handshaker.fatalSE(Handshaker.java:168) + at com.sun.net.ssl.internal.ssl.ClientHandshaker.serverCertificate(ClientHandshaker.java:846) + at com.sun.net.ssl.internal.ssl.ClientHandshaker.processMessage(ClientHandshaker.java:106) + at com.sun.net.ssl.internal.ssl.Handshaker.processLoop(Handshaker.java:495) + at com.sun.net.ssl.internal.ssl.Handshaker.process_record(Handshaker.java:433) + at com.sun.net.ssl.internal.ssl.SSLSocketImpl.readRecord(SSLSocketImpl.java:815) + at com.sun.net.ssl.internal.ssl.SSLSocketImpl.performInitialHandshake(SSLSocketImpl.java:1025) + at com.sun.net.ssl.internal.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1038) + at InstallCert.main(InstallCert.java:63) + Caused by: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target + at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:221) + at sun.security.validator.PKIXValidator.engineValidate(PKIXValidator.java:145) + at sun.security.validator.Validator.validate(Validator.java:203) + at com.sun.net.ssl.internal.ssl.X509TrustManagerImpl.checkServerTrusted(X509TrustManagerImpl.java:172) + at InstallCert$SavingTrustManager.checkServerTrusted(InstallCert.java:158) + at com.sun.net.ssl.internal.ssl.JsseX509TrustManager.checkServerTrusted(SSLContextImpl.java:320) + at com.sun.net.ssl.internal.ssl.ClientHandshaker.serverCertificate(ClientHandshaker.java:839) + ... 7 more + Caused by: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target + at sun.security.provider.certpath.SunCertPathBuilder.engineBuild(SunCertPathBuilder.java:236) + at java.security.cert.CertPathBuilder.build(CertPathBuilder.java:194) + at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:216) + ... 13 more + + Server sent 2 certificate(s): + + 1 Subject CN=ecc.fedora.redhat.com, O=example.com, C=US + Issuer CN=Certificate Shack, O=example.com, C=US + sha1 2e 7f 76 9b 52 91 09 2e 5d 8f 6b 61 39 2d 5e 06 e4 d8 e9 c7 + md5 dd d1 a8 03 d7 6c 4b 11 a7 3d 74 28 89 d0 67 54 + + 2 Subject CN=Certificate Shack, O=example.com, C=US + Issuer CN=Certificate Shack, O=example.com, C=US + sha1 fb 58 a7 03 c4 4e 3b 0e e3 2c 40 2f 87 64 13 4d df e1 a1 a6 + md5 72 a0 95 43 7e 41 88 18 ae 2f 6d 98 01 2c 89 68 + + Enter certificate to add to trusted keystore or 'q' to quit: [1] + +What happened was that the program opened a connection to the specified +host and started an SSL handshake. It printed the exception stack trace +of the error that occured and shows you the certificates used by the +server. Now it prompts you for the certificate you want to add to your +trusted KeyStore. You should only do this if you are sure that this is +the certificate of the trusted host you want to connect to. You may +want to check the MD5 and SHA1 certificate fingerprints against a +fingerprint generated on the server (e.g. using keytool) to make sure +it is the correct certificate. + +If you've changed your mind, enter 'q'. If you really want to add the +certificate, enter '1'. (You could also add a CA certificate by +entering a different certificate, but you usually don't want to do +that'). Once you have made your choice, the program will print the +following: + + [ + [ + Version: V3 + Subject: CN=ecc.fedora.redhat.com, O=example.com, C=US + Signature Algorithm: MD5withRSA, OID = 1.2.840.113549.1.1.4 + + Key: SunPKCS11-Solaris RSA public key, 1024 bits (id 5158256, session object) + modulus: 1402933022884660852748661816869706021655226675890 + 635441166580364941191074987345500771612454338502131694873337 + 233737712894815966313948609351561047977102880577818156814678 + 041303637255354084762814638611185951230474669455913908815827 + 173696651397340074281578017567044868711049821409365743953199 + 69584127568303024757 + public exponent: 65537 + Validity: [From: Wed Jan 18 13:16:12 PST 2006, + To: Wed Apr 18 14:16:12 PDT 2007] + Issuer: CN=Certificate Shack, O=example.com, C=US + SerialNumber: [ 0f] + + Certificate Extensions: 2 + [1]: ObjectId: 2.16.840.1.113730.1.1 Criticality=false + NetscapeCertType [ + SSL server + ] + + [2]: ObjectId: 2.5.29.15 Criticality=false + KeyUsage [ + Key_Encipherment + ] + + ] + Algorithm: [MD5withRSA] + Signature: + 0000: 6D F4 2A 63 76 2A 05 70 A2 21 0E 1E 4A 31 BE 6B m.*cv*.p.!..J1.k + 0010: 15 64 D8 BB 35 36 82 B0 0D 2A 96 FA 7A 9F A1 59 .d..56...*..z..Y + 0020: CA 90 C3 28 C5 A6 9B 59 05 3B EB B2 8D C9 5E 38 ...(...Y.;....^8 + 0030: 62 ED 1A D7 93 DF 2A A5 D6 54 94 23 15 A2 0C E5 b.....*..T.#.... + 0040: 13 40 2C 3E 59 E4 2A EB 51 AC 9E 28 44 23 87 B1 .@,>Y.*.Q..(D#.. + 0050: 34 0B AC F3 E0 39 CA B8 35 B4 78 07 BF 28 4C C4 4....9..5.x..(L. + 0060: 9A 2B A3 E9 04 26 78 19 F0 62 EA 0A B5 BB DC 0B .+...&x..b...... + 0070: 90 59 E7 77 90 F8 BC 8A 1B 74 4B 4D C1 F8 3B 6C .Y.w.....tKM..;l + + ] + + Added certificate to keystore 'jssecacerts' using alias 'ecc.fedora.redhat.com-1' + +It displayed the complete certificate and then added it to a Java +KeyStore 'jssecacerts' in the current directory. To use it in your +program, either configure JSSE to use it as its trust store (as +explained in the documentation) or copy it into your +\$JAVA\_HOME/jre/lib/security directory. If you want all Java +applications to recognize the certificate as trusted and not just JSSE, +you could also overwrite the cacerts file in that directory. + +After all that, JSSE will be able to complete a handshake with the +host, which you can verify by running the program again: + + % java InstallCert ecc.fedora.redhat.com + Loading KeyStore jssecacerts... + Opening connection to ecc.fedora.redhat.com:443... + Starting SSL handshake... + + No errors, certificate is already trusted + + Server sent 2 certificate(s): + + 1 Subject CN=ecc.fedora.redhat.com, O=example.com, C=US + Issuer CN=Certificate Shack, O=example.com, C=US + sha1 2e 7f 76 9b 52 91 09 2e 5d 8f 6b 61 39 2d 5e 06 e4 d8 e9 c7 + md5 dd d1 a8 03 d7 6c 4b 11 a7 3d 74 28 89 d0 67 54 + + 2 Subject CN=Certificate Shack, O=example.com, C=US + Issuer CN=Certificate Shack, O=example.com, C=US + sha1 fb 58 a7 03 c4 4e 3b 0e e3 2c 40 2f 87 64 13 4d df e1 a1 a6 + md5 72 a0 95 43 7e 41 88 18 ae 2f 6d 98 01 2c 89 68 + + Enter certificate to add to trusted keystore or 'q' to quit: [1] + q + KeyStore not changed + +I hope that helps. For more information about the InstallCert program, +have a look at the source code. I am sure you can figure out how it +works. + +Posted at 22:28 Oct 09, 2006 by Andreas Sterbenz in Java diff --git a/www/JakartaMail-License.md b/www/JakartaMail-License.md new file mode 100644 index 00000000..bf7087c2 --- /dev/null +++ b/www/JakartaMail-License.md @@ -0,0 +1,29 @@ +Jakarta Mail License +==================== + +Jakarta Mail uses several licenses: + +- Most of the Jakarta Mail source code is licensed under the + [Eclipse Public License (EPL) v2.0](http://www.eclipse.org/legal/epl-2.0) + and [GNU General Public License (GPL) v2 with Classpath Exception]( + https://www.gnu.org/software/classpath/license.html); + see the license information at the top of each source file. +- The source code for the forked copy of Jakarta Activation + is licensed under the + [Eclipse Distribution License (EDL) v1.0]( + http://www.eclipse.org/org/documents/edl-v10.php); + again, the license is in each source file. +- The source code for the demo programs is licensed under the + [Eclipse Distribution License (EDL) v1.0]( + http://www.eclipse.org/org/documents/edl-v10.php). +- The binary jar files published to the Maven repository are licensed + under the same licenses as the corresponding source + code; see the file `META-INF/LICENSE.txt` in each jar file. + +You'll find the text of the licenses in the workspace in various +`LICENSE.txt` or `LICENSE.md` files. +Don't let the presence of these license files in the workspace confuse +you into thinking that they apply to all files in the workspace. + +You should always read the license file included with every download, +and read the license text included in every source file. diff --git a/www/Links.md b/www/Links.md new file mode 100644 index 00000000..bdbc040f --- /dev/null +++ b/www/Links.md @@ -0,0 +1,63 @@ +# Links + +Here are some links to sites with lots of good information on Internet +mail and some articles on the Jakarta Mail API. If you know of other good +sources of such information, please let us know at mail-dev@eclipse.org. + +* + JavaMail Client on the NetBeans Platform by Geertjan Wielenga + (first of a multi-part series) + +* + Test email components in your software by Jason Kitchen + +* + JavaMail Quick Start by Tony Loton + +* + Java Tip 115: Secure JavaMail with JSSE by Eugen Kuleshov and + Dmitry I. Platonoff + +* + Email Web Application using JSP Tag Libraries + +* The MIME Information Page + +* + How Internet Mail Works by Dave Sill + +* SMTP Inside Out + by Heinz Tschabitscher + +* + Behind the Scenes: How Email Works + +* E-mail in Wikipedia + +* + How E-mail Works by Marshall Brain and Tim Crosby + +* + Deciphering Internet E-mail in Webopedia + +* jGuru JavaMail FAQ + +* JavaMail, by Ian Moraes, in + + Java Developer's Journal, October 1999 (Registration required.) + +* What Is JavaMail?, by Rachel Gollub, in + + Java Developer's Journal, October 1999 (Registration required.) + +* + Managing e-zines with JavaMail and XSLT, Part 1 by + Benoît Marchal + +* + Managing e-zines with JavaMail and XSLT, Part 2 by + Benoît Marchal + +* + Introduction to the Java Mail API by Tony Nemil and Anil Hemrajani diff --git a/www/Mbox-Provider.md b/www/Mbox-Provider.md new file mode 100644 index 00000000..54978440 --- /dev/null +++ b/www/Mbox-Provider.md @@ -0,0 +1,30 @@ +Jakarta Mail Mbox Provider +========================== + +The mbox provider is a Jakarta Mail local store provider that manages files +in [ Unix mbox format ](http://en.wikipedia.org/wiki/Mbox) +(in particular, the *mboxcl2* variant). + +The mbox provider has only been tested on Solaris, OpenSolaris +and distributions based on Debian. +I tried it once on Windows, long ago, but there's no file +locking support for use on Windows. On Solaris and OpenSolaris it +depends on native file locking code. + +To build the mbox provider for Solaris/OpenSolaris: + + % (cd mbox; mvn) + % (cd mbox/native; mvn) + +To build the mbox provider for distributions based on Debian: + + % (cd mbox; mvn) + % (cd mbox/native; mvn -Plinux) + +This depends on having the **c89** command in your PATH. + +For based on Debian you need to have installed liblockfile-dev package. + +To use the mbox provider you'll need to add mbox/target/mbox.jar to +your CLASSPATH and add mbox/native/target/libmbox.so to your +LD\_LIBRARY\_PATH. diff --git a/www/Mbox-Store.md b/www/Mbox-Store.md new file mode 100644 index 00000000..ca929db5 --- /dev/null +++ b/www/Mbox-Store.md @@ -0,0 +1,83 @@ +mbox Store +========== + +The mbox Store supports reading messages from files in the UNIX +[mbox](http://en.wikipedia.org/wiki/Mbox) format. The mbox Store is +included in the Jakarta Mail source code, but is not currently distributed +with Jakarta Mail. To use the mbox Store, you'll need to build it +yourself. + +### File Locking + +The mbox Store supports several file locking choices. To properly +interact with other native programs accessing UNIX mailboxes, native +file locking code is required. This native file locking code has only +been tested on Solaris, and requires a native compiler to build. Native +code is used to access the Solaris mailbox locking functions in the +libmail library. Unfortunately, the mailbox locking protocol depends on +creating hard links, which is not supported before JDK 7. + +The mbox Store can also use Java file locking support, which will allow +coordination between multiple applications using the mbox Store, but +not with native applications accessing the same mailboxes. + +Finally, the mbox Store can operate with no locking at all. This is +only appropriate if you're sure that only a single instance of your +Java application is accessing the mailbox, and no native applications +are accessing the mailbox. You'll need to coordinate access to the +mailbox within your application to ensure that each mailbox is accessed +by only a single thread at a time. + +The file locking options are selected by setting the mail.mbox.locktype +System property: + +|Lock Type|Description| +|---------|-----------| +|native|This is the default, which requires native code as described above.| +|java|This uses java.nio.channels.FileLock.| +|none|No file locking is done| + +### Mailbox Names + +Mailbox names are of the form **mbox:*name***. If ***name*** is a +relative path name, it is normally relative to the current directory. +If the System property mail.mbox.homerelative is set to true, relative +names are relative to the current user's home directory. + +The mailbox name can also be of the form **mbox:\~/*name***, which is +always relative to the current user's home directory, or +**mbox:\~*user/name***, which is relative to the given user's home +directory. (The latter only works on Solaris.) + +The mailbox name **mbox:INBOX** is the current user's Inbox, e.g., in +/var/mail on Solaris. + +### Build Instructions + +To build the mbox Store provider, assuming the "c89" compiler is in +your PATH and the JDK is in /usr/java: + + export MACH=`uname -p` + export JAVA_HOME=/usr/java + cd mbox + mvn + cd native + mvn + +In distributions based on Debian you need to to have installed +liblockfile-dev package and use the profile **linux** when executing +mvn in the native folder: + + mvn -Plinux + +You can override the default options for the compiler and linker for +the native component by specifying Maven properties. The defaults +correspond to this: + + mvn -Dcompiler.name=c89 \ + -Dcompiler.start.options='-Xa -xO2 -v -D_REENTRANT -I${env.JAVA_HOME}/include -I${env.JAVA_HOME}/include/solaris' \ + -Dlinker.name=c89 \ + -Dlinker.start.options='-G' \ + -Dlinker.end.options='-L${env.JAVA_HOME}/jre/lib/${env.MACH} -lmail -ljava -lc' + +XXX - Still need to provide more information. diff --git a/www/OAuth2.md b/www/OAuth2.md new file mode 100644 index 00000000..3632079d --- /dev/null +++ b/www/OAuth2.md @@ -0,0 +1,91 @@ +OAuth2 Support +============== + +JavaMail 1.5.5 and later +------------------------ + +Starting with JavaMail 1.5.5, support for +[OAuth2 authentication](https://tools.ietf.org/html/rfc6749) +[as used for email](https://developers.google.com/gmail/xoauth2_protocol) +is built-in and no longer requires SASL (although the SASL OAuth2 +support continues to work). + +Since OAuth2 uses an "access token" instead of a password, you'll want +to configure JavaMail to use only the XOAUTH2 mechanism. The access +token is passed as the password, which obviously won't work with any of +the other authentication mechanisms. For example, to access Gmail: + + Properties props = new Properties(); + props.put("mail.imap.ssl.enable", "true"); // required for Gmail + props.put("mail.imap.auth.mechanisms", "XOAUTH2"); + Session session = Session.getInstance(props); + Store store = session.getStore("imap"); + store.connect("imap.gmail.com", username, oauth2_access_token); + +You'll need to acquire an OAuth2 access token to be used for the +session, e.g., using +[these Google tools](http://code.google.com/p/google-mail-oauth2-tools/wiki/JavaSampleCode) +and the procedure described +[here](http://code.google.com/apis/accounts/docs/OAuth2.html) +to obtain OAuth2 credentials from the +[Google Developers Console](https://console.developers.google.com/). +In particular, you'll need the Client ID and the Client secret from the +Google Developers Console for use with the oauth2.py program to +generate a Refresh Token, from which you can generate an Access Token. +(Note that the OAuth2 access token does **not** need to be base64 +encoded first; the XOAUTH2 provider will do that. Note also that the +Google OAuth2 provider at the link above is **not** needed, only the +oauth2.py program to generate an access token.) + +The use of OAuth2 with Yahoo services is described +[here](https://developer.yahoo.com/oauth2/guide/openid_connect/getting_started.html), +although +[it's not clear that this still works](http://stackoverflow.com/questions/36058534/how-can-yahoo-mail-be-accessed-by-imap-using-oauth-or-oauth2-authentication) +since Yahoo will no longer allow you to create an app with Mail permissions. + +To connect to Outlook.com using OAuth2, see +[this page](http://technet.microsoft.com/en-ca/dn440163) +and the procedure described +[here](http://technet.microsoft.com/en-ca/hh243647) +for creating a Refresh Token and Access Token. +Get your Client ID and Client secret from the +[Microsoft account Developer Center](https://account.live.com/developers/applications). +The general procedure above should work to connect to +imap-mail.outlook.com, but the access token will need to be acquired as +described on the Outlook.com page. + +OAuth2 is also supported with SMTP; change "imap" to "smtp" in the +property names. OAuth2 is **not** supported for pop3. + +Please send feedback to [mail-dev@eclipse.org](https://accounts.eclipse.org/mailing-list/mail-dev). + + +JavaMail 1.5.2 and later +------------------------ + +Starting with JavaMail 1.5.2, support for +[OAuth2 authentication](https://developers.google.com/gmail/xoauth2_protocol) +via the [SASL](http://www.ietf.org/rfc/rfc4422.txt) XOAUTH2 mechanism +is included. Please send feedback to [mail-dev@eclipse.org](https://accounts.eclipse.org/mailing-list/mail-dev). + +The SASL XOAUTH2 provider will be +[added to the Java security configuration](http://docs.oracle.com/javase/7/docs/api/java/security/Security.html#addProvider(java.security.Provider)) +when SASL support is first used. The application must have the +permission `SecurityPermission("insertProvider.JavaMail-OAuth2")`. + +Since OAuth2 uses an "access token" instead of a password, you'll want +to configure JavaMail to use only the SASL XOAUTH2 mechanism. The +access token is passed as the password, which obviously won't work with +any of the other authentication mechanisms. For example, to access +Gmail: + + Properties props = new Properties(); + props.put("mail.imap.ssl.enable", "true"); // required for Gmail + props.put("mail.imap.sasl.enable", "true"); + props.put("mail.imap.sasl.mechanisms", "XOAUTH2"); + props.put("mail.imap.auth.login.disable", "true"); + props.put("mail.imap.auth.plain.disable", "true"); + Session session = Session.getInstance(props); + Store store = session.getStore("imap"); + store.connect("imap.gmail.com", username, oauth2_access_token); + diff --git a/www/Outlook.md b/www/Outlook.md new file mode 100644 index 00000000..1be61879 --- /dev/null +++ b/www/Outlook.md @@ -0,0 +1,5 @@ +*This page should have a lot more information about Outlook.com. For +now it's just a collection of notes.* + +As of Oct 2013, outlook.com fails to find messages using a date range +search - start \<= msg \<= end. diff --git a/www/POP3-Remote-Store.md b/www/POP3-Remote-Store.md new file mode 100644 index 00000000..f4ce8842 --- /dev/null +++ b/www/POP3-Remote-Store.md @@ -0,0 +1,13 @@ +POP3 Remote Store +================= + +The POP3 Remote Store is an experimental Store that behaves much the +way a typical email client expects when using POP3. That is, all +messages and all folders are really stored locally (in this case using +the [Mbox Store](Mbox-Store)), and new messages are fetched +from the server using the POP3 protocol. + +The POP3 Remote Store is not currently distributed with Jakarta Mail, but +is included in the Jakarta Mail source code in the mbox project. + +XXX - still need to provide more information here. diff --git a/www/POP3-Store.md b/www/POP3-Store.md new file mode 100644 index 00000000..44ff093c --- /dev/null +++ b/www/POP3-Store.md @@ -0,0 +1,12 @@ +POP3 Store +========== + +The POP3 Store supports reading mail from mail servers using the POP3 +protocol. The primary documentation for the POP3 Store is in the +javadocs for the +[com.sun.mail.pop3 package](docs/api/com/sun/mail/pop3/package-summary.html). +Be sure to read the package level javadocs, which describe the +properties you can set, as well as the javadocs for the individual +classes in the package. + +This page is currently a placeholder for more information about the POP3 Store. diff --git a/www/README-JakartaMail.md b/www/README-JakartaMail.md new file mode 100644 index 00000000..cb4e55bd --- /dev/null +++ b/www/README-JakartaMail.md @@ -0,0 +1,317 @@ +# Table of Contents +* [Latest News](#Latest_News) +* [Download Jakarta Mail Release](#Download_Jakarta_Mail_Release) +* [API Documentation](#API_Documentation) +* [Samples](#Samples) +* [Help](#Help) +* [Bugs](#Bugs) +* [Development Releases](#Development_Releases) +* [Jakarta Mail for Android](#Jakarta_Mail_for_Android) +* [Project Documentation](#Project_Documentation) + +
+ +# Latest News + +## August 18, 2021 - Jakarta Mail implementation moves to Eclipse Angus ## + +To break tight integration between Jakarta Mail Specification API and the implementation, +sources of the implementation were moved to the new +project - [Eclipse Angus](https://eclipse-ee4j.github.io/angus-mail) - +and further development continues there. +Eclipse Angus is the direct successor of JavaMail/JakartaMail. + +## April 8, 2021 - Jakarta Mail 1.6.7 Final Release ## + +The 1.6.7 release is a bug fix release of the Jakarta Mail project +in the 1.x line, and includes several bug fixes and enhancements. +The main jar file is located at +[com.sun.mail:jakarta.mail](https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/1.6.7/jakarta.mail-1.6.7.jar). + +## April 6, 2021 - Jakarta Mail 2.0.1 Final Release ## + +The 2.0.1 release is a bug fix release of the Jakarta Mail project +in the 2.x line, and includes several bug fixes and enhancements. +The main jar file is located at +[com.sun.mail:jakarta.mail](https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/2.0.1/jakarta.mail-2.0.1.jar). + +## February 28, 2021 - Jakarta Mail 1.6.6 Final Release ## + +The 1.6.6 release is a bug fix release of the Jakarta Mail project +in the 1.x line, and includes several bug fixes and enhancements. +The main jar file is located at +[com.sun.mail:jakarta.mail](https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/1.6.6/jakarta.mail-1.6.6.jar). + + +## October 23, 2020 - Jakarta Mail 2.0.0 Final Release ## + +Jakarta Mail 2.0.0 release is the first release with package +namespace changed to `jakarta.mail`. The main jar file +is located at [com.sun.mail:jakarta.mail](https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/2.0.0/jakarta.mail-2.0.0.jar). + +This release contains no other enhancements nor bug fixes, +except for the minimal required Java SE version which is now Java SE 8. +This is also the release included in Jakarta EE 9. +Applications are able to switch to this new version +by just changing all imports that use `javax.mail.*` +to instead use `jakarta.mail.*`. + +## March 10, 2020 - Jakarta Mail 1.6.5 Final Release ## + +The 1.6.5 release is (hopefully) the last release of the Jakarta Mail project +in the 1.x line, and includes several bug fixes and enhancements. +The main jar file is located at +[com.sun.mail:jakarta.mail](https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/1.6.5/jakarta.mail-1.6.5.jar). + +Jakarta Mail, like other parts of [Jakarta EE](https://jakarta.ee), +is moving to the `jakarta.*` package namespace. +This is a major change, and so the next release will be Jakarta Mail 2.0.0, +which will be included in Jakarta EE 9. +Applications should be able to switch to this new version fairly easily +by just changing all imports that use `javax.mail.*` to instead use +`jakarta.mail.*`. + +## August 28, 2019 - Jakarta Mail 1.6.4 Final Release ## + +The 1.6.4 release is the first release of the Jakarta Mail project using the +[Jakarta EE Specification Process](https://jakarta.ee/about/jesp/) +and includes several bug fixes and enhancements. +The main jar file is located at +[com.sun.mail:jakarta.mail](https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/1.6.4/jakarta.mail-1.6.4.jar). + +## July 3, 2019 - Jakarta Mail is the new name for JavaMail ## + +The JavaMail technology contributed to the Eclipse Foundation has been renamed +to "Jakarta Mail" to reflect its role in the +[Jakarta EE platform](https://jakarta.ee/). + +## November 26, 2018 - JavaMail 1.6.3 Final Release ## + +The 1.6.3 release is the first release of the Eclipse project for JavaMail +and includes no bug fixes or enhancements. It does include changes +to the Maven coordinates. The main jar file is now located at +[com.sun.mail:jakarta.mail](https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/1.6.3/jakarta.mail-1.6.3.jar). + +## September 14, 2018 - JavaMail project moves to the Eclipse Foundation! ## + +The JavaMail project is now hosted at the Eclipse Foundation as part of +the [EE4J project](https://projects.eclipse.org/projects/ee4j). + +
+ +# Download Jakarta Mail Release + +The latest release of Jakarta Mail is 2.0.1. + +The following table provides easy access to the latest release. Most +people will only need the main Jakarta Mail implementation in the +jakarta.mail.jar file. + +|Item|Description| +|:---|:----------| +|[jakarta.mail.jar](https://github.com/eclipse-ee4j/mail/releases/download/2.0.1/jakarta.mail-2.0.1.jar/jakarta.mail-2.0.1.jar)|The Jakarta Mail implementation, including the SMTP, IMAP, and POP3 protocol providers| +|[README.txt](docs/README.txt)|Overview of the release| +|[NOTES.txt](docs/NOTES.txt)|Additional notes about using Jakarta Mail| +|[SSLNOTES.txt](docs/SSLNOTES.txt)|Notes on using SSL/TLS with Jakarta Mail| +|[NTLMNOTES.txt](docs/NTLMNOTES.txt)|Notes on using NTLM authentication with Jakarta Mail| +|[CHANGES.txt](docs/CHANGES.txt)|Changes since the previous release| +|[COMPAT.txt](docs/COMPAT.txt)|Important notes about compatibility| + + +In addition, the Jakarta Mail jar files are published to the Maven repository. +The main Jakarta Mail jar file, which is all most applications will need, +can be included using this Maven dependency: +``` + + + com.sun.mail + jakarta.mail + 2.0.1 + + +``` +You can find all of the Jakarta Mail jar files in +[Maven Central](http://search.maven.org). + + +|jar file|groupId|artifactId|Description| +|:-------|:------|:---------|:----------| +|[jakarta.mail.jar](https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/2.0.1/jakarta.mail-2.0.1.jar)|com.sun.mail|jakarta.mail|The Jakarta Mail implementation jar file, including the SMTP, IMAP, and POP3 protocol providers| +|[jakarta.mail-api.jar](https://repo1.maven.org/maven2/jakarta/mail/jakarta.mail-api/2.0.1/jakarta.mail-api-2.0.1.jar)|jakarta.mail|jakarta.mail-api|The Jakarta Mail API definitions only, suitable for compiling against; use only with a Maven "provided" dependency scope| +|[mailapi.jar](https://repo1.maven.org/maven2/com/sun/mail/mailapi/2.0.1/mailapi-2.0.1.jar)|com.sun.mail|mailapi|The Jakarta Mail implementation with no protocol providers; use with one of the following providers| +|[smtp.jar](https://repo1.maven.org/maven2/com/sun/mail/smtp/2.0.1/smtp-2.0.1.jar)|com.sun.mail|smtp|The SMTP protocol provider| +|[imap.jar](https://repo1.maven.org/maven2/com/sun/mail/imap/2.0.1/imap-2.0.1.jar)|com.sun.mail|imap|The IMAP protocol provider| +|[pop3.jar](https://repo1.maven.org/maven2/com/sun/mail/pop3/2.0.1/pop3-2.0.1.jar)|com.sun.mail|pop3|The POP3 protocol provider| +|[gimap.jar](https://repo1.maven.org/maven2/com/sun/mail/gimap/2.0.1/gimap-2.0.1.jar)|com.sun.mail|gimap|An EXPERIMENTAL Gmail IMAP protocol provider that supports Gmail-specific features| +|[dsn.jar](https://repo1.maven.org/maven2/com/sun/mail/dsn/2.0.1/dsn-2.0.1.jar)|com.sun.mail|dsn|Support for parsing and creating messages containing Delivery Status Notifications| +|[logging-mailhandler.jar](https://repo1.maven.org/maven2/com/sun/mail/logging-mailhandler/2.0.1/logging-mailhandler-2.0.1.jar)|com.sun.mail|logging-mailhandler|A java.util.logging handler that uses Jakarta Mail, suitable for use in Google App Engine.| + +
+ +# API Documentation + +The Jakarta Mail API is defined through the +[Jakarta EE Specification Process](https://jakarta.ee/about/jesp/). + +The Jakarta Mail specification and API documentation are available +[here](https://jakarta.ee/specifications/mail/). + +Note that Jakarta Mail 1.6 is identical to JavaMail 1.6. + +The JavaMail 1.6 and earlier API is defined through the Java Community Process as +[JSR 919](http://jcp.org/en/jsr/detail?id=919). + +The following documents summarize the API changes in each release of +the JavaMail API specification: + +- [JavaMail 2.0](docs/JavaMail-2.0-changes.txt) +- [JavaMail 1.6](docs/JavaMail-1.6-changes.txt) +- [JavaMail 1.5](docs/JavaMail-1.5-changes.txt) +- [JavaMail 1.4](docs/JavaMail-1.4-changes.txt) +- [JavaMail 1.3](docs/JavaMail-1.3-changes.txt) +- [JavaMail 1.2](docs/JavaMail-1.2-changes.txt) +- [JavaMail 1.1](docs/JavaMail-1.1-changes.txt) + +
+ +# Samples + +Some sample programs showing how to use the Jakarta Mail APIs are available +[here](https://github.com/eclipse-ee4j/mail/releases/download/2.0.1/jakartamail-samples.zip). + +
+ +# Help + +Please read the +[Jakarta Mail FAQ](FAQ.html)! +Read it again. Tell everyone you know to read it. Thank you! + +You can post questions to the +[mail-dev mailing list](https://accounts.eclipse.org/mailing-list/mail-dev). + +Or, post a question on [Stack Overflow](http://stackoverflow.com/) using the +[javamail](http://stackoverflow.com/questions/tagged/javamail) tag. + +
+ +# Bugs + +Jakarta Mail bugs are tracked in the +[GitHub Jakarta Mail project issue tracker](https://github.com/eclipse-ee4j/mail/issues). + +
+ +# Development Releases + +From time to time snapshot releases of the next version of Jakarta Mail +under development are published to the +[Jakarta Sonatype OSS repository](https://jakarta.oss.sonatype.org). +These snapshot releases have received only minimal testing, but may +provide previews of bug fixes or new features under development. + +For example, you can download the jakarta.mail.jar file from the Jakarta Mail +2.0.2-SNAPSHOT release +[here](https://jakarta.oss.sonatype.org/content/repositories/snapshots/com/sun/mail/jakarta.mail/2.0.2-SNAPSHOT/). +Be sure to scroll to the bottom and choose the jar file with the most +recent time stamp. + +You'll need to add the following configuration to your Maven ~/.m2/settings.xml +to be able to use these with Maven: + +``` + + + + jakarta-snapshots + + + jakarta-snapshots + Jakarta Snapshots + + true + always + fail + + https://jakarta.oss.sonatype.org/content/repositories/snapshots/ + default + + + + +``` + +And then when you build use `mvn -Pjakarta-snapshots ...`. + +If you want the plugin repository to be enabled all the time so you don't need the -P, add: + +``` + + jakarta-snapshots + +``` + +
+ +# Jakarta Mail for Android + +The latest release includes support for Jakarta Mail on Android. +See the [Android](Android) page for details. + +
+ +# Project Documentation + +You'll find more information about the protocol providers supported by +Jakarta Mail on the following pages: + +- [ smtp ](SMTP-Transport) +- [ imap ](IMAP-Store) +- [ pop3 ](POP3-Store) +- [ mbox ](Mbox-Store) +- [ pop3remote ](POP3-Remote-Store) + +If you're interested in writing your own protocol provider (most people +won't need to), you can find more documentation on protocol providers +[here](https://javaee.github.io/javamail/docs/Providers.pdf). + +The use of +[OAuth2 authentication](https://developers.google.com/gmail/xoauth2_protocol) +with Jakarta Mail is described [here](OAuth2). + +The following pages provide hints and tips for using particular mail servers: + +- [Gmail](Gmail) +- [ Yahoo! Mail ](Yahoo) +- [ Exchange and Office 365 ](Exchange) +- [ Outlook.com ](Outlook) + +The following pages provide hints and tips for using Jakarta Mail on +particular operating systems or environments: + +- [Windows](Windows) +- [Google App Engine](Google-App-Engine) + +See [Build Instructions](Build-Instructions) for instructions on how to +download and build the most recent Jakarta Mail source code. You can also +find a bundle of the source code for the most recent Jakarta Mail release +in the [Releases](https://github.com/eclipse-ee4j/mail/releases) area of +this project. + +If you're interested in contributing to Jakarta Mail, see the +[Contributions](Contributions) page. + +You can find a list of products related to Jakarta Mail on the +[Third Party Products](ThirdPartyProducts) page. + +Please see our page of +[links to additional information about Jakarta Mail and Internet email](Links) +and our list of +[books about Jakarta Mail and Internet email](Books). + +To understand the Jakarta Mail license, see the [License](JakartaMail-License) page. + +
+ +By contributing to this project, you agree to these additional terms of +use, described in [CONTRIBUTING](CONTRIBUTING.md). diff --git a/www/README.md b/www/README.md new file mode 100644 index 00000000..71381ef4 --- /dev/null +++ b/www/README.md @@ -0,0 +1,222 @@ +
+ +The Jakarta Mail API provides a platform-independent and +protocol-independent framework to build mail and messaging +applications. +The Jakarta Mail API is available as an optional package for use with the +[Java SE platform](http://www.oracle.com/technetwork/java/javase/index.html) +and is also included in the +[Jakarta EE platform](http://jakarta.ee) and the +[Java EE platform](http://www.oracle.com/technetwork/java/javaee/index.html). + +**NOTE:** The documentation for the implementation of this specification, Angus Mail , is available +[here](https://eclipse-ee4j.github.io/angus-mail/), the documentation for older versions, +Jakarta Mail/JavaMail, is available [here](README-JakartaMail) + +
+ +# Table of Contents +* [Latest News](#Latest_News) +* [API Documentation](#API_Documentation) +* [Help](#Help) +* [Bugs](#Bugs) +* [Development Releases](#Development_Releases) + +# Latest News + +## November 20, 2021 - Jakarta Mail 2.1.0 Final Release ## + +The 2.1.0 release breaks the tight integration between Jakarta Mail Specification +API and the implementation and provides standalone API jar file only. +The implementation itself, formerly JakartaMail, is now standalone project - +[Eclipse Angus](https://eclipse-ee4j.github.io/angus-mail/). +This version of the specification is included +in the [Jakarta EE 10 Platform](https://jakarta.ee/specifications/platform/10/). + +## August 18, 2021 - Jakarta Mail implementation moves to Eclipse Angus ## + +To break tight integration between Jakarta Mail Specification API and the implementation, +sources of the implementation were moved to the new +project - [Eclipse Angus](https://eclipse-ee4j.github.io/angus-mail) - +and further development continues there. +Eclipse Angus is the direct successor of JavaMail/JakartaMail. + +## April 8, 2021 - Jakarta Mail 1.6.7 Final Release ## + +The 1.6.7 release is a bug fix release of the Jakarta Mail project +in the 1.x line, and includes several bug fixes and enhancements. +The main jar file is located at +[com.sun.mail:jakarta.mail](https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/1.6.7/jakarta.mail-1.6.7.jar). + +## April 6, 2021 - Jakarta Mail 2.0.1 Final Release ## + +The 2.0.1 release is a bug fix release of the Jakarta Mail project +in the 2.x line, and includes several bug fixes and enhancements. +The main jar file is located at +[com.sun.mail:jakarta.mail](https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/2.0.1/jakarta.mail-2.0.1.jar). + +## February 28, 2021 - Jakarta Mail 1.6.6 Final Release ## + +The 1.6.6 release is a bug fix release of the Jakarta Mail project +in the 1.x line, and includes several bug fixes and enhancements. +The main jar file is located at +[com.sun.mail:jakarta.mail](https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/1.6.6/jakarta.mail-1.6.6.jar). + + +## October 23, 2020 - Jakarta Mail 2.0.0 Final Release ## + +Jakarta Mail 2.0.0 release is the first release with package +namespace changed to `jakarta.mail`. The main jar file +is located at [com.sun.mail:jakarta.mail](https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/2.0.0/jakarta.mail-2.0.0.jar). + +This release contains no other enhancements nor bug fixes, +except for the minimal required Java SE version which is now Java SE 8. +This is also the release included in Jakarta EE 9. +Applications are able to switch to this new version +by just changing all imports that use `javax.mail.*` +to instead use `jakarta.mail.*`. + +## March 10, 2020 - Jakarta Mail 1.6.5 Final Release ## + +The 1.6.5 release is (hopefully) the last release of the Jakarta Mail project +in the 1.x line, and includes several bug fixes and enhancements. +The main jar file is located at +[com.sun.mail:jakarta.mail](https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/1.6.5/jakarta.mail-1.6.5.jar). + +Jakarta Mail, like other parts of [Jakarta EE](https://jakarta.ee), +is moving to the `jakarta.*` package namespace. +This is a major change, and so the next release will be Jakarta Mail 2.0.0, +which will be included in Jakarta EE 9. +Applications should be able to switch to this new version fairly easily +by just changing all imports that use `javax.mail.*` to instead use +`jakarta.mail.*`. + +## August 28, 2019 - Jakarta Mail 1.6.4 Final Release ## + +The 1.6.4 release is the first release of the Jakarta Mail project using the +[Jakarta EE Specification Process](https://jakarta.ee/about/jesp/) +and includes several bug fixes and enhancements. +The main jar file is located at +[com.sun.mail:jakarta.mail](https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/1.6.4/jakarta.mail-1.6.4.jar). + +## July 3, 2019 - Jakarta Mail is the new name for JavaMail ## + +The JavaMail technology contributed to the Eclipse Foundation has been renamed +to "Jakarta Mail" to reflect its role in the +[Jakarta EE platform](https://jakarta.ee/). + +## November 26, 2018 - JavaMail 1.6.3 Final Release ## + +The 1.6.3 release is the first release of the Eclipse project for JavaMail +and includes no bug fixes or enhancements. It does include changes +to the Maven coordinates. The main jar file is now located at +[com.sun.mail:jakarta.mail](https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/1.6.3/jakarta.mail-1.6.3.jar). + +## September 14, 2018 - JavaMail project moves to the Eclipse Foundation! ## + +The JavaMail project is now hosted at the Eclipse Foundation as part of +the [EE4J project](https://projects.eclipse.org/projects/ee4j). + +
+ +# API Documentation + +The Jakarta Mail API is defined through the +[Jakarta EE Specification Process](https://jakarta.ee/about/jesp/). + +The Jakarta Mail specification and API documentation are available +[here](https://jakarta.ee/specifications/mail/). + +Note that Jakarta Mail 1.6 is identical to JavaMail 1.6. + +The JavaMail 1.6 and earlier API is defined through the Java Community Process as +[JSR 919](http://jcp.org/en/jsr/detail?id=919). + +The following documents summarize the API changes in each release of +the JavaMail API specification: + +- [JavaMail 2.1](docs/JavaMail-2.1-changes.txt) +- [JavaMail 2.0](docs/JavaMail-2.0-changes.txt) +- [JavaMail 1.6](docs/JavaMail-1.6-changes.txt) +- [JavaMail 1.5](docs/JavaMail-1.5-changes.txt) +- [JavaMail 1.4](docs/JavaMail-1.4-changes.txt) +- [JavaMail 1.3](docs/JavaMail-1.3-changes.txt) +- [JavaMail 1.2](docs/JavaMail-1.2-changes.txt) +- [JavaMail 1.1](docs/JavaMail-1.1-changes.txt) + +
+ +# Help + +Please read the +[Jakarta Mail FAQ](FAQ.html)! +Read it again. Tell everyone you know to read it. Thank you! + +You can post questions to the +[mail-dev mailing list](https://accounts.eclipse.org/mailing-list/mail-dev). + +Or, post a question on [Stack Overflow](http://stackoverflow.com/) using the +[javamail](http://stackoverflow.com/questions/tagged/javamail) tag. + +
+ +# Bugs + +Jakarta Mail API bugs are tracked in the +[GitHub Jakarta Mail project issue tracker](https://github.com/jakartaee/mail-api/issues). + +
+ +# Development Releases + +From time to time snapshot releases of the next version of Jakarta Mail +Specification API under development are published to the +[Jakarta Sonatype OSS repository](https://jakarta.oss.sonatype.org). +These snapshot releases have received only minimal testing, but may +provide previews of bug fixes or new features under development. + +For example, you can download the jakarta.mail-api.jar file from the Jakarta Mail +2.1.1-SNAPSHOT release +[here](https://jakarta.oss.sonatype.org/content/repositories/snapshots/jakarta/mail/jakarta.mail-api/2.1.1-SNAPSHOT/). +Be sure to scroll to the bottom and choose the jar file with the most +recent time stamp. + +You'll need to add the following configuration to your Maven ~/.m2/settings.xml +to be able to use these with Maven: + +``` + + + + jakarta-snapshots + + + jakarta-snapshots + Jakarta Snapshots + + true + always + fail + + https://jakarta.oss.sonatype.org/content/repositories/snapshots/ + default + + + + +``` + +And then when you build use `mvn -Pjakarta-snapshots ...`. + +If you want the plugin repository to be enabled all the time so you don't need the -P, add: + +``` + + jakarta-snapshots + +``` + +
+ +By contributing to this project, you agree to these additional terms of +use, described in [CONTRIBUTING](CONTRIBUTING). diff --git a/www/SMTP-Transport.md b/www/SMTP-Transport.md new file mode 100644 index 00000000..39cb9422 --- /dev/null +++ b/www/SMTP-Transport.md @@ -0,0 +1,13 @@ +SMTP Transport +============== + +The only Transport (for sending mail) provided with Jakarta Mail uses the +SMTP protocol. The primary documentation for the SMTP Transport is in +the javadocs for the +[com.sun.mail.smtp package](docs/api/com/sun/mail/smtp/package-summary.html). +Be sure to read the package level javadocs, which describe the +properties you can set, as well as the javadocs for the individual +classes in the package. + +This page is currently a placeholder for more information about the +SMTP Transport. diff --git a/www/TCK-Results.md b/www/TCK-Results.md new file mode 100644 index 00000000..568e0f4f --- /dev/null +++ b/www/TCK-Results.md @@ -0,0 +1,97 @@ +TCK Results +=========== + +As required by the +[Eclipse Foundation Technology Compatibility Kit License](https://www.eclipse.org/legal/tck.php), +following is a summary of the TCK results for releases of Jakarta Mail. + +# 2.0.1 Certification Request + +- [x] Organization Name ("Organization") and, if applicable, URL:
+ [Eclipse Foundation](https://www.eclipse.org/) +- [x] Product Name, Version and download URL (if applicable):
+ [EE4J implementation of Jakarta Mail 2.0.1](https://eclipse-ee4j.github.io/mail/) +- [x] Specification Name, Version and download URL:
+ [Jakarta Mail 2.0](https://jakarta.ee/specifications/mail/2.0/) +- [x] TCK Version, digital SHA-256 fingerprint and download URL:
+ [Jakarta Mail TCK 2.0.0](https://download.eclipse.org/jakartaee/mail/2.0/jakarta-mail-tck-2.0.0.zip), SHA-256: 9bc321997af2e4c7837a6b16e9231bdc8a34e0b97fa6dfafdd792fc316721c3b +- [x] Public URL of TCK Results Summary:
+ [TCK results summary](https://eclipse-ee4j.github.io/mail/TCK-Results.html) +- [x] Any Additional Specification Certification Requirements:
+ None +- [x] Java runtime used to run the implementation:
+ Oracle JDK 1.8.0_251, Oracle JDK 11.0.10 +- [x] Summary of the information for the certification environment, operating system, cloud, ...:
+ Apache James mail server 3.0.1, Linux +- [x] By checking this box I acknowledge that the Organization I represent accepts the terms of the [EFTL](https://www.eclipse.org/legal/tck.php). +- [x] By checking this box I attest that all TCK requirements have been met, including any compatibility rules. + +Test results: + +``` +[javatest.batch] Completed running 321 tests. +[javatest.batch] Number of Tests Passed = 321 +[javatest.batch] Number of Tests Failed = 0 +[javatest.batch] Number of Tests with Errors = 0 +[javatest.batch] Number of Tests Not Run = 0 +``` + +# 2.0.0 Certification Request + +- [x] Organization Name ("Organization") and, if applicable, URL:
+ [Eclipse Foundation](https://www.eclipse.org/) +- [x] Product Name, Version and download URL (if applicable):
+ [EE4J implementation of Jakarta Mail 2.0.0](https://eclipse-ee4j.github.io/mail/) +- [x] Specification Name, Version and download URL:
+ [Jakarta Mail 2.0](https://jakarta.ee/specifications/mail/2.0/) +- [x] TCK Version, digital SHA-256 fingerprint and download URL:
+ [Jakarta Mail TCK 2.0.0](https://download.eclipse.org/jakartaee/mail/2.0/jakarta-mail-tck-2.0.0.zip), SHA-256: 9bc321997af2e4c7837a6b16e9231bdc8a34e0b97fa6dfafdd792fc316721c3b +- [x] Public URL of TCK Results Summary:
+ [TCK results summary](https://eclipse-ee4j.github.io/mail/TCK-Results.html) +- [x] Any Additional Specification Certification Requirements:
+ None +- [x] Java runtime used to run the implementation:
+ Oracle JDK 1.8.0_191 +- [x] Summary of the information for the certification environment, operating system, cloud, ...:
+ Apache James mail server 3.0.1, Linux +- [x] By checking this box I acknowledge that the Organization I represent accepts the terms of the [EFTL](https://www.eclipse.org/legal/tck.php). +- [x] By checking this box I attest that all TCK requirements have been met, including any compatibility rules. + +Test results: + +``` +[javatest.batch] Number of Tests Passed = 321 +[javatest.batch] Number of Tests Failed = 0 +[javatest.batch] Number of Tests with Errors = 0 +``` + +# 1.6.4 Certification Request + +- [x] Organization Name ("Organization") and, if applicable, URL:
+ [Eclipse Foundation](https://www.eclipse.org/) +- [x] Product Name, Version and download URL (if applicable):
+ [EE4J implementation of Jakarta Mail 1.6.4](index.html) +- [x] Specification Name, Version and download URL:
+ [Jakarta Mail 1.6](https://jakarta.ee/specifications/mail/1.6/) +- [x] TCK Version, digital SHA-256 fingerprint and download URL:
+ [Jakarta Mail TCK 1.6.0](https://download.eclipse.org/jakartaee/mail/1.6/eclipse-mail-tck-1.6.0.zip), SHA-256: fb1a4195b6b91321bbdcc64683aec1e98939c9695679c720a1c7c5b14e4f8e56 +- [x] Public URL of TCK Results Summary:
+ [TCK results summary](TCK-Results.html) +- [x] Any Additional Specification Certification Requirements:
+ None +- [x] Java runtime used to run the implementation:
+ Oracle JDK 1.8.0_191 +- [x] Summary of the information for the certification environment, operating system, cloud, ...:
+ Apache James mail server 3.0.1, Linux +- [x] By checking this box I acknowledge that the Organization I represent accepts the terms of the [EFTL](https://www.eclipse.org/legal/tck.php). +- [x] By checking this box I attest that all TCK requirements have been met, including any compatibility rules. + +Test results: + +``` +[javatest.batch] Completed running 321 tests. +[javatest.batch] Number of Tests Passed = 321 +[javatest.batch] Number of Tests Failed = 0 +[javatest.batch] Number of Tests with Errors = 0 +[javatest.batch] Number of Tests Not Run = 0 +``` diff --git a/www/ThirdPartyProducts.md b/www/ThirdPartyProducts.md new file mode 100644 index 00000000..78eb6b05 --- /dev/null +++ b/www/ThirdPartyProducts.md @@ -0,0 +1,287 @@ +# Third-Party Products + +(Last updated Oct 16, 2017) + +Links to third-party products related to the Jakarta Mail APIs. Send us +a note at mail-dev@eclipse.org +if you want your product listed here. + +* Sending emails in Java should be easier. Jodd provides some nice + classes for sending emails in an easier, practical way. + Jodd Email is available at + https://jodd.org/email/ + +* simple-java-mail is a very simple Java mailing API for sending simple + to complex emails. It's a wrapper for the JavaMail smtp support. + simple-java-mail is available at + + https://github.com/bbottema/simple-java-mail/ + +* exJello is a JavaMail provider that connects to a Microsoft Exchange + server (actually, it uses the WebDAV interface exposed by Outlook Web + Access). It is designed as a drop-in replacement for the standard + POP3 and SMTP providers. This allows you to send and receive messages + through your Exchange server in situations where a POP3/SMTP interface + is not available (through a restrictive firewall, for example, or if + your administrator simply does not provide a POP3 or SMTP gateway). + Available at: + http://code.google.com/p/exjello/ + +* mailxel is a personal mail store and mail client with focus on + management and organization of high volume mail boxes. Like gmail, + but private. The main features are: fast search, tagging, GTD + inbox management workflow, efficient data storage, address + management, automated server-side mail folder organization, normal + mail functionality (send, recieve, forward etc etc). + Available at: + + http://code.google.com/p/mailxel/ + +* libpst - A Java library to read Microsoft proprietary PST files. + Available at: + + https://github.com/rjohnsondev/java-libpst + +* Apache POI - the Java API for Microsoft Documents. + The Apache POI Project's mission is to create and maintain Java + APIs for manipulating various file formats based upon the Office + Open XML standards (OOXML) and Microsoft's OLE 2 Compound Document + format (OLE2). In short, you can read and write MS Excel files + using Java. In addition, you can read and write MS Word and MS + PowerPoint files using Java. The project has recently added + support for Outlook (HSMF), which allows reading Outlook MSG + files. At this time, it provides simple read access to some of the + textual content of MSG files. + Available at: + http://poi.apache.org/ + +* Cubusmail is a Ajax based IMAP mail client which has a desktop application + like user interface. It provides functions like MIME support, address book, + folder manipulation, drag & drop and message searching. + Available at: + + http://code.google.com/p/cubusmail + +* DKIM for JavaMail is an open source library that allows you to sign + a message with + DomainKeys Identified Mail (DKIM). + Available at: + + http://www.agitos.de/dkim-for-javamail/ + +* j-XChange is a pure Java implementation of the entire Collaboration Data + Objects (CDO 1.21) library for accessing Microsoft Exchange Servers in a + platform independent manner. Available at: + + http://sourceforge.net/projects/j-xchange + +* Jack Mail Client is a simple mail client that uses any mail server + with minimal configuration. Jack Mail Client is written in pure Java + and is available under the GPL license at: + + http://sourceforge.net/projects/jackmailclient + +* GreenMail is an embeddable, lightweight and sandboxed email server for + testing and developing purposes. Available at: + + http://www.icegreen.com/greenmail + +* Aspirin is an embeddable send-only SMTP server that reuses parts + of the Apache James mail server. Available at: + + https://github.com/masukomi/aspirin + +* JEC provides a pure Java API to access Microsoft Exchange Server. + With it you can access and manipulate emails, calendar, contacts, and tasks + in the Exchange server. It supports 2 types of licenses - + 1) Non-Profits, Academic Institutions, and Private Individuals, and + 2) commercial. For more information see: + + http://www.javaexchangeconnector.com/ + +* yawebmail is a webmail-client written in Java as a webapp. + It supports SMTP (including SMTP-Authentication), POP3 and IMAP. + Just put the yawebmail.war file into the deployment-directory of your + Servlet-container (tomcat, jetty, weblogic, ..) and you're ready to go! + Take a test ride on the yawebmail-Homepage! + + http://yawebmail.sourceforge.net/ + +* Aperture is a Java framework for extracting and querying full-text + content and metadata from various information systems (e.g. file + systems, web sites, mail boxes) and the file formats (e.g. + documents, images) occurring in these systems. It provides a + JavaMail-based incremental IMAP crawler. Available at: + + http://aperture.sourceforge.net/ + +* JCharset - a charset provider that handles UTF-7, which is a mail safe + version of Unicode (RFC 2152), and some other charsets that aren't + currently supported by Java. + This package is open source (GNU), and it would probably help many JavaMail + fans out there. Available at: + + http://www.freeutils.net/source/jcharset/ + +* The jmbox project (read jambox) enables developers to use the + JavaMail API to manage mail stored in local repositories like + Outlook Express, Mozilla, Netscape, etc. A JavaMail enabled + application needs only to include the jmbox distribution jar in its + classpath to automatically benefit from local mail management, the + same way it would do with POP3 or IMAP remote mail. At the moment + jmbox supports navigation and reading from Outlook Express 5/6 mail + (dbx format). Writing into folders and support for other + repositories (mbox) will be added. Available at: + + https://sourceforge.net/projects/jmbox/. + +* hipergate has a WebMail client and local store provider based on + JavaMail. hipergate stores e-mail messages in the local filesytem + of a web server, indexes them using a relational database and makes + them available through a web interface. JavaMail is tightly + integrated with the hipergate Contact Manager and can keep track of + any sent or received messages for each contact listed in the agenda. + Available at: + http://www.hipergate.org and + + http://sourceforge.net/projects/hipergate/ + +* jASEN is a pure Java Anti Spam ENgine combining bayesian-like scanning with + intelligent email inspection and classification. + jASEN is best suited to developers wishing to integrate anti-spam services + into an existing server based Java email application, but can be used for + client applications. Available at: + http://www.jasen.org + +* SplashMail is a simple, free, source-available web application for + accessing your email over the web. It may be simple, but it provides + all the common features most users need. Available at: + + http://www.twinfeats.com/tf/twinfeats/Java/SplashMail/index.tfs + +* mstor is a local store provider for JavaMail. Based on the mbox + format, mstor facilitates the storage and retrieval of email messages + in the local filesystem. In addition, mstor supports additional + metadata not inherently supported by the mbox format, and is designed + to handle large mailboxes without a significant degradation in + performance. Available at: + + http://mstor.sourceforge.net/index.html + +* IAIK-CMS with S/MIMEv3 provides a complete implementation of the + CMS, S/MIMEv3 and ESS (Enhanced Security Services for S/MIME) + protocols. It can be used for signing, encrypting, digesting, + authenticating any kind of digital data and enhances the JavaMail + API with the cryptographic services of the S/MIME and ESS + standards. It comes with a great variety of cryptographic + algorithms, supports data compression according to S/MIMEv3.1, and + allows easy integration of smartcards or other hardware security + modules. Please see + + http://jcewww.iaik.at/sic/Products/Communication_Messaging_Security/CMS-S_MIME + +* JavaMail-Crypto is a simple, easy-to-use API that provides a unified way to + access OpenPGP and S/MIME encryption functionality with JavaMail. It is + released under the LGPL, and available at + + http://javamail-crypto.sourceforge.net/ + +* Mousetrap Mail is a free email client written in Java. + Available at: + http://mousetrap.sourceforge.net/ + +* PGPMime for Java: A JavaMail extension allowing encryption and signing + using the PGP/MIME standard. + Available at: + http://jpgpmime.sourceforge.net/ + +* JTNEF: A Java TNEF package for processing TNEF streams (WINMAIL.DAT + attachments) in email messages sent by Outlook and Exchange. + Available at: + + http://www.freeutils.net/source/jtnef/ + +* JavaMaildir is a local Store provider for the JavaMail API that + provides access to qmail-style Maildir folders with some extensions. + Available at: + http://javamaildir.sourceforge.net/ + +* Ebitec's JMS Mail bridge is a software product that interfaces + between traditional e-mail protocols (SMTP, POP) and a + JMS server. The Ebitec Mail Bridge is independent of + JMS server vendor and therefore easily integrated into your + existing systems. Advanced features are included such as + processing different types of e-mail with multiple attachments, + encode e-mail into XML, and support for both queues and topics. + Search for it at: + + http://www.componentsource.com + +* JDAVMail is a JavaMail service provider allowing JavaMail-compliant + clients to access HotMail mailboxes (read/delete/move/copy mail, + create/rename/delete folders, ...). JDAVMail implements the + WebDAV-like protocol used by some HotMail clients. The package is + published under the LGPL license and is available at + + http://jdavmail.sourceForge.net + +* email client demo program from + + The Java Cookbook. Source code is available for download at: + http://javacook.darwinsys.com/ + +* jwma is a WebMail implementation in Java, depending on an IMAP + server as post office, and an SMTP server for mail transport. + jwma is an open source project. + http://jwma.sourceforge.net + +* PlexMailer offers a set of powerful tools to prevent against + unsolicted emails (SPAM). It supports POP3, IMAP, and MBOX + protocols and can be run as an email client or as a proxy server + between a mail server and another email client. PlexMailer comes + with dozens of filters and hooks to other online resources such as + ORBS, MAPS, and DUL to protect against unsolicited emails and + report senders of those emails to appropriate authorities. It + supports Java Web Start for seamless installation and automatic + upgrades for future enhancements and bug fixes. Available at: + + http://www.plexobject.com/software/plexmailer/. + +* Pooka: An email client using JavaMail and Swing. Supports IMAP + (including disconnected IMAP and IMAP over SSL), POP3, and local + mbox stores. Source is available under the GNU GPL. Available at: + http://www.suberic.net/pooka/. + +* A sample application using the Devsphere Mapping Framework: + A servlet called FormMailer converts data collected with HTML + forms to objects and then to key-value pairs. The obtained ASCII + text is mailed to one or more addresses using JavaMail. + A standalone application called MailMonitor uses JavaMail to get + the messages from the mail server. Then, it converts the obtained + key-value pairs to objects, which are forwarded to a dynamically + loaded class for processing. The application is described in + Chapters 12-17 of the Developer's Guide, available at + + http://www.devsphere.com/mapping/docs/guide/application.html. + An evaluation copy of the Devsphere Mapping Framework is available at + http://www.devsphere.com. + +* Saké Mail: A web-based mail client implemented as a Java servlet + using JavaMail. + Available at: + http://www.endymion.com/products/sake/mail/. + +* Apache JAMES: The Java Apache Mail Enterprise Server (a.k.a. Apache + James) is a 100% pure Java server designed to be a complete and + portable enterprise mail engine solution based on currently + available open protocols (SMTP, POP3, IMAP, HTTP). + Available at: http://james.apache.org + +* Apache JetSpeed: An Open Source GroupWare/Portal product similar to + Lotus Notes or Microsoft Exchange that implements portal features + such as My Netscape and My Yahoo. + Available at: + https://portals.apache.org/jetspeed-2/ + +* An MH provider, from the folks who bring you ICEMail. Available at: + http://www.trustice.com/java/icemh. diff --git a/www/Windows.md b/www/Windows.md new file mode 100644 index 00000000..f7cb2431 --- /dev/null +++ b/www/Windows.md @@ -0,0 +1,31 @@ +Windows Hints and Tips +====================== + +TCP TIME\_WAIT +-------------- + +When making a large number of connections (e.g., to a mail server) in a +short amount of time, you might run out of sockets and not be able to +create any more connections. The existing connections will be in a +TIME\_WAIT state as shown by netstat. The following articles explain +this situation in more detail and include tips for how to deal with +it: + +- [Microsoft TechNet](http://technet.microsoft.com/en-us/library/cc757512%28WS.10%29.aspx) +- [Microsoft MSDN](http://msdn.microsoft.com/en-us/library/ms819739.aspx) +- [Microsoft Support](http://support.microsoft.com/kb/328476) (talks about SQL Server, but applies here as well) + +Note that it seems the +[number of available ports has increased in Windows Server 2008](http://support.microsoft.com/kb/929851). + +.msg and .eml Files +------------------- + +Windows applications typically store single messages in MIME format in +".eml" files. Jakarta Mail can read these files using the MimeMessage +constructor that takes an InputStream. + +Windows applications typically store messages in the Windows +proprietary Outlook message format in ".msg" files. Jakarta Mail can't +process these files directly, but the +[Apache POI project](http://poi.apache.org/) might help. diff --git a/www/Workspace-Structure.md b/www/Workspace-Structure.md new file mode 100644 index 00000000..20fb2e98 --- /dev/null +++ b/www/Workspace-Structure.md @@ -0,0 +1,215 @@ +Jakarta Mail Workspace Structure +================================ + +Here's the structure of the Jakarta Mail workspace, showing the different +maven modules I needed to create to allow Jakarta Mail to be built by +maven. + +First, the main maven module. + + pom.xml + +Then, some files left over from the ant build. +These are no longer used or maintained. + + ant-common.xml + build.properties + build.xml + mbox.xml + project.properties + project.xml + +Finally, some files for checking that the API signatures match the spec +(not yet integrated into the build). + + mail.sig + siggen + sigtest + +The main Jakarta Mail source code module, containing all the code that goes +into mail.jar. + + mail/pom.xml + mail/src/main/java/com/sun/mail/handlers/image_gif.java + ... + mail/src/main/java/com/sun/mail/util/UUEncoderStream.java + mail/src/main/java/javax/mail/Address.java + ... + mail/src/main/java/javax/mail/util/package.html + mail/src/main/java/overview.html + mail/src/main/resources/META-INF/MANIFEST.MF + mail/src/main/resources/META-INF/javamail.charset.map + mail/src/main/resources/META-INF/javamail.default.address.map + mail/src/main/resources/META-INF/javamail.default.providers + mail/src/main/resources/META-INF/mailcap + mail/src/oldtest/java/javax/mail/internet/addrlist + ... + mail/src/oldtest/java/javax/mail/internet/tokenlist + +Several modules containing demo source code. They're buildable to make +sure they do build before shipping them, but they're shipped only as +source code. Note the embedded README.txt files + + demo/pom.xml + demo/src/main/java/CRLFOutputStream.java + demo/src/main/java/NewlineOutputStream.java + demo/src/main/java/README.txt + demo/src/main/java/copier.java + demo/src/main/java/folderlist.java + demo/src/main/java/internal/... + demo/src/main/java/monitor.java + demo/src/main/java/mover.java + demo/src/main/java/msgmultisendsample.java + demo/src/main/java/msgsend.java + demo/src/main/java/msgsendsample.java + demo/src/main/java/msgshow.java + demo/src/main/java/namespace.java + demo/src/main/java/populate.java + demo/src/main/java/registry.java + demo/src/main/java/search.java + demo/src/main/java/sendfile.java + demo/src/main/java/sendhtml.java + demo/src/main/java/smtpsend.java + demo/src/main/java/transport.java + demo/src/main/java/uidmsgshow.java + client/pom.xml + client/src/main/java/ComponentFrame.java + client/src/main/java/FolderModel.java + client/src/main/java/FolderTreeNode.java + client/src/main/java/FolderViewer.java + client/src/main/java/MessageViewer.java + client/src/main/java/MultipartViewer.java + client/src/main/java/README.txt + client/src/main/java/SimpleAuthenticator.java + client/src/main/java/SimpleClient.java + client/src/main/java/StoreTreeNode.java + client/src/main/java/TextViewer.java + client/src/main/java/simple.mailcap + servlet/pom.xml + servlet/src/main/java/JakartaMail.html + servlet/src/main/java/JakartaMailServlet.java + servlet/src/main/java/README.txt + webapp/build.bat + webapp/build.sh + webapp/pom.xml + webapp/src/main/java/demo/AttachmentServlet.java + webapp/src/main/java/demo/FilterServlet.java + webapp/src/main/java/demo/MailUserBean.java + webapp/src/main/webapp/WEB-INF/web.xml + webapp/src/main/webapp/compose.jsp + webapp/src/main/webapp/errordetails.jsp + webapp/src/main/webapp/errorpage.jsp + webapp/src/main/webapp/folders.jsp + webapp/src/main/webapp/index.html + webapp/src/main/webapp/login.jsp + webapp/src/main/webapp/logout.jsp + webapp/src/main/webapp/messagecontent.jsp + webapp/src/main/webapp/messageheaders.jsp + webapp/src/main/webapp/send.jsp + webapp/webapp.README.txt + taglib/pom.xml + taglib/src/main/java/demo/AttachmentInfo.java + taglib/src/main/java/demo/ListAttachmentsTEI.java + taglib/src/main/java/demo/ListAttachmentsTag.java + taglib/src/main/java/demo/ListMessagesTEI.java + taglib/src/main/java/demo/ListMessagesTag.java + taglib/src/main/java/demo/MessageInfo.java + taglib/src/main/java/demo/MessageTEI.java + taglib/src/main/java/demo/MessageTag.java + taglib/src/main/java/demo/SendTag.java + taglib/src/main/resources/META-INF/taglib.tld + logging/pom.xml + logging/src/main/java/MailHandlerDemo.java + logging/src/main/java/maildemo.properties + logging/src/main/java/maildemo.policy + logging/src/main/java/SummaryFormatter.java + logging/src/main/java/FileErrorManager.java + logging/src/main/java/README.txt + + +Several modules that extract subsets of the mail.jar file to build +other jar files. The source code for each of these jar files could be +moved into these modules, and then mail.jar could be constructed by +combining all these jar files. I did it this way because I like having +all the source code in one place, but it's probably less maven-like. + + mailapi/pom.xml + imap/pom.xml + imap/src/main/resources/META-INF/MANIFEST.MF + imap/src/main/resources/META-INF/javamail.providers + pop3/pom.xml + pop3/src/main/resources/META-INF/MANIFEST.MF + pop3/src/main/resources/META-INF/javamail.providers + smtp/pom.xml + smtp/src/main/resources/META-INF/MANIFEST.MF + smtp/src/main/resources/META-INF/javamail.address.map + smtp/src/main/resources/META-INF/javamail.providers + mailhandler/pom.xml + +A module to act as parent of the imap, pop3, and smtp modules to allow +sharing of some common rules. + + parent-distrib/pom.xml + +A module that contains only the Delivery Status Notification support. I +moved all the source code here because none of this appears in +mail.jar. + + dsn/pom.xml + dsn/src/main/java/com/sun/mail/dsn/DeliveryStatus.java + dsn/src/main/java/com/sun/mail/dsn/MessageHeaders.java + dsn/src/main/java/com/sun/mail/dsn/MultipartReport.java + dsn/src/main/java/com/sun/mail/dsn/message_deliverystatus.java + dsn/src/main/java/com/sun/mail/dsn/multipart_report.java + dsn/src/main/java/com/sun/mail/dsn/package.html + dsn/src/main/java/com/sun/mail/dsn/text_rfc822headers.java + dsn/src/main/resources/META-INF/MANIFEST.MF + dsn/src/main/resources/META-INF/mailcap + +The mbox protocol provider module. Again, source code moved here +because none of this appears in mail.jar. Also includes a submodule to +build the native code (even though the native source code is in the +upper module; is that too weird?) + + mbox/pom.xml + mbox/src/main/cpp/com/sun/mail/mbox/UNIXFile.c + mbox/src/main/cpp/com/sun/mail/mbox/UNIXInbox.c + mbox/src/main/java/com/sun/mail/mbox/ContentLengthCounter.java + ... + mbox/src/main/java/com/sun/mail/mbox/UNIXInbox.java + mbox/src/main/java/com/sun/mail/remote/POP3RemoteStore.java + mbox/src/main/java/com/sun/mail/remote/RemoteDefaultFolder.java + mbox/src/main/java/com/sun/mail/remote/RemoteInbox.java + mbox/src/main/java/com/sun/mail/remote/RemoteStore.java + mbox/src/main/resources/META-INF/MANIFEST.MF + mbox/src/main/resources/META-INF/javamail.providers + mbox/native/pom.xml + +A module just for building the javadocs. Putting these rules in the +parent pom.xml just didn't work so I moved them here. + + javadoc/pom.xml + +Finally, the documentation. Not a module. Most of it is copied to the +website gh-pages branch when a release is published. + + doc/release/ApacheJServ.html + doc/release/CHANGES.txt + doc/release/COMPAT.txt + doc/release/IssueMap.txt + doc/release/JavaWebServer.html + doc/release/NOTES.txt + doc/release/NTLMNOTES.txt + doc/release/README.txt + doc/release/SSLNOTES.txt + doc/release/Tomcat.html + doc/release/classpath-NT.html + doc/release/iPlanet.html + doc/release/images/direct-classpath.jpg + doc/release/images/indirect-classpath.jpg + doc/spec/JavaMail-1.1-changes.txt + doc/spec/JavaMail-1.2-changes.txt + doc/spec/JavaMail-1.3-changes.txt + doc/spec/JavaMail-1.4-changes.txt + doc/spec/JavaMail-1.5-changes.txt + doc/spec/JavaMail-1.6-changes.txt diff --git a/www/Yahoo.md b/www/Yahoo.md new file mode 100644 index 00000000..3029e268 --- /dev/null +++ b/www/Yahoo.md @@ -0,0 +1,21 @@ +Yahoo! Mail +=========== + +This page is currently a placeholder for describing hints and tips for +using Jakarta Mail with Yahoo! Mail. Basic Yahoo! Mail usage information +can be found in the +[Jakarta Mail FAQ](FAQ.html#yahoomail). + +See also the +[Wikipedia page on Yahoo! Mail](http://en.wikipedia.org/wiki/Yahoo!_Mail#Free_IMAP_and_SMTPs_access) +for information about accessing the Yahoo! Mail IMAP server. I've just +added a feature to Jakarta Mail to enable Yahoo! Mail IMAP server support - +set the property "mail.imap.yahoo.guid" to "1". As of 3/19/2015, this +no longer seems to be necessary. + +On 3/12/2015 a user reported +that using the Jakarta Mail equivalent of UID FETCH X:Y (UID) where X is +greater than any existing UID in the folder never returns. + +As of 8/19/2015, Yahoo Mail doesn't handle some IMAP SEARCH terms +correctly. For example, the NOT term seems to be completely ignored. diff --git a/www/_config.yml b/www/_config.yml new file mode 100644 index 00000000..dcda8480 --- /dev/null +++ b/www/_config.yml @@ -0,0 +1,16 @@ +github: [metadata] +remote_theme: jakartaee/jekyll-theme-jakarta-ee + +title: [Jakarta Mail] +description: [Specification] + +links: + source: https://github.com/jakartaee/mail-api + javadocs: docs/api/ + download: https://github.com/eclipse-ee4j/mail/releases + mailinglist: https://accounts.eclipse.org/mailing-list/mail-dev + faq: FAQ + contrib: CONTRIBUTING + +include: + - CONTRIBUTING.md diff --git a/www/_includes/sidebar.html b/www/_includes/sidebar.html new file mode 100644 index 00000000..9d3a5185 --- /dev/null +++ b/www/_includes/sidebar.html @@ -0,0 +1,72 @@ + + \ No newline at end of file diff --git a/www/docs/COMPAT.txt b/www/docs/COMPAT.txt new file mode 100644 index 00000000..a7bbedef --- /dev/null +++ b/www/docs/COMPAT.txt @@ -0,0 +1,413 @@ + COMPATIBILITY NOTES + =================== + + Jakarta Mail API 2.0.1 release + ------------------------------ + +-- Jakarta Mail 2.0.0 -- + +The Jakarta Mail 2.0 specification is the successor of the Jakarta +Mail 1.6 specification. Except new package namespace - jakarta.mail +there are no changes. + +-- Jakarta Mail 1.6.x -- + +The Jakarta Mail 1.6 specification is fully compatible with the JavaMail +1.5 specification, with the exceptions listed below. + +In addition, changes in the implementation may impact +applications that depend on behavior beyond what is defined by the +Jakarta Mail specification, or that use features specific to the +implementation. This note summarizes potential compatibility issues +with this release of the Jakarta Mail API. + + +-- Jakarta Mail 1.6.4 -- + +- Jakarta Mail is the new name for JavaMail. + +- NTLMv2 supported by default. + + Jakarta Mail now supports the newest NTLMv2 authentication protocol + by default for any servers that support the NTLM authentication + mechanism. All recent Microsoft Exchange servers support NTLMv2, + but if this causes compatibility problems it can be disabled by + setting the property "mail..auth.ntlm.v2" to "false". + +- Protocol providers now always loaded using ServiceLoader and config files + + The changes in Jakarta Mail 1.6.2 to use ServiceLoader introduced + an incompatibility with some commonn use cases. To resolve that + incompatibility, the load order for providers has changed to: + + 1. Non-default providers available as services. + 2. Providers configured via javamail.providers. + 3. Providers configured via javamail.default.providers. + 4. Default providers available as services. + + An implementation-specific @DefaultProvider annotation is used + to mark the providers included with Jakarta Mail (#4 above), and + should not be used by applications. + + +-- JavaMail 1.6.3 -- + +- Maven coordinates for JavaMail changed. + + JavaMail has moved to the Eclipse Foundation as part of the EE4J + project, and will be included in the Jakarta EE specification. + The Maven coordinates for JavaMail are now: + + - com.sun.mail:jakarta.mail - complete JavaMail jar file + - jakarta.mail:jakarta.mail-api - API jar file for compiling only + + When updating dependencies to use JavaMail 1.6.3 or newer, the + artifactId will need to be changed as above. The APIs are + otherwise compatible. + +- Java module system name changed. + + Experimental support for the Java platform module system was + added in the previous release using the name "java.mail" for the + API module (mailapi.jar). In this release the name of that + module is changed to "jakarta.mail". + + +-- JavaMail 1.6.2 -- + +- Protocol providers now loaded using the java.util.ServiceLoader mechanism. + + All the protocol providers included with JavaMail, as well as + third party providers, can use the Service Loader mechanism to + configure the provider, instead of using the + META-INF/javamail.default.providers or META-INF/javamail.providers + file. These JavaMail provider configuration files are only read + if the ServiceLoader fails to find a provider that supports the + requested protocol. This may have the effect of changing the order + in which providers are loaded, which should only be an issue if + multiple providers support the same protocol name. + + +-- JavaMail 1.6.1 -- + +- com.sun.mail.util.logging no longer included in mailapi.jar. + + If you're using mailapi.jar and depend on the com.sun.mail.util.logging + classes, you'll need to include the logging-mailhandler.jar file in + your application class path. + + + +-- JavaMail 1.6 -- + +- Public API updated to use generics + + Methods in the following classes have been updated to use generics. + This change should be binary compatible but may require source + code changes in applications. + + javax.mail.Multipart + javax.mail.Part + javax.mail.Service + javax.mail.internet.InternetHeaders + javax.mail.internet.MimeBodyPart + javax.mail.internet.MimeMessage + javax.mail.internet.MimePart + javax.mail.internet.ParameterList + +- JDK 1.7 or newer required + + The JavaMail reference implementation now requires JDK 1.7 + or newer. It is expected that the large majority of users + are already using JDK 1.7 or newer. + +- MailDateFormat changes + + The following changes to MailDateFormat may impact applications: + + * parse(String) now throws a ParseException on invalid input instead + of returning null, to conform to the DateFormat contract + * the following methods now throw UnsupportedOperationException + to prevent tampering with MailDateFormat's internals: + + get2DigitYearStart + applyLocalizedPattern + applyPattern + set2DigitYearStart + setDateFormatSymbols + +- method added to UIDFolder interface + + The UIDFolder interface has a new getUIDNext() method. Any + classes implementing the UIDFolder interface will need to add + this method. The IMAPFolder class implements the UIDFolder + interface and has provided this method for some time. + +- YoungerTerm, OlderTerm, and ModifiedSinceTerm fall back to local searching + + In general, SearchTerms that are not understood by the IMAP + provider or not supported by the IMAP server fall back to doing + local searching. The IMAP-specific YoungerTerm, OlderTerm, and + ModifiedSinceTerm were instead throwing an exception if the server + didn't support the extension that the search term depended on. + This has been fixed to fall back to doing the search locally. + This behavior can be changed by setting the property + "mail.imap.throwsearchexception" to "true" to cause an exception + to be thrown if the server can't perform the search. + + + +-- JavaMail 1.5.6 -- + +- finalizers close sockets abruptly + + It's important for finalizers to close an open socket + connection to prevent file descriptor leaks. Previously the + finalizers for the IMAP and POP3 providers would try to close + the connection cleanly, which could result in a timeout waiting + for the server. They now close the connection without + performing any socket I/O, which may result in an unclean + shutdown when seen from the server. Applications should always + close Stores and Folders when done with them to avoid the need + for the finalizer to do this cleanup. The Session property + "mail..finalizecleanclose" can be set to "true" to + force the connection to be closed cleanly in the finalizer. + +- InternetAddress.getLocalAddress uses canonical host name + + The InternetAddress.getLocalAddress method now uses the + java.net.InetAddress.getCanonicalHostName method if neither the + "mail.from" nor "mail.host" properties have been set. The System + property "mail.mime.address.usecanonicalhostname" can be set to + "false" to revert to the previous behavior. + +- SMTPTransport.sasllogin no longer public + + The SMTPTransport.sasllogin method should never have been + declared public. It's used internally when SASL authentication + is requested; applications should not use the method directly. + + + +-- JavaMail 1.5.4 -- + +- Idlemanager.watch no longer throws IOException + + The IdleManager.watch method was declared to throw IOException, + but never actually threw it. The declaraction has been changed, + which will cause a source incompatibility for code expecting to + catch IOException when calling the watch method. + + + +-- JavaMail 1.5.3 -- + +- Date search terms result in wrong greater-than SEARCH commands for IMAP + + The IMAP SentDateTerm and ReceivedDateTerm greater-than comparison + was actually doing a greater-than-or-equal-to comparison. This + has been fixed in the 1.5.3 release, but programs that accidentally + relied on the old behavior may get different results. + +- Authenticator is now synchronized + + The call to the Authenticator's getPasswordAuthentication method + is now synchronized so that the state stored in the Authenticator + is safe if multiple threads try to use the Authenticator + simultaneously. If the application's getPasswordAuthentication + method blocks, it will prevent other threads in the same + Session from using the Authenticator. + + + +-- JavaMail 1.5 -- + +- RFC 2231 parameter encoding/decoding enabled by default + + The System properties "mail.mime.decodeparameters" and + "mail.mime.encodeparameters" now default to true instead of false. + Now that most mailers support RFC 2231, this is expected to + increase interoperability, although in rare cases, and especially + when dealing with older mailers, this may cause problems. + Parameters may appear encoded, and with a different name, + than what the receiver is expecting. + +- ContentType.toString and ContentDisposition.toString never return null + + These methods were previously documented to return null in + error cases when the fields of the class were not valid. + These methods now return an empty string in these cases, to + be consistent with the general contract of Object.toString. + +- additional classes, methods, and fields + + JavaMail 1.5 adds classes to existing packages, methods to + existing classes, and fields to existing classes. All of + these changes have the potential to break source compatibility + for applications using the JavaMail API. + +- JDK 1.5 or newer required + + The JavaMail reference implementation now requires JDK 1.5 + or newer. It is expected that the large majority of users + are already using JDK 1.6 or newer. + +- protected fields in final classes in javax.mail.search made private + + Some of the final classes in the javax.mail.search package + contained protected fields. Since these classes were final + and couldn't be subclassed, the "protected" access qualifier + had no effect. These fields are now private. It's hard to + imagine how this change could impact any applications other + than perhaps those using reflection to access these classes. + +- MailHandler default attachment filters + + The default used for attachment filters has changed from allow + all log records (null) to instead use body filter assigned to + getFilter(). This is a safer choice as it maintains any + existing filter rules when attachments are added. + +- MailHandler default 'TO' address recipient + + If the 'TO' address key is not specified then the local address + is used. The previous behavior was to omit the 'TO' address + header. This can break configurations that are only sending to + a set of 'CC' or 'BCC' addresses. To revert this behavior + simply specify a 'TO' address key with an empty address value. + +- MailHandler intern of error manager, filters, and formatters. + + When MailHandler is created, the error manager, filters, and + formatters are checked for equality. When equal objects are + found they are replaced with a single representation. This + allows objects of the same type to share state for improving + performance, adding functionality, etc. To revert to the + previous behavior the error manager, filters, and formatters + must retain or be wrapped with objects that retain the identity + equals and hash code to prevent interning. + + + +-- JavaMail 1.4.4 -- + +- authorization ID may be null + + The IMAP and SMTP providers support a + "mail..sasl.authorizationid" property that allows you + to specify an authorization ID separately from the authentication + ID that's specified as the user name in properties or in the connect + method. The PLAIN authentication method, and some SASL authentication + methods support use of the separate authorization ID. In previous + releases, if the authorization ID was not specified, it defaulted + to the authentication ID (user name). This can cause problems if + the server doesn't allow an authorization ID even though the SASL + method allows specifying one. In this release, if no authorization + ID is specified, null is passed to the SASL method. If this causes + problems for a SASL method implementation or a server, the + "mail..sasl.authorizationid" property should be set to + the user name used for authentication. + + + +-- JavaMail 1.4.3 -- + +- SMTPTransport.isConnected behavior changed + + The SMTPTransport.isConnected method uses the SMTP NOOP command + to determine if the server is still alive. Because many older + servers were broken in various ways, any response (other than + the 421 "connection timed out" response) was considered a + successful response and the server was considered to be still + alive. Unfortunately, Microsoft Exchange has a bug that causes + it to return a response code of 451 when it times out a connection + instead of the expected 421 response code. SMTPTransport.isConnected + now considers only a 250 response code to indicate success, per + the SMTP spec. The old behavior can be restored by setting the + new mail.smtp.noop.strict property to false. + + + +-- JavaMail 1.4.2 -- + +- mail.smtp.quitwait default changed + + In previous releases, JavaMail would drop the SMTP connection + to the server immediately after sending the QUIT command. + This violates the SMTP spec. The property "mail.stmp.quitwait" + controls this behavior. In this release the default behavior + (if the property isn't specified) has changed so that JavaMail + will wait for the response from the server before dropping the + connection. In some cases, with some servers, this additional + wait time may be noticeable. + + +- MessagingException.getMessage output changed + + The MessagingException class, which is the base class for all + JavaMail exceptions, has been retrofitted to support the + exception chaining feature added to the java.lang.Throwable + class in J2SE 1.4. The visible impact of this change is that + the String returned by the getMessage method will only return + the immediate message for the top level exception, instead of + including messages for all nested exceptions. + + +- connection timeouts no longer use a thread + + To support connection timeouts in older versions of the JDK, + it was necessary for JavaMail to create a thread to make the + connection, so that it could interrupt and abandon that + thread if the connection timeout expired. J2SE 1.4 added + the ability to specify the connection timeout directly, so + JavaMail no longer uses an additional thread for this purpose. + + +- ByteArrayDataSource now part of javax.mail.util + + The ByteArrayDataSource class, which was previously included + in source form in the demo directory, is now a standard part + of the JavaMail API in the new javax.mail.util package. + Applications that are modified to make use of classes in the + new package, and that also included a copy of the demo version + of ByteArrayDataSource, should be careful to avoid potential + name conflicts between these two classes. + + +- mail.SSLSocketFactory.class property no longer supported + + The JavaMail implementation previously used this undocumented + property to locate the SSLSocketFactory from which it would + create SSLSockets when making an SSL or TLS connection. This + property is no longer used. The standard + javax.net.ssl.SSLSocketFactory is used instead, which supports + a standard way of overriding the choice of default SSLSocketFactory. + See the SSLSocketFactory javadocs for details. Most applications + should never need to override the default SSLSocketFactory. + + +- Quota class moved from com.sun.mail.imap to javax.mail + + The new Quota APIs in JavaMail are taken directly from the old + IMAP-specific classes in the com.sun.mail.imap package. If you've + been using these classes, you'll need to update your application + to use the new classes in the javax.mail package. + + +- getProtocol method removed from com.sun.mail.imap.IMAPFolder + + The getProtocol method returns an instance of IMAPProtocol. + This was originally intended to allow applications to + experiment with extending the IMAP protocol support to use IMAP + commands not directly implemented by the IMAP protocol + provider. Unfortunately, to safely use the IMAPProtocol + object, you need to obey the locking requirements of the + IMAPFolder object, and there's no way to do that from outside + the IMAPFolder object. The doCommand method was added to + IMAPFolder to resolve this problem. Now, with the introduction + of IDLE support to the IMAP protocol provider, it's critical to + obey the locking requirements. To prevent mistakes, the old, + unsafe, getProtocol method has been removed. Applications + should use the doCommand method for simple IMAP extensions. + Use of more complex IMAP extensions may require modification + of the IMAP protocol provider. diff --git a/www/docs/JavaMail-1.1-changes.txt b/www/docs/JavaMail-1.1-changes.txt new file mode 100644 index 00000000..028dbecc --- /dev/null +++ b/www/docs/JavaMail-1.1-changes.txt @@ -0,0 +1,656 @@ + + JavaMail 1.1 + ============ + +Following is a description of the new APIs that are being +introduced in JavaMail 1.1 + +Please send comments and feedback to javamail@sun.com + +(1) MessageContext +================== + +In some cases it is desirable for the object representing the content +of a BodyPart to know something about the "context" in which it is +operating, e.g., what other data is contained in the same Multipart +object, who sent the message containing the data, etc. This allows +for more interesting content types that know more about the message +containing them and the mail system in general. + +Some uses of multipart/related might require these capabilities. +For instance, the handler for a text/html body part contained in a +multipart/related object might need to know about the containing +object in order to find the related image data needed to display the +HTML document. + +There is one particular case in the current implementation where +this need arises. (This is a bug in the current release.) When +constructing a MimeMessage object for a nested message contained +in another message, the DataContentHandler needs the Session +object in order to construct the new MimeMessage object. + +To solve these problems we introduce a new class, a new interface, +and a number of new methods. + +The MessageContext class provides the basic information about the +"context" in which a content object is operating: + +/** + * The context in which a piece of Message content is contained. A + * MessageContext object is returned by the + * getMessageContext method of the + * MessageAware interface. MessageAware is + * typically implemented by DataSources to allow a + * DataContentHandler to pass on information about the + * context in which a data content object is operating. + * + * @see javax.mail.MessageAware + * @see javax.activation.DataSource + * @see javax.activation.DataContentHandler + */ +public class MessageContext { + + /** + * Create a MessageContext object describing the context of the + * given Part. + */ + public MessageContext(Part part) + + /** + * Return the Part that contains the content. + * + * @return the containing Part, or null if not known + */ + public Part getPart() + + /** + * Return the Message that contains the content. + * Follows the parent chain up through containing Multipart + * objects until it comes to a Message object, or null. + * + * @return the containing Message, or null if not known + */ + public Message getMessage() + + /** + * Return the Session we're operating in. + * + * @return the Session, or null if not known + */ + public Session getSession() +} + + +A MessageContext object can be obtained by a DataContentHandler from a +DataSource that also implements the MessageAware interface: + +/** + * An interface optionally implemented by DataSources to + * supply information to a DataContentHandler about the + * message context in which the data content object is operating. + * + * @see javax.mail.MessageContext + * @see javax.activation.DataSource + * @see javax.activation.DataContentHandler + */ +public interface MessageAware { + /** + * Return the message context. + */ + public MessageContext getMessageContext(); +} + + +This new interface and class provides the basic information needed by +the DataContentHandler to use in constructing more "interesting" objects +representing a particular type of data. + +To allow navigation up the chain of components contained in a Message, +we add the following methods. + +First, on BodyPart we add: + + /** + * The Multipart object containing this + * BodyPart, if known. + */ + protected Multipart parent; + + /** + * Return the containing Multipart object, + * or null if not known. + */ + public Multipart getParent() + + +On Multipart we add: + + /** + * The Part containing this Multipart, + * if known. + */ + protected Part parent; + + /** + * Return the Part that contains this + * (codMultipartnull if not known. + */ + public Part getParent() + + /** + * Set the parent of this Multipart to be the specified + * Part. Normally called by the Message + * or BodyPart setContent(Multipart) + * method.

+ * + * parent may be null if the + * Multipart is being removed from its containing + * Part. + */ + public void setParent(Part parent) + + +To enable this new functionality we change the implementations of +MimeBodyPart, MimeMessage, and MimeMultipart to maintain the "parent" +links where possible. We also change MimePartDataSource to implement +the MessageAware interface. + +=================================================================== + +(2) MessageID +============= +The MimeMessage class requires a getMessageID() method. + +The client can now fetch it as a header, but since this is a "standard" +RFC822 header, we want to provide an easier access method. + +An added benefit is that protocols like IMAP, which provide this info +as part of the ENVELOPE structure, can implement this method much more +efficiently. + + /** + * Returns the value of the "Message-ID" header field. Returns + * null if this field is unavailable or its value is absent.

+ * + * The default implementation provided here uses the + * getHeader() method to return the value of the + * "Message-ID" field. + * + * @return Message-ID + * @exception MessagingException, if the retrieval of this field + * causes any exception. + * @see javax.mail.search.MessageIDTerm + */ + public String getMessageID() throws MessagingException; + +=================================================================== + +(3) UIDFolder +============= + +The following methods in the UIDFolder interface have certain problems. + +We are proposing changes that will fix these problems. These are +binary incompatible changes, but we think these changes are necessary for +this interface to work in a useful manner. We are also not aware of +anyone that has shipped a Store Provider that implements this interface, +so we are hoping that the effect of this change is minimal (non-existent). + +(1) Message getMessageByUID(long uid) + +Description: + Get the Message corresponding to the given UID. If no such +message exists, the java.util.NoSuchElementException is thrown. + +Problem: + A disconnected client can have a stash of UIDs from a +previous session. Some of these UIDs may have been expunged from the +server, but the disconnected client does not know this. It is quite +reasonable (and expected) for a disconnected client to use this +method when reconnecting - to check whether a UID is valid or not at +the server. + Since failure is an expected result here, using a +RunTimeException to indicate it, seems wrong and counter-intuitive for +the client. + +Solution: + Our solution is to allow this method to return null to indicate +that the requested UID is not valid anymore. Thus, this method will no +longer throw the java.util.NoSuchElementException. + +(2) Message[] getMessagesByUID(long start, long end) + +Description: + Get the Messages corresponding to the given UID range. If any +UID is invalid, the java.util.NoSuchElementException is thrown. + +Problem: + Similar, but worse than (1). We think that disconnected clients +(or clients that prefer to use UIDs) may issue + getMessagesByUID(1, LASTUID) +to get all the Messages at the server, especially when the client does +not know the exact UIDs for this folder. In this case, we certainly +do not want this method to fail if some id in the given range is +not a valid UID; rather we want it to return all available Messages from +the server. + +Solution: + Our solution is to remove the NoSuchElementException exception +and allow this method to return Message objects in the given range. + +(3) Message[] getMessagesByUID(long[] uids) + +Description: + Get the Messages corresponding to the given UID range. If any +UID is invalid, the java.util.NoSuchElementException is thrown. + +Problem: + Identical to (1). + A disconnected client can have a stash of UIDs from a +previous session. Some of these UIDs may have been expunged from the +server, but the disconnected client does not know this. It is quite +reasonable (and expected) for a disconnected client to use this +method when reconnecting - to check whether a set of UIDs are valid +or not at the server. + Since failure can be an expected result, using a +RunTimeException to indicate it, seems wrong and counter-intuitive for +the client. + +Solution: + Our solution is to allow this method to return null entries +to indicate that a requested UID is not valid anymore. Thus, the +message array returned by this method can have null entries for the +invalid UIDs; and this method will no longer throw the +java.util.NoSuchElementException. + Note that the size of the returned Message array is the same +as the size of the request array of UIDs, and that each entry in the +Message array corresponds to the same index entry in the UID array. +=================================================================== + +(4) InternetAddress +=================== + +The InternetAddress class needs the following protected field to +properly support encoding of the "personal name". + + protected String encodedPersonal; // the encoded personal name + +No other API changes are associated with this. + +This is a binary compatible change to JavaMail 1.0. However, there is +a potential problem for any existing InternetAddress subclasses, which +can cause them to break. This typically will affect only providers, +not clients. + +Details: +------- + +The InternetAddress implementation will use this field to store the +encoded personal name. + + The getPersonal() method will return the protected +'personal' field; if this field is null, it will check the 'encodedPersonal' +field and decode its value and return it. + The toString() method will use the protected 'encodedPersonal' +field to create the RFC2047 compliant address string. If this field is +null, it will check the 'personal' field, encode that if necessary and +use it. + +This implies that, if an InternetAddress subclass changes either +the 'personal' or 'encodedPersonal' fields, it should set the other +to null to force its recomputation. Unfortunately, this also implies +that existing subclasses of InternetAddress that directly set the +'personal' field can break in certain situations. + We feel that the risk of this happening is minimal, since we +don't expect that our users have subclassed InternetAddress. Also, this +is necessary to properly support encoded personal names, so we feel that +this has to be done. +================================================================ + +(5) MimeCharset +================ + +A utility method to convert java charsets into MIME charsets is +needed. + +The JDK supports a variety of charsets. The JDK has names for these +charsets, unfortunately they dont always match to their MIME or IANA +equivalents. + +It is necessary in some cases, (especially for providers) to map the +JDK charset names into their MIME or IANA equivalents. This method does +that. + +The API: +------- + +This is a new static method to the javax.mail.internet.MimeUtility class + + /** + * Convert a java charset into its MIME charset name.

+ * + * Note that a future version of JDK (post 1.2) might provide + * this functionality, in which case, we might deprecate this + * method then. + * + * @param charset the JDK charset + * @return the MIME/IANA equivalent. If a mapping + * is not possible, the passed in charset itself + * is returned. + */ + public static String mimeCharset(String charset); + +==================================================================== + +(6) getDefaultJavaCharset() +============================ + +This method returns the default charset for the platform's locale, as +a Java charset. This is a new static method to the MimeUtility class. + + /** + * Get the default charset for this locale.

+ * + * @return the default charset of the platform's locale, + * as a Java charset. (NOT a MIME charset) + */ + public static String getDefaultJavaCharset() + +==================================================================== + +(7) Method to print out the nested Exceptions +============================================= + +The MessagingException class currently allows nested exceptions. It +would be nice to have one single method to dump out all the +nested exceptions' messages into System.out + +Proposal +-------- + +Override the getMessage() method from the superclass (Throwable), to +append the messages from all nested Exceptions. This is similar to +java.rmi.RemoteException. + +================================================================== + +(8) New SearchTerms +==================== + +The current address related search terms - AddressTerm, FromTerm and +RecipientTerm are limited in that they operate on Address objects, not +Strings. These terms use the equals() method to compare the addresses - +which is not useful for the common case of substring comparisons. + +Hence we introduce three new SearchTerms: + +public AddressStringTerm extends StringTerm { + /** + * Constructor. + * @param pattern the address pattern to be compared + */ + protected AddressStringTerm(String pattern); + + /** + * Check whether the address pattern specified in the + * constructor is a substring of the string representation of + * the given Address object. + * + * @param address the address to match against + */ + protected boolean match(Address address); +} + +public FromStringTerm extends AddressStringTerm { + /** + * Constructor. + * @param address the address to be compared. + */ + public FromStringTerm(String string); + + /** + * Check whether the address specified in the constructor is + * a substring of the "From" attribute of this message. + * + * @param msg the address comparison is applied to this Message + */ + public boolean match(Message msg); +} + +public RecipientStringTerm extends AddressStringTerm { + + /** + * Constructor. + * + * @param type the recipient type + * @param address the address to be compared. + */ + public RecipientStringTerm(Message.RecipientType type, String address); + + /** + * Return the type of recipient to match with. + */ + public Message.RecipientType getRecipientType(); + + /** + * Check whether the address specified in the constructor is + * a substring of the given Recipient attribute of this message. + * + * @param msg the address comparison is applied to this Message + */ + public boolean match(Message msg); +} + +================================================================== + +(9) InternetAddress.toString(Address[] addresses, int used) +=========================================================== + +As per RFC2047 (MIME), the length of a header field that contains +encoded-words is limited to 76 characters. + +There are two methods in the InternetAddress class that generate +RFC822 style address strings: + + - The toString() method on InternetAddress, which generates + the string for one InternetAddress object + - The toString() static method, which generates a comma separated + string for the given array of InternetAddress objects. + +Both these methods currently do not honor the 76 character limit. +Actually, the former does to an extent, since the encodedWord +generator (i.e the MimeUtility.encodeWord() method) does break +encoded words into multiples, if they stretch beyond 76 characters. + +Solution +-------- + +For the 1.1 release, we are planning to fix the the toString() +static method as follows: + +Add a new static method + static String toString(Address[] address, int used) + +This method takes an array of Address objects and an integer representing +the number of "used" character positions for the first line of this +field. The typical use of this method is when setting RFC822 headers, +like the "From" header. 'used' can be set to sizeof("From: ") in +this case. + +When generating the string, this method starts a new line if the +addition of the next address.toString() causes the current line's +line-length to go over 76. + +Note that this algorithm does not work right if the length of a single +InternetAddress is itself more than 76 characters. Also, it does not +optimally break an address field, so that the maximum characters are +accommodated in a single line. + +So, essentially, this is an initial attempt to solve this problem. We +will add more APIs in the next version to further refine this. +================================================================== + +(10) Folder.getMode() +===================== + +It is currently not possible to tell whether a folder is open READ_ONLY +or READ_WRITE without attempting to write it and catching the exception. + +We propose to add a protected field to Folder to store the open mode and +a new method to Folder to return the open mode. Because existing +subclasses will not use this new field, we can't guarantee that the +method will always return the correct value (although all Folder subclasses +in the JavaMail package will be updated to return the correct value). + + /** + * The open mode (Folder.READ_ONLY, + * Folder.READ_WRITE, or -1 if not known). + */ + protected int mode = -1; + + /** + * Return the open mode of this folder. Returns + * Folder.READ_ONLY, Folder.READ_WRITE, + * or -1 if the open mode is not known (usually only because an older + * Folder provider has not been updated to use this new + * method). + * + * @exception IllegalStateException if this folder is not opened + * @return the open mode of this folder + */ + public int getMode() { + if (!isOpen()) + throw new IllegalStateException("Folder not open"); + return mode; + } + +==================================================================== + +(11) Folder.getURLName() +======================== + +The URLName support in the JavaMail 1.0 API's is incomplete and +inadequately specified. While you can get a Folder from a Session +given a URLName for the folder, you can't find out the URLName +for a given Folder object. We propose adding the following method +to Folder: + + /** + * Return a URLName representing this folder. The returned URLName + * does not include the password used to access the store. + * + * @return the URLName representing this folder + * @see URLName + */ + public URLName getURLName() throws MessagingException + +Previously it was not specified whether the URLName returned from +the Store.getURLName method would include the password field or +not, but sometimes it did. We propose to tighen the specification +and fix the implementation so that the password field is not returned: + + /** + * Return a URLName representing this store. The returned URLName + * does not include the password field.

+ * + * Subclasses should only override this method if their + * URLName does not follow the standard format. + * + * @return the URLName representing this store + * @see URLName + */ + public URLName getURLName() + +Similarly for Transport. + +Previously it was unspecified how the Store and Transport connect +methods interacted with the url field. In some cases it would be +updated and in other cases it would not. We propose to tighen the +specification as follows: + + /** + * Connect to the specified address. This method provides a simple + * authentication scheme that requires a username and password.

+ * + * If the connection is successful, an "open" ConnectionEvent is + * delivered to any ConnectionListeners on this Store.

+ * + * It is an error to connect to an already connected Store.

+ * + * The implementation in the Store class will collect defaults + * for the host, user, and password from the session, prompting the + * user if necessary, and will then call the protocolConnect method, + * which the subclass must override. The subclass should also + * implement the getURLName method, or use the + * implementation in this class.

+ * + * On a successful connection, the setURLName method is + * called with a URLName that includes the information used to make + * the connection, including the password.

+ * + * If the password passed in is null and this is the first successful + * connection to this store, the user name and the password + * collected from the user will be saved as defaults for subsequent + * connection attempts to this same store. If the password passed + * in is not null, it is not saved, on the assumption that the + * application is managing passwords explicitly. + * + * @param host the host to connect to + * @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 store is already connected + * @see javax.mail.event.ConnectionEvent + */ + public void connect(String host, String user, String password) + throws MessagingException + +And add this method to Store and Transport: + + /** + * Set the URLName representing this store. + * Normally used to update the url field + * after a store has successfully connected.

+ * + * Subclasses should only override this method if their + * URLName does not follow the standard format.

+ * + * The implementation in the Store class simply sets the + * url field. + * + * @see URLName + */ + protected void setURLName(URLName url) + +And finally, to simplify the implementation of Store and Transport, +and make the common design patterns between them more clear, we're +considering introducing a new Service class as a superclass of +Store and Transport, and moving all common methods (the various +connnect methods, URLName methods, and some listener methods) to +the superclass. Note that this is a binary compatible change. + +===================================================================== + +12) New Service class +====================== + +To emphasize the commonality in behavior between the Store and +Transport classes, and to simplify maintenance of these classes, we +propose moving many of the common methods to a new superclass called +javax.mail.Service. Store and Transport would then extend Service. +These existing methods currently have identical implementations in the +Store and Transport classes so moving them to a common superclass will +not change the behavior of either Store or Transport. + +The Service class will contain all the methods and fields having to do +with connecting, connection listeners, and naming via URLNames. The +Store class retains the methods for getting Folders and managing Store +and Folder listeners. The Transport class retains the methods for +sending messages and managing Transport listeners. + +Note that this is a binary compatible change both for existing users of +the Store and Transport classes, as well as for existing subclasses of +these classes. + +====================================================================== diff --git a/www/docs/JavaMail-1.2-changes.txt b/www/docs/JavaMail-1.2-changes.txt new file mode 100644 index 00000000..8c64f08f --- /dev/null +++ b/www/docs/JavaMail-1.2-changes.txt @@ -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 + * content array is assumed to be valid and is used + * directly in the writeTo method. This flag is + * set to true when an empty message is created or when the + * saveChanges method is called. + */ + protected boolean modified = false; + + /** + * Parse the InputStream setting the headers and + * content fields appropriately. Also resets the + * modified flag.

+ * + * 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 headers field is set to an empty InternetHeaders + * object. The flags field is set to an empty Flags + * object. The modified flag is set to true. + */ + public MimeMessage(Session session) + + /** + * Output the message as an RFC 822 format stream, without + * specified headers. If the modified flag is not + * set and the content array is not null, the + * content 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.

+ * + * If any part of a message's headers or contents are changed, + * saveChanges 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.

+ * + * Messages obtained from folders opened READ_ONLY should not be + * modified and saveChanges should not be called on such messages.

+ * + * This method sets the modified flag to true and then + * calls the updateHeaders 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 parsed 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 + * getInputStream method or getContent method + * from returning the correct data. In such a case the application may + * use this method and attempt to decode the raw data itself.

+ * + * This implementation simply calls the getContentStream + * 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.

+ */ + +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 + * source MimeMessage. The new message is independent + * of the original.

+ * + * @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 connect method + * calls this method as needed.

+ * + * The protocolConnect method should return + * false if a user name or password is required + * for authentication but the corresponding parameter is null; + * the connect method will prompt the user when + * needed to supply missing information. This method may + * also return false 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.

+ * + * The protocolConnect 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.

+ * + * This class does not take pattern strings. It always formats the + * date based on the specification below.

+ * + * 3.3 Date and Time Specification

+ * + * 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.

+ * + * date-time = [ day-of-week "," ] date FWS time [CFWS]

+ * + * day-of-week = ([FWS] day-name) / obs-day-of-week

+ * + * day-name = "Mon" / "Tue" / "Wed" / "Thu" / "Fri" / "Sat" / "Sun"

+ * + * date = day month year

+ * + * year = 4*DIGIT / obs-year

+ * + * month = (FWS month-name FWS) / obs-month

+ * + *

month-name = "Jan" / "Feb" / "Mar" / "Apr" /
+ *             "May" / "Jun" / "Jul" / "Aug" /
+ *             "Sep" / "Oct" / "Nov" / "Dec"
+ *

+ * day = ([FWS] 1*2DIGIT) / obs-day

+ * + * time = time-of-day FWS zone

+ * + * time-of-day = hour ":" minute [ ":" second ]

+ * + * hour = 2DIGIT / obs-hour

+ * + * minute = 2DIGIT / obs-minute

+ * + * second = 2DIGIT / obs-second

+ * + * zone = (( "+" / "-" ) 4DIGIT) / obs-zone

+ * + * + * The day is the numeric day of the month. The year is any numeric year in + * the common era.

+ * + * The time-of-day specifies the number of hours, minutes, and optionally + * seconds since midnight of the date indicated.

+ * + * The date and time-of-day SHOULD express local time.

+ * + * 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.

+ * + * 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.

+ * + */ +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 null, 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.

+ * + * 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.
+ * 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.
+ * 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 filename 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 saveChanges method need to be called on + * this message? This flag is set to false by the public constructor + * and set to true by the saveChanges method. The + * writeTo method checks this flag and calls the + * saveChanges method as necessary. This avoids the + * common mistake of forgetting to call the saveChanges + * 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.

+ * + * If any part of a message's headers or contents are changed, + * saveChanges 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.

+ * + * Messages obtained from folders opened READ_ONLY should not be + * modified and saveChanges should not be called on such messages.

+ * + * This method sets the modified flag to true, the + * save flag to true, and then calls the + * updateHeaders 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 saved flag is not set, + * the saveChanges method is called. + * If the modified flag is not + * set and the content array is not null, the + * content 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 getEncoding(DataSource) except that instead + * of reading the data from an InputStream it uses the + * writeTo method to examine the data. This is more + * efficient in the common case of a DataHandler + * 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 InputStream the + * DataHandler uses a thread, a pair of pipe streams, + * and the writeTo method to produce the data.

+ */ + 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 personal 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.

+ * + * This implementation returns an array with a single entry containing + * the return value of the getDefaultFolder 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 + * user. 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.

+ * + * 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 shared 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.

+ * + * 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 null + * 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 null 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, + * contentStream is another such stream representing + * the content of this message. In this case, content + * 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, + * contentStream is another such stream representing + * the content of this body part. In this case, content + * 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 start (inclusive) + * up to end (exclusive). start must be + * non-negative. If end 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) diff --git a/www/docs/JavaMail-1.3-changes.txt b/www/docs/JavaMail-1.3-changes.txt new file mode 100644 index 00000000..78cb952b --- /dev/null +++ b/www/docs/JavaMail-1.3-changes.txt @@ -0,0 +1,303 @@ + + JavaMail 1.3 + ============ + + (Updated April 1, 2002) + +Following is a description of the new APIs that are being +introduced in JavaMail 1.3. 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. + +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." + + +=================================================================== + +1. Add setSender and getSender methods to MimeMessage (4405115) +--------------------------------------------------------------- + +These convenience methods support setting and reading the RFC 822 +Sender header. + + /** + * Returns the value of the RFC 822 "Sender" header field. + * If the "Sender" header field is absent, null + * is returned.

+ * + * This implementation uses the getHeader method + * to obtain the requisite header field. + * + * @return Address object + * @exception MessagingException + * @see #headers + * @since JavaMail 1.3 + */ + public Address getSender() throws MessagingException + + /** + * Set the RFC 822 "Sender" header field. Any existing values are + * replaced with the given address. If address is null, + * this header is removed. + * + * @param address the sender of this message + * @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 + * @since JavaMail 1.3 + */ + public void setSender(Address address) throws MessagingException + +=================================================================== + +2. Add setContentID method to MimeBodyPart (4377720) +---------------------------------------------------- + +This convenience method supports setting the Content-ID header. + + /** + * Set the "Content-ID" header field of this body part. + * If the cid parameter is null, any existing + * "Content-ID" is removed. + * + * @exception IllegalWriteException if the underlying + * implementation does not support modification + * @exception IllegalStateException if this body part is + * obtained from a READ_ONLY folder. + * @exception MessagingException + * @since JavaMail 1.3 + */ + public void setContentID(String cid) throws MessagingException + +=================================================================== + +3. Add mail.mime.charset property (4377731) +------------------------------------------- + +The "mail.mime.charset" System property (NOTE: *not* Session property) +names the default charset to be used by JavaMail. If not set, the +standard J2SE "file.encoding" System property is used. This allows +applications to specify a default character set for sending messages +that's different than the character set used for files stored on the +system. This is common on Japanese systems. + +=================================================================== + +4. Add getDeletedMesageCount method to Folder (4388730) +------------------------------------------------------- + +This convenience method would return a count of the number of deleted +messages in a folder. + + /** + * Get the number of deleted messages in this Folder.

+ * + * This method can be invoked on a closed folder. However, note + * that for some folder implementations, getting the deleted message + * count can be an expensive operation involving actually opening + * the folder. In such cases, a provider can choose not to support + * this functionality in the closed state, in which case this method + * must return -1.

+ * + * Clients invoking this method on a closed folder must be aware + * that this is a potentially expensive operation. Clients must + * also be prepared to handle a return value of -1 in this case.

+ * + * This implementation returns -1 if this folder is closed. Else + * this implementation gets each Message in the folder using + * getMessage(int) and checks whether its + * DELETED flag is set. The total number of messages + * that have this flag set is returned. + * + * @return number of deleted messages. -1 may be returned + * by certain implementations if this method is + * invoked on a closed folder. + * @exception FolderNotFoundException if this folder does + * not exist. + * @exception MessagingException + * @since JavaMail 1.3 + */ + public int getDeletedMessageCount() throws MessagingException + +=================================================================== + +5. Support parsing "illegal" Internet addresses (4650940) +--------------------------------------------------------- + +The parse method on the InternetAddress class takes a flag that tells +whether or not to strictly enforce the RFC822 syntax rules. Currently, +when the flag is false most rules are still checked while a few are not. +To better support the range of "invalid" addresses seen in real messages, +and in combination with the following two changes, the parseHeader +method would enforce fewer syntax rules when the strict flag is false +and would enforce more rules when the strict flag is true. If the +strict flag is false and the parse is successful in separating out an +email address or addresses, the syntax of the addresses themselves +would not be checked. (Introducing a new method preserves +compatibility with users of the existing parse method.) + + /** + * Parse the given sequence of addresses into InternetAddress + * objects. If strict is false, the full syntax rules for + * individual addresses are not enforced. If strict is + * true, many (but not all) of the RFC822 syntax rules are enforced. + * + * Non-strict parsing is typically used when parsing a list of + * mail addresses entered by a human. Strict parsing is typically + * used when parsing address headers in mail messages. + * + * @param addresslist comma separated address strings + * @param strict enforce RFC822 syntax + * @return array of InternetAddress objects + * @exception AddressException if the parse failed + * @since JavaMail 1.3 + */ + public static InternetAddress[] parseHeader(String s, boolean strict) + throws AddressException + + +To allow applications to check the syntax of addresses that might've +been parsed with the strict flag set to false, we add a validate +method. + + /** + * Validate that this address conforms to the syntax rules + * of RFC 822. The current implementation checks many, not + * all, syntax rules. Note that, even though the syntax of + * the address may be correct, there's no guarantee that a + * mailbox of that name exists. + * + * @exception AddressException if the address + * isn't valid. + * @since JavaMail 1.3 + */ + public void validate() throws AddressException + + +To control the strict flag when constructing a single InternetAddress +object we add a new constructor. + + /** + * Parse the given string and create an InternetAddress. + * If strict is false, the detailed syntax of the + * address isn't checked. + * + * @param address the address in RFC822 format + * @param strict enforce RFC822 syntax + * @exception AddressException if the parse failed + * @since JavaMail 1.3 + */ + public InternetAddress(String address, boolean strict) + throws AddressException + +=================================================================== + +6. Add mail.mime.address.strict property (4650940) +-------------------------------------------------- + +The MimeMessage class will use the new parseHeader method introduced +above to parse headers in messages. The "mail.mime.address.strict" +Session property will control the strict flag passed to the parseHeader +method. The default is true. + +=================================================================== + +7. Add mail.mime.decodetext.strict property (4201203) +----------------------------------------------------- + +RFC 2047 requires that encoded text start at the beginning of a +whitespace separated word. Some mailers, especially Japanese mailers, +improperly encode text and included encoded text in the middle of words. +The "mail.mime.decodetext.strict" System property (NOTE: *not* Session +property) controls whether JavaMail will attempt to decode such +incorrectly encoded text. The default is true. + +=================================================================== + +8. Add mail.mime.encodeeol.strict property (4650949) +---------------------------------------------------- + +When choosing an encoding for the data of a message, JavaMail assumes +that any of CR, LF, or CRLF are valid line terminators in message +parts that contain only printable ASCII characters, even if the part is +not a MIME text type. It's common, especially on UNIX systems, for +data of MIME type application/octet-stream (for example) to really be +textual data that should be transmitted with the encoding rules for +MIME text. In rare cases, such pure ASCII text may in fact be binary +data in which the CR and LF characters must be preserved exactly. The +"mail.mime.encodeeol.strict" System property (NOTE: *not* Session +property) controls whether JavaMail will consider a lone CR or LF in a +body part that's not a MIME text type to indicate that the body part +needs to be encoded. + +=================================================================== + +9. Add isGroup and getGroup methods to InternetAddress (4650952) +---------------------------------------------------------------- + +To better support RFC822 group addresses, the following methods +would be added. + + /** + * Indicates whether this address is an RFC 822 group address. + * Note that a group address is different than the mailing + * list addresses supported by most mail servers. Group addresses + * are rarely used; see RFC 822 for details. + * + * @return true if this address represents a group + * @since JavaMail 1.3 + */ + public boolean isGroup() + + /** + * Return the members of a group address. A group may have zero, + * one, or more members. If this address is not a group, null + * is returned. The strict parameter controls whether + * the group list is parsed using strict RFC 822 rules or not. + * The parsing is done using the parseHeader method. + * + * @return array of InternetAddress objects, or null + * @exception AddressException if the group list can't be parsed + * @since JavaMail 1.3 + */ + public InternetAddress[] getGroup(boolean strict) throws AddressException + + +=================================================================== + +10. Support per-session debug output stream (4517686) +----------------------------------------------------- + +To allow the debugging output for a session to be redirected, we add +the following methods to Session. + + /** + * Set the stream to be used for debugging output for this session. + * If out is null, System.out will be used. + * Note that debugging output that occurs before any session is created, + * as a result of setting the mail.debug system property, + * will always be sent to System.out. + * + * @param out the PrintStream to use for debugging output + * @since JavaMail 1.3 + */ + public void setDebugOut(PrintStream out) + + /** + * Returns the stream to be used for debugging output. If no stream + * has been set, System.out is returned. + * + * @return the PrintStream to use for debugging output + * @since JavaMail 1.3 + */ + public PrintStream getDebugOut() diff --git a/www/docs/JavaMail-1.4-changes.txt b/www/docs/JavaMail-1.4-changes.txt new file mode 100644 index 00000000..d0309961 --- /dev/null +++ b/www/docs/JavaMail-1.4-changes.txt @@ -0,0 +1,1061 @@ + + 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 mail.mime.encodefilename 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 mail.mime.encodefilename 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 + * connect(host, user, password) 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 mail.mime.multipart.ignoremissingendboundary + * System property may be set to false to cause a + * MessagingException to be thrown if the multipart + * data does not end with the required end boundary line. If this + * property is set to true or not set, missing end + * boundaries are not considered an error and the final body part + * ends at the end of the data.

+ + +=================================================================== + +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 mail.mime.multipart.ignoremissingboundaryparameter + * System property may be set to false to cause a + * MessagingException to be thrown if the Content-Type + * of the MimeMultipart does not include a boundary parameter. + * If this property is set to true 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 updateHeaders 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 + * setText, setContent, or + * setDataHandler 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 + * used indicates how many characters have been used in + * the current line; it is usually the length of the header name.

+ * + * 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 + * javamail.default.address.map or + * javamail.address.map 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 + * mail.mime.encodeparameters 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 RFC 2087 + * for more information.

+ * + * @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 + * getQuota 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 + * Quota.Resource 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 charset + * 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 IOException + * 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 offset for length + * 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 start (inclusive) + * up to end (exclusive). start must be + * non-negative. If end 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 SharedFileInputStream is a + * BufferedInputStream that buffers + * data from the file and supports the mark + * and reset methods. It also supports the + * newStream method that allows you to create + * other streams that represent subsets of the file. + * A RandomAccessFile 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 SharedFileInputStream + * for the file. + * + * @param file the file + */ + public SharedFileInputStream(File file) throws IOException + + /** + * Creates a SharedFileInputStream + * for the named file. + * + * @param file the file + */ + public SharedFileInputStream(String file) throws IOException + + /** + * Creates a SharedFileInputStream + * 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 SharedFileInputStream + * 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 read + * method of InputStream. + * + * @return the next byte of data, or -1 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. + * + *

This method implements the general contract of the corresponding + * {@link java.io.InputStream#read(byte[], int, int) read} + * method of the {@link java.io.InputStream} 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 -1 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 skip + * method of InputStream. + * + * @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 mark + * method of InputStream. + * + * @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 reset + * method of InputStream. + *

+ * If markpos is -1 + * (no mark has been set or the mark has been + * invalidated), an IOException + * is thrown. Otherwise, pos is + * set equal to markpos. + * + * @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 mark + * and reset methods. The markSupported + * method of SharedFileInputStream returns + * true. + * + * @return a boolean indicating if this stream type supports + * the mark and reset 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 start (inclusive) + * up to end (exclusive). start must be + * non-negative. If end 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 +} diff --git a/www/docs/JavaMail-1.5-changes.txt b/www/docs/JavaMail-1.5-changes.txt new file mode 100644 index 00000000..655400dc --- /dev/null +++ b/www/docs/JavaMail-1.5-changes.txt @@ -0,0 +1,823 @@ + + JavaMail 1.5 + ============ + + (Updated February 7, 2013) + +Following is a description of the changes to the JavaMail +API introduced in JavaMail 1.5. The numbers in parentheses +are bug numbers; you can find more information about the +bug reports at: + + https://github.com/javaee/javamail/issues/ + +Please send comments and feedback to javamail_ww@oracle.com. + +JavaMail 1.5 will also require at least J2SE 5.0. This allows +JavaMail to take advantage of features of more modern Java SE releases. + + +=================================================================== + +1. Add FetchProfile.Item.SIZE (37) +---------------------------------- + +The FetchProfile.Item.SIZE item allows prefetching the size of +a message. Previously this was an IMAP-specific fetch item. + + /** + * SIZE is a fetch profile item that can be included in a + * FetchProfile during a fetch request to a Folder. + * This item indicates that the sizes of the messages in the specified + * range should be prefetched.

+ * + * @since JavaMail 1.5 + */ + public static final Item SIZE; + + +=================================================================== + +2. Fix protected fields in final classes in javax.mail.search (38) +------------------------------------------------------------------ + +Several final classes in the javax.mail.search package contain +protected fields. Since the classes are final, they can't be +subclassed, and the protected fields can not be accessed. This +change cleans up these fields by making them private. The following +fields are changed: + +javax.mail.search.AndTerm: + private SearchTerm[] terms; + +javax.mail.search.FlagTerm: + private boolean set; + private Flags flags; + +javax.mail.search.HeaderTerm: + private String headerName; + +javax.mail.search.NotTerm: + private SearchTerm term; + +javax.mail.search.OrTerm: + private SearchTerm[] terms; + +javax.mail.search.RecipientTerm: + private Message.RecipientType type; + + +=================================================================== + +3. Add MimeMultipart(String subtype, BodyPart... bps) constructor (39) +---------------------------------------------------------------------- + +These convenience constructors create a MimeMultipart object given an +array or varargs list of BodyParts. + + /** + * Construct a MimeMultipart object of the default "mixed" subtype, + * and with the given body parts. More body parts may be added later. + * + * @since JavaMail 1.5 + */ + public MimeMultipart(BodyPart... parts) throws MessagingException + + /** + * Construct a MimeMultipart object of the given subtype + * and with the given body parts. More body parts may be added later. + * + * @since JavaMail 1.5 + */ + public MimeMultipart(String subtype, BodyPart... parts) + throws MessagingException + + +=================================================================== + +4. Exceptions should support exception chaining (40) +---------------------------------------------------- + +javax.mail.MessagingException was designed before exception chainging +was added to Java SE, but it does support a similar concept itself, +and that support should be made available to all subclasses. + +javax.mail.AuthenticationFailedException: + /** + * Constructs an AuthenticationFailedException with the specified + * detail message and embedded exception. The exception is chained + * to this exception. + * + * @param message The detailed error message + * @param e The embedded exception + * @since JavaMail 1.5 + */ + public AuthenticationFailedException(String message, Exception e) + +javax.mail.FolderClosedException: + /** + * Constructs a FolderClosedException with the specified + * detail message and embedded exception. The exception is chained + * to this exception. + * + * @param folder The Folder + * @param message The detailed error message + * @param e The embedded exception + * @since JavaMail 1.5 + */ + public FolderClosedException(Folder folder, String message, Exception e) + +javax.mail.FolderNotFoundException: + /** + * Constructs a FolderNotFoundException with the specified + * detail message and embedded exception. The exception is chained + * to this exception. + * + * @param folder The Folder + * @param s The detailed error message + * @param e The embedded exception + * @since JavaMail 1.5 + */ + public FolderNotFoundException(Folder folder, String s, Exception e) + +javax.mail.IllegalWriteException: + /** + * Constructs an IllegalWriteException with the specified + * detail message and embedded exception. The exception is chained + * to this exception. + * + * @param s The detailed error message + * @param e The embedded exception + * @since JavaMail 1.5 + */ + public IllegalWriteException(String s, Exception e) + +javax.mail.MessageRemovedException: + /** + * Constructs a MessageRemovedException with the specified + * detail message and embedded exception. The exception is chained + * to this exception. + * + * @param s The detailed error message + * @param e The embedded exception + * @since JavaMail 1.5 + */ + public MessageRemovedException(String s, Exception e) + +javax.mail.MethodNotSupportedException: + /** + * Constructs a MethodNotSupportedException with the specified + * detail message and embedded exception. The exception is chained + * to this exception. + * + * @param s The detailed error message + * @param e The embedded exception + * @since JavaMail 1.5 + */ + public MethodNotSupportedException(String s, Exception e) + +javax.mail.NoSuchProviderException: + /** + * Constructs a NoSuchProviderException with the specified + * detail message and embedded exception. The exception is chained + * to this exception. + * + * @param message The detailed error message + * @param e The embedded exception + * @since JavaMail 1.5 + */ + public NoSuchProviderException(String message, Exception e) + +javax.mail.ReadOnlyFolderException: + /** + * Constructs a ReadOnlyFolderException with the specified + * detail message and embedded exception. The exception is chained + * to this exception. + * + * @param folder The Folder + * @param message The detailed error message + * @param e The embedded exception + * @since JavaMail 1.5 + */ + public ReadOnlyFolderException(Folder folder, String message, Exception e) + +javax.mail.StoreClosedException: + /** + * Constructs a StoreClosedException with the specified + * detail message and embedded exception. The exception is chained + * to this exception. + * + * @param store The dead Store object + * @param message The detailed error message + * @param e The embedded exception + * @since JavaMail 1.5 + */ + public StoreClosedException(Store store, String message, Exception e) + + +=================================================================== + +5. ParameterList needs to support use by IMAP (41) +-------------------------------------------------- + +The IMAP provider has special needs when processing multi-segment +parameters defined by RFC 2231. This new method supports such use +by the IMAP provider. + + /** + * Normal users of this class will use simple parameter names. + * In some cases, for example, when processing IMAP protocol + * messages, individual segments of a multi-segment name + * (specified by RFC 2231) will be encountered and passed to + * the {@link #set} method. After all these segments are added + * to this ParameterList, they need to be combined to represent + * the logical parameter name and value. This method will combine + * all segments of multi-segment names.

+ * + * Normal users should never need to call this method. + * + * @since JavaMail 1.5 + */ + public void combineSegments() + + +=================================================================== + +6. ContentType and ContentDisposition toString should never return null (42) +---------------------------------------------------------------------------- + +The general contract of Object.toString is that it never returns null. +The toString methods of ContentType and ContentDisposition were defined +to return null in certain error cases. Given the general toString contract +it seems unlikely that anyone ever depended on these special cases, and +it would be more useful for these classes to obey the general contract. +These methods have been changed to return an empty string in these error +cases. + +javax.mail.internet.ContentType: + /** + * Retrieve a RFC2045 style string representation of + * this Content-Type. Returns an empty string if + * the conversion failed. + * + * @return RFC2045 style string + */ + public String toString() + +javax.mail.internet.ContentDisposition: + /** + * Retrieve a RFC2045 style string representation of + * this ContentDisposition. Returns an empty string if + * the conversion failed. + * + * @return RFC2045 style string + * @since JavaMail 1.2 + */ + public String toString() + + +=================================================================== + +7. Add Transport.send(msg, username, password) method (44) +---------------------------------------------------------- + +It's now very common that email servers require authentication before +sending a message, so we add these new convenience methods. + + /** + * Send a message. The message will be sent to all recipient + * addresses specified in the message (as returned from the + * Message method getAllRecipients). + * The send method calls the saveChanges + * method on the message before sending it.

+ * + * Use the specified user name and password to authenticate to + * the mail server. + * + * @param msg the message to send + * @param user the user name + * @param password this user's password + * @exception SendFailedException if the message could not + * be sent to some or any of the recipients. + * @exception MessagingException + * @see Message#saveChanges + * @see #send(Message) + * @see javax.mail.SendFailedException + * @since JavaMail 1.5 + */ + public static void send(Message msg, + String user, String password) throws MessagingException + + /** + * Send the message to the specified addresses, ignoring any + * recipients specified in the message itself. The + * send method calls the saveChanges + * method on the message before sending it.

+ * + * Use the specified user name and password to authenticate to + * the mail server. + * + * @param msg the message to send + * @param addresses the addresses to which to send the message + * @param user the user name + * @param password this user's password + * @exception SendFailedException if the message could not + * be sent to some or any of the recipients. + * @exception MessagingException + * @see Message#saveChanges + * @see #send(Message) + * @see javax.mail.SendFailedException + * @since JavaMail 1.5 + */ + public static void send(Message msg, Address[] addresses, + String user, String password) throws MessagingException + + +=================================================================== + +8. Add MimeMessage.setFrom(String) method (45) +---------------------------------------------- + +This new convenience method allows the From header to be set using a String. + + /** + * Set the RFC 822 "From" header field. Any existing values are + * replaced with the given addresses. If address is null, + * this header is removed. + * + * @param address the sender(s) of this message + * @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 + * @since JvaMail 1.5 + */ + public void setFrom(String address) throws MessagingException + + +=================================================================== + +9. Add Message.getSesssion() method (46) +---------------------------------------- + +Alow access to the Session used when the Message was created. + + /** + * Return the Session used when this message was created. + * + * @return the message's Session + * @since JavaMail 1.5 + */ + public Session getSession() + + +=================================================================== + +10. MimeBodyPart.attachFile should set the disposition to ATTACHMENT (47) +------------------------------------------------------------------------- + +An oversight when these methods were originally added. Clearly attachments +should set the disposition to ATTACHMENT. + + /** + * 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. The disposition of this part is set to + * {@link Part#ATTACHMENT Part.ATTACHMENT}. + * + * @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 + + +=================================================================== + +11. Add MimeMessage.reply(replyToAll, setAnswered) method (48) +-------------------------------------------------------------- + +Add a method to control whether the ANSWERED flag is set in the original +message when creating a reply message. + + /** + * Get a new Message suitable for a reply to this message. + * The new Message will have its attributes and headers + * set up appropriately. Note that this new message object + * will be empty, i.e., it will not have a "content". + * These will have to be suitably filled in by the client.

+ * + * If replyToAll is set, the new Message will be addressed + * to all recipients of this message. Otherwise, the reply will be + * addressed to only the sender of this message (using the value + * of the getReplyTo method).

+ * + * If setAnswered is set, the + * {@link javax.mail.Flags.Flag#ANSWERED ANSWERED} flag is set + * in this message.

+ * + * The "Subject" field is filled in with the original subject + * prefixed with "Re:" (unless it already starts with "Re:"). + * The "In-Reply-To" header is set in the new message if this + * message has a "Message-Id" header. + * + * The current implementation also sets the "References" header + * in the new message to include the contents of the "References" + * header (or, if missing, the "In-Reply-To" header) in this message, + * plus the contents of the "Message-Id" header of this message, + * as described in RFC 2822. + * + * @param replyToAll reply should be sent to all recipients + * of this message + * @param setAnswered set the ANSWERED flag in this message? + * @return the reply Message + * @exception MessagingException + * @since JavaMail 1.5 + */ + public Message reply(boolean replyToAll, boolean setAnswered) + throws MessagingException + + +=================================================================== + +12. Add additional "next" methods to HeaderTokenizer (49) +--------------------------------------------------------- + +These additional "next" methods make it easier to parse headers that don't +obey the MIME syntax requirements. + + /** + * Parses the next token from this String. + * If endOfAtom is not NUL, the token extends until the + * endOfAtom character is seen, or to the end of the header. + * This method is useful when parsing headers that don't + * obey the MIME specification, e.g., by failing to quote + * parameter values that contain spaces. + * + * @param endOfAtom if not NUL, character marking end of token + * @return the next Token + * @exception ParseException if the parse fails + * @since JavaMail 1.5 + */ + public Token next(char endOfAtom) throws ParseException + + /** + * Parses the next token from this String. + * endOfAtom is handled as above. If keepEscapes is true, + * any backslash escapes are preserved in the returned string. + * This method is useful when parsing headers that don't + * obey the MIME specification, e.g., by failing to escape + * backslashes in the filename parameter. + * + * @param endOfAtom if not NUL, character marking end of token + * @param keepEscapes keep all backslashes in returned string? + * @return the next Token + * @exception ParseException if the parse fails + * @since JavaMail 1.5 + */ + public Token next(char endOfAtom, boolean keepEscapes) + throws ParseException + + +=================================================================== + +13. Add @MailSessionDefinition and @MailSessionDefinitions for Java EE 7 (51) +----------------------------------------------------------------------------- + +These new annotations support configuring JavaMail Session resources in +Java EE 7 application servers. + +javax.mail.MailSessionDefinition: + +/** + * Annotation used by Java EE applications to define a MailSession + * to be registered with JNDI. The MailSession may be configured + * by setting the annotation elements for commonly used Session + * properties. Additional standard and vendor-specific properties may be + * specified using the properties element. + *

+ * The session will be registered under the name specified in the + * name element. It may be defined to be in any valid + * Java EE namespace, and will determine the accessibility of + * the session from other components. + * + * @since JavaMail 1.5 + */ +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +public @interface MailSessionDefinition { + + /** + * Description of this mail session. + */ + String description() default ""; + + /** + * JNDI name by which the mail session will be registered. + */ + String name(); + + /** + * Store protocol name. + */ + String storeProtocol() default ""; + + /** + * Transport protocol name. + */ + String transportProtocol() default ""; + + /** + * Host name for the mail server. + */ + String host() default ""; + + /** + * User name to use for authentication. + */ + String user() default ""; + + /** + * Password to use for authentication. + */ + String password() default ""; + + /** + * From address for the user. + */ + String from() default ""; + + /** + * Properties to include in the Session. + * Properties are specified using the format: + * propertyName=propertyValue with one property per array element. + */ + String[] properties() default {}; +} + + +javax.mail.MailSessionDefinitions: + +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import java.lang.annotation.ElementType; +import java.lang.annotation.RetentionPolicy; + +/** + * Declares one or more MailSessionDefinition annotations. + * + * @see MailSessionDefinition + * @since JavaMail 1.5 + */ +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +public @interface MailSessionDefinitions { + MailSessionDefinition[] value(); +} + + +=================================================================== + +14. Make cachedContent field protected in MimeMessage and MimeBodyPart (52) +--------------------------------------------------------------------------- + +Exposing this previously private field makes it easier to subclass these +classes. + + /** + * If our content is a Multipart or Message object, we save it + * the first time it's created by parsing a stream so that changes + * to the contained objects will not be lost.

+ * + * If this field is not null, it's return by the {@link #getContent} + * method. The {@link #getContent} method sets this field if it + * would return a Multipart or MimeMessage object. This field is + * is cleared by the {@link #setDataHandler} method. + * + * @since JavaMail 1.5 + */ + protected Object cachedContent; + + +=================================================================== + +15. Make MimeMultipart fields protected to allow subclassing (53) +----------------------------------------------------------------- + +Most of these fields control how the MimeMultipart class parses messages +that don't conform to the MIME spec. The new initializeProperties method +initializes these fields based on System properties. Exposing these +previously private fields makes it easier to subclass MimeMultipart. + + /** + * Have we seen the final bounary line? + * + * @since JavaMail 1.5 + */ + protected boolean complete = true; + + /** + * The MIME multipart preamble text, the text that + * occurs before the first boundary line. + * + * @since JavaMail 1.5 + */ + protected String preamble = null; + + /** + * Flag corresponding to the "mail.mime.multipart.ignoremissingendboundary" + * property, set in the {@link #initializeProperties} method called from + * constructors and the parse method. + * + * @since JavaMail 1.5 + */ + protected boolean ignoreMissingEndBoundary = true; + + /** + * Flag corresponding to the + * "mail.mime.multipart.ignoremissingboundaryparameter" + * property, set in the {@link #initializeProperties} method called from + * constructors and the parse method. + * + * @since JavaMail 1.5 + */ + protected boolean ignoreMissingBoundaryParameter = true; + + /** + * Flag corresponding to the + * "mail.mime.multipart.ignoreexistingboundaryparameter" + * property, set in the {@link #initializeProperties} method called from + * constructors and the parse method. + * + * @since JavaMail 1.5 + */ + protected boolean ignoreExistingBoundaryParameter = false; + + /** + * Flag corresponding to the "mail.mime.multipart.allowempty" + * property, set in the {@link #initializeProperties} method called from + * constructors and the parse method. + * + * @since JavaMail 1.5 + */ + protected boolean allowEmpty = false; + + /** + * Initialize flags that control parsing behavior, + * based on System properties described above in + * the class documentation. + * + * @since JavaMail 1.5 + */ + protected void initializeProperties() + +The following additional System properties are defined corresponding to +the last two fields above: + +mail.mime.multipart.ignoreexistingboundaryparameter: + + Normally the boundary parameter in the Content-Type header of a multipart + body part is used to specify the separator between parts of the multipart + body. This System property may be set to "true" to cause + the parser to look for a line in the multipart body that looks like a + boundary line and use that value as the separator between subsequent parts. + This may be useful in cases where a broken anti-virus product has rewritten + the message incorrectly such that the boundary parameter and the actual + boundary value no longer match. + The default value of this property is false. + +mail.mime.multipart.allowempty: + + Normally, when writing out a MimeMultipart that contains no body + parts, or when trying to parse a multipart message with no body parts, + a MessagingException is thrown. The MIME spec does not allow + multipart content with no body parts. This + System property may be set to "true" to override this behavior. + When writing out such a MimeMultipart, a single empty part will be + included. When reading such a multipart, a MimeMultipart will be created + with no body parts. + The default value of this property is false. + + +=================================================================== + +16. Need simple way to override MIME type and encoding of attachment (55) +------------------------------------------------------------------------- + +First, we define an interface that allows a DataSource to specify the +Content-Transfer-Encoding to use: + +package javax.mail; + +/** + * A {@link javax.activation.DataSource DataSource} that also implements + * EncodingAware may specify the Content-Transfer-Encoding + * to use for its data. Valid Content-Transfer-Encoding values specified + * by RFC 2045 are "7bit", "8bit", "quoted-printable", "base64", and "binary". + *

+ * For example, a {@link javax.activation.FileDataSource FileDataSource} + * could be created that forces all files to be base64 encoded:

+ * 

+ *  public class Base64FileDataSource extends FileDataSource
+ *					implements EncodingAware {
+ *	public Base64FileDataSource(File file) {
+ *	    super(file);
+ *	}
+ *
+ *	// implements EncodingAware.getEncoding()
+ *	public String getEncoding() {
+ *	    return "base64";
+ *	}
+ *  }
+ *

+ * + * @since JavaMail 1.5 + * @author Bill Shannon + */ + +public interface EncodingAware { + + /** + * Return the MIME Content-Transfer-Encoding to use for this data, + * or null to indicate that an appropriate value should be chosen + * by the caller. + * + * @return the Content-Transfer-Encoding value, or null + */ + public String getEncoding(); +} + +Then we add new methods to MimeBodyPart: + + /** + * Use the specified file with the specified Content-Type and + * Content-Transfer-Encoding to provide the data for this part. + * If contentType or encoding are null, appropriate values will + * be chosen. + * 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 disposition of this part is set to + * {@link Part#ATTACHMENT Part.ATTACHMENT}. + * + * @param file the File object to attach + * @param contentType the Content-Type, or null + * @param encoding the Content-Transfer-Encoding, or null + * @exception IOException errors related to accessing the file + * @exception MessagingException message related errors + * @since JavaMail 1.5 + */ + public void attachFile(File file, String contentType, String encoding) + throws IOException, MessagingException + + /** + * Use the specified file with the specified Content-Type and + * Content-Transfer-Encoding to provide the data for this part. + * If contentType or encoding are null, appropriate values will + * be chosen. + * 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 disposition of this part is set to + * {@link Part#ATTACHMENT Part.ATTACHMENT}. + * + * @param file the name of the file + * @param contentType the Content-Type, or null + * @param encoding the Content-Transfer-Encoding, or null + * @exception IOException errors related to accessing the file + * @exception MessagingException message related errors + * @since JavaMail 1.5 + */ + public void attachFile(String file, String contentType, String encoding) + throws IOException, MessagingException + + +=================================================================== + +17. Enable RFC 2231 support by default (56) +------------------------------------------- + +RFC 2231 support for encoded parameter values is now widely implemented, +it's time to change the default to support this standard. Given the +way RFC 2231 is defined, it's extremely unlikely that this would cause +compatibility problems with existing applications. + +The System properties mail.mime.decodeparameters and mail.mime.encodeparameters +now default to true instead of false. diff --git a/www/docs/JavaMail-1.6-changes.txt b/www/docs/JavaMail-1.6-changes.txt new file mode 100644 index 00000000..a6906b66 --- /dev/null +++ b/www/docs/JavaMail-1.6-changes.txt @@ -0,0 +1,677 @@ + + JavaMail 1.6 + ============ + + (Updated July 17, 2017) + +Following is a description of the changes to the JavaMail +API introduced in JavaMail 1.6. The numbers in parentheses +are bug numbers; you can find more information about the +bug reports at: + + https://github.com/javaee/javamail/issues/ + +Please send comments and feedback to javamail_ww@oracle.com. + +JavaMail 1.6 will also require at least Java SE 7. + + +=================================================================== + +1. MailSessionDefinition should use Repeatable annotation for Java EE 8 (226) +----------------------------------------------------------------------------- + +The MailSessionDefinition annotation now includes the Repeatable annotation: + + @Target({ElementType.TYPE}) + @Retention(RetentionPolicy.RUNTIME) + @Repeatable(MailSessionDefinitions.class) + public @interface MailSessionDefinition { + ... + } + +The Repeatable annotation is not known to Java SE 7 and will be ignored +(as expected) when JavaMail 1.6 is used on Java SE 7. + + +=================================================================== + +2. MimeMessage.updateHeaders should set Date header if not already set (77) +--------------------------------------------------------------------------- + +RFC 2822 requires a Date header. The MimeMessage.updateHeaders method +now sets the Date header if it's not already set: + + /** + * Called by the saveChanges method to actually + * update the MIME headers. The implementation here sets the + * Content-Transfer-Encoding header (if needed + * and not already set), the Date header (if + * not already set), the MIME-Version header + * and the Message-ID header. Also, if the content + * of this message is a MimeMultipart, its + * updateHeaders method is called.

+ * + * If the {@link #cachedContent} field is not null (that is, + * it references a Multipart or Message object), then + * that object is used to set a new DataHandler, any + * stream data used to create this object is discarded, + * and the {@link #cachedContent} field is cleared. + * + * @exception IllegalWriteException if the underlying + * implementation does not support modification + * @exception IllegalStateException if this message is + * obtained from a READ_ONLY folder. + * @exception MessagingException for other failures + */ + protected synchronized void updateHeaders() throws MessagingException { + ... + } + + +=================================================================== + +3. Update public API to use generics (232) +------------------------------------------ + +Methods on the following APIs have been updated to use generics +when appropriate: + + javax.mail.Multipart + javax.mail.Part + javax.mail.Service + javax.mail.internet.InternetHeaders + javax.mail.internet.MimeBodyPart + javax.mail.internet.MimeMessage + javax.mail.internet.MimePart + javax.mail.internet.ParameterList + +Details follow: + +diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/Multipart.java +- a/mail/src/main/java/javax/mail/Multipart.java ++++ b/mail/src/main/java/javax/mail/Multipart.java +@@ -72,2 +72,1 @@ +- @SuppressWarnings("rawtypes") +- protected Vector parts = new Vector(); // Holds BodyParts ++ protected Vector parts = new Vector<>(); // Holds BodyParts +diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/Part.java +- a/mail/src/main/java/javax/mail/Part.java ++++ b/mail/src/main/java/javax/mail/Part.java +@@ -452,2 +452,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getAllHeaders() throws MessagingException; ++ public Enumeration

getAllHeaders() throws MessagingException; +@@ -463,2 +462,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getMatchingHeaders(String[] header_names) ++ public Enumeration
getMatchingHeaders(String[] header_names) +@@ -475,2 +473,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getNonMatchingHeaders(String[] header_names) ++ public Enumeration
getNonMatchingHeaders(String[] header_names) +diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/Service.java +- a/mail/src/main/java/javax/mail/Service.java ++++ b/mail/src/main/java/javax/mail/Service.java +@@ -640,2 +640,2 @@ +- @SuppressWarnings("rawtypes") +- protected void queueEvent(MailEvent event, Vector vector) { ++ protected void queueEvent(MailEvent event, ++ Vector vector) { +diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/internet/InternetHeaders.java +- a/mail/src/main/java/javax/mail/internet/InternetHeaders.java ++++ b/mail/src/main/java/javax/mail/internet/InternetHeaders.java +@@ -300,2 +300,1 @@ +- @SuppressWarnings("rawtypes") +- protected List headers; ++ protected List headers; +@@ -589,2 +585,1 @@ +- @SuppressWarnings({"rawtypes", "unchecked"}) +- public Enumeration getAllHeaders() { ++ public Enumeration
getAllHeaders() { +@@ -600,2 +595,1 @@ +- @SuppressWarnings({"rawtypes", "unchecked"}) +- public Enumeration getMatchingHeaders(String[] names) { ++ public Enumeration
getMatchingHeaders(String[] names) { +@@ -611,2 +605,1 @@ +- @SuppressWarnings({"rawtypes", "unchecked"}) +- public Enumeration getNonMatchingHeaders(String[] names) { ++ public Enumeration
getNonMatchingHeaders(String[] names) { +@@ -649,2 +640,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getAllHeaderLines() { ++ public Enumeration getAllHeaderLines() { +@@ -660,2 +650,1 @@ +- @SuppressWarnings({"rawtypes", "unchecked"}) +- public Enumeration getMatchingHeaderLines(String[] names) { ++ public Enumeration getMatchingHeaderLines(String[] names) { +@@ -671,2 +660,1 @@ +- @SuppressWarnings({"rawtypes", "unchecked"}) +- public Enumeration getNonMatchingHeaderLines(String[] names) { ++ public Enumeration getNonMatchingHeaderLines(String[] names) { +diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/internet/MimeBodyPart.java +- a/mail/src/main/java/javax/mail/internet/MimeBodyPart.java ++++ b/mail/src/main/java/javax/mail/internet/MimeBodyPart.java +@@ -1036,2 +1036,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getAllHeaders() throws MessagingException { ++ public Enumeration
getAllHeaders() throws MessagingException { +@@ -1045,2 +1044,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getMatchingHeaders(String[] names) ++ public Enumeration
getMatchingHeaders(String[] names) +@@ -1055,2 +1053,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getNonMatchingHeaders(String[] names) ++ public Enumeration
getNonMatchingHeaders(String[] names) +@@ -1073,2 +1070,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getAllHeaderLines() throws MessagingException { ++ public Enumeration getAllHeaderLines() throws MessagingException { +@@ -1083,2 +1079,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getMatchingHeaderLines(String[] names) ++ public Enumeration getMatchingHeaderLines(String[] names) +@@ -1094,2 +1089,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getNonMatchingHeaderLines(String[] names) ++ public Enumeration getNonMatchingHeaderLines(String[] names) +diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/internet/MimeMessage.java +- a/mail/src/main/java/javax/mail/internet/MimeMessage.java ++++ b/mail/src/main/java/javax/mail/internet/MimeMessage.java +@@ -1992,2 +1991,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getAllHeaders() throws MessagingException { ++ public Enumeration
getAllHeaders() throws MessagingException { +@@ -2004,2 +2002,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getMatchingHeaders(String[] names) ++ public Enumeration
getMatchingHeaders(String[] names) +@@ -2017,2 +2014,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getNonMatchingHeaders(String[] names) ++ public Enumeration
getNonMatchingHeaders(String[] names) +@@ -2043,2 +2039,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getAllHeaderLines() throws MessagingException { ++ public Enumeration getAllHeaderLines() throws MessagingException { +@@ -2055,2 +2050,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getMatchingHeaderLines(String[] names) ++ public Enumeration getMatchingHeaderLines(String[] names) +@@ -2068,2 +2062,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getNonMatchingHeaderLines(String[] names) ++ public Enumeration getNonMatchingHeaderLines(String[] names) +diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/internet/MimePart.java +- a/mail/src/main/java/javax/mail/internet/MimePart.java ++++ b/mail/src/main/java/javax/mail/internet/MimePart.java +@@ -111,2 +111,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getAllHeaderLines() throws MessagingException; ++ public Enumeration getAllHeaderLines() throws MessagingException; +@@ -123,2 +122,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getMatchingHeaderLines(String[] names) ++ public Enumeration getMatchingHeaderLines(String[] names) +@@ -136,2 +134,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getNonMatchingHeaderLines(String[] names) ++ public Enumeration getNonMatchingHeaderLines(String[] names) +diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/internet/ParameterList.java +- a/mail/src/main/java/javax/mail/internet/ParameterList.java ++++ b/mail/src/main/java/javax/mail/internet/ParameterList.java +@@ -627,2 +627,1 @@ +- @SuppressWarnings("rawtypes") +- public Enumeration getNames() { ++ public Enumeration getNames() { + + +=================================================================== + +4. MailDateFormat changes for version 1.6 (174) +----------------------------------------------- + +The parse(String) method currently returns null for invalid dates, +which violates the contract of DateFormat. It should throw ParseException. + +Some methods of MailDateFormat throw UnsupportedOperationException. +The following methods should also do so: + + /** + * This method always throws an UnsupportedOperationException and + * should not be used because RFC 2822 mandates a specific pattern. + * + * @throws UnsupportedOperationException if this method is invoked + * @since JavaMail 1.6 + */ + @Override + public void applyLocalizedPattern(String pattern) { + throw new UnsupportedOperationException("Method " + + "applyLocalizedPattern() shouldn't be called"); + } + + /** + * This method always throws an UnsupportedOperationException and + * should not be used because RFC 2822 mandates a specific pattern. + * + * @throws UnsupportedOperationException if this method is invoked + * @since JavaMail 1.6 + */ + @Override + public void applyPattern(String pattern) { + throw new UnsupportedOperationException("Method " + + "applyPattern() shouldn't be called"); + } + + /** + * This method always throws an UnsupportedOperationException and + * should not be used because RFC 2822 mandates another strategy + * for interpreting 2-digits years. + * + * @return the start of the 100-year period into which two digit + * years are parsed + * @throws UnsupportedOperationException if this method is invoked + * @since JavaMail 1.6 + */ + @Override + public Date get2DigitYearStart() { + throw new UnsupportedOperationException("Method " + + "get2DigitYearStart() shouldn't be called"); + } + + /** + * This method always throws an UnsupportedOperationException and + * should not be used because RFC 2822 mandates another strategy + * for interpreting 2-digits years. + * + * @throws UnsupportedOperationException if this method is invoked + * @since JavaMail 1.6 + */ + @Override + public void set2DigitYearStart(Date startDate) { + throw new UnsupportedOperationException("Method " + + "set2DigitYearStart() shouldn't be called"); + } + + /** + * This method always throws an UnsupportedOperationException and + * should not be used because RFC 2822 mandates specific date + * format symbols. + * + * @throws UnsupportedOperationException if this method is invoked + * @since JavaMail 1.6 + */ + @Override + public void setDateFormatSymbols(DateFormatSymbols newFormatSymbols) { + throw new UnsupportedOperationException("Method " + + "setDateFormatSymbols() shouldn't be called"); + } + +MailDateFormat should include a proper clone method: + + /** + * Overrides Cloneable. + * + * @return a clone of this instance + * @since JavaMail 1.6 + */ + @Override + public MailDateFormat clone() { + return (MailDateFormat) super.clone(); + } + + +=================================================================== + +5. Store, Transport, and Folder should implement AutoCloseable (159) +-------------------------------------------------------------------- + +To enable use in a try-with-resources block, the Store, Transport, +and Folder classes should implement the java.lang.AutoCloseable interface. +Store and Transport are subclasses of Service, which already has the +required close() method, so having Service implement AutoCloseable is +sufficient. The Folder class includes a close method with a required +"expunge" parameter so we add a new close() method with no parameter +that behaves the same as close(true), and have Folder implement AutoCloseable. + + public abstract class Service implements AutoCloseable { + ... + } + + public abstract class Folder implements AutoCloseable { + ... + + /** + * Close this Folder and expunge deleted messages.

+ * + * A CLOSED ConnectionEvent is delivered to any ConnectionListeners + * registered on this Folder. Note that the folder is closed even + * if this method terminates abnormally by throwing a + * MessagingException.

+ * + * This method supports the {@link java.lang.AutoCloseable AutoCloseable} + * interface.

+ * + * This implementation calls close(true). + * + * @exception IllegalStateException if this folder is not opened + * @exception MessagingException for other failures + * @see javax.mail.event.ConnectionEvent + * @since JavaMail 1.6 + */ + @Override + public void close() throws MessagingException { + close(true); + } + } + + +=================================================================== + +6. The UIDFolder interface should have a getter for UIDNEXT (104) +----------------------------------------------------------------- + +The UIDFolder interface models the UID support in the IMAP protocol. +After UIDFolder was originally created, the IMAP protocol added +support for getting the value of the next UID that will be assigned. +The IMAP provider in JavaMail has supported this for quite some time; +it should be added to the UIDFolder interface: + + /** + * Returns the predicted UID that will be assigned to the + * next message that is appended to this folder. + * Messages might be appended to the folder after this value + * is retrieved, causing this value to be out of date. + * This value might only be updated when a folder is first opened. + * Note that messages may have been appended to the folder + * while it was open and thus this value may be out of + * date.

+ * + * If the value is unknown, -1 is returned.

+ * + * @return the UIDNEXT value, or -1 if unknown + * @exception MessagingException for failures + * @since JavaMail 1.6 + */ + public long getUIDNext() throws MessagingException; + +Ideally this new method added to the interface would include a default +implementation to provide compatibility with existing classes that +implement this method. However, since the JavaMail 1.6 reference +implementation targets Java SE 7, this is not possible. It's very +likely that the only class implementing this interface is the IMAPFolder +class in the JavaMail reference implementation, thus this incompatibility +is extremely unlikely to cause a problem in practice. + + +=================================================================== + +7. The UIDFolder interface should have a MAXUID constant (244) +-------------------------------------------------------------- + +An IMAP UID is a 32-bit unsigned integer and is represented as a Java long. +A new constant indicates the maximum value of a UID: + + /** + * The largest value possible for a UID, a 32-bit unsigned integer. + * This can be used to fetch all new messages by keeping track of the + * last UID that was seen and using: + * 

+	 *
+	 * 	Folder f = store.getFolder("whatever");
+	 *	UIDFolder uf = (UIDFolder)f;
+	 *	Message[] newMsgs =
+	 *		uf.getMessagesByUID(lastSeenUID + 1, UIDFolder.MAXUID);
+	 *
+	 *

+ * + * @since JavaMail 1.6 + */ + public static final long MAXUID = 0xffffffffL; + + +=================================================================== + +8. MimeMultipart should throw ParseException for parsing errors (75) +-------------------------------------------------------------------- + +ParseException indicates an error parsing MIME messages. In addition +to applying to MIME headers, it seems reasonable to expand it to cover +multipart message parsing. Since ParseException is a subclass of +MessagingException, it merely reports more precisely the cause of the +error. + +The description of ParseException is changed to: + + * The exception thrown due to an error in parsing RFC822 + * or MIME headers, including multipart bodies. + +MimeMultipart documents that ParseException can be thrown from an +existing constructor and method: + + /** + * Constructs a MimeMultipart object and its bodyparts from the + * given DataSource.

+ * + * This constructor handles as a special case the situation where the + * given DataSource is a MultipartDataSource object. In this case, this + * method just invokes the superclass (i.e., Multipart) constructor + * that takes a MultipartDataSource object.

+ * + * Otherwise, the DataSource is assumed to provide a MIME multipart + * byte stream. The parsed flag is set to false. When + * the data for the body parts are needed, the parser extracts the + * "boundary" parameter from the content type of this DataSource, + * skips the 'preamble' and reads bytes till the terminating + * boundary and creates MimeBodyParts for each part of the stream. + * + * @param ds DataSource, can be a MultipartDataSource + * @exception ParseException for failures parsing the message + * @exception MessagingException for other failures + */ + public MimeMultipart(DataSource ds) throws MessagingException + + ... + + /** + * Parse the InputStream from our DataSource, constructing the + * appropriate MimeBodyParts. The parsed 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. + * The {@link #initializeProperties} method is called before + * parsing the data. + * + * @exception ParseException for failures parsing the message + * @exception MessagingException for other failures + * @since JavaMail 1.2 + */ + protected synchronized void parse() throws MessagingException + + +=================================================================== + +9. Support addressing i18n via RFC 6530/6531/6532 (93) +------------------------------------------------------ + +To enable support for UTF-8 email addresses, the following methods +are added to InternetAddress: + + /** + * Convert the given array of InternetAddress objects into + * a comma separated sequence of address strings. The + * resulting string contains Unicode characters.

+ * + * @param addresses array of InternetAddress objects + * @exception ClassCastException if any address object in the + * given array is not an InternetAddress object. + * Note that this is a RuntimeException. + * @return comma separated string of addresses + * @since JavaMail 1.6 + */ + public static String toUnicodeString(Address[] addresses) + + /** + * Convert the given array of InternetAddress objects into + * a comma separated sequence of address strings. The + * resulting string contains Unicode characters.

+ * + * 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 is used to determine the + * line-break positions in the resulting address sequence string. + * + * @param addresses array of InternetAddress objects + * @param used number of character positions already used, in + * the field into which the address string is to + * be inserted. + * @exception ClassCastException if any address object in the + * given array is not an InternetAddress object. + * Note that this is a RuntimeException. + * @return comma separated string of addresses + * @since JavaMail 1.6 + */ + public static String toUnicodeString(Address[] addresses, int used) + + +The following constructor and method are added to InternetHeaders: + + /** + * Read and parse the given RFC822 message stream till the + * blank line separating the header from the body. The input + * stream is left positioned at the start of the body. The + * header lines are stored internally.

+ * + * For efficiency, wrap a BufferedInputStream around the actual + * input stream and pass it as the parameter.

+ * + * No placeholder entries are inserted; the original order of + * the headers is preserved. + * + * @param is RFC822 input stream + * @param allowutf8 if UTF-8 encoded headers are allowed + * @exception MessagingException for any I/O error reading the stream + * @since JavaMail 1.6 + */ + public InternetHeaders(InputStream is, boolean allowutf8) + throws MessagingException + + + /** + * Read and parse the given RFC822 message stream till the + * blank line separating the header from the body. Store the + * header lines inside this InternetHeaders object. The order + * of header lines is preserved.

+ * + * Note that the header lines are added into this InternetHeaders + * object, so any existing headers in this object will not be + * affected. Headers are added to the end of the existing list + * of headers, in order. + * + * @param is RFC822 input stream + * @param allowutf8 if UTF-8 encoded headers are allowed + * @exception MessagingException for any I/O error reading the stream + * @since JavaMail 1.6 + */ + public void load(InputStream is, boolean allowutf8) + throws MessagingException + +The following Session property can be set to enable implicit use of +these new methods: + +mail.mime.allowutf8: + + If set to "true", UTF-8 strings are allowed in message headers, + e.g., in addresses. This should only be set if the mail server also + supports UTF-8. + + +=================================================================== + +10. Look for resource files in /conf on JDK 1.9 (247) +---------------------------------------------------------------- + +JDK 1.9 adds a new /conf directory to hold configuration +files that were previously stored in /lib. When using +JavaMail on JDK 1.9, it should look for its (optional) configuration +files in the /conf directory. + +The specification of the Session class is changed as follows: + + /** + * The Session class represents a mail session and is not subclassed. + * It collects together properties and defaults used by the mail API's. + * A single default session can be shared by multiple applications on + * the desktop. Unshared sessions can also be created.

+ * + * The Session class provides access to the protocol providers that + * implement the Store, Transport, and related + * classes. The protocol providers are configured using the following + * files: + *

    + *
  • javamail.providers and + * javamail.default.providers
    • + *
  • javamail.address.map and + * javamail.default.address.map
    • + *
+ *

+ * Each javamail.X resource file is searched for + * using three methods in the following order: + *

    + *
  1. java.home/conf/javamail.X
    2. + *
  2. META-INF/javamail.X
    3. + *
  3. META-INF/javamail.default.X
    4. + *
+ *

+ * (Where java.home is the value of the "java.home" System + * property and conf is the directory named "conf" if it exists, + * otherwise the directory named "lib"; the "conf" directory was + * introduced in JDK 1.9.) + *

+ * The first method allows the user to include their own version of the + * resource file by placing it in the conf directory where the + * java.home property points. The second method allows an + * application that uses the JavaMail APIs to include their own resource + * files in their application's or jar file's META-INF + * directory. The javamail.default.X default files + * are part of the JavaMail mail.jar file and should not be + * supplied by users.

+ + +=================================================================== + +11. Flags convenience methods (249) +----------------------------------- + +When copying messages from one server to another, it's sometimes necessary +to adjust the message flags based on the capabilities of the target server. +It would be convenient if the Flags class had methods to clear any flags +not supported by the target server, to clear all user flags, and to clear +all system flags. + + /** + * Remove any flags not in the given Flags object. + * Useful for clearing flags not supported by a server. If the + * given Flags object includes the Flags.Flag.USER flag, all user + * flags in this Flags object are retained. + * + * @param f the flags to keep + * @return true if this Flags object changed + * @since JavaMail 1.6 + */ + public boolean retainAll(Flags f) + + /** + * Clear all of the system flags. + * + * @since JavaMail 1.6 + */ + public void clearSystemFlags() + + /** + * Clear all of the user flags. + * + * @since JavaMail 1.6 + */ + public void clearUserFlags() diff --git a/www/docs/JavaMail-2.0-changes.txt b/www/docs/JavaMail-2.0-changes.txt new file mode 100644 index 00000000..b99792a9 --- /dev/null +++ b/www/docs/JavaMail-2.0-changes.txt @@ -0,0 +1,26 @@ + + JavaMail 2.0 + ============ + + (Updated October 23, 2020) + +Following is a description of the changes to the Jakarta Mail +API introduced in Jakarta Mail 2.0. The numbers in parentheses +are bug numbers; you can find more information about the +bug reports at: + + https://github.com/eclipse-ee4j/mail/issues/ + +Please send comments and feedback to mail-dev@eclipse.org. + +Jakarta Mail 2.0 will also require at least Java SE 8. + + +=================================================================== + +1. API package namespace is jakarta.mail +----------------------------------------------------------------------------- + +Previous version of the Jakarta Mail Specification which is based on +JavaMail 1.6 used javax.mail package namespace. +New Jakarta Mail Specification uses jakarta.mail package namespace instead. diff --git a/www/docs/JavaMail-2.1-changes.txt b/www/docs/JavaMail-2.1-changes.txt new file mode 100644 index 00000000..740a9e56 --- /dev/null +++ b/www/docs/JavaMail-2.1-changes.txt @@ -0,0 +1,26 @@ + + JavaMail 2.1 + ============ + + (Updated August 19, 2021) + +Following is a description of the changes to the Jakarta Mail +API introduced in Jakarta Mail 2.1. The numbers in parentheses +are bug numbers; you can find more information about the +bug reports at: + + https://github.com/jakartaee/mail-api/issues/ + +Please send comments and feedback to mail-dev@eclipse.org. + +Jakarta Mail 2.1 will also require at least Java SE 8. + + +=================================================================== + +1. Provide standalone jakarta.mail-api jar file (567) +----------------------------------------------------------------------------- + +Previous version of the Jakarta Mail API was provided in a jar containing APIs together +with implementation classes. This is no longer true and standalone jakarta.mail-api jar +file is available. diff --git a/www/docs/NOTES.txt b/www/docs/NOTES.txt new file mode 100644 index 00000000..9d3fab86 --- /dev/null +++ b/www/docs/NOTES.txt @@ -0,0 +1,206 @@ + NOTES + ===== + + Jakarta Mail API 2.0.1 release + ------------------------------ + +Welcome to the 2.0.1 release of the Jakarta Mail API implementation. + +Please refer to CHANGES.txt for a list of the changes since the +previous release. + +Please see the FAQ at https://eclipse-ee4j.github.io/mail/FAQ + +Protocol Providers +------------------ + +The Jakarta Mail API jar file "jakarta.mail.jar" includes the full Jakarta Mail +API implementation and the Sun protocol providers - IMAP, SMTP, and +POP3. The simplest way to use the Jakarta Mail API is to just use the +jakarta.mail.jar file and ignore the other jar files in this package. + +In some cases it may be desirable to minimize the size of the Jakarta Mail +API code used by an application (e.g., in a microservice). +In this case you might want to include the "mailapi.jar" file, which +includes *no* protocol providers, along with just the jar file for the +protocol provider you need. For example, a microservice that only needs +to send mail could use the "mailapi.jar" file and the "smtp.jar" file. + +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 Jakarta Mail API. The Sun protocol providers depend on + implementation-specific utility APIs within the mailapi.jar file. + (Third party protocol providers that don't depend on these APIs + should work fine.) + + +NOTE: The Sun protocol provider documentation is included in the javadocs + for the Jakarta Mail API. This documentation describes how to + use features of the Sun protocol providers to directly access + some features of the SMTP, IMAP, and POP3 protocols that are + not otherwise supported by the standard Jakarta Mail API. + + +Gmail IMAP Provider +------------------- + +This release includes an EXPERIMENTAL Gmail IMAP provider. +Normal use of Gmail is handled by the standard "imap" protocol +provider, but the new "gimap" protocol provider supports additional +Gmail-specific non-standard features. See the javadocs for the +com.sun.mail.gimap package for details. Note that the gimap.jar file +needs to be added to your CLASSPATH to use this new provider. + + +SASL Support +------------ + +On systems that support the Java SASL API (javax.security.sasl, JSR-28), +such as J2SE 5.0 and later, the IMAP provider can use the SASL API to +find an appropriate authentication mechanism. The SASL API also allows +you to plug in support for custom authentication mechanisms. See The +Java SASL API Programming and Deployment Guide at +https://docs.oracle.com/javase/8/docs/technotes/guides/security/sasl/sasl-refguide.html +for details on developing custom SASL mechanisms. See the javadocs for +the com.sun.mail.imap package for the properties required to enable and +configure SASL support. + + +DSN Support +----------- + +This release of Jakarta Mail includes EXPERIMENTAL support for creating +and parsing Delivery Status Notifications, as defined by RFC 3462 +and RFC 3464. To make use of this support you need to include dsn.jar +in your CLASSPATH along with jakarta.mail.jar. See the javadocs for the +com.sun.mail.dsn package for more details. + +The DSN package also provides support for creating and parsing Message +Disposition Notifications, as defined by RFC 3798. + +The APIs unique to this package should be considered EXPERIMENTAL. +They may be changed in the future in ways that are incompatible with +applications using the current APIs. + + +NTLM Support +------------ + +This release of Jakarta Mail includes EXPERIMENTAL support for the +Microsoft NTLM authentication mechanism used by Exchange. See the +file NTLMNOTES.txt for details. + + +OSGi Support +------------ + +The Jakarta Mail jar files are now OSGi bundles. Please let us know +of any problems using Jakarta Mail with OSGi. + + +How to submit bug reports +------------------------- + +If you've found a bug, or if you just need help figuring out how to use +the Jakarta Mail 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 for how to turn on + session debugging for the demo programs. In your own + program, call "session.setDebug(true);". + +Your problem: jakarta.mail or jakarta.activation classes not found when compiling. +Our response: You didn't set CLASSPATH correctly to find jakarta.mail.jar and + jakarta.activation.jar. See README.txt. + +Your problem: NoSuchProviderException - No such provider for rfc822. +Our response: You unjar'ed jakarta.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 https://eclipse-ee4j.github.io/mail/FAQ +before submitting bug reports. + +Send your bug reports to: + + mail-dev@eclipse.org + + + + +Servers tested with: +-------------------- + + The IMAP implementation works with IMAP4 and IMAP4rev1 servers. + The current release has been tested with: + Oracle Beehive + Oracle Communications Messaging Server 8.0 + UW IMAP4 server version 2003.339 + Cyrus IMAP4 server version 1.6.19 + Microsoft Exchange 2010 + Microsoft Exchange 2013 + Microsoft Exchange 2016 + + Previous releases have been tested with: + Sun Java System Messaging Server version 5.2 + Sun Java System Messaging Server version 6.3 + Sun Java System Messaging Server version 7.0 + Sun Internet Mail Server version 2.0, 3.2, and 4.0 + Netscape Messaging Server version 3.01 and 4.1 + Microsoft MCIS Mail Server + Lotus Notes + Software.com IMAP server + Qualcomm Worldmail + + The current release of the SMTP implementation has been tested with: + Sendmail version 8.13.8 + Oracle Beehive + Oracle Communications Messaging Server 8.0 + Microsoft Exchange 2010 + Microsoft Exchange 2013 + Microsoft Exchange 2016 + + Previous releases have been tested with: + Sendmail version 8.6 and 8.9.1 + Sun Java System Messaging Server version 5.2 + Sun Java System Messaging Server version 6.3 + Sun Java System Messaging Server version 7.0 + Sun Internet Mail Server version 3.2 and 4.0 + Netscape Messaging Server version 3.01 and 4.1 + Microsoft Exchange + Microsoft MCIS Mail Server + Qualcomm Worldmail + +How to give feedback +-------------------- + +Please send your feedback to this email-address: + + mail-dev@eclipse.org + +Check out our website at https://eclipse-ee4j.github.io/mail/. + +You can also find help on StackOverflow: + + https://stackoverflow.com/questions/tagged/javamail + + +------------------------------------------------------------------ diff --git a/www/docs/NTLMNOTES.txt b/www/docs/NTLMNOTES.txt new file mode 100644 index 00000000..86f2fc15 --- /dev/null +++ b/www/docs/NTLMNOTES.txt @@ -0,0 +1,33 @@ + Notes for use of NTLM authentication support with Jakarta Mail + -------------------------------------------------------------- + +Thanks to the efforts of Luis Serralheiro, Jakarta Mail now suports the use +of Microsoft's proprietary NTLM authentication mechanism. This support +within Jakarta Mail is now derived from the NTLM support in the JDK and +included directly in Jakarta Mail, with no external dependencies. + +This release of Jakarta Mail was tested with Microsoft Exchange 2010, 2013, +and 2016. + +The SMTP and IMAP providers support the use of NTLM authentication. +The following properties can be used to configure the NTLM support: + +mail..auth.ntlm.domain + The NTLM authentication domain. + +mail..auth.ntlm.flags + NTLM protocol-specific flags. (not currently used) + See http://curl.haxx.se/rfc/ntlm.html#theNtlmFlags for details. + +mail..auth.ntlm.v2 + If set to true, use the NTLMv2 protocol. Defaults to true. + Must be set to false explicitly to disable use of NTLMv2. + + +NOTE: This capability is very new and has NOT been thoroughly tested. + Please send any feedback or bug reports to us at mail-dev@eclipse.org. + +WARNING: This support, and the APIs and properties used to control it, +should be considered EXPERIMENTAL. They may be changed in the future +in ways that are incompatible with applications using the current APIs +and properties. diff --git a/www/docs/README.txt b/www/docs/README.txt new file mode 100644 index 00000000..6b6b17e0 --- /dev/null +++ b/www/docs/README.txt @@ -0,0 +1,171 @@ + README + ====== + + Jakarta Mail API 2.0.1 release + ------------------------------ + +Welcome to the Jakarta Mail API 2.0.1 release! This release includes +versions of the Jakarta Mail API implementation, IMAP, SMTP, and POP3 +service providers, some examples, and documentation for the Jakarta Mail +API. + +Please see the FAQ at https://eclipse-ee4j.github.io/mail/FAQ + +JDK Version notes +----------------- + +The Jakarta Mail API supports JDK 1.8 or higher. Note that we have +currently tested this implementation with JDK 1.8 and 11. + +Jakarta Mail requires Jakarta Activation 2.0.0 or newer. + + +Protocols supported +------------------- + +This release supports the following Internet standard mail protocols: + + IMAP - a message Store protocol, for reading messages from a server + POP3 - a message Store protocol, for reading messages from a server + SMTP - a message Transport protocol, for sending messages to a server + +The following table lists the names of the supported protocols (as used +in the Jakarta Mail API) and their capabilities: + + Protocol Store or Uses Supports + Name Transport? SSL? STARTTLS? + ------------------------------------------------- + imap Store No Yes + imaps Store Yes N/A + gimap Store Yes N/A + pop3 Store No Yes + pop3s Store Yes N/A + smtp Transport No Yes + smtps Transport Yes N/A + +See our web page at https://eclipse-ee4j.github.io/mail/ +for the latest information on third party protocol providers. + + +Download +-------- + +See the Jakarta Mail project page to download this release. + + https://eclipse-ee4j.github.io/mail/ + + +Requirements +------------ + +Note that the Jakarta Mail API requires the Jakarta Activation +package to be installed as well. + +Download the latest version of Jakarta Activation from + + https://github.com/eclipse-ee4j/jaf/releases + +and install it in a suitable location. + + +Installation +------------ + + UNIX/Linux + ---------- + + 1. Download the jakarta.mail.jar file from the Jakarta Mail project website. + https://github.com/eclipse-ee4j/mail/releases + + 2. Set your CLASSPATH to include the "jakarta.mail.jar" file obtained from + the download, as well as the current directory. + + Assuming you have downloaded jakarta.mail.jar to the /u/me/download/ + directory, the following would work: + + export CLASSPATH=$CLASSPATH:/u/me/download/jakarta.mail.jar:. + + (Don't forget the trailing "." for the current directory.) + Include the "jakarta.activation.jar" file that you + obtained from downloading Jakarta Activation. For example: + + export CLASSPATH=$CLASSPATH:/u/me/download/jakarta.activation.jar + + 3. Download the jakartamail-samples.zip file from the project website. + https://github.com/eclipse-ee4j/mail/releases + + 4. Compile any sample program using your Java compiler. For example: + + javac msgshow.java + + 5. Run the sample program. The '-' option lists the required and optional + command-line options to successfully run any sample. For example: + + java msgshow - + + lists the available options. And + + java msgshow -T imap -H -U -P -f INBOX 5 + + uses the IMAP protocol to display message number 5 from your INBOX. + + (Additional instructions on how to run the simple mail reader sample + and servlet sample are provided in client/README.txt and servlet/README.txt, + respectively.) + + + Windows + ------- + + 1. Download the jakarta.mail.jar file from the Jakarta Mail project website. + https://github.com/eclipse-ee4j/mail/releases + + 2. Set your CLASSPATH to include the "jakarta.mail.jar" file obtained from + the download, as well as the current directory. + + Assuming you have downloaded jakarta.mail.jar to the /u/me/download/ + directory, the following would work: + + set CLASSPATH=%CLASSPATH%;c:\download\jakarta.mail.jar;. + + (Don't forget the trailing "." for the current directory.) + Include the "jakarta.activation.jar" file that you + obtained from downloading Jakarta Activation. For example: + + set CLASSPATH=%CLASSPATH%;c:\download\jakarta.activation.jar + + 3. Download the jakartamail-samples.zip file from the project website. + https://github.com/eclipse-ee4j/mail/releases + + 4. Compile any sample program using your Java compiler. For example: + + javac msgshow.java + + 5. Run the sample program. The '-' option lists the required and optional + command-line options to successfully run any sample. For example: + + java msgshow - + + lists the available options. And + + java msgshow -T imap -H -U -P -f INBOX 5 + + uses the IMAP protocol to display message number 5 from your INBOX. + + (Additional instructions on how to run the simple mail reader sample + and servlet sample are provided in client/README.txt and servlet/README.txt, + respectively.) + + +Problems? +--------- + +The Jakarta Mail FAQ at https://eclipse-ee4j.github.io/mail/FAQ +includes information on protocols supported, installation problems, +debugging tips, etc. + +See the NOTES.txt file for information on how to report bugs. + +Enjoy! + +The Jakarta Mail API Team diff --git a/www/docs/SSLNOTES.txt b/www/docs/SSLNOTES.txt new file mode 100644 index 00000000..fbef7ecc --- /dev/null +++ b/www/docs/SSLNOTES.txt @@ -0,0 +1,311 @@ + Notes for use of SSL with Jakarta Mail + -------------------------------------- + +Jakarta Mail now supports accessing mail servers over connections secured +using SSL or TLS. To simplify such access, 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". + +Alternatively, you can configure Jakarta Mail to use one of the SSL-enabled +protocol names. In addition to the non-SSL Jakarta Mail protocols "imap", +"pop3", and "smtp", the protocols "imaps", "pop3s", and "smtps" can +be used to connect to the corresponding services using an SSL +connection. + +In addition, the "imap" and "smtp" protocols support use of the +STARTTLS command (see RFC 2487 and RFC 3501) to switch the connection +to be secured by TLS. + +Use of the STARTTLS command is preferred in cases where the server +supports both SSL and non-SSL connections. + +This SSL/TLS support in Jakarta Mail works only when Jakarta Mail is used +on a version of J2SE that includes SSL support. We have tested this +support on J2SE 1.4 and newer, which include SSL support. The +SSL support is provided by the JSSE package, which is also available +for earlier versions of J2SE. We have not tested such configurations. + +-- 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. + + +-- Secure protocols + +When using the new protocol names, configuration properties must also use +these protocol names. For instance, set the property "mail.smtps.host" +to specify the host name of the machine to connect to when using the +"smtps" protocol for SMTP over SSL. Similarly, to set the IMAP protocol +timeout when using the "imaps" protocol for IMAP over SSL, set the property +"mail.imaps.timeout". See the package documentation for the different +protocol packages for the list of available properties, which are +always set using property names of the form mail... + +The Transport.send method will use the default transport protocol, +which remains "smtp". To enable SMTP connections over SSL, set the +"mail.smtp.ssl.enable" property to "true". This is usually the easiest +approach. + +Alternatively, to change the default transport protocol +returned by the Session.getTransport() method to SMTP over SSL, set +the property "mail.transport.protocol" to "smtps". To change the +transport used for internet addresses (as returned by the +Session.getTransport(Address) method, and used by the Transport.send +method), use + + session.setProtocolForAddress("rfc822", "smtps"); + + +-- Trusted Certificates + +To establish an SSL/TLS connection, the Jakarta Mail client must be able +to verify that the security certificate presented by the server +it is connecting to is "trusted" by the client. Trusted certificates +are maintained in a Java keystore file on the client. The J2SE +SDK "keytool" command is used to maintain the keystore file. + +There are two common approaches for verifying server certificates. +The first approach is probably most common for servers accessible to +partners outside a company. The second approach is probably most +common for servers used within a company. + +1. Server certificates may be signed be a well known public + Certificate Authority. The default Java keystore file contains + the public keys of well known Certificate Authorities and can + verify the server's certificate by following the chain of + certificates signing the server's certificate back to one of + these well known CA certificates. + + In this case the client doesn't need to manage certificates + explicitly but can just use the default keystore file. + +2. Server certificates may be "self-signed". In this case there is + no chain of signatures to use in verifying the server's certificate. + Instead, the client will need the server's certificate in the + client's keystore file. The server's certificate is imported into + the keystore file once, using the keytool command, and after that + is used to verify connections to the server. A single keystore file + may contain certificates of many servers. + + In this case the client will need to set the appropriate System + properties to point to the client's keystore file containing the + trusted certificate. These properties can be set when invoking + the "java" command, or can be set programmatically. For example, + + java -Djavax.net.ssl.trustStore=$HOME/.keystore ... + + See the JSSE Reference Guide for details: + http://download.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#CustomizingStores + + +-- 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 Jakarta Mail, 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. + +Jakarta Mail 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. + + +-- Debugging + +Debugging problems with certificates and keystores can be difficult. +The JSSE Reference Guide contains information on debugging utilities +that can help. See: +http://download.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#Debug + +There are some debugging options in the JDK that can help, depending +on the sorts of problems you're having. Setting the following system +properties will produce additional debugging output: + + java.security.debug=certpath + javax.net.debug=trustmanager + +Set these on the command line when you run your program using, for example: + + java -Djava.security.debug=certpath -Djavax.net.debug=trustmanager ... + + +-- 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. + +For more information on using the keytool command, see the keytool +reference pages at: +http://download.oracle.com/javase/6/docs/technotes/guides/security/index.html + + +-- 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 Jakarta Mail 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. diff --git a/www/docs/classpath-NT.html b/www/docs/classpath-NT.html new file mode 100644 index 00000000..40b265d7 --- /dev/null +++ b/www/docs/classpath-NT.html @@ -0,0 +1,125 @@ + + + + + + + + + + + + + + + + + NT Classpath + + + +

+
+ +

JavaMail

+ +

JavaMail Reference Implementation

+ + + +
+
+ +
+
+
+ +

+Environment variables are administered on Windows NT from the +System +Properties Control Panel settings (Start->Settings->Control Panel; +it's the System icon in the Control Panel). The Environment +tab contains all of the System and User Variables. +

System Variables exist for all users while User Variables only exist +for the current user. Only users with Administrator privileges are able +to define System Variables. For this example, environment variables will +be defined as User Variables. +

If this is the first time the CLASSPATH environment variable is being +defined, select the first User Variables entry (its name/value pair will +show up below the User Variables list). Enter 'CLASSPATH' in the 'Variable:' +text edit field. +

If the CLASSPATH environment variable has already been previously defined, +simply select it from the User Variables list. +

There are a couple of ways of adding something to an environment variable. +It can be added directly, or through the use of a separately defined environment +variable. +

When the JavaMail and Java Activation Framework (JAF) jar files are +added directly to the CLASSPATH, the Value field should contain (for example) +".;D:\Java\javamail-1.2\mail.jar;D:\Java\jaf-1.0.1\activation.jar". +

+
  +

When the JavaMail and Java Activation Framework (JAF) jar files are +added to the CLASSPATH using separate environment variables, the Value +field should contain (for example) ".;%JAVAMAIL_JAR%;%JAF_JAR%" +
  +

+
  +

Once you have finished updating the Value field, you must press the +Set button. Then press OK. It is not necessary to reboot or log out, however +these new settings will only be present in new Command Prompt windows. +Any existing windows must be closed and reopened for the new settings to +take effect. Any running Java applications which inherit the system CLASSPATH +also need to be restarted. + +

+
+
+ + + +