Javadoc'd everything public. Fixed bug where Token was not publicly visible

Author: RobertoGraham

src/main/java/io/github/robertograham/nadir/Account.java

@@ -1,8 +1,21 @@
 package io.github.robertograham.nadir;
 
+/**
+ * The {@code Account} class represents an EA account
+ *
+ * @since 1.0.0
+ */
 public interface Account {
 
+    /**
+     * @return The UID (user ID) of this {@code Account}
+     * @since 1.0.0
+     */
     long userId();
 
+    /**
+     * @return The EAID (EA username) of this {@code Account}
+     * @since 1.0.0
+     */
     String username();
 }

src/main/java/io/github/robertograham/nadir/AccountResource.java

@@ -4,9 +4,27 @@
 import java.util.List;
 import java.util.Optional;
 
+/**
+ * An object from which actions related to EA accounts can be performed
+ *
+ * @since 1.0.0
+ */
 public interface AccountResource {
 
+    /**
+     * @return An {@link Optional} of {@link Account} that's non-empty if the HTTP response contained an account
+     * @throws StryderErrorException If there's an HTTP error response
+     * @throws IOException           If an {@link java.io.InputStream} cannot be created from the HTTP response
+     * @since 1.0.0
+     */
     Optional<Account> findOneBySessionToken() throws IOException;
 
-    Optional<List<Account>> findAllBySearchTerms(final String... names) throws IOException;
+    /**
+     * @param searchTerms The terms that will be used to search for EA accounts
+     * @return An {@link Optional} of {@link List} of {@link Account} that's non-empty if the HTTP response contained any accounts
+     * @throws StryderErrorException If there's an HTTP error response
+     * @throws IOException           If an {@link java.io.InputStream} cannot be created from the HTTP response
+     * @since 1.0.0
+     */
+    Optional<List<Account>> findAllBySearchTerms(final String... searchTerms) throws IOException;
 }

src/main/java/io/github/robertograham/nadir/AuthenticationResource.java

@@ -15,6 +15,7 @@
 import java.net.URISyntaxException;
 import java.nio.charset.StandardCharsets;
 import java.util.*;
+import java.util.function.Function;
 import java.util.regex.Pattern;
 
 final class AuthenticationResource {
@@ -113,8 +114,9 @@ private Optional<Token> fetchToken() throws IOException {
                 .addParameter("prompt", "none")
                 .addParameter("release_type", "prod")
                 .build(),
-            optionalResultResponseHandlerProvider.forClass(Token.class)
-        );
+            optionalResultResponseHandlerProvider.forClass(TokenImpl.class)
+        )
+            .map(Function.identity());
     }
 
     Optional<Token> userCredentialsGrantedToken(final String emailAddress,

src/main/java/io/github/robertograham/nadir/JsonOptionalResultResponseHandlerProvider.java

@@ -17,7 +17,7 @@
 enum JsonOptionalResultResponseHandlerProvider implements OptionalResultResponseHandlerProvider {
 
     INSTANCE(
-        Token.Adapter.INSTANCE,
+        TokenImpl.Adapter.INSTANCE,
         AccountImpl.Adapter.INSTANCE,
         XSearchResult.Adapter.INSTANCE
     );

src/main/java/io/github/robertograham/nadir/Nadir.java

@@ -2,32 +2,86 @@
 
 import java.io.IOException;
 
+/**
+ * Entry-point for the {@code nadir} library
+ * <p>
+ * Can be instantiated via {@link Nadir#newNadir(String, String)}
+ * which will use the default {@link Nadir.Builder} options
+ * <p>
+ * Can be created via {@link Nadir#newBuilder(String, String)} which returns an instance of {@link Nadir.Builder}
+ * that lets you customise the object returned by {@link Builder#build()}
+ *
+ * @since 1.0.0
+ */
 public interface Nadir extends AutoCloseable {
 
+    /**
+     * @param emailAddress EA account email address
+     * @param password     EA account password
+     * @return An instance of {@link Nadir.Builder} that can be used to build an instance of {@code Nadir}
+     * @throws NullPointerException If {@code emailAddress is null}
+     * @throws NullPointerException If {@code password is null}
+     * @since 1.0.0
+     */
     static Builder newBuilder(final String emailAddress,
                               final String password) {
         return new NadirBuilderImpl(emailAddress, password);
     }
 
+    /**
+     * @param emailAddress EA account email address
+     * @param password     EA account password
+     * @return An authenticated instance of {@code Nadir} configured with the default {@link Nadir.Builder} options
+     * @see Nadir#newBuilder(String, String)
+     * @see Builder#build()
+     * @since 1.0.0
+     */
     static Nadir newNadir(final String emailAddress,
                           final String password) throws IOException {
         return Nadir.newBuilder(emailAddress, password)
             .build();
     }
 
+    /**
+     * @return The EA account email address this instance was configured to use
+     * @since 1.0.0
+     */
     String emailAddress();
 
+    /**
+     * @return The EA account password this instance was configured to use
+     * @since 1.0.0
+     */
     String password();
 
+    /**
+     * @return A non-expired instance of {@link Token} with at least 5 minutes of use left
+     * @since 1.0.0
+     */
     Token session();
 
+    /**
+     * @return an instance of {@link AccountResource} from which EA account related actions can be performed
+     * @since 1.0.0
+     */
     AccountResource accounts();
 
     @Override
     void close();
 
+    /**
+     * Used to build instances of {@link Nadir}
+     *
+     * @since 1.0.0
+     */
     interface Builder {
 
+        /**
+         * @return An authenticated instance of {@link Nadir}
+         * @throws StryderErrorException If any erroneous HTTP responses are encountered during authentication
+         * @throws IOException           If any number of problems occur during authentication
+         * @since 1.0.0
+         */
         Nadir build() throws IOException;
     }
 }

src/main/java/io/github/robertograham/nadir/StryderErrorException.java

@@ -7,6 +7,11 @@
 import javax.json.JsonObject;
 import java.util.Optional;
 
+/**
+ * An exception thrown due to erroneous HTTP responses
+ *
+ * @since 1.0.0
+ */
 public final class StryderErrorException extends HttpResponseException {
 
     private final JsonObject jsonObject;
@@ -21,6 +26,11 @@ public final class StryderErrorException extends HttpResponseException {
         jsonObject = null;
     }
 
+    /**
+     * @return an {@link Optional} of {@link JsonObject} that's non-empty if a JSON object
+     * was included in the erroneous HTTP response
+     * @since 1.0.0
+     */
     public Optional<JsonObject> jsonObject() {
         return Optional.ofNullable(jsonObject);
     }

src/main/java/io/github/robertograham/nadir/Token.java

@@ -1,77 +1,30 @@
 package io.github.robertograham.nadir;
 
-import javax.json.JsonObject;
-import javax.json.bind.adapter.JsonbAdapter;
 import java.time.LocalDateTime;
-import java.util.Objects;
 
-final class Token {
-
-    private final String accessToken;
-    private final String tokenType;
-    private final LocalDateTime accessTokenExpiresAt;
-
-    private Token(String accessToken, String tokenType, LocalDateTime accessTokenExpiresAt) {
-        this.accessToken = accessToken;
-        this.tokenType = tokenType;
-        this.accessTokenExpiresAt = accessTokenExpiresAt;
-    }
-
-    public String accessToken() {
-        return accessToken;
-    }
-
-    public String tokenType() {
-        return tokenType;
-    }
-
-    public LocalDateTime accessTokenExpiresAt() {
-        return accessTokenExpiresAt;
-    }
-
-    @Override
-    public String toString() {
-        return "Token{" +
-            "accessToken='" + accessToken + '\'' +
-            ", tokenType='" + tokenType + '\'' +
-            ", accessTokenExpiresAt=" + accessTokenExpiresAt +
-            '}';
-    }
-
-    @Override
-    public boolean equals(final Object object) {
-        if (this == object)
-            return true;
-        if (!(object instanceof Token))
-            return false;
-        final var token = (Token) object;
-        return accessToken.equals(token.accessToken) &&
-            tokenType.equals(token.tokenType) &&
-            accessTokenExpiresAt.equals(token.accessTokenExpiresAt);
-    }
-
-    @Override
-    public int hashCode() {
-        return Objects.hash(accessToken, tokenType, accessTokenExpiresAt);
-    }
-
-    enum Adapter implements JsonbAdapter<Token, JsonObject> {
-
-        INSTANCE;
-
-        @Override
-        public JsonObject adaptToJson(final Token token) {
-            throw new UnsupportedOperationException();
-        }
-
-        @Override
-        public Token adaptFromJson(final JsonObject jsonObject) {
-            return new Token(
-                jsonObject.getString("access_token"),
-                jsonObject.getString("token_type"),
-                LocalDateTime.now()
-                    .plusSeconds(Long.parseLong(jsonObject.getString("expires_in")))
-            );
-        }
-    }
+/**
+ * Representation of a user's authentication session
+ *
+ * @since 1.0.0
+ */
+public interface Token {
+
+    /**
+     * @return An access token that can be used to authenticate against API endpoints
+     * @since 1.0.0
+     */
+    String accessToken();
+
+    /**
+     * @return The type of token this, I have only seen {@code Bearer} so far
+     * @since 1.0.0
+     */
+    String tokenType();
+
+    /**
+     * @return The time when this session will be invalid. A valid {@code Token} can be obtained using
+     * {@link Nadir#session()}
+     * @since 1.0.0
+     */
+    LocalDateTime accessTokenExpiresAt();
 }

src/main/java/io/github/robertograham/nadir/TokenImpl.java

@@ -0,0 +1,80 @@
+package io.github.robertograham.nadir;
+
+import javax.json.JsonObject;
+import javax.json.bind.adapter.JsonbAdapter;
+import java.time.LocalDateTime;
+import java.util.Objects;
+
+final class TokenImpl implements Token {
+
+    private final String accessToken;
+    private final String tokenType;
+    private final LocalDateTime accessTokenExpiresAt;
+
+    private TokenImpl(String accessToken, String tokenType, LocalDateTime accessTokenExpiresAt) {
+        this.accessToken = accessToken;
+        this.tokenType = tokenType;
+        this.accessTokenExpiresAt = accessTokenExpiresAt;
+    }
+
+    @Override
+    public String accessToken() {
+        return accessToken;
+    }
+
+    @Override
+    public String tokenType() {
+        return tokenType;
+    }
+
+    @Override
+    public LocalDateTime accessTokenExpiresAt() {
+        return accessTokenExpiresAt;
+    }
+
+    @Override
+    public String toString() {
+        return "Token{" +
+            "accessToken='" + accessToken + '\'' +
+            ", tokenType='" + tokenType + '\'' +
+            ", accessTokenExpiresAt=" + accessTokenExpiresAt +
+            '}';
+    }
+
+    @Override
+    public boolean equals(final Object object) {
+        if (this == object)
+            return true;
+        if (!(object instanceof TokenImpl))
+            return false;
+        final var token = (TokenImpl) object;
+        return accessToken.equals(token.accessToken) &&
+            tokenType.equals(token.tokenType) &&
+            accessTokenExpiresAt.equals(token.accessTokenExpiresAt);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(accessToken, tokenType, accessTokenExpiresAt);
+    }
+
+    enum Adapter implements JsonbAdapter<TokenImpl, JsonObject> {
+
+        INSTANCE;
+
+        @Override
+        public JsonObject adaptToJson(final TokenImpl token) {
+            throw new UnsupportedOperationException();
+        }
+
+        @Override
+        public TokenImpl adaptFromJson(final JsonObject jsonObject) {
+            return new TokenImpl(
+                jsonObject.getString("access_token"),
+                jsonObject.getString("token_type"),
+                LocalDateTime.now()
+                    .plusSeconds(Long.parseLong(jsonObject.getString("expires_in")))
+            );
+        }
+    }
+}