CCM NG:

- Some JavaDoc
- Added taglist-maven-plugin to reports for ccm-core


git-svn-id: https://svn.libreccm.org/ccm/ccm_ng@3554 8810af33-2d31-482b-a856-94f89814c4df

ccm-core/pom.xml

@@ -435,6 +435,11 @@
                 <artifactId>jdepend-maven-plugin</artifactId>
                 <version>2.0</version>
             </plugin>
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>taglist-maven-plugin</artifactId>
+                <version>2.4</version>
+            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-project-info-reports-plugin</artifactId>

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;

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)

ccm-core/src/main/java/org/libreccm/core/Group.java

@@ -41,6 +41,7 @@ import javax.xml.bind.annotation.XmlElementWrapper;
 import javax.xml.bind.annotation.XmlRootElement;
 
 /**
+ * A {@code Group} is collection of {@link User}s.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -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<Role> 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)

ccm-core/src/main/java/org/libreccm/core/GroupManager.java

@@ -23,6 +23,7 @@ import javax.inject.Inject;
 import javax.persistence.EntityManager;
 
 /**
+ * Provides methods for managing the members of a {@link Group}.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/core/GroupRepository.java

@@ -26,6 +26,8 @@ import javax.persistence.EntityManager;
 import javax.persistence.TypedQuery;
 
 /**
+ * A repository class for retrieving, storing and deleting {@link Group}s.
+ * 
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/core/MultipleMatchingUserException.java

@@ -19,6 +19,8 @@
 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 <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

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
+ * Represents a {@link Privilege} granted to a {@link Subject} on an 
- * all objects.
+ * {@link CcmObject} or all {@link CcmObjects}.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

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 <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -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 privilege The privilege. Can't be {@code null}.
-     * @param object    The object. Can be null.
+     * @param object    The object. Can be {@code null}.
-     * @param user      The user. Can't be 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}.

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;
 

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 <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -45,16 +51,16 @@ import javax.persistence.NamedQuery;
 @NamedQueries({
     @NamedQuery(name = "findRolesForName",
                 query = "SELECT r FROM Role r "
-                + "WHERE r.name = :roleName "
+                            + "WHERE r.name = :roleName "
-                + "ORDER BY r.name"),
+                            + "ORDER BY r.name"),
     @NamedQuery(name = "findRolesForSourceGroup",
                 query = "SELECT r FROM Role r "
-                + "WHERE r.sourceGroup = :sourceGroup "
+                            + "WHERE r.sourceGroup = :sourceGroup "
-                + "ORDER BY r.name"),
+                            + "ORDER BY r.name"),
     @NamedQuery(name = "findRolesForImplicitGroup",
                 query = "SELECT r FROM Role r "
-                + "WHERE r.implicitGroup = :implicitGroup "
+                            + "WHERE r.implicitGroup = :implicitGroup "
-                + "ORDER BY r.name")
+                            + "ORDER BY r.name")
 })
 @SuppressWarnings("PMD.ShortClassName") //Role is perfectly fine name.
 public class Role implements Serializable {

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];
 

ccm-core/src/main/java/org/libreccm/core/UserNotFoundException.java

@@ -20,6 +20,8 @@
 package org.libreccm.core;
 
 /**
+ * Thrown by several methods of the {@link UserManager} if a {@link User} can't
+ * be found.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/core/UserRepository.java

@@ -25,13 +25,14 @@ import javax.inject.Inject;
 import javax.persistence.TypedQuery;
 
 /**
+ * Provides methods for retrieving, storing and deleting {@link User} objects.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped
 public class UserRepository extends AbstractEntityRepository<Long, User> {
 
-   @Inject
+    @Inject
     private transient PrivilegeRepository privilegeRepository;
 
     @Override
@@ -58,7 +59,7 @@ public class UserRepository extends AbstractEntityRepository<Long, User> {
         systemUser.setScreenName("system");
 
         final Privilege adminPrivilege = privilegeRepository.retrievePrivilege(
-                "admin");
+            "admin");
         final Permission systemPermission = new Permission();
         systemPermission.setGrantee(systemUser);
         systemPermission.setGrantedPrivilege(adminPrivilege);
@@ -74,12 +75,20 @@ public class UserRepository extends AbstractEntityRepository<Long, User> {
      * {@code public-user}.
      *
      * @return The public user or {@code null} if there is no account for the
-     * public user.
+     *         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<User> query = getEntityManager().createNamedQuery(
             "findUserByScreenName", User.class);
@@ -97,6 +106,29 @@ public class UserRepository extends AbstractEntityRepository<Long, User> {
         }
     }
 
+    /**
+     * 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<User> query = getEntityManager().createNamedQuery(
             "findUserByEmailAddress", User.class);

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