[Major] updated a lot of JavaDoc and made sure that every class has at least a header JavaDoc with a description. Added a TODO under the doc folder with some TODOs =)

MANIFEST.MF

@@ -0,0 +1,2 @@
+Manifest-Version: 1.0
+

docs/TODO

@@ -0,0 +1,14 @@
+A list of TODOs for Privilege
+============================================
+
+- Write up a proper explanation on the idea on how Privilege, PrivilegePolicy,
+  Restrictable and Roles fit together to grant privileges to Users
+
+- Re-think the PrivilegePolicy and its 
+  actionAllowed(Role, Privilege, Restrictable)-method. Maybe the Privilege
+  argument is not needed, as this should be on the Role anyhow...
+
+- Finish the JavaDoc
+
+- Set up a website =)
+

privilege.jardesc

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<jardesc>
+    <jar path="/home/eitch/privilege.jar"/>
+    <options buildIfNeeded="true" compress="true" descriptionLocation="/Privilege/privilege.jardesc" exportErrors="true" exportWarnings="true" includeDirectoryEntries="false" overwrite="false" saveDescription="false" storeRefactorings="false" useSourceFolders="false"/>
+    <storedRefactorings deprecationInfo="true" structuralOnly="false"/>
+    <selectedProjects/>
+    <manifest generateManifest="false" manifestLocation="/Privilege/MANIFEST.MF" manifestVersion="1.0" reuseManifest="false" saveManifest="true" usesManifest="true">
+        <sealing sealJar="false">
+            <packagesToSeal/>
+            <packagesToUnSeal/>
+        </sealing>
+    </manifest>
+    <selectedElements exportClassFiles="true" exportJavaFiles="true" exportOutputFolder="false">
+        <javaElement handleIdentifier="=Privilege/src"/>
+        <file path="/Privilege/.classpath"/>
+        <file path="/Privilege/.project"/>
+    </selectedElements>
+</jardesc>

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

@@ -34,11 +34,15 @@ import ch.eitchnet.privilege.handler.PrivilegeHandler;
  * can be used to run the {@link PrivilegeHandler}
  * </p>
  * 
- * @author rvonburg
+ * <p>
+ * <b>Note:</b>This class is not yet implemented!
+ * </p>
  * 
+ * @author rvonburg
  */
 public class BootstrapConfigurationHelper {
-//	private static final Logger logger = Logger.getLogger(BootstrapConfigurationHelper.class);
+
+	// private static final Logger logger = Logger.getLogger(BootstrapConfigurationHelper.class);
 
 	private static String path;
 
@@ -58,6 +62,7 @@ public class BootstrapConfigurationHelper {
 
 	/**
 	 * @param args
+	 *            the args from the command line
 	 */
 	public static void main(String[] args) {
 		BasicConfigurator.resetConfiguration();

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

@@ -16,7 +16,6 @@ import ch.eitchnet.privilege.i18n.PrivilegeException;
  * The {@link ClassHelper} class is a helper to instantiate classes using reflection
  * 
  * @author rvonburg
- * 
  */
 public class ClassHelper {
 

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

@@ -15,8 +15,9 @@ import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
 
 /**
- * @author rvonburg
+ * Helper class to hash a String for a certain hash algorithm, using the Java {@link MessageDigest} classes
  * 
+ * @author rvonburg
  */
 public class HashHelper {
 

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

@@ -24,15 +24,20 @@ import ch.eitchnet.privilege.handler.PrivilegeHandler;
 import ch.eitchnet.privilege.i18n.PrivilegeException;
 
 /**
- * @author rvonburg
+ * This class implements the initializing of the {@link PrivilegeHandler} by loading an XML file containing the
+ * configuration
  * 
+ * @author rvonburg
  */
 public class InitializationHelper {
 
 	private static final Logger logger = Logger.getLogger(InitializationHelper.class);
 
 	/**
+	 * Initializes the {@link PrivilegeHandler} from the configuration file
+	 * 
 	 * @param privilegeContainerXmlFile
+	 *            a {@link File} reference to the XML file containing the configuration for Privilege
 	 * 
 	 * @return the {@link PrivilegeHandler} instance loaded from the configuration file
 	 */
@@ -110,7 +115,12 @@ public class InitializationHelper {
 	}
 
 	/**
+	 * Converts an {@link XmlConstants#XML_PARAMETERS} element containing {@link XmlConstants#XML_PARAMETER} elements to
+	 * a {@link Map} of String key/value pairs
+	 * 
 	 * @param element
+	 *            the XML {@link Element} with name {@link XmlConstants#XML_PARAMETERS} containing
+	 *            {@link XmlConstants#XML_PARAMETER} elements
 	 * 
 	 * @return the {@link Map} of the parameter name/value combinations from the given {@link Element}
 	 */

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

@@ -15,14 +15,23 @@ import java.io.InputStreamReader;
 import java.security.MessageDigest;
 
 /**
- * @author rvonburg
+ * <p>
+ * Simple main class which can be used to create a hash from a password which the user must type in at the command line
+ * </p>
  * 
+ * <p>
+ * TODO: Note: currently the password input is echoed which is a security risk. This is a TODO
+ * </p>
+ * 
+ * @author rvonburg
  */
 public class PasswordCreator {
 
 	/**
 	 * @param args
-	 * @throws Exception 
+	 *            the args from the command line, NOT USED
+	 * @throws Exception
+	 *             thrown if anything goes wrong
 	 */
 	public static void main(String[] args) throws Exception {
 

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

@@ -11,8 +11,9 @@
 package ch.eitchnet.privilege.helper;
 
 /**
- * @author rvonburg
+ * The constants used in parsing XML documents which contain the configuration for Privilege
  * 
+ * @author rvonburg
  */
 public class XmlConstants {
 	/**

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

@@ -30,8 +30,9 @@ import org.dom4j.io.XMLWriter;
 import ch.eitchnet.privilege.i18n.PrivilegeException;
 
 /**
- * @author rvonburg
+ * Helper class for performing XML based tasks using Dom4J
  * 
+ * @author rvonburg
  */
 public class XmlHelper {
 

src/ch/eitchnet/privilege/i18n/AccessDeniedException.java

@@ -11,17 +11,19 @@
 package ch.eitchnet.privilege.i18n;
 
 /**
- * @author rvonburg
+ * Exception thrown if access is denied during login, or if a certain privilege is not granted
  * 
+ * @author rvonburg
  */
 public class AccessDeniedException extends PrivilegeException {
 
 	private static final long serialVersionUID = 1L;
 
 	/**
-	 * @param string
+	 * @param msg
+	 *            detail on why and where access was denied
 	 */
-	public AccessDeniedException(String string) {
-		super(string);
+	public AccessDeniedException(String msg) {
+		super(msg);
 	}
 }

src/ch/eitchnet/privilege/i18n/PrivilegeException.java

@@ -11,24 +11,31 @@
 package ch.eitchnet.privilege.i18n;
 
 /**
- * @author rvonburg
+ * Main {@link RuntimeException} thrown if something goes wrong in Privilege
  * 
+ * @author rvonburg
  */
 public class PrivilegeException extends RuntimeException {
 
 	private static final long serialVersionUID = 1L;
 
 	/**
+	 * Default constructor
+	 * 
 	 * @param string
+	 *            message to go with the exception
 	 */
 	public PrivilegeException(String string) {
 		super(string);
 	}
 
 	/**
+	 * Constructor with underlying exception
 	 * 
 	 * @param string
+	 *            message to go with the exception
 	 * @param t
+	 *            throwable to wrap with this exception which is the underlying exception of this exception
 	 */
 	public PrivilegeException(String string, Throwable t) {
 		super(string, t);

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

@@ -13,11 +13,16 @@ package ch.eitchnet.privilege.model;
 import java.io.Serializable;
 import java.util.Locale;
 
+import ch.eitchnet.privilege.handler.PrivilegeHandler;
 import ch.eitchnet.privilege.i18n.PrivilegeException;
+import ch.eitchnet.privilege.model.internal.Session;
 
 /**
- * @author rvonburg
+ * The {@link Certificate} is the object a client keeps when accessing a Privilege enabled system. This object is the
+ * instance which is always used when performing an access and is returned when a user performs a login through
+ * {@link PrivilegeHandler#authenticate(String, String)}
  * 
+ * @author rvonburg
  */
 public final class Certificate implements Serializable {
 
@@ -31,11 +36,22 @@ public final class Certificate implements Serializable {
 	private Locale locale;
 
 	/**
+	 * Default constructor initializing with all information needed for this certificate
+	 * 
+	 * <p>Note, both the authentication token and password are private fields which are generated on login and only known by the {@link PrivilegeHandler}</p>
+	 * 
 	 * @param sessionId
+	 *            the users session id
 	 * @param username
+	 *            the users login name
 	 * @param authToken
+	 *            the authentication token defining the users unique session and is a private field of this certificate.
+	 *            It corresponds with the authentication token on the {@link Session}
 	 * @param authPassword
+	 *            the password to access the authentication token, this is not known to the client but set by the
+	 *            {@link PrivilegeHandler} on authentication. It corresponds with the authentication password on the {@link Session}
 	 * @param locale
+	 *            the users {@link Locale}
 	 */
 	public Certificate(String sessionId, String username, String authToken, String authPassword, Locale locale) {
 
@@ -86,12 +102,12 @@ public final class Certificate implements Serializable {
 	}
 
 	/**
-	 * Returns the authToken if the given authPassword is corret, null otherwise
+	 * Returns the authToken if the given authPassword is correct, null otherwise
 	 * 
 	 * @param authPassword
-	 *            the auth password with which this certificate was created
+	 *            the authentication password with which this certificate was created
 	 * 
-	 * @return the authToken if the given authPassword is corret, null otherwise
+	 * @return the authToken if the given authPassword is correct, null otherwise
 	 */
 	public String getAuthToken(String authPassword) {
 		if (this.authPassword.equals(authPassword))
@@ -170,5 +186,4 @@ public final class Certificate implements Serializable {
 		builder.append("]");
 		return builder.toString();
 	}
-
 }

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

@@ -13,9 +13,17 @@ package ch.eitchnet.privilege.model;
 import java.io.Serializable;
 import java.util.Set;
 
+import ch.eitchnet.privilege.handler.PrivilegeHandler;
+import ch.eitchnet.privilege.model.internal.Privilege;
+import ch.eitchnet.privilege.model.internal.Role;
+import ch.eitchnet.privilege.policy.PrivilegePolicy;
+
 /**
- * @author rvonburg
+ * To keep certain details of the {@link Privilege} itself hidden from remote clients and make sure instances are only
+ * edited by users with the correct privilege, this representational version is allowed to be viewed by remote clients
+ * and simply wraps all public data from the {@link Privilege}
  * 
+ * @author rvonburg
  */
 public class PrivilegeRep implements Serializable {
 
@@ -28,11 +36,19 @@ public class PrivilegeRep implements Serializable {
 	private Set<String> allowList;
 
 	/**
+	 * Default constructor
+	 * 
 	 * @param name
+	 *            the name of this privilege, which is unique to all privileges known in the {@link PrivilegeHandler}
 	 * @param policy
+	 *            the {@link PrivilegePolicy} configured to evaluate if the privilege is granted
 	 * @param allAllowed
+	 *            a boolean defining if a {@link Role} with this {@link Privilege} has unrestricted access to a
+	 *            {@link Restrictable}
 	 * @param denyList
+	 *            a list of deny rules for this {@link Privilege}
 	 * @param allowList
+	 *            a list of allow rules for this {@link Privilege}
 	 */
 	public PrivilegeRep(String name, String policy, boolean allAllowed, Set<String> denyList, Set<String> allowList) {
 		this.name = name;

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

@@ -11,9 +11,15 @@
 package ch.eitchnet.privilege.model;
 
 import ch.eitchnet.privilege.model.internal.Privilege;
+import ch.eitchnet.privilege.policy.PrivilegePolicy;
 
 /**
- * TODO javadoc
+ * <p>
+ * Objects implementing this interface are used to grant/restrict privileges to them. A {@link PrivilegePolicy}
+ * implements the logic on granting/restricting privileges for a {@link Restrictable} and the
+ * {@link #getPrivilegeName()} is used to find the {@link Privilege} which has the associated {@link PrivilegePolicy}
+ * for evaluating access
+ * </p>
  * 
  * @author rvonburg
  * 

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

@@ -13,9 +13,14 @@ package ch.eitchnet.privilege.model;
 import java.io.Serializable;
 import java.util.Set;
 
+import ch.eitchnet.privilege.model.internal.Role;
+
 /**
- * @author rvonburg
+ * To keep certain details of the {@link Role} itself hidden from remote clients and make sure instances are only edited
+ * by users with the correct privilege, this representational version is allowed to be viewed by remote clients and
+ * simply wraps all public data from the {@link Role}
  * 
+ * @author rvonburg
  */
 public class RoleRep implements Serializable {
 
@@ -25,8 +30,12 @@ public class RoleRep implements Serializable {
 	private Set<String> privileges;
 
 	/**
+	 * Default constructor
+	 * 
 	 * @param name
+	 *            the name of this role
 	 * @param privileges
+	 *            the set of privileges granted to this role
 	 */
 	public RoleRep(String name, Set<String> privileges) {
 		this.name = name;

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

@@ -14,9 +14,15 @@ import java.io.Serializable;
 import java.util.Locale;
 import java.util.Set;
 
+import ch.eitchnet.privilege.model.internal.Role;
+import ch.eitchnet.privilege.model.internal.User;
+
 /**
- * @author rvonburg
+ * To keep certain details of the {@link User} itself hidden from remote clients and make sure instances are only edited
+ * by users with the correct privilege, this representational version is allowed to be viewed by remote clients and
+ * simply wraps all public data from the {@link User}
  * 
+ * @author rvonburg
  */
 public class UserRep implements Serializable {
 
@@ -31,13 +37,22 @@ public class UserRep implements Serializable {
 	private Locale locale;
 
 	/**
+	 * Default constructor
+	 * 
 	 * @param userId
+	 *            the user's id
 	 * @param username
+	 *            the user's login name
 	 * @param firstname
+	 *            the user's first name
 	 * @param surname
+	 *            the user's surname
 	 * @param userState
+	 *            the user's {@link UserState}
 	 * @param roles
+	 *            the set of {@link Role}s assigned to this user
 	 * @param locale
+	 *            the user's {@link Locale}
 	 */
 	public UserRep(String userId, String username, String firstname, String surname, UserState userState,
 			Set<String> roles, Locale locale) {

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

@@ -14,11 +14,25 @@ import java.util.Collections;
 import java.util.HashSet;
 import java.util.Set;
 
+import ch.eitchnet.privilege.handler.PrivilegeHandler;
 import ch.eitchnet.privilege.model.PrivilegeRep;
+import ch.eitchnet.privilege.model.Restrictable;
+import ch.eitchnet.privilege.policy.PrivilegePolicy;
 
 /**
- * @author rvonburg
+ * <p>
+ * {@link Privilege} is the main model object for Privilege. A {@link Role} has a set of Privileges assigned to it which
+ * defines the privileges a logged in user with that role has. For every privilege a {@link PrivilegePolicy} is
+ * configured which is used to evaluate if privilege is granted to a {@link Restrictable}
+ * </p>
  * 
+ * <p>
+ * {@link Privilege}s have allow and deny rules which the configured {@link PrivilegeHandler} uses to
+ * </p>
+ * 
+ * <p>Note: This is an internal object which is not to be serialized or passed to clients, {@link PrivilegeRep}s are used for that</p>
+ * 
+ * @author rvonburg
  */
 public final class Privilege {
 
@@ -29,12 +43,19 @@ public final class Privilege {
 	private final Set<String> allowList;
 
 	/**
+	 * Default constructor
 	 * 
 	 * @param name
+	 *            the name of this privilege, which is unique to all privileges known in the {@link PrivilegeHandler}
 	 * @param policy
+	 *            the {@link PrivilegePolicy} configured to evaluate if the privilege is granted
 	 * @param allAllowed
+	 *            a boolean defining if a {@link Role} with this {@link Privilege} has unrestricted access to a
+	 *            {@link Restrictable}
 	 * @param denyList
+	 *            a list of deny rules for this {@link Privilege}
 	 * @param allowList
+	 *            a list of allow rules for this {@link Privilege}
 	 */
 	public Privilege(String name, String policy, boolean allAllowed, Set<String> denyList, Set<String> allowList) {
 		this.name = name;

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

@@ -17,8 +17,17 @@ import java.util.Set;
 import ch.eitchnet.privilege.model.RoleRep;
 
 /**
- * @author rvonburg
+ * <p>
+ * A {@link User} is assigned a set of roles. These roles have a set of privileges assigned to them by name and they
+ * define the privileges granted to a user with this role
+ * </p>
  * 
+ * <p>
+ * Note: This is an internal object which is not to be serialized or passed to clients, {@link RoleRep}s are used for
+ * that
+ * </p>
+ * 
+ * @author rvonburg
  */
 public final class Role {
 
@@ -26,9 +35,12 @@ public final class Role {
 	private final Set<String> privileges;
 
 	/**
+	 * Default constructor
 	 * 
 	 * @param name
+	 *            the name of the role
 	 * @param privileges
+	 *            a set of names of privileges granted to this role
 	 */
 	public Role(String name, Set<String> privileges) {
 		this.name = name;

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

@@ -10,9 +10,22 @@
 
 package ch.eitchnet.privilege.model.internal;
 
+import ch.eitchnet.privilege.handler.PrivilegeHandler;
+import ch.eitchnet.privilege.model.Certificate;
+
 /**
- * @author rvonburg
+ * <p>
+ * A {@link Session} is linked to currently logged in user. The {@link PrivilegeHandler} creates an instance of this
+ * class once a {@link User} has successfully logged in and keeps this object private but hands out a
+ * {@link Certificate} which the user must use every time a privilege needs to be granted
+ * </p>
  * 
+ * <p>
+ * Note: This is an internal object which is not to be serialized or passed to clients, the client must keep his
+ * {@link Certificate} which is used for accessing privileges
+ * </p>
+ * 
+ * @author rvonburg
  */
 public final class Session {
 
@@ -24,18 +37,32 @@ public final class Session {
 	private final String authPassword;
 
 	/**
+	 * Default constructor
+	 * 
+	 * <p>
+	 * Note, both the authentication token and password are private fields which are generated on login and only known
+	 * by the {@link PrivilegeHandler}
+	 * </p>
 	 * 
 	 * @param sessionId
-	 * @param authToken
-	 * @param authPassword
+	 *            the users session id
 	 * @param username
+	 *            the users login name
+	 * @param authToken
+	 *            the authentication token defining the users unique session and is a private field of this session. It
+	 *            corresponds with the authentication token on the {@link Certificate}
+	 * @param authPassword
+	 *            the password to access the authentication token, this is not known to the client but set by the
+	 *            {@link PrivilegeHandler} on authentication. It corresponds with the authentication password on the
+	 *            {@link Certificate}
 	 * @param loginTime
+	 *            the time the user logged in
 	 */
-	public Session(String sessionId, String authToken, String authPassword, String username, long loginTime) {
+	public Session(String sessionId, String username, String authToken, String authPassword, long loginTime) {
 		this.sessionId = sessionId;
+		this.username = username;
 		this.authToken = authToken;
 		this.authPassword = authPassword;
-		this.username = username;
 		this.loginTime = loginTime;
 	}
 

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

@@ -19,6 +19,14 @@ import ch.eitchnet.privilege.model.UserRep;
 import ch.eitchnet.privilege.model.UserState;
 
 /**
+ * This class defines the actual login information for a given user which can be granted privileges. Every user is
+ * granted a set of {@link Role}s and has a {@link UserState} including detail information like first name and surname
+ * 
+ * <p>
+ * Note: This is an internal object which is not to be serialized or passed to clients, {@link UserRep}s are used for
+ * that
+ * </p>
+ * 
  * @author rvonburg
  * 
  */
@@ -39,14 +47,24 @@ public final class User {
 	private final Locale locale;
 
 	/**
+	 * Default constructor
+	 * 
 	 * @param userId
+	 *            the user's id
 	 * @param username
+	 *            the user's login name
 	 * @param password
+	 *            the user's password (hashed)
 	 * @param firstname
+	 *            the user's first name
 	 * @param surname
+	 *            the user's surname
 	 * @param userState
+	 *            the user's {@link UserState}
 	 * @param roles
+	 *            the set of {@link Role}s assigned to this user
 	 * @param locale
+	 *            the user's {@link Locale}
 	 */
 	public User(String userId, String username, String password, String firstname, String surname, UserState userState,
 			Set<String> roles, Locale locale) {
@@ -125,6 +143,8 @@ public final class User {
 	 * Returns true if this user has the specified role
 	 * 
 	 * @param role
+	 *            the name of the {@link Role} to check for
+	 * 
 	 * @return true if the this user has the specified role
 	 */
 	public boolean hasRole(String role) {

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

@@ -16,8 +16,9 @@ import ch.eitchnet.privilege.model.internal.Privilege;
 import ch.eitchnet.privilege.model.internal.Role;
 
 /**
- * @author rvonburg
+ * XXX re-think this implementation...
  * 
+ * @author rvonburg
  */
 public class DefaultPrivilege implements PrivilegePolicy {
 

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

@@ -13,17 +13,32 @@ package ch.eitchnet.privilege.policy;
 import ch.eitchnet.privilege.model.Restrictable;
 import ch.eitchnet.privilege.model.internal.Privilege;
 import ch.eitchnet.privilege.model.internal.Role;
+import ch.eitchnet.privilege.model.internal.User;
 
 /**
- * @author rvonburg
+ * <p>
+ * {@link PrivilegePolicy} implements logic to determine if a {@link User} which has the given {@link Role} and the
+ * given {@link Privilege} has access to the given {@link Restrictable}
+ * </p>
  * 
+ * <p>
+ * Re-think this interface and especially the {@link #actionAllowed(Role, Privilege, Restrictable)}-method... maybe we
+ * need one with out the {@link Privilege} in its signature?
+ * </p>
+ * 
+ * @author rvonburg
  */
 public interface PrivilegePolicy {
 
 	/**
+	 * Checks if the given {@link Role} and the given {@link Privilege} has access to the given {@link Restrictable}
+	 * 
 	 * @param role
+	 *            the {@link Role} trying to access the {@link Restrictable}
 	 * @param privilege
+	 *            the {@link Privilege} to check with
 	 * @param restrictable
+	 *            the {@link Restrictable} to which the user wants access
 	 * 
 	 * @return return true if the action is allowed, false if not
 	 */