[Minor] added some java docs

src/ch/eitchnet/privilege/handler/DefaultEncryptionHandler.java

@@ -18,7 +18,7 @@ import java.util.Map;
 
 import org.apache.log4j.Logger;
 
-import ch.eitchnet.privilege.helper.EncryptionHelper;
+import ch.eitchnet.privilege.helper.HashHelper;
 import ch.eitchnet.privilege.helper.XmlConstants;
 import ch.eitchnet.privilege.i18n.PrivilegeException;
 
@@ -60,7 +60,7 @@ public class DefaultEncryptionHandler implements EncryptionHandler {
 	public String convertToHash(String string) {
 		try {
 
-			return EncryptionHelper.encryptString(this.hashAlgorithm, string);
+			return HashHelper.stringToHash(this.hashAlgorithm, string);
 
 		} catch (NoSuchAlgorithmException e) {
 			throw new PrivilegeException("Algorithm " + this.hashAlgorithm + " was not found!", e);

src/ch/eitchnet/privilege/handler/XmlPersistenceHandler.java

@@ -192,7 +192,7 @@ public class XmlPersistenceHandler implements PersistenceHandler {
 			}
 
 			// write DOM to file
-			XmlHelper.writeDocument(rootElement, usersFile);
+			XmlHelper.writeElement(rootElement, usersFile);
 			this.userMapDirty = true;
 		}
 
@@ -219,7 +219,7 @@ public class XmlPersistenceHandler implements PersistenceHandler {
 			}
 
 			// write DOM to file
-			XmlHelper.writeDocument(rootElement, rolesFile);
+			XmlHelper.writeElement(rootElement, rolesFile);
 			this.roleMapDirty = true;
 		}
 
@@ -247,7 +247,7 @@ public class XmlPersistenceHandler implements PersistenceHandler {
 			}
 
 			// write DOM to file
-			XmlHelper.writeDocument(rootElement, privilegesFile);
+			XmlHelper.writeElement(rootElement, privilegesFile);
 			this.privilegeMapDirty = true;
 		}
 

src/ch/eitchnet/privilege/helper/BootstrapConfigurationHelper.java

@@ -21,15 +21,17 @@ import org.dom4j.Document;
 import org.dom4j.DocumentFactory;
 import org.dom4j.Element;
 
+import ch.eitchnet.privilege.handler.PrivilegeHandler;
+
 /**
  * <p>
  * This class is a simple application which can be used to bootstrap a new configuration for the
- * {@link PrivilegeContainer}
+ * {@link PrivilegeHandler}
  * </p>
  * 
  * <p>
  * Simple execute the application and it will ask a few questions and then write a new set of configuration files which
- * can be used to run the {@link PrivilegeContainer}
+ * can be used to run the {@link PrivilegeHandler}
  * </p>
  * 
  * @author rvonburg

src/ch/eitchnet/privilege/helper/ClassHelper.java

@@ -13,13 +13,28 @@ package ch.eitchnet.privilege.helper;
 import ch.eitchnet.privilege.i18n.PrivilegeException;
 
 /**
+ * The {@link ClassHelper} class is a helper to instantiate classes using reflection
+ * 
  * @author rvonburg
  * 
  */
 public class ClassHelper {
 
+	/**
+	 * Returns an instance of the class' name given by instantiating the class through an empty arguments constructor
+	 * 
+	 * @param <T>
+	 *            the type of the class to return
+	 * @param className
+	 *            the name of a class to instantiate through an empty arguments constructor
+	 * 
+	 * @return the newly instantiated object from the given class name
+	 * 
+	 * @throws PrivilegeException
+	 *             if the class could not be instantiated
+	 */
 	@SuppressWarnings("unchecked")
-	public static <T> T instantiateClass(String className) {
+	public static <T> T instantiateClass(String className) throws PrivilegeException {
 		try {
 
 			Class<T> clazz = (Class<T>) Class.forName(className);
@@ -31,7 +46,20 @@ public class ClassHelper {
 		}
 	}
 
-	public static <T> T instantiateClass(Class<T> clazz) {
+	/**
+	 * Instantiates an object for the given {@link Class} using an empty arguments constructor
+	 * 
+	 * @param <T>
+	 *            the type of the class to return
+	 * @param clazz
+	 *            the {@link Class} from which a new object is to be instantiated using an empty arguments constructor
+	 * 
+	 * @return the newly instantiated object from the given {@link Class}
+	 * 
+	 * @throws PrivilegeException
+	 *             if the {@link Class} could not be instantiated
+	 */
+	public static <T> T instantiateClass(Class<T> clazz) throws PrivilegeException {
 		try {
 
 			return clazz.getConstructor().newInstance();
@@ -41,8 +69,21 @@ public class ClassHelper {
 		}
 	}
 
+	/**
+	 * Loads the {@link Class} object for the given class name
+	 * 
+	 * @param <T>
+	 *            the type of {@link Class} to return
+	 * @param className
+	 *            the name of the {@link Class} to load and return
+	 * 
+	 * @return the {@link Class} object for the given class name
+	 * 
+	 * @throws PrivilegeException
+	 *             if the class could not be instantiated
+	 */
 	@SuppressWarnings("unchecked")
-	public static <T> Class<T> loadClass(String className) {
+	public static <T> Class<T> loadClass(String className) throws PrivilegeException {
 		try {
 
 			Class<T> clazz = (Class<T>) Class.forName(className);

src/ch/eitchnet/privilege/helper/HashHelper.java

@@ -18,16 +18,31 @@ import java.security.NoSuchAlgorithmException;
  * @author rvonburg
  * 
  */
-public class EncryptionHelper {
+public class HashHelper {
 
 	/**
-	 * Hex char table for fast calculating of hex value
+	 * Hex char table for fast calculating of hex values
 	 */
 	private static final byte[] HEX_CHAR_TABLE = { (byte) '0', (byte) '1', (byte) '2', (byte) '3', (byte) '4',
 			(byte) '5', (byte) '6', (byte) '7', (byte) '8', (byte) '9', (byte) 'a', (byte) 'b', (byte) 'c', (byte) 'd',
 			(byte) 'e', (byte) 'f' };
 
-	public static String encryptString(String hashAlgorithm, String string) throws NoSuchAlgorithmException,
+	/**
+	 * Creates the hash of the given string using {@link MessageDigest} and the defined hash algorithm
+	 * 
+	 * @param hashAlgorithm
+	 *            the algorithm to use for hashing
+	 * @param string
+	 *            the string to hash
+	 * 
+	 * @return a new string encrypted by the defined algorithm
+	 * 
+	 * @throws NoSuchAlgorithmException
+	 *             if the algorithm is not found
+	 * @throws UnsupportedEncodingException
+	 *             if something is wrong with the given string to hash
+	 */
+	public static String stringToHash(String hashAlgorithm, String string) throws NoSuchAlgorithmException,
 			UnsupportedEncodingException {
 
 		MessageDigest digest = MessageDigest.getInstance(hashAlgorithm);

src/ch/eitchnet/privilege/helper/InitializationHelper.java

@@ -33,7 +33,8 @@ public class InitializationHelper {
 
 	/**
 	 * @param privilegeContainerXmlFile
-	 * @return
+	 * 
+	 * @return the {@link PrivilegeHandler} instance loaded from the configuration file
 	 */
 	public static PrivilegeHandler initializeFromXml(File privilegeContainerXmlFile) {
 
@@ -110,7 +111,8 @@ public class InitializationHelper {
 
 	/**
 	 * @param element
-	 * @return
+	 * 
+	 * @return the {@link Map} of the parameter name/value combinations from the given {@link Element}
 	 */
 	@SuppressWarnings("unchecked")
 	public static Map<String, String> convertToParameterMap(Element element) {

src/ch/eitchnet/privilege/helper/PasswordCreator.java

@@ -22,6 +22,7 @@ public class PasswordCreator {
 
 	/**
 	 * @param args
+	 * @throws Exception 
 	 */
 	public static void main(String[] args) throws Exception {
 
@@ -48,7 +49,7 @@ public class PasswordCreator {
 
 		System.out.print("Password: ");
 		String password = r.readLine().trim();
-		System.out.print("Hash is: " + EncryptionHelper.encryptString(hashAlgorithm, password));
+		System.out.print("Hash is: " + HashHelper.stringToHash(hashAlgorithm, password));
 	}
 
 }

src/ch/eitchnet/privilege/helper/XmlConstants.java

@@ -15,45 +15,156 @@ package ch.eitchnet.privilege.helper;
  * 
  */
 public class XmlConstants {
+	/**
+	 * XML_ROOT_PRIVILEGE_CONTAINER = "PrivilegeContainer" :
+	 */
 	public static final String XML_ROOT_PRIVILEGE_CONTAINER = "PrivilegeContainer";
+	/**
+	 * XML_ROOT_PRIVILEGE_ROLES = "PrivilegeRoles" :
+	 */
 	public static final String XML_ROOT_PRIVILEGE_ROLES = "PrivilegeRoles";
+	/**
+	 * XML_ROOT_PRIVILEGES = "Privileges" :
+	 */
 	public static final String XML_ROOT_PRIVILEGES = "Privileges";
+	/**
+	 * XML_ROOT_PRIVILEGE_USERS = "PrivilegesUsers" :
+	 */
 	public static final String XML_ROOT_PRIVILEGE_USERS = "PrivilegesUsers";
+	/**
+	 * XML_ROOT_PRIVILEGE_POLICIES = "PrivilegePolicies" :
+	 */
 	public static final String XML_ROOT_PRIVILEGE_POLICIES = "PrivilegePolicies";
 
+	/**
+	 * XML_HANDLER_PERSISTENCE = "PersistenceHandler" :
+	 */
 	public static final String XML_HANDLER_PERSISTENCE = "PersistenceHandler";
+	/**
+	 * XML_HANDLER_ENCRYPTION = "EncryptionHandler" :
+	 */
 	public static final String XML_HANDLER_ENCRYPTION = "EncryptionHandler";
+	/**
+	 * XML_HANDLER_PRIVILEGE = "PrivilegeHandler" :
+	 */
 	public static final String XML_HANDLER_PRIVILEGE = "PrivilegeHandler";
 
+	/**
+	 * XML_ROLES = "Roles" :
+	 */
 	public static final String XML_ROLES = "Roles";
+	/**
+	 * XML_ROLE = "Role" :
+	 */
 	public static final String XML_ROLE = "Role";
+	/**
+	 * XML_USERS = "Users" :
+	 */
 	public static final String XML_USERS = "Users";
+	/**
+	 * XML_USER = "User"
+	 */
 	public static final String XML_USER = "User";
+	/**
+	 * XML_PRIVILEGES = "Privileges" :
+	 */
 	public static final String XML_PRIVILEGES = "Privileges";
+	/**
+	 * XML_PRIVILEGE = "Privilege" :
+	 */
 	public static final String XML_PRIVILEGE = "Privilege";
+	/**
+	 * XML_POLICY = "Policy" :
+	 */
 	public static final String XML_POLICY = "Policy";
+	/**
+	 * XML_PARAMETERS = "Parameters" :
+	 */
 	public static final String XML_PARAMETERS = "Parameters";
+	/**
+	 * XML_PARAMETER = "Parameter" :
+	 */
 	public static final String XML_PARAMETER = "Parameter";
+	/**
+	 * XML_ALL_ALLOWED = "AllAllowed" :
+	 */
 	public static final String XML_ALL_ALLOWED = "AllAllowed";
+	/**
+	 * XML_DENY = "Deny" :
+	 */
 	public static final String XML_DENY = "Deny";
+	/**
+	 * XML_ALLOW = "Allow" :
+	 */
 	public static final String XML_ALLOW = "Allow";
+	/**
+	 * XML_FIRSTNAME = "Firstname" :
+	 */
 	public static final String XML_FIRSTNAME = "Firstname";
+	/**
+	 * XML_SURNAME = "Surname" :
+	 */
 	public static final String XML_SURNAME = "Surname";
+	/**
+	 * XML_STATE = "State" :
+	 */
 	public static final String XML_STATE = "State";
+	/**
+	 * XML_LOCALE = "Locale" :
+	 */
 	public static final String XML_LOCALE = "Locale";
 
+	/**
+	 * XML_ATTR_CLASS = "class" :
+	 */
 	public static final String XML_ATTR_CLASS = "class";
+	/**
+	 * XML_ATTR_NAME = "name" :
+	 */
 	public static final String XML_ATTR_NAME = "name";
+	/**
+	 * XML_ATTR_VALUE = "value" :
+	 */
 	public static final String XML_ATTR_VALUE = "value";
+	/**
+	 * XML_ATTR_POLICY = "policy" :
+	 */
 	public static final String XML_ATTR_POLICY = "policy";
+	/**
+	 * XML_ATTR_USER_ID = "userId" :
+	 */
 	public static final String XML_ATTR_USER_ID = "userId";
+	/**
+	 * XML_ATTR_USERNAME = "username" :
+	 */
 	public static final String XML_ATTR_USERNAME = "username";
+	/**
+	 * XML_ATTR_PASSWORD = "password" :
+	 */
 	public static final String XML_ATTR_PASSWORD = "password";
 
+	/**
+	 * XML_PARAM_HASH_ALGORITHM = "hashAlgorithm" :
+	 */
 	public static final String XML_PARAM_HASH_ALGORITHM = "hashAlgorithm";
+	/**
+	 * XML_PARAM_POLICY_FILE = "policyXmlFile" :
+	 */
 	public static final String XML_PARAM_POLICY_FILE = "policyXmlFile";
+	/**
+	 * XML_PARAM_ROLES_FILE = "rolesXmlFile" :
+	 */
 	public static final String XML_PARAM_ROLES_FILE = "rolesXmlFile";
+	/**
+	 * XML_PARAM_USERS_FILE = "usersXmlFile" :
+	 */
 	public static final String XML_PARAM_USERS_FILE = "usersXmlFile";
+	/**
+	 * XML_PARAM_PRIVILEGES_FILE = "privilegesXmlFile" :
+	 */
 	public static final String XML_PARAM_PRIVILEGES_FILE = "privilegesXmlFile";
+	/**
+	 * XML_PARAM_BASE_PATH = "basePath" :
+	 */
 	public static final String XML_PARAM_BASE_PATH = "basePath";
 }

src/ch/eitchnet/privilege/helper/XmlHelper.java

@@ -35,10 +35,21 @@ import ch.eitchnet.privilege.i18n.PrivilegeException;
  */
 public class XmlHelper {
 
+	/**
+	 * DEFAULT_ENCODING = "UTF-8" : defines the default UTF-8 encoding expected of XML files
+	 */
 	public static final String DEFAULT_ENCODING = "UTF-8";
 
 	private static final Logger logger = Logger.getLogger(XmlHelper.class);
 
+	/**
+	 * Parses an XML file on the file system using dom4j and returns the resulting {@link Document} object
+	 * 
+	 * @param xmlFile
+	 *            the {@link File} which has the path to the XML file to read
+	 * 
+	 * @return a {@link Document} object containing the dom4j {@link Element}s of the XML file
+	 */
 	public static Document parseDocument(File xmlFile) {
 
 		try {
@@ -58,6 +69,14 @@ public class XmlHelper {
 		}
 	}
 
+	/**
+	 * Writes a dom4j {@link Document} to an XML file on the file system
+	 * 
+	 * @param document
+	 *            the {@link Document} to write to the file system
+	 * @param file
+	 *            the {@link File} describing the path on the file system where the XML file should be written to
+	 */
 	public static void writeDocument(Document document, File file) {
 
 		logger.info("Exporting document element " + document.getName() + " to " + file.getAbsolutePath());
@@ -94,7 +113,15 @@ public class XmlHelper {
 		}
 	}
 
-	public static void writeDocument(Element rootElement, File file) {
+	/**
+	 * Writes a dom4j {@link Element} to an XML file on the file system
+	 * 
+	 * @param rootElement
+	 *            the {@link Element} to write to the file system
+	 * @param file
+	 *            the {@link File} describing the path on the file system where the XML file should be written to
+	 */
+	public static void writeElement(Element rootElement, File file) {
 
 		Document document = DocumentFactory.getInstance().createDocument(DEFAULT_ENCODING);
 		document.setRootElement(rootElement);

src/ch/eitchnet/privilege/model/Restrictable.java

@@ -10,19 +10,27 @@
 
 package ch.eitchnet.privilege.model;
 
+import ch.eitchnet.privilege.model.internal.Privilege;
+
 /**
+ * TODO javadoc
+ * 
  * @author rvonburg
  * 
  */
 public interface Restrictable {
 
 	/**
-	 * @return
+	 * Returns the name of the {@link Privilege} which is to be used to validate privileges against
+	 * 
+	 * @return the name of the {@link Privilege} which is to be used to validate privileges against
 	 */
 	public String getPrivilegeName();
 
 	/**
-	 * @return
+	 * Returns the value which defines or describes what privilege is to be granted
+	 * 
+	 * @return the value which defines or describes what privilege is to be granted
 	 */
 	public Object getPrivilegeValue();
 }

src/ch/eitchnet/privilege/model/UserState.java

@@ -10,13 +10,37 @@
 
 package ch.eitchnet.privilege.model;
 
+import ch.eitchnet.privilege.model.internal.User;
+
 /**
+ * The {@link UserState} enum defines the different states a {@link User} can have:
+ * <ul>
+ * <li>NEW - the user is new, and cannot login</li>
+ * <li>ENABLED - the user has been enabled, meaning a password has been set and the user has at least one role assigned
+ * and may thus login</li>
+ * <li>DISABLED - the user been disabled by an administrator</li>
+ * <li>EXPIRED - the user has automatically expired through a predefined time</li>
+ * </ul>
+ * 
  * @author rvonburg
  * 
  */
 public enum UserState {
+	/**
+	 * the user is new, and cannot login
+	 */
 	NEW,
+	/**
+	 * the user has been enabled, meaning a password has been set and the user has at least one role assigned and may
+	 * thus login
+	 */
 	ENABLED,
+	/**
+	 * the user been disabled by an administrator
+	 */
 	DISABLED,
+	/**
+	 * the user has automatically expired through a predefined time
+	 */
 	EXPIRED;
 }

src/ch/eitchnet/privilege/model/internal/Role.java

@@ -43,18 +43,24 @@ public final class Role {
 	}
 
 	/**
-	 * @return
+	 * Returns the {@link Set} of {@link Privilege} names which is granted to this {@link Role}
+	 * 
+	 * @return the {@link Set} of {@link Privilege} names which is granted to this
 	 */
 	public Set<String> getPrivileges() {
 		return this.privileges;
 	}
 
 	/**
-	 * @param key
+	 * Determines if this {@link Role} has the {@link Privilege} with the given name
-	 * @return
+	 * 
+	 * @param name
+	 *            the name of the {@link Privilege}
+	 * 
+	 * @return true if this {@link Role} has the {@link Privilege} with the given name
 	 */
-	public boolean hasPrivilege(String key) {
+	public boolean hasPrivilege(String name) {
-		return this.privileges.contains(key);
+		return this.privileges.contains(name);
 	}
 
 	/**

src/ch/eitchnet/privilege/model/internal/User.java

@@ -69,7 +69,7 @@ public final class User {
 	 * @return the userId
 	 */
 	public String getUserId() {
-		return userId;
+		return this.userId;
 	}
 
 	/**
@@ -80,11 +80,9 @@ public final class User {
 	}
 
 	/**
+	 * Returns the hashed password for this {@link User}
 	 * 
-	 * @param privilegeHandler
+	 * @return the hashed password for this {@link User}
-	 * @param certificate
-	 * 
-	 * @return
 	 */
 	public String getPassword() {
 

src/ch/eitchnet/privilege/policy/PrivilegePolicy.java

@@ -24,7 +24,8 @@ public interface PrivilegePolicy {
 	 * @param role
 	 * @param privilege
 	 * @param restrictable
-	 * @return
+	 * 
+	 * @return return true if the action is allowed, false if not
 	 */
 	public boolean actionAllowed(Role role, Privilege privilege, Restrictable restrictable);
 }