- removed NoSessionConfirmedException from getSessionState

- added javadocs

src/nodash/core/NoCore.java

@@ -36,10 +36,23 @@ import nodash.models.NoSession.NoState;
 public final class NoCore {
   private NoAdapter adapter;
 
+  /**
+   * Instantiates an instance of the NoCore, using the given adapter to interact with saved hashes,
+   * byte sets and sessions.
+   * 
+   * @param adapter an object implementing the NoAdapter interface.
+   */
   public NoCore(NoAdapter adapter) {
     this.adapter = adapter;
   }
 
+  /**
+   * Internal helper method to simplify getting a session or throwing the correct exception.
+   * 
+   * @param cookie the encrypted user cookie representing the NoSession UUID.
+   * @return a NoSession object with a UUID matching the decrypted cookie.
+   * @throws NoSessionExpiredException - if the session cannot be found.
+   */
   private NoSession getNoSession(byte[] cookie) throws NoSessionExpiredException {
     boolean containsSession;
     try {
@@ -58,8 +71,19 @@ public final class NoCore {
     throw new NoSessionExpiredException();
   }
 
+  /**
+   * Attempts to log a user in with a given data file and password.
+   * 
+   * @param data the user file as a byte array.
+   * @param password the user's password as a char array.
+   * @return a byte array representing the encrypted user cookie.
+   * @throws NoUserNotValidException - if the given combination of data and password fails to render
+   *         a user object, or if the user object's hash is not found by the internal NoAdapter.
+   * @throws NoUserAlreadyOnlineException - if the discovered user's hash is already online, as
+   *         determined by the internal NoAdapter's {@code isOnline} method.
+   */
   public byte[] login(byte[] data, char[] password) throws NoUserNotValidException,
-      NoUserAlreadyOnlineException, NoSessionExpiredException {
+      NoUserAlreadyOnlineException {
     NoSession session = new NoSession(data, password);
 
     /* 1. Check that user is a valid user of the system based on their hash. */
@@ -92,18 +116,24 @@ public final class NoCore {
 
     /* 5. Apply any incoming ByteSets to the session. */
     for (NoByteSet byteSet : session.getIncomingSafe()) {
+      boolean failed = true;
       try {
         session.consume(byteSet);
+        failed = false;
       } catch (NoByteSetBadDecryptionException e) {
         throw new NoDashFatalException("Bad byte sets on consumption.", e);
       } catch (NoSessionConfirmedException e) {
         throw new NoDashFatalException("NoSession is confirmed despite being newly created.");
+      } catch (NoSessionExpiredException e) {
+        throw new NoDashFatalException("NoSession is expired despite being newly created.");
       } finally {
-        try {
+        if (failed) {
-          adapter.addNoByteSets(session.getIncomingSafe(), session.getNoUserSafe()
+          try {
-              .getRsaPublicKey());
+            adapter.addNoByteSets(session.getIncomingSafe(), session.getNoUserSafe()
-        } catch (NoAdapterException e) {
+                .getRsaPublicKey());
-          throw new NoDashFatalException("Could not return failed byte sets to pool.", e);
+          } catch (NoAdapterException e) {
+            throw new NoDashFatalException("Could not return failed byte sets to pool.", e);
+          }
         }
       }
     }
@@ -113,11 +143,21 @@ public final class NoCore {
       session.check();
     } catch (NoSessionConfirmedException e) {
       throw new NoDashFatalException("NoSession is confirmed despite being newly created.");
+    } catch (NoSessionExpiredException e) {
+      throw new NoDashFatalException("NoSession has expired despite being newly created.");
     }
 
     return session.getEncryptedUuid();
   }
 
+  /**
+   * Attempts to register the given NoUser object as a new user on the system.
+   * 
+   * @param user the NoUser object to be registered.
+   * @param password the password given by the new user, as a char array.
+   * @return a NoRegister object containing the encrypted session UUID and the user data file as a
+   *         byte array.
+   */
   public NoRegister register(NoUser user, char[] password) {
     NoSession session = new NoSession(user);
     try {
@@ -170,11 +210,38 @@ public final class NoCore {
     }
   }
 
-  public NoState getSessionState(byte[] cookie) throws NoSessionConfirmedException,
+  /**
-      NoSessionExpiredException {
+   * Returns the state of the session identified by the encrypted cookie.
-    return getNoSession(cookie).getNoState();
+   * 
+   * @param cookie the byte array representation of the encrypted cookie.
+   * @return a NoState enum representing the state of the associated NoSession.
+   * @throws NoSessionExpiredException - if the associated NoSession cannot be found.
+   */
+  public NoState getSessionState(byte[] cookie) throws NoSessionExpiredException {
+    try {
+      return getNoSession(cookie).getNoState();
+    } catch (NoSessionConfirmedException e) {
+      return NoState.CONFIRMED;
+    }
   }
 
+  /**
+   * Initiates a save attempt on the NoSession associated to the encrypted UUID, with the provided
+   * password.
+   * 
+   * @param cookie the byte array representation of the encrypted cookie.
+   * @param password the password given by the user, as a char array.
+   * @return a byte array representing the user's new file.
+   * @throws NoSessionExpiredException - if the associated NoSession cannot be found or has exceeded
+   *         the session time limits.
+   * @throws NoSessionConfirmedException - if the associated NoSession has already been confirmed
+   *         and therefore cannot be saved.
+   * @throws NoSessionNotChangedException - if the NoUser associated with the session has not been
+   *         changed (specifically: if the hashes of the current and original NoUser objects held by
+   *         the NoSession are equal)
+   * @throws NoSessionAlreadyAwaitingConfirmationException - if the associated NoSession is already
+   *         awaiting confirmation.
+   */
   public byte[] save(byte[] cookie, char[] password) throws NoSessionExpiredException,
       NoSessionConfirmedException, NoSessionNotChangedException,
       NoSessionAlreadyAwaitingConfirmationException {
@@ -188,25 +255,42 @@ public final class NoCore {
     return session.initiateSaveAttempt(password);
   }
 
-  public void confirm(byte[] cookie, char[] password, byte[] data) throws NoSessionExpiredException, NoSessionConfirmedException, NoSessionNotAwaitingConfirmationException, NoUserNotValidException {
+  /**
+   * Attempts to confirm a save attempt by re-supplying the password and byte array, along with the
+   * session cookie
+   * 
+   * @param cookie the byte array representation of the encrypted cookie.
+   * @param password the password originally given at the save attempt, as a char array.
+   * @param data the byte array given by the save attempt.
+   * @throws NoSessionExpiredException - if the NoSession cannot be found or has exceeded the
+   *         session expiry time.
+   * @throws NoSessionConfirmedException - if the NoSession has already been confirmed.
+   * @throws NoSessionNotAwaitingConfirmationException - if the NoSession is not awaiting a save
+   *         confirmation.
+   * @throws NoUserNotValidException - if the given file and password do not generate a valid user
+   *         file.
+   */
+  public void confirm(byte[] cookie, char[] password, byte[] data)
+      throws NoSessionExpiredException, NoSessionConfirmedException,
+      NoSessionNotAwaitingConfirmationException, NoUserNotValidException {
     NoSession session = getNoSession(cookie);
     byte[] oldHash = session.getOriginalHash();
     byte[] newHash = session.getNoUserSafe().createHash();
-    
+
     session.confirmSave(adapter, data, password);
-    
+
     try {
       adapter.insertHash(newHash);
     } catch (NoAdapterException e) {
       throw new NoDashFatalException("Could not insert confirmed hash.", e);
     }
-    
+
     try {
       adapter.shredNoSession(cookie);
     } catch (NoAdapterException e) {
       throw new NoDashFatalException("Could not shred session.", e);
     }
-    
+
     try {
       adapter.goOffline(session.getNoUserSafe().createHash());
     } catch (NoAdapterException e) {
@@ -222,15 +306,23 @@ public final class NoCore {
     }
   }
 
+  /**
+   * Destroys the NoSession, returning ByteSets to the pool if necessary and takes the user hash out
+   * of the online pool through the adapter.
+   * 
+   * @param cookie the byte set representation of the encrypted NoSession UUID.
+   * @throws NoSessionExpiredException - if the NoSession cannot be found or has exceeded the
+   *         session expiry time.
+   */
   public void shred(byte[] cookie) throws NoSessionExpiredException {
     NoSession session = getNoSession(cookie);
-    
+
     try {
       adapter.shredNoSession(cookie);
     } catch (NoAdapterException e) {
       throw new NoDashFatalException("Could not shred session.", e);
     }
-    
+
     try {
       adapter.addNoByteSets(session.getIncomingSafe(), session.getNoUserSafe().getRsaPublicKey());
     } catch (NoAdapterException e) {