Some JavaDoc

ccm-cms/src/main/java/org/librecms/ui/contentsections/AbstractCurrentUserPermissions.java

@@ -15,17 +15,36 @@ import java.util.stream.Collectors;
 import javax.inject.Inject;
 
 /**
+ * A helper class to build {@link GrantedPrivilegeModel} for a specific category
+ * of privileges granted to the current user.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 abstract class AbstractCurrentUserPermissions {
 
+    /**
+     * CDI managed {@link PermissionChecker} instance used to check the
+     * permissions of the current user.
+     */
     @Inject
     private PermissionChecker permissionChecker;
 
+    /**
+     * CDI managed {@link PermissionManager} instance used to enumerate the
+     * permission constants in the class provided by
+     * {@link #getPrivilegesClass()}.
+     */
     @Inject
     private PermissionManager permissionManager;
 
+    /**
+     * Builds a list of {@link GrantedPrivilegeModel}s for the current user and
+     * the privileges returned by {@link #getPrivilegesClass() }.
+     *
+     * @param folder The folder for which the permissions are checked.
+     *
+     * @return A list of {@link GrantedPrivilegeModel} instances.
+     */
     public List<GrantedPrivilegeModel> buildCurrentUserPermissions(
         final Folder folder
     ) {
@@ -36,8 +55,22 @@ abstract class AbstractCurrentUserPermissions {
             .collect(Collectors.toList());
     }
 
+    /**
+     * Provides the class with privilege constants to use.
+     *
+     * @return The class with privilege constants to use.
+     */
     protected abstract Class<?> getPrivilegesClass();
 
+    /**
+     * Build a {@link GrantedPrivilegeModel} for a folder and a privilege.
+     *
+     * @param folder    The folder to use.
+     * @param privilege The privilege.
+     *
+     * @return A {@link GrantedPrivilegeModel} for the current user, the
+     *         provided folder and the provided privilege.
+     */
     private GrantedPrivilegeModel buildCurrentUserPermission(
         final Folder folder, final String privilege
     ) {

ccm-cms/src/main/java/org/librecms/ui/contentsections/AbstractFolderTree.java

@@ -16,14 +16,26 @@ import javax.inject.Inject;
 import javax.transaction.Transactional;
 
 /**
+ * Abstract base class for building folder trees.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 abstract class AbstractFolderTree<T extends FolderTreeNode<T, P>, P extends PermissionsModel> {
 
+    /**
+     * {@link FolderManager} instance to work the the folders.
+     */
     @Inject
     private FolderManager folderManager;
 
+    /**
+     * Builds the subfolder tree for a folder and the content section.
+     *
+     * @param section       The content section to which the folder belongs.
+     * @param currentFolder The current folder.
+     *
+     * @return A list of {@link FolderTreeNode}s representing the folder tree.
+     */
     @Transactional(Transactional.TxType.REQUIRED)
     public List<T> buildFolderTree(
         final ContentSection section, final Folder currentFolder
@@ -48,14 +60,42 @@ abstract class AbstractFolderTree<T extends FolderTreeNode<T, P>, P extends Perm
             ).collect(Collectors.toList());
     }
 
+    /**
+     * Creates a new {@link FolderTreeNode}.
+     *
+     * @return A new {@link FolderTreeNode}.
+     */
     protected abstract T newFolderTreeNode();
 
+    /**
+     * Retrieves the root folder of the current content section.
+     *
+     * @param section The content section.
+     *
+     * @return The root folder of the current content section.
+     */
     @Transactional(Transactional.TxType.REQUIRED)
     protected abstract Folder getRootFolder(final ContentSection section);
 
+    /**
+     * Builds the permissions model for a folder.
+     *
+     * @param folder The folder.
+     *
+     * @return The permissions model.
+     */
     @Transactional(Transactional.TxType.REQUIRED)
     protected abstract P buildPermissionsModel(final Folder folder);
 
+    /**
+     * Helper method for building a folder tree.
+     *
+     * @param section           The content section to which the folder belongs.
+     * @param currentFolderPath The path of the current folder.
+     * @param folder            The folder for which the node is build.
+     *
+     * @return A {@link FolderTreeNode} for the provided {@code folder}.
+     */
     private T buildFolderTreeNode(
         final ContentSection section,
         final String currentFolderPath,
@@ -93,6 +133,13 @@ abstract class AbstractFolderTree<T extends FolderTreeNode<T, P>, P extends Perm
         return node;
     }
 
+    /**
+     * Compare function for ordering folder by their name.
+     * 
+     * @param folder1 First folder to compare.
+     * @param folder2 Second folder to compare.
+     * @return The result of comparing the names of the two folders.
+     */
     private int compareFolders(final Folder folder1, final Folder folder2) {
         return folder1.getName().compareTo(folder2.getName());
     }

ccm-cms/src/main/java/org/librecms/ui/contentsections/AbstractGrantedPrivileges.java

@@ -18,17 +18,33 @@ import java.util.stream.Collectors;
 import javax.inject.Inject;
 
 /**
+ * Abstract builder for {@link PrivilegesGrantedToRoleModel} instances.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 abstract class AbstractGrantedPrivileges {
 
+    /**
+     * {@link PermissionChecker} instance used.
+     */
     @Inject
     private PermissionChecker permissionChecker;
 
+    /**
+     * {@link PermissionManager} instance used.
+     */
     @Inject
     private PermissionManager permissionManager;
 
+    /**
+     * Build a permissions matrix for the provided folder.
+     *
+     * @param section The content section to which the folder belongs.
+     * @param folder  The folder.
+     *
+     * @return A list of {@link PrivilegesGrantedToRoleModel} (the rows and
+     *         columns of the matrix).
+     */
     public List<PrivilegesGrantedToRoleModel> buildPermissionsMatrix(
         final ContentSection section, final Folder folder
     ) {
@@ -39,6 +55,22 @@ abstract class AbstractGrantedPrivileges {
             .collect(Collectors.toList());
     }
 
+    /**
+     * Provides the privileges class to use.
+     *
+     * @return The class containing the constants for the privileges to use.
+     */
+    protected abstract Class<?> getPrivilegesClass();
+
+    /**
+     * Helper method for building a {@link PrivilegesGrantedToRoleModel}.
+     *
+     * @param role   The role for which the model is build.
+     * @param folder The folder for which the model is build.
+     *
+     * @return A {@link PrivilegesGrantedToRoleModel} for the {@code role} and
+     *         the {@code folder}.
+     */
     private PrivilegesGrantedToRoleModel buildPrivilegesGrantedToRoleModel(
         final Role role, final Folder folder
     ) {
@@ -65,6 +97,16 @@ abstract class AbstractGrantedPrivileges {
         return model;
     }
 
+    /**
+     * Helper method for building a {@link GrantedPrivilegeModel}.
+     *
+     * @param role        The role for which the model is build.
+     * @param folder      The folder for which the model is build.
+     * @param privilege   The privilege for which the model is build.
+     * @param permissions The permissions to use for building the model.
+     *
+     * @return A {@link GrantedPrivilegeModel} for the provided parameters.
+     */
     private GrantedPrivilegeModel buildGrantedPrivilegeModel(
         final Role role,
         final Folder folder,
@@ -90,6 +132,4 @@ abstract class AbstractGrantedPrivileges {
         return model;
     }
 
-    protected abstract Class<?> getPrivilegesClass();
-    
 }

ccm-cms/src/main/java/org/librecms/ui/contentsections/AdminPermissionsChecker.java

@@ -13,39 +13,100 @@ import javax.enterprise.context.RequestScoped;
 import javax.inject.Inject;
 
 /**
+ * A helper for checking if the current user has a permission granting certain
+ * privileges.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped
 public class AdminPermissionsChecker {
 
+    /**
+     * The {@link PermissionChecker} instance to use.
+     */
     @Inject
     private PermissionChecker permissionChecker;
 
+    /**
+     * Checks of the the {@link AdminPrivileges#ADMINISTER_CATEGORIES} privilege
+     * has been granted to the current user.
+     *
+     * @param section The {@link ContentSection} one which the privilege might
+     *                has been granted.
+     *
+     * @return {@code true} if the {@link AdminPrivileges#ADMINISTER_CATEGORIES}
+     *         privilege has been granted to the current user for the provided
+     *         {@link ContentSection}, otherwise {@code false}.
+     */
     public boolean canAdministerCategories(final ContentSection section) {
         return permissionChecker.isPermitted(
             AdminPrivileges.ADMINISTER_CATEGORIES, section
         );
     }
 
+    /**
+     * Checks of the the {@link AdminPrivileges#ADMINISTER_CONTENT_TYPES}
+     * privilege has been granted to the current user.
+     *
+     * @param section The {@link ContentSection} one which the privilege might
+     *                has been granted.
+     *
+     * @return {@code true} if the
+     *         {@link AdminPrivileges#ADMINISTER_CONTENT_TYPES} privilege has
+     *         been granted to the current user for the provided
+     *         {@link ContentSection}, otherwise {@code false}.
+     */
     public boolean canAdministerContentTypes(final ContentSection section) {
         return permissionChecker.isPermitted(
             AdminPrivileges.ADMINISTER_CONTENT_TYPES, section
         );
     }
 
+    /**
+     * Checks of the the {@link AdminPrivileges#ADMINISTER_LIFECYLES} privilege
+     * has been granted to the current user.
+     *
+     * @param section The {@link ContentSection} one which the privilege might
+     *                has been granted.
+     *
+     * @return {@code true} if the {@link AdminPrivileges#ADMINISTER_LIFECYLES}
+     *         privilege has been granted to the current user for the provided
+     *         {@link ContentSection}, otherwise {@code false}.
+     */
     public boolean canAdministerLifecycles(final ContentSection section) {
         return permissionChecker.isPermitted(
             AdminPrivileges.ADMINISTER_LIFECYLES, section
         );
     }
 
+    /**
+     * Checks of the the {@link AdminPrivileges#ADMINISTER_ROLES} privilege has
+     * been granted to the current user.
+     *
+     * @param section The {@link ContentSection} one which the privilege might
+     *                has been granted.
+     *
+     * @return {@code true} if the {@link AdminPrivileges#ADMINISTER_ROLES}
+     *         privilege has been granted to the current user for the provided
+     *         {@link ContentSection}, otherwise {@code false}.
+     */
     public boolean canAdministerRoles(final ContentSection section) {
         return permissionChecker.isPermitted(
             AdminPrivileges.ADMINISTER_ROLES, section
         );
     }
 
+    /**
+     * Checks of the the {@link AdminPrivileges#ADMINISTER_WORKFLOWS} privilege
+     * has been granted to the current user.
+     *
+     * @param section The {@link ContentSection} one which the privilege might
+     *                has been granted.
+     *
+     * @return {@code true} if the {@link AdminPrivileges#ADMINISTER_WORKFLOWS}
+     *         privilege has been granted to the current user for the provided
+     *         {@link ContentSection}, otherwise {@code false}.
+     */
     public boolean canAdministerWorkflows(final ContentSection section) {
         return permissionChecker.isPermitted(
             AdminPrivileges.ADMINISTER_WORKFLOWS, section

ccm-cms/src/main/java/org/librecms/ui/contentsections/AssetFolderController.java

@@ -6,6 +6,7 @@
 package org.librecms.ui.contentsections;
 
 import org.libreccm.l10n.GlobalizationHelper;
+import org.libreccm.l10n.LocalizedString;
 import org.libreccm.security.AuthorizationRequired;
 import org.libreccm.security.PermissionManager;
 import org.libreccm.security.Role;
@@ -43,6 +44,7 @@ import javax.ws.rs.PathParam;
 import javax.ws.rs.QueryParam;
 
 /**
+ * Controller for managing the asset folders of a content section.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -51,54 +53,117 @@ import javax.ws.rs.QueryParam;
 @Path("/{sectionIdentifier}/assetfolders")
 public class AssetFolderController {
 
+    /**
+     * The {@link AssetFolderModel} stores information about the current asset
+     * folder for the view.
+     */
     @Inject
     private AssetFolderModel assetFolderModel;
 
+    /**
+     * The {@link AssetFolderTree} stores information about the current asset
+     * folder for the view.
+     */
     @Inject
     private AssetFolderTree assetFolderTree;
 
+    /**
+     * Used to build the {@link AssetPermissionsModel}.
+     */
     @Inject
     private AssetPermissionsModelProvider assetPermissions;
 
+    /**
+     * A special permissions checker for {@link Asset}s.
+     */
     @Inject
     private AssetPermissionsChecker assetPermissionsChecker;
 
+    /**
+     * {@link AssetManager} for performing operations on {@link Asset}s.
+     */
     @Inject
     private AssetManager assetManager;
 
+    /**
+     * {@link AssetRepository} for storing and retrieving {@link Asset}s.
+     */
     @Inject
     private AssetRepository assetRepo;
 
+    /**
+     * Stores information about the currnet {@link ContentSection} for the view.
+     */
     @Inject
     private ContentSectionModel contentSectionModel;
 
+    /**
+     * Provides several services.
+     */
     @Inject
     private ContentSectionsUi sectionsUi;
 
+    /**
+     * Provides information about the permissions of a user for {@link Asset}s.
+     */
     @Inject
     private CurrentUserAssetPermissions currentUserPermissions;
 
+    /**
+     * Performs operations on folders.
+     */
     @Inject
     private FolderManager folderManager;
 
+    /**
+     * Stores and retrieves {@link Folder}s.
+     */
     @Inject
     private FolderRepository folderRepo;
 
+    /**
+     * A helper for working with {@link LocalizedString}s.
+     */
     @Inject
     private GlobalizationHelper globalizationHelper;
 
+    /**
+     * Helper for getting the privileges for the current user for an
+     * {@link Asset}.
+     */
     @Inject
     private GrantedAssetPrivileges grantedPrivileges;
 
+    /**
+     * MVC {@link Models} instance. Used to store data for the view which is not
+     * provided by a model class.
+     */
     @Inject
     private Models models;
 
+    /**
+     * Performs operations on permissions.
+     */
     @Inject
     private PermissionManager permissionManager;
 
+    /**
+     * Used to retrieve roles.
+     */
     @Inject
     private RoleRepository roleRepo;
 
+    /**
+     * Lists the assets and subfolders in the
+     * {@link ContentSection#rootAssetsFolder}.
+     *
+     * @param sectionIdentifier The identifier for the content section.
+     * @param filterTerm        An optional filter term.
+     * @param firstResult       The index of the first result to show.
+     * @param maxResults        The maximum number of results to show.
+     *
+     * @return The template to use for generating the view.
+     */
     @GET
     @Path("/")
     @AuthorizationRequired
@@ -114,6 +179,17 @@ public class AssetFolderController {
         );
     }
 
+    /**
+     * Lists the assets and subfolders in an assets folder.
+     *
+     * @param sectionIdentifier The identifier for the content section.
+     * @param folderPath        The path of the folder.
+     * @param filterTerm        An optional filter term.
+     * @param firstResult       The index of the first result to show.
+     * @param maxResults        The maximum number of results to show.
+     *
+     * @return The template to use for generating the view.
+     */
     @GET
     @Path("/{folderPath:(.+)?}")
     @AuthorizationRequired
@@ -204,6 +280,14 @@ public class AssetFolderController {
         return "org/librecms/ui/contentsection/assetfolder/assetfolder.xhtml";
     }
 
+    /**
+     * Creates a new subfolder in the {@link ContentSection#rootAssetsFolder}.
+     *
+     * @param sectionIdentifier The identifier for the content section.
+     * @param folderName        The name of the new folder.
+     *
+     * @return A redirect for showing the to the listing of the root folder.
+     */
     @POST
     @Path("/")
     @AuthorizationRequired
@@ -217,6 +301,15 @@ public class AssetFolderController {
         );
     }
 
+    /**
+     * Creates a new subfolder in the {@link ContentSection#rootAssetsFolder}.
+     *
+     * @param sectionIdentifier The identifier for the content section.
+     * @param parentFolderPath  Path of the parent folder of the new folder.
+     * @param folderName        The name of the new folder.
+     *
+     * @return A redirect for showing the to the listing of the parent folder.
+     */
     @POST
     @Path("/{parentFolderPath:(.+)?}")
     @AuthorizationRequired
@@ -275,6 +368,17 @@ public class AssetFolderController {
         );
     }
 
+    /**
+     * Update the permissions of a role for the
+     * {@link ContentSection#rootAssetsFolder}.
+     *
+     * @param sectionIdentifier The identifier for the content section.
+     * @param roleParam         The name of the role.
+     * @param permissions       The new permissions of the role for the root
+     *                          assets folder.
+     *
+     * @return A redirect to the listing of the root assets folder.
+     */
     @POST
     @Path("/@permissions/{role}/")
     @AuthorizationRequired
@@ -289,6 +393,17 @@ public class AssetFolderController {
         );
     }
 
+    /**
+     * Update the permissions of a role for a folder.
+     *
+     * @param sectionIdentifier The identifier for the content section.
+     * @param folderPath        The path of the folder.
+     * @param roleParam         The name of the role.
+     * @param permissions       The new permissions of the role for the assets
+     *                          folder.
+     *
+     * @return A redirect to the listing of the assets folder.
+     */
     @POST
     @Path("/@permissions/{role}/{folderPath:(.+)?}")
     @AuthorizationRequired
@@ -374,6 +489,15 @@ public class AssetFolderController {
         );
     }
 
+    /**
+     * Renames a folder.
+     *
+     * @param sectionIdentifier The identifier for the content section.
+     * @param folderPath        The path of the folder.
+     * @param folderName        The new name of the folder.
+     *
+     * @return A redirect to the listing of the assets folder.
+     */
     @POST
     @Path("/@rename/{folderPath:(.+)?}")
     @AuthorizationRequired
@@ -435,6 +559,15 @@ public class AssetFolderController {
         );
     }
 
+    /**
+     * Helper method for showing a error message if there is not folder for the
+     * provided path.
+     *
+     * @param section    The current {@link ContentSection}.
+     * @param folderPath The requested folder path.
+     *
+     * @return The error message view.
+     */
     private String showAssetFolderNotFound(
         final ContentSection section, final String folderPath
     ) {
@@ -443,6 +576,13 @@ public class AssetFolderController {
         return "org/librecms/ui/contentsection/assetfolder/asssetfolder-not-found.xhtml";
     }
 
+    /**
+     * Helper methods for building the breadcrumbs.
+     *
+     * @param folderPath The path of the current folder.
+     *
+     * @return The {@link FolderBreadcrumbsModel} for the path of the folder.
+     */
     private List<FolderBreadcrumbsModel> buildBreadcrumbs(
         final String folderPath
     ) {
@@ -469,6 +609,15 @@ public class AssetFolderController {
         return breadcrumbs;
     }
 
+    /**
+     * Helper method for building the {@link AssetFolderRowModel} for a
+     * subfolder.
+     *
+     * @param section The current content section.
+     * @param entry   The entry to process.
+     *
+     * @return A {@link AssetFolderRowModel} for hte provided entry.
+     */
     private AssetFolderRowModel buildRowModel(
         final ContentSection section, final AssetFolderEntry entry
     ) {