diff --git a/ccm-core/pom.xml b/ccm-core/pom.xml index 3e15cb3dc..704b666a2 100644 --- a/ccm-core/pom.xml +++ b/ccm-core/pom.xml @@ -435,6 +435,11 @@ jdepend-maven-plugin 2.0 + + org.codehaus.mojo + taglist-maven-plugin + 2.4 + org.apache.maven.plugins maven-project-info-reports-plugin diff --git a/ccm-core/src/main/java/com/arsdigita/mail/MailConfig.java b/ccm-core/src/main/java/com/arsdigita/mail/MailConfig.java index 31152589c..cc6a76510 100755 --- a/ccm-core/src/main/java/com/arsdigita/mail/MailConfig.java +++ b/ccm-core/src/main/java/com/arsdigita/mail/MailConfig.java @@ -26,7 +26,6 @@ import com.arsdigita.util.parameter.ParameterError; import com.arsdigita.util.parameter.StringParameter; import com.arsdigita.util.parameter.URLParameter; import com.arsdigita.util.UncheckedWrapperException; -import com.arsdigita.web.Web; import java.io.IOException; import java.net.URL; diff --git a/ccm-core/src/main/java/org/libreccm/core/CcmObject.java b/ccm-core/src/main/java/org/libreccm/core/CcmObject.java index 5ee7a937c..3cdc6eb7e 100644 --- a/ccm-core/src/main/java/org/libreccm/core/CcmObject.java +++ b/ccm-core/src/main/java/org/libreccm/core/CcmObject.java @@ -89,6 +89,9 @@ public class CcmObject implements Serializable { @XmlElement(name = "display-name", namespace = CORE_XML_NS) private String displayName; + /** + * Permissions granted on this object. + */ @OneToMany(mappedBy = "object") @XmlElementWrapper(name = "permissions", namespace = CORE_XML_NS) @XmlElement(name = "permission", namespace = CORE_XML_NS) diff --git a/ccm-core/src/main/java/org/libreccm/core/Group.java b/ccm-core/src/main/java/org/libreccm/core/Group.java index 67baacf8d..cd13844bb 100644 --- a/ccm-core/src/main/java/org/libreccm/core/Group.java +++ b/ccm-core/src/main/java/org/libreccm/core/Group.java @@ -41,7 +41,8 @@ import javax.xml.bind.annotation.XmlElementWrapper; import javax.xml.bind.annotation.XmlRootElement; /** - * + * A {@code Group} is collection of {@link User}s. + * * @author Jens Pelzetter */ @Entity @@ -55,16 +56,26 @@ public class Group extends Subject implements Serializable { private static final long serialVersionUID = -5555063356689597270L; + /** + * The name of the {@code Group}. Must be unique. + */ @Column(name = "name", length = 512, unique = true, nullable = false) @NotBlank @XmlElement(name = "name", namespace = CORE_XML_NS) private String name; + /** + * The {@link Role}s assigned to the {@code Group}. + */ @OneToMany(mappedBy = "sourceGroup") @XmlElementWrapper(name = "roles", namespace = CORE_XML_NS) @XmlElement(name ="role", namespace = CORE_XML_NS) private List roles; + /** + * The members of the group. For adding or removing members the methods + * provided by the {@link GroupManager} should be used. + */ @OneToMany(mappedBy = "group") @XmlElementWrapper(name = "group-memberships", namespace = CORE_XML_NS) @XmlElement(name = "group-membership", namespace = CORE_XML_NS) diff --git a/ccm-core/src/main/java/org/libreccm/core/GroupManager.java b/ccm-core/src/main/java/org/libreccm/core/GroupManager.java index 02bcdb77f..2e110556b 100644 --- a/ccm-core/src/main/java/org/libreccm/core/GroupManager.java +++ b/ccm-core/src/main/java/org/libreccm/core/GroupManager.java @@ -23,7 +23,8 @@ import javax.inject.Inject; import javax.persistence.EntityManager; /** - * + * Provides methods for managing the members of a {@link Group}. + * * @author Jens Pelzetter */ @RequestScoped diff --git a/ccm-core/src/main/java/org/libreccm/core/GroupRepository.java b/ccm-core/src/main/java/org/libreccm/core/GroupRepository.java index 7314ed84c..923ed56be 100644 --- a/ccm-core/src/main/java/org/libreccm/core/GroupRepository.java +++ b/ccm-core/src/main/java/org/libreccm/core/GroupRepository.java @@ -26,7 +26,9 @@ import javax.persistence.EntityManager; import javax.persistence.TypedQuery; /** - * + * A repository class for retrieving, storing and deleting {@link Group}s. + * + * * @author Jens Pelzetter */ @RequestScoped diff --git a/ccm-core/src/main/java/org/libreccm/core/MultipleMatchingUserException.java b/ccm-core/src/main/java/org/libreccm/core/MultipleMatchingUserException.java index 24864f05f..44d143caa 100644 --- a/ccm-core/src/main/java/org/libreccm/core/MultipleMatchingUserException.java +++ b/ccm-core/src/main/java/org/libreccm/core/MultipleMatchingUserException.java @@ -19,7 +19,9 @@ package org.libreccm.core; /** - * + * Thrown by {@link UserRepository#findByEmailAddress(java.lang.String)} if + * there is more than one user with the same email address. + * * @author Jens Pelzetter */ class MultipleMatchingUserException extends RuntimeException { diff --git a/ccm-core/src/main/java/org/libreccm/core/Permission.java b/ccm-core/src/main/java/org/libreccm/core/Permission.java index 652fe6b30..01f774c95 100644 --- a/ccm-core/src/main/java/org/libreccm/core/Permission.java +++ b/ccm-core/src/main/java/org/libreccm/core/Permission.java @@ -41,8 +41,8 @@ import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; /** - * Represents a {@link Privilege} granted to a {@link Subject} on an object or - * all objects. + * Represents a {@link Privilege} granted to a {@link Subject} on an + * {@link CcmObject} or all {@link CcmObjects}. * * @author Jens Pelzetter */ diff --git a/ccm-core/src/main/java/org/libreccm/core/PermissionManager.java b/ccm-core/src/main/java/org/libreccm/core/PermissionManager.java index 64f311cde..198d5d2c5 100644 --- a/ccm-core/src/main/java/org/libreccm/core/PermissionManager.java +++ b/ccm-core/src/main/java/org/libreccm/core/PermissionManager.java @@ -24,6 +24,7 @@ import javax.enterprise.context.RequestScoped; import javax.inject.Inject; /** + * This class provides methods for managing {@link Permissions}. * * @author Jens Pelzetter */ @@ -162,7 +163,7 @@ public class PermissionManager { if (publicUser == null) { - //If the public user is not available an null value for the + //If the public user is not available an null value for the //subject parameter is an illegal argument. throw new IllegalArgumentException( "Illegal value 'null' provided for parameter privilege"); @@ -192,9 +193,9 @@ public class PermissionManager { * the provided {@code object} is {@code null} the method will only check * for wildcard permission (permissions for all objects). * - * @param privilege The privilege. Can't be null. - * @param object The object. Can be null. - * @param user The user. Can't be null. + * @param privilege The privilege. Can't be {@code null}. + * @param object The object. Can be {@code null}. + * @param user The user. Can be {@code null}. * * @return {@code true} if the provided {@code user} has a permission * granting the provided privilege for the provided object, @@ -252,6 +253,28 @@ public class PermissionManager { return result; } + /** + * Checks if a {@link Group} is granted a {@link Privilege} on a + * {@link CcmObject} or on all {@link CcmObject}s. + * + * As for + * {@link #isPermitted(org.libreccm.core.Privilege, org.libreccm.core.CcmObject, org.libreccm.core.User)}, + * this method also checks if the {@code admin} privilege was granted to the + * group for the provided {@code object} or for all objects. + * + * @param privilege The privilege. Can't be {@code null}. + * @param object The object. Can be {@code null}. + * @param group The group. Can't be {@code null}. + * + * @return {@code true} if the group has a permission granting the provided + * {@code privilege} on the the provided {@code object} (or on all + * objects), {@code false} of not. + * + * @see #isPermitted(org.libreccm.core.Privilege, + * org.libreccm.core.CcmObject, org.libreccm.core.Subject) + * @see #isPermitted(org.libreccm.core.Privilege, + * org.libreccm.core.CcmObject, org.libreccm.core.User) + */ public boolean isPermitted(final Privilege privilege, final CcmObject object, final Group group) { @@ -306,6 +329,11 @@ public class PermissionManager { * the public user from the database. If there is no public user the method * will return {@code false}. * + * Internally this methods calls + * {@link #isPermitted(org.libreccm.core.Privilege, org.libreccm.core.CcmObject, org.libreccm.core.Subject)} + * and throws an {@link UnauthorizedAcccessException} if the return value is + * {@code null}. + * * @param privilege The privilege to check. Can't be {@code null}. * @param object The object on which the privilege is granted. Can't be * {@code null}. diff --git a/ccm-core/src/main/java/org/libreccm/core/Privilege.java b/ccm-core/src/main/java/org/libreccm/core/Privilege.java index 8919bc5e7..d47ceb6ea 100644 --- a/ccm-core/src/main/java/org/libreccm/core/Privilege.java +++ b/ccm-core/src/main/java/org/libreccm/core/Privilege.java @@ -63,17 +63,25 @@ public class Privilege implements Serializable { private static final long serialVersionUID = -3986038536996049440L; - //Constant for the admin privilege. + /** + * Constant for the {@code admin} privilege because this privilege is used + * very often. + */ public static final String ADMIN = "admin"; + /** + * ID for the privilege. + */ @Id @Column(name = "privilege_id") @GeneratedValue(strategy = GenerationType.AUTO) @XmlElement(name = "privilege-id", namespace = CORE_XML_NS) private long privilegeId; - @Column(name = "label", length = 255, nullable = false) - //Field is named like this in the old PDL class, don't want to change it now + /** + * The label of the {@code Privilege}. + */ + @Column(name = "label", length = 255, nullable = false, unique = true) @XmlElement(name = "label", namespace = CORE_XML_NS) private String label; diff --git a/ccm-core/src/main/java/org/libreccm/core/Role.java b/ccm-core/src/main/java/org/libreccm/core/Role.java index 776fead11..3060649ad 100644 --- a/ccm-core/src/main/java/org/libreccm/core/Role.java +++ b/ccm-core/src/main/java/org/libreccm/core/Role.java @@ -37,6 +37,12 @@ import javax.persistence.NamedQueries; import javax.persistence.NamedQuery; /** + * A role can be assigned to a group. This class was migrated from the old CCM + * code (com.arsdigita.kernel.Role}. Obviously it does not more than to provide + * an named association between to groups. + * + * @todo Check if this class can be removed or refactored to make the whole + * system of users, groups and permissions simpler. * * @author Jens Pelzetter */ @@ -45,16 +51,16 @@ import javax.persistence.NamedQuery; @NamedQueries({ @NamedQuery(name = "findRolesForName", query = "SELECT r FROM Role r " - + "WHERE r.name = :roleName " - + "ORDER BY r.name"), + + "WHERE r.name = :roleName " + + "ORDER BY r.name"), @NamedQuery(name = "findRolesForSourceGroup", query = "SELECT r FROM Role r " - + "WHERE r.sourceGroup = :sourceGroup " - + "ORDER BY r.name"), + + "WHERE r.sourceGroup = :sourceGroup " + + "ORDER BY r.name"), @NamedQuery(name = "findRolesForImplicitGroup", query = "SELECT r FROM Role r " - + "WHERE r.implicitGroup = :implicitGroup " - + "ORDER BY r.name") + + "WHERE r.implicitGroup = :implicitGroup " + + "ORDER BY r.name") }) @SuppressWarnings("PMD.ShortClassName") //Role is perfectly fine name. public class Role implements Serializable { diff --git a/ccm-core/src/main/java/org/libreccm/core/UserManager.java b/ccm-core/src/main/java/org/libreccm/core/UserManager.java index b8e27b639..aaf3a47fa 100644 --- a/ccm-core/src/main/java/org/libreccm/core/UserManager.java +++ b/ccm-core/src/main/java/org/libreccm/core/UserManager.java @@ -18,7 +18,6 @@ */ package org.libreccm.core; - import org.apache.commons.codec.binary.Base64; import java.nio.charset.StandardCharsets; @@ -46,6 +45,14 @@ public class UserManager { @Inject private transient UserRepository userRepository; + /** + * Helper method for generating an password hash. + * + * @param password The password to hash. + * @param salt The salt to append. + * + * @return The password hash. + */ private byte[] generateHash(final byte[] password, final byte[] salt) { final byte[] saltedPassword = new byte[password.length + salt.length]; diff --git a/ccm-core/src/main/java/org/libreccm/core/UserNotFoundException.java b/ccm-core/src/main/java/org/libreccm/core/UserNotFoundException.java index 6aa986d47..6b23534e2 100644 --- a/ccm-core/src/main/java/org/libreccm/core/UserNotFoundException.java +++ b/ccm-core/src/main/java/org/libreccm/core/UserNotFoundException.java @@ -20,7 +20,9 @@ package org.libreccm.core; /** - * + * Thrown by several methods of the {@link UserManager} if a {@link User} can't + * be found. + * * @author Jens Pelzetter */ public class UserNotFoundException extends Exception { diff --git a/ccm-core/src/main/java/org/libreccm/core/UserRepository.java b/ccm-core/src/main/java/org/libreccm/core/UserRepository.java index 0159ed425..04761bcbf 100644 --- a/ccm-core/src/main/java/org/libreccm/core/UserRepository.java +++ b/ccm-core/src/main/java/org/libreccm/core/UserRepository.java @@ -25,15 +25,16 @@ import javax.inject.Inject; import javax.persistence.TypedQuery; /** + * Provides methods for retrieving, storing and deleting {@link User} objects. * * @author Jens Pelzetter */ @RequestScoped public class UserRepository extends AbstractEntityRepository { - @Inject + @Inject private transient PrivilegeRepository privilegeRepository; - + @Override public Class getEntityClass() { return User.class; @@ -56,14 +57,14 @@ public class UserRepository extends AbstractEntityRepository { public User retrieveSystemUser() { final User systemUser = new User(); systemUser.setScreenName("system"); - + final Privilege adminPrivilege = privilegeRepository.retrievePrivilege( - "admin"); + "admin"); final Permission systemPermission = new Permission(); systemPermission.setGrantee(systemUser); systemPermission.setGrantedPrivilege(adminPrivilege); systemUser.addGrantedPermission(systemPermission); - + return systemUser; } @@ -73,13 +74,21 @@ public class UserRepository extends AbstractEntityRepository { * ordinary user account in the database with the screen name * {@code public-user}. * - * @return The public user or {@code null} if there is no account for the - * public user. + * @return The public user or {@code null} if there is no account for the + * public user. */ public User retrievePublicUser() { return findByScreenName("public-user"); } + /** + * Retrieve a user by its screen name. + * + * @param screenname The {@code screename} of the user. + * + * @return The user identified by the provided {@code screenname} if there + * is such a user, {@code null} if not. + */ public User findByScreenName(final String screenname) { final TypedQuery query = getEntityManager().createNamedQuery( "findUserByScreenName", User.class); @@ -97,6 +106,29 @@ public class UserRepository extends AbstractEntityRepository { } } + /** + * Finds a user by one of the email addresses assigned to the user. + * + * @param emailAddress The email address of the user. + * + * @return The user identified by the provided email address if there is + * such a user, {@code null} otherwise. + * + * @throws MultipleMatchingUserException Because the email addresses are + * represented by an embedded entity + * (see {@link User} and + * {@link EmailAddress}) it is not + * possible to enforce uniqueness on + * the database level. Therefore this + * method deals with the case that + * there is more than on matching user + * and throws an (unchecked) exception + * if this is the case. However if + * this the case something very + * strange has happened and the + * database should be checked + * carefully. + */ public User findByEmailAddress(final String emailAddress) { final TypedQuery query = getEntityManager().createNamedQuery( "findUserByEmailAddress", User.class); diff --git a/ccm-core/src/test/java/org/libreccm/core/PermissionManagerTest.java b/ccm-core/src/test/java/org/libreccm/core/PermissionManagerTest.java index 88af98c14..ce4aee3a6 100644 --- a/ccm-core/src/test/java/org/libreccm/core/PermissionManagerTest.java +++ b/ccm-core/src/test/java/org/libreccm/core/PermissionManagerTest.java @@ -109,11 +109,6 @@ public class PermissionManagerTest { public void tearDown() { } - // TODO add test methods here. - // The methods must be annotated with annotation @Test. For example: - // - // @Test - // public void hello() {} @Deployment public static WebArchive createDeployment() { final PomEquippedResolveStage pom = Maven