init www

Signed-off-by: Lukas Jungmann <lukas.jungmann@oracle.com>

.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

.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 "<version>[[:digit:]]\.[[:digit:]]\.[[:digit:]]</version" | cut -f 2 -d ">" | 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

.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

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)

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

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
+<a href="https://accounts.eclipse.org/mailing-list/mail-dev">mai-dev@eclipse.org</a>.
+
+* <a href="http://www.amazon.com/exec/obidos/ISBN=1449367240/javasoftsunmicroA">
+  JavaMail API</a>, by Elliotte Rusty Harold.
+
+* <a href="http://www.amazon.com/exec/obidos/ISBN=1565924797/javasoftsunmicroA">
+  Internet Email</a>, by David Wood.
+
+* <a href="http://www.amazon.com/exec/obidos/ISBN=1555582125/javasoftsunmicroA">
+  Programmer's Guide to Internet Mail</a>, by John Rhoton.
+
+* <a href="http://www.amazon.com/exec/obidos/ISBN=0201432889/javasoftsunmicroA">
+  Internet Email Protocols: A Developer's Guide</a>, by Kevin Johnson.
+
+* <a href="http://www.amazon.com/exec/obidos/ISBN=1565928709/javasoftsunmicroA">
+  Java Network Programming, 2nd Edition</a>, by Elliotte Rusty Harold.
+
+* <a href="http://www.amazon.com/exec/obidos/ISBN=0471345970/javasoftsunmicroA">
+  Essential Email Standards: RFCs and Protocols Made Practical</a>,
+  by Pete Loshin.
+
+* <a href="http://www.amazon.com/exec/obidos/ISBN=0139786104/javasoftsunmicroA">
+  Internet Messaging: From the Desktop to the Enterprise</a>,
+  by Marshall T. Rose and David Strom.
+
+* <a href="http://www.amazon.com/exec/obidos/ISBN=0890069395/javasoftsunmicroA">
+  Internet E-Mail: Protocols, Standards, &amp; Implementation</a>,
+  by Lawrence Hughes.
+
+* <a href="http://www.amazon.com/exec/obidos/ISBN=059600012X/javasoftsunmicroA">
+  Managing IMAP</a>, by Dianna Mullet and Kevin Mullet.
+
+* <a href="http://www.amazon.com/exec/obidos/ISBN=1861004656/javasoftsunmicroA">
+  Professional Java Server Programming J2EE Edition</a>.
+
+* <a href="http://www.amazon.com/exec/obidos/ISBN=0596001703/javasoftsunmicroA">
+  Java Cookbook: Solutions and Examples for Java Developers</a>,
+  by Ian F. Darwin.
+
+* <a href="http://www.amazon.com/exec/obidos/ISBN=0761534288/javasoftsunmicroA">
+  JavaServer Pages (JSP) Fast &amp; Easy Web Development</a>,
+  by Aneesha Bakharia.

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.

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:
+    <pre>
+    set autoindent
+    set tabstop=8
+    set shiftwidth=4
+    </pre>
+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.