Merge pull request #371 from jwtk/355-documentation

Documentation revamp

CHANGELOG.md

@@ -2,38 +2,34 @@
 
 ### 0.10.0
 
-This is a minor feature enhancement that ensures Base64 encoding is identical and deterministic on all JDK and
+This is a fairly large feature enhancement release that enables the following:
-Android platforms.  JJWT previously relied on the underlying platform encoder (JAXB xml DataBinding or Android's native
-Base64), however in some cases this produced unexpected results across platforms, including when compared against the
-JDK's >= 8 Base64 implementation.
 
-JJWT now embeds a super lightweight (1 class) and *extremely* fast RFC-compliant Base64 implementation to guarantee 
+* Modular project structure resulting in pluggable JJWT dependencies ([Issue 348](https://github.com/jwtk/jjwt/issues/348))
-portability across all supported platforms.  It is now enabled automatically and there is nothing you need to 
+* Auto-configuration for Jackson or JSON-Java [JSON processors](https://github.com/jwtk/jjwt#json).
-do to enable it.
+* [Automatic SignatureAlgorithm selection](https://github.com/jwtk/jjwt#jws-create-key) based on specified signing Key.
+* Algorithm and Key [Strength Assertions](https://github.com/jwtk/jjwt#jws-key)
+* [Simplified Key generation](https://github.com/jwtk/jjwt#jws-key-create)
+* Deterministic [Base64(URL) support](https://github.com/jwtk/jjwt#base64) on all JDK and Android platforms
+* [Custom JSON processing](https://github.com/jwtk/jjwt#json-custom)
+* Complete [documentation](https://github.com/jwtk/jjwt)
+* and a bunch of other [minor fixes and enhancements](https://github.com/jwtk/jjwt/milestone/11).
 
-However, if the default implementation isn't sufficient for your purposes, you may now specify your own
+**BACKWARDS-COMPATIBILITY NOTICE:**
-encoder during JWT building or decoder during JWT parsing as you see fit.
 
-For example, an encoder during building:
+JJWT's new modular design utilizes distinctions between compile and runtime dependencies to ensure you only depend
+on the public APIs that are safe to use in your application.  All internal/private implementation classes have
+been moved to a new `jjwt-impl` runtime dependency.
 
-```java
+If you depended on any internal implementation classes in the past, you have two choices:
-Encoder<byte[], String> encoder = new MyBase64UrlEncoder(); //implement me
 
-Jwts.builder()
+1. Refactor your code to use the public-only API classes and interfaces in the `jjwt-api` .jar.  Any functionality
-    .base64UrlEncodeWith(encoder)
+   you might have used in the internal implementation should be available via newer cleaner interfaces and helper 
-    // ... etc ...
+   classes in that .jar.
-    .compact();
-```
    
-Or a decoder during parsing:
+2. Specify the new `jjwt-impl` .jar not as a runtime dependency but as a compile dependency.  This would make your
-```java
+   upgrade to JJWT 0.10.0 fully backwards compatible, but you do so _at your own risk_.  JJWT will make **NO** 
-Decoder<String, byte[]> decoder = new MyBase64UrlDecoder(); //implement me
+   semantic version compatibility guarantees in the `jjwt-impl` .jar moving forward.  Semantic versioning will be 
-
+   very carefully adhered to in all other JJWT dependencies however.
-Jwts.parser()
-    .base64UrlDecodeWith(decoder)
-    // ... etc ...
-    .parseClaimsJws(jws);
-```
 
 ### 0.9.1
 

api/src/main/java/io/jsonwebtoken/security/Keys.java

@@ -148,7 +148,7 @@ public final class Keys {
      * <td>3072 bits</td>
      * </tr>
      * <tr>
-     * <td>PS256</td>
+     * <td>PS384</td>
      * <td>3072 bits</td>
      * </tr>
      * <tr>
@@ -185,16 +185,14 @@ public final class Keys {
      * <tr>
      * <td>EC512</td>
      * <td>512 bits</td>
-     * <td>{@code P-512}</td>
+     * <td>{@code P-521}</td>
      * <td>{@code secp521r1}</td>
      * </tr>
      * </table>
      *
      * @param alg the {@code SignatureAlgorithm} to inspect to determine which asymmetric algorithm to use.
      * @return a new {@link KeyPair} suitable for use with the specified asymmetric algorithm.
-     * @throws IllegalArgumentException if {@code alg} equals {@link SignatureAlgorithm#HS256 HS256},
+     * @throws IllegalArgumentException if {@code alg} is not an asymmetric algorithm
-     *                                  {@link SignatureAlgorithm#HS384 HS384}, {@link SignatureAlgorithm#HS512 HS512}
-     *                                  or {@link SignatureAlgorithm#NONE NONE}.
      */
     public static KeyPair keyPairFor(SignatureAlgorithm alg) throws IllegalArgumentException {
         Assert.notNull(alg, "SignatureAlgorithm cannot be null.");