Add doc-comments to ApiServer and Hash, some TODO comments

2 files changed, 58 insertions, 40 deletions

diff --git a/src/main/java/org/openslx/imagemaster/server/ApiServer.java b/src/main/java/org/openslx/imagemaster/server/ApiServer.java
index 57df2b9..eda48eb 100644
--- a/src/main/java/org/openslx/imagemaster/server/ApiServer.java
+++ b/src/main/java/org/openslx/imagemaster/server/ApiServer.java
@@ -43,12 +43,10 @@ public class ApiServer {
 	/**
 	 * Request for authentication
 	 * 
-	 * @param login
-	 *            (username@organization)
-	 * @param password
+	 * @param login The user's login in the form "user@organization.com"
+	 * @param password user's password
 	 * @return SessionData struct with session id/token iff login successful
-	 * @throws AuthenticationException
-	 *             if login not successful
+	 * @throws AuthenticationException if login not successful
 	 */
 	public static SessionData authenticate(String login, String password)
 			throws AuthenticationException {
@@ -66,11 +64,9 @@ public class ApiServer {
 	/**
 	 * Request information about user for given token
 	 * 
-	 * @param token
-	 *            - a user's token
+	 * @param token a user's token
 	 * @return UserInfo struct for given token's user
-	 * @throws InvalidTokenException
-	 *             if no user matches the given token
+	 * @throws InvalidTokenException if no user matches the given token
 	 */
 	public static UserInfo getUserFromToken(String token)
 			throws InvalidTokenException {
@@ -83,7 +79,7 @@ public class ApiServer {
 
 	/**
 	 * Request ftp credentials to upload a new image to the masterserver.
-	 * @param imageDescription MetdaData of the new image
+	 * @param imageDescription MetaData of the new image
 	 * @param serverSessionData the session data of the authenticated uni/hs server
 	 * @return the genereated ftp credentials
 	 * @throws AuthorizationException if the uni/hs server has no valid session
@@ -115,13 +111,15 @@ public class ApiServer {
 	}
 
 	/**
-	 * Start the server authentication of a uni/hs server.
+	 * Start the server authentication of a uni/hs satellite server.
 	 * @param organization the organization that the server belongs to
-	 * @return a random string that needs to be encrypted with the private key
+	 * @return a random string that needs to be encrypted with the private
+	 *          key of the requesting satellite server
 	 * @throws TException
 	 */
 	public static String startServerAuthentication(String organization)
 			throws TException {
+		// TODO: Proper exceptions
 		if (organization == null || organization == "") {
 			throw new TException("Empty organization");
 		}
@@ -132,16 +130,17 @@ public class ApiServer {
 	}
 
 	/**
-	 * Authenticate the uni/hs server with the encrypted string.
+	 * Authenticate the uni/hs satellite server with the encrypted string.
 	 * @param organization the organization that the server belongs to
 	 * @param challengeResponse the encrypted string
-	 * @return session data iff the authentication was successfull
+	 * @return session data iff the authentication was successful
 	 * @throws AuthenticationException
 	 * @throws TException
 	 */
 	public static ServerSessionData serverAuthenticate(String organization,
 			String challengeResponse) throws AuthenticationException,
 			TException {
+		// TODO: Proper exceptions
 		if (organization == null || challengeResponse == null) {
 			throw new TException("Empty organization org challengeResponse");
 		}
diff --git a/src/main/java/org/openslx/imagemaster/util/Hash.java b/src/main/java/org/openslx/imagemaster/util/Hash.java
index 8ac0e5f..24eb595 100644
--- a/src/main/java/org/openslx/imagemaster/util/Hash.java
+++ b/src/main/java/org/openslx/imagemaster/util/Hash.java
@@ -6,7 +6,9 @@ import java.security.NoSuchAlgorithmException;
 
 public class Hash
 {
-	// Cache of md5 digesters
+	/**
+	 * Cache of md5 digesters
+	 */
 	private static final ThreadLocal<MessageDigest> md5hash = new ThreadLocal<MessageDigest>() {
 		@Override
 		public MessageDigest initialValue()
@@ -20,7 +22,9 @@ public class Hash
 			}
 		}
 	};
-	// Cache of sha256 digesters
+	/**
+	 * Cache of sha256 digesters
+	 */
 	private static final ThreadLocal<MessageDigest> sha256hash = new ThreadLocal<MessageDigest>() {
 		@Override
 		public MessageDigest initialValue()
@@ -34,32 +38,35 @@ public class Hash
 			}
 		}
 	};
-	// Cache of sha512 digesters
-	private static final ThreadLocal<MessageDigest> sha512hash = new ThreadLocal<MessageDigest>() {
-		@Override
-		public MessageDigest initialValue()
-		{
-			try {
-				return MessageDigest.getInstance( "SHA-512" );
-			} catch ( NoSuchAlgorithmException e ) {
-				e.printStackTrace();
-				System.exit(1);
-				return null;
-			}
-		}
-	};
-	// For converting to hex string
+	/**
+	 * For converting to hex string
+	 */
 	private static final char[] HEX_CHARS = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F' };
-	// Constant
+	/**
+	 * Constant for the utf-8 charset, saves repeated lookups
+	 */
 	private static final Charset UTF8 = Charset.forName( "UTF-8" );
 
 	// MD5
 	
+	/**
+	 * Compute md5 hash of given binary data.
+	 * 
+	 * @param bytes the binary data in a byte array
+	 * @return hex representation of the 128bit md5 hash
+	 */
 	public static String md5( final byte[] bytes )
 	{
 		return toHexString( md5hash.get().digest( bytes ) );
 	}
 	
+	/**
+	 * Compute md5 hash of the given string.
+	 * The string will be converted to utf-8 before computation.
+	 * 
+	 * @param text the text to hash
+	 * @return hex representation of the 128bit md5 hash
+	 */
 	public static String md5( final String text )
 	{
 		return md5( text.getBytes( UTF8 ));
@@ -67,25 +74,37 @@ public class Hash
 	
 	// SHA-256
 	
+	/**
+	 * Compute sha256 hash of given binary data.
+	 * 
+	 * @param bytes the binary data in a byte array
+	 * @return hex representation of the 256bit sha256 hash
+	 */
 	public static String sha256( final byte[] bytes )
 	{
 		return toHexString( sha256hash.get().digest( bytes ) );
 	}
-	
+
+	/**
+	 * Compute sha256 hash of the given string.
+	 * The string will be converted to utf-8 before computation.
+	 * 
+	 * @param text the text to hash
+	 * @return hex representation of the 256bit sha256 hash
+	 */
 	public static String sha256( final String text )
 	{
 		return sha256( text.getBytes( UTF8 ));
 	}
 	
-	// SHA-512
-	
-	public static MessageDigest getSha512Digest()
-	{
-		return sha512hash.get();
-	}
-
 	// Helper
 	
+	/**
+	 * Convert given binary data to hex.
+	 * 
+	 * @param bytes binary data in a byte array
+	 * @return upper case hex representation of bytes 
+	 */
 	private static String toHexString( final byte[] bytes )
 	{
 		final char[] hexChars = new char[bytes.length * 2];