JavaDoc for the admin UI (general UI classes, general classes for admin UI, users management)

ccm-core/src/main/java/org/libreccm/ui/IsAuthenticatedFilter.java

@@ -31,6 +31,8 @@ import javax.ws.rs.container.PreMatching;
 import javax.ws.rs.core.Response;
 
 /**
+ * Filter for securing EE MVC UIs. Checks if the current user is authenticated.
+ * If not the user is redirected to the login application.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/ui/Message.java

@@ -19,13 +19,20 @@
 package org.libreccm.ui;
 
 /**
+ * Stores a message to be displayed in the UI.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 public class Message {
 
+    /**
+     * The message (or the translation key for the message).
+     */
     private final String message;
 
+    /**
+     * The type of the message.
+     */
     private final MessageType messageType;
 
     public Message(String message, MessageType messageType) {

ccm-core/src/main/java/org/libreccm/ui/MessageType.java

@@ -19,6 +19,8 @@
 package org.libreccm.ui;
 
 /**
+ * Possible message types. The types are equivalent to the contextual classes
+ * of the Bootstrap framework.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/ui/MvcLocaleResolver.java

@@ -28,6 +28,8 @@ import javax.mvc.locale.LocaleResolver;
 import javax.mvc.locale.LocaleResolverContext;
 
 /**
+ * A locale resolver implementation that simply passes the locale negoiated by
+ * LibreCCM to Jakarta EE MVC.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/ui/admin/AdminApplication.java

@@ -30,12 +30,17 @@ import javax.ws.rs.ApplicationPath;
 import javax.ws.rs.core.Application;
 
 /**
+ * Collects the controllers for the admin application and registers them with
+ * JAX-RS.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @ApplicationPath("/@admin")
 public class AdminApplication extends Application {
 
+    /**
+     * Injection point for the admin pages.
+     */
     @Inject
     private Instance<AdminPage> adminPages;
 

ccm-core/src/main/java/org/libreccm/ui/admin/AdminConstants.java

@@ -19,6 +19,7 @@
 package org.libreccm.ui.admin;
 
 /**
+ * Some constants for the admin application
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -28,6 +29,9 @@ public class AdminConstants {
         // Nothing
     }
     
+    /**
+     * Bundle that provides the translations for the admin application.
+     */
     public static final String ADMIN_BUNDLE = "org.libreccm.ui.AdminBundle";
     
     

ccm-core/src/main/java/org/libreccm/ui/admin/AdminMessages.java

@@ -33,6 +33,18 @@ import javax.inject.Inject;
 import javax.inject.Named;
 
 /**
+ * Provides simple access to the messages in the admin bundle. The make it as
+ * easy as possible to access the messages this class is implemented as a map a
+ * made available as named bean. For simple messages, {@code AdminMesssages} can
+ * be used like a map in a facelets template:
+ *
+ * <pre>
+ * #{AdminMessages['some.message.key'])
+ * </pre>
+ *
+ * Messages with placeholders can be retrieved using
+ * {@link #getMessage(java.lang.String, java.util.List)} or
+ * {@link #getMessage(java.lang.String, java.lang.Object[])}.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -40,11 +52,20 @@ import javax.inject.Named;
 @Named("AdminMessages")
 public class AdminMessages extends AbstractMap<String, String> {
 
+    /**
+     * Provides access to the locale negoiated by LibreCCM.
+     */
     @Inject
     private GlobalizationHelper globalizationHelper;
 
+    /**
+     * The {@link ResourceBundle} to use.
+     */
     private ResourceBundle messages;
 
+    /**
+     * Loads the resource bundle.
+     */
     @PostConstruct
     private void init() {
         messages = ResourceBundle.getBundle(
@@ -53,6 +74,13 @@ public class AdminMessages extends AbstractMap<String, String> {
         );
     }
 
+    /**
+     * Retrieves a message from the resource bundle.
+     * 
+     * @param key The key of the message.
+     * @return The translated message or {@code ???message???} if the the key is
+     * not found in the resource bundle (message is replaced with the key).
+     */
     public String getMessage(final String key) {
         if (messages.containsKey(key)) {
             return messages.getString(key);
@@ -61,12 +89,29 @@ public class AdminMessages extends AbstractMap<String, String> {
         }
     }
 
+    /**
+     * Retrieves a message with placeholders.
+     * 
+     * @param key The key of the message.
+     * @param parameters The parameters for the placeholders.
+     * @return The translated message or {@code ???message???} if the the key is
+     * not found in the resource bundle (message is replaced with the key).
+     */
     public String getMessage(
         final String key, final List<Object> parameters
     ) {
         return getMessage(key, parameters.toArray());
     }
 
+    /**
+     * The translated message or {@code ???message???} if the the key is
+     * not found in the resource bundle (message is replaced with the key).
+     * 
+      @param key The key of the message.
+     * @param parameters The parameters for the placeholders.
+     * @return The translated message or {@code ???message???} if the the key is
+     * not found in the resource bundle (message is replaced with the key).
+     */
     public String getMessage(
         final String key, final Object[] parameters
     ) {
@@ -77,6 +122,11 @@ public class AdminMessages extends AbstractMap<String, String> {
         }
     }
 
+    @Override
+    public String get(final Object key) {
+        return get((String) key);
+    }
+    
     public String get(final String key) {
         return getMessage(key);
     }

ccm-core/src/main/java/org/libreccm/ui/admin/AdminPage.java

@@ -23,6 +23,8 @@ import java.util.Set;
 import javax.mvc.MvcContext;
 
 /**
+ * Implementations of this interface provide the controllers etc. for an admin
+ * page.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -37,7 +39,8 @@ public interface AdminPage {
 
     /**
      * A identifier to use by {@link MvcContext#uri(java.lang.String)} to
-     * generate the URI of the page. The identifier has the same format as used in JavaDoc:
+     * generate the URI of the page. The identifier has the same format as used
+     * in JavaDoc:
      * <pre>
      *     ControllerSimpleClassName#methodName
      * </pre>

ccm-core/src/main/java/org/libreccm/ui/admin/AdminPageModel.java

@@ -19,6 +19,9 @@
 package org.libreccm.ui.admin;
 
 /**
+ * Model for the data of an admin page.
+ * 
+ * @see AdminPage
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/ui/admin/AdminPagesModel.java

@@ -32,6 +32,7 @@ import javax.inject.Inject;
 import javax.inject.Named;
 
 /**
+ * Model for the available admin pages.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -39,6 +40,9 @@ import javax.inject.Named;
 @Named("AdminPagesModel")
 public class AdminPagesModel {
 
+    /**
+     * Injection point for the admin pages.
+     */
     @Inject
     private Instance<AdminPage> adminPages;
 
@@ -50,6 +54,12 @@ public class AdminPagesModel {
      */
     private final Map<String, ResourceBundle> bundles = new HashMap<>();
 
+    /**
+     * Retrieves the available admin pages and converts them into
+     * {@link AdminPageModel}s for usage in the views.
+     *
+     * @return A list of the available admin pages.
+     */
     public List<AdminPageModel> getAdminPages() {
         return adminPages
             .stream()
@@ -86,7 +96,7 @@ public class AdminPagesModel {
         if (bundles.containsKey(bundleName)) {
             return bundles.get(bundleName);
         } else {
-            final ResourceBundle bundle =  ResourceBundle.getBundle(
+            final ResourceBundle bundle = ResourceBundle.getBundle(
                 bundleName,
                 globalizationHelper.getNegotiatedLocale()
             );

ccm-core/src/main/java/org/libreccm/ui/admin/package-info.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright (C) 2020 LibreCCM Foundation.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+ * MA 02110-1301  USA
+ */
+/**
+ * Base classes for the admin application.
+ */
+package org.libreccm.ui.admin;

ccm-core/src/main/java/org/libreccm/ui/admin/usersgroupsroles/EmailFormController.java

@@ -37,7 +37,6 @@ import javax.enterprise.context.RequestScoped;
 import javax.inject.Inject;
 import javax.mvc.Controller;
 import javax.mvc.Models;
-import javax.mvc.binding.BindingResult;
 import javax.transaction.Transactional;
 import javax.ws.rs.FormParam;
 import javax.ws.rs.POST;
@@ -45,21 +44,23 @@ import javax.ws.rs.Path;
 import javax.ws.rs.PathParam;
 
 /**
+ * Controller managing the post request from the email edit form.
+ *
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped
 @Controller
 @Path(
-    "/users-groups-roles/users/{userIdentifier}/email-addresses/{emailIdentifier}/save")
+    "/users-groups-roles/users/{userIdentifier}/email-addresses/{emailIdentifier}/save"
+)
 public class EmailFormController {
 
     @Inject
     private AdminMessages adminMessages;
 
-    @Inject
+//    @Inject
-    private BindingResult bindingResult;
+//    private BindingResult bindingResult;
-
     @Inject
     private EmailFormModel emailFormModel;
 

ccm-core/src/main/java/org/libreccm/ui/admin/usersgroupsroles/EmailFormModel.java

@@ -29,6 +29,7 @@ import javax.enterprise.context.RequestScoped;
 import javax.inject.Named;
 
 /**
+ * Model providing the data for the email edit form.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -38,7 +39,7 @@ public class EmailFormModel {
 
     private String userIdentifier;
     
-    private int emailId;
+    private int emailId = -1;
 
     private String address;
 
@@ -77,7 +78,7 @@ public class EmailFormModel {
     }
 
     public boolean isNew() {
-        return emailId == 0;
+        return emailId == -1;
     }
 
        public String getUserIdentifier() {

ccm-core/src/main/java/org/libreccm/ui/admin/usersgroupsroles/OverviewModel.java

@@ -31,6 +31,7 @@ import javax.inject.Named;
 import javax.transaction.Transactional;
 
 /**
+ * Model for the overview page of the users/groups/roles admin module.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/ui/admin/usersgroupsroles/PartyRoleMembership.java

@@ -21,6 +21,7 @@ package org.libreccm.ui.admin.usersgroupsroles;
 import org.libreccm.security.Role;
 
 /**
+ * Model friendly representation of the role membership of a {@link Party}.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/ui/admin/usersgroupsroles/UserDetailsModel.java

@@ -40,6 +40,7 @@ import javax.inject.Named;
 import javax.transaction.Transactional;
 
 /**
+ * Model used by the user details view and the user edit form.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/ui/admin/usersgroupsroles/UserFormController.java

@@ -48,6 +48,7 @@ import javax.ws.rs.Path;
 import javax.ws.rs.PathParam;
 
 /**
+ * Controller managing the user post requests from the user edit form.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/ui/admin/usersgroupsroles/UserGroupMembership.java

@@ -21,6 +21,7 @@ package org.libreccm.ui.admin.usersgroupsroles;
 import org.libreccm.security.Group;
 
 /**
+ * Model friendly representation of a group membership of the user.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/ui/admin/usersgroupsroles/UserGroupsFormEntry.java

@@ -19,6 +19,7 @@
 package org.libreccm.ui.admin.usersgroupsroles;
 
 /**
+ * Model for an selectable group in the user groups form.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/ui/admin/usersgroupsroles/UserRolesFormEntry.java

@@ -19,6 +19,7 @@
 package org.libreccm.ui.admin.usersgroupsroles;
 
 /**
+ * Model for an entry of a selectable role in the user roles form.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/ui/admin/usersgroupsroles/UsersController.java

@@ -48,6 +48,8 @@ import javax.ws.rs.PathParam;
 import javax.ws.rs.QueryParam;
 
 /**
+ * Controller for the user details view and the {@code GET} requests to the 
+ * user edit form.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/ui/admin/usersgroupsroles/UsersGroupsRolesController.java

@@ -28,6 +28,7 @@ import javax.ws.rs.GET;
 import javax.ws.rs.Path;
 
 /**
+ * 
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/ui/admin/usersgroupsroles/UsersTableModel.java

@@ -32,6 +32,7 @@ import javax.inject.Named;
 import javax.transaction.Transactional;
 
 /**
+ * Model for the table/list of users.
  *  
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/org/libreccm/ui/admin/usersgroupsroles/package-info.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright (C) 2020 LibreCCM Foundation.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+ * MA 02110-1301  USA
+ */
+/**
+ * Provides the backend for the user interface for managing users, groups and 
+ * roles.
+ */
+package org.libreccm.ui.admin.usersgroupsroles;

ccm-core/src/main/java/org/libreccm/ui/package-info.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright (C) 2020 LibreCCM Foundation.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+ * MA 02110-1301  USA
+ */
+/**
+ * Utility classes for Jakarta EE MVC based user interfaces.
+ */
+package org.libreccm.ui;