CCM NG: More JavaDoc for the page model system

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

ccm-core/src/main/java/org/libreccm/pagemodel/PageModelManager.java

@@ -20,6 +20,8 @@ package org.libreccm.pagemodel;
 
 import com.arsdigita.util.UncheckedWrapperException;
 
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
 import org.libreccm.core.CoreConstants;
 import org.libreccm.modules.CcmModule;
 import org.libreccm.modules.Module;
@@ -57,6 +59,9 @@ import javax.transaction.Transactional;
 @RequestScoped
 public class PageModelManager {
 
+    private static final Logger LOGGER = LogManager.getLogger(
+        PageModelManager.class);
+
     @Inject
     private EntityManager entityManager;
 
@@ -76,6 +81,8 @@ public class PageModelManager {
      */
     @PostConstruct
     private void init() {
+        LOGGER.debug("Initalising {}...", PageModelManager.class.getName());
+
         final ServiceLoader<CcmModule> modules = ServiceLoader.load(
             CcmModule.class);
 
@@ -91,6 +98,9 @@ public class PageModelManager {
                                model);
             }
         }
+        LOGGER.debug("Initalised {}. Found {} ComponentModels.",
+                     PageModelManager.class.getName(),
+                     components.size());
     }
 
     /**
@@ -124,11 +134,20 @@ public class PageModelManager {
             throw new IllegalArgumentException(
                 "The name of a page model can't be null or empty.");
         }
+        LOGGER.debug(
+            "Creating new PageModel with name \"{}\" for application \"{}\" and type \"{}\".",
+            name,
+            application.getPrimaryUrl(),
+            type);
 
         final long count = pageModelRepo.countByApplicationAndName(application,
                                                                    name);
 
         if (count > 0) {
+            LOGGER.error("A page model with the name \"{}\" for the "
+                             + "application \"{}\" already exists.",
+                         name,
+                         application.getPrimaryUrl());
             throw new IllegalArgumentException(String.format(
                 "A page model with the name \"%s\" for the application \"%s\" "
                     + "already exists.",
@@ -153,6 +172,7 @@ public class PageModelManager {
      *
      * @param pageModel The {@link PageModel} for which the draft version is
      *                  retrieved.
+     *
      * @return The draft version of the provided {@link PageModel}.
      */
     @AuthorizationRequired
@@ -177,6 +197,7 @@ public class PageModelManager {
      * Checks if a {@link PageModel} has a live version.
      *
      * @param pageModel The {@link PageModel} to check for a live version.
+     *
      * @return {@code true} if there is a live version for the provided
      *         {@link PageModel}, {@code false} otherwise.
      */
@@ -190,9 +211,15 @@ public class PageModelManager {
     }
 
     /**
+     * Retrieves the live version of a {@link PageModel}. This method does not
+     * require any privileges.
      *
-     * @param pageModel
+     * @param pageModel The {@link PageModel} of which the live version is
-     * @return
+     *                  retrieved.
+     *
+     * @return An {@link Optional} containing the live version of the provided
+     *         {@link PageModel} if there is a live version. Otherwise an empty
+     *         {@link Optional} is returned.
      */
     @Transactional(Transactional.TxType.REQUIRED)
     public Optional<PageModel> getLiveVersion(final PageModel pageModel) {
@@ -208,12 +235,24 @@ public class PageModelManager {
         }
     }
 
+    /**
+     * Publishes the draft version of a {@link PageModel}. If there is already a
+     * live version of the provided {@link PageModel} the live version is
+     * updated. If no live version exists a new live version is created.
+     *
+     * @param pageModel The {@link PageModel} to publish.
+     *
+     * @return The live version of the provided {@link PageModel}.
+     */
+    @AuthorizationRequired
+    @RequiresPrivilege(CoreConstants.PRIVILEGE_ADMIN)
+    @Transactional(Transactional.TxType.REQUIRED)
     public PageModel publish(final PageModel pageModel) {
         final PageModel draftModel = getDraftVersion(pageModel);
         final PageModel liveModel;
 
         if (isLive(pageModel)) {
-            liveModel = getLiveVersion(pageModel).get();
+            liveModel = getLiveVersion(draftModel).get();
         } else {
             liveModel = new PageModel();
         }
@@ -244,6 +283,15 @@ public class PageModelManager {
         return liveModel;
     }
 
+    /**
+     * Helper method for coping the {@link ComponentModel}s from the draft
+     * version to the live version.
+     *
+     * @param draftModel The draft version of the {@link ComponentModel} to copy
+     *                   to the live version of its {@link PageModel}.
+     *
+     * @return The live version of the {@link ComponentModel}.
+     */
     @SuppressWarnings("unchecked")
     private ComponentModel publishComponentModel(final ComponentModel draftModel) {
 
@@ -345,6 +393,15 @@ public class PageModelManager {
         return liveModel;
     }
 
+    /**
+     * Helper method to determine if a property is excluded from the publishing
+     * process.
+     *
+     * @param name The name of the property.
+     *
+     * @return {@code true} if the property is excluded from the publishing
+     *         process, {@link false} if not.
+     */
     private boolean propertyIsExcluded(final String name) {
         final String[] excluded = new String[]{
             "uuid",
@@ -362,6 +419,11 @@ public class PageModelManager {
         return result;
     }
 
+    /**
+     * Returns all available {@link ComponentModel}.
+     *
+     * @return A list of all available {@link ComponentModel}s.
+     */
     public List<PageModelComponentModel> findAvailableComponents() {
         final List<PageModelComponentModel> list = new ArrayList<>(components
             .values());
@@ -373,6 +435,16 @@ public class PageModelManager {
         return list;
     }
 
+    /**
+     * Finds the description specific {@link ComponentModel}.
+     *
+     * @param className The fully qualified name of the {@link ComponentModel}
+     *                  class.
+     *
+     * @return An {@link Optional} containing the description of the
+     *         {@link ComponentModel} if there is a {@link ComponentModel} with
+     *         the specified {@code name}. Otherwise an empty {@link Optional}.
+     */
     public Optional<PageModelComponentModel> findComponentModel(
         final String className) {
 
@@ -384,9 +456,10 @@ public class PageModelManager {
     }
 
     /**
-     * Add a {@link ComponentModel} to a {@link PageModel}.
+     * Adds a {@link ComponentModel} to a {@link PageModel}.
      *
-     * @param pageModel The {@link PageModel} to which component model is added.
+     * @param pageModel      The {@link PageModel} to which component model is
+     *                       added.
      * @param componentModel The {@link ComponentModel} to add.
      */
     public void addComponentModel(final PageModel pageModel,

ccm-core/src/main/java/org/libreccm/pagemodel/PageModelRepository.java

@@ -19,6 +19,9 @@
 package org.libreccm.pagemodel;
 
 import org.libreccm.core.AbstractEntityRepository;
+import org.libreccm.core.CoreConstants;
+import org.libreccm.security.AuthorizationRequired;
+import org.libreccm.security.RequiresPrivilege;
 import org.libreccm.web.CcmApplication;
 
 import java.util.List;
@@ -27,8 +30,10 @@ import java.util.UUID;
 
 import javax.enterprise.context.RequestScoped;
 import javax.persistence.TypedQuery;
+import javax.transaction.Transactional;
 
 /**
+ * Repository for {@link PageModel}s.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -49,6 +54,11 @@ public class PageModelRepository extends AbstractEntityRepository<Long, PageMode
         return pageModel.getPageModelId() == 0;
     }
 
+    /**
+     * Sets the UUID field of a new {@link PageModel}.
+     *
+     * @param pageModel The new {@link PageModel}.
+     */
     @Override
     public void initNewEntity(final PageModel pageModel) {
         if (pageModel == null) {
@@ -64,6 +74,25 @@ public class PageModelRepository extends AbstractEntityRepository<Long, PageMode
         }
     }
 
+    @AuthorizationRequired
+    @RequiresPrivilege(CoreConstants.PRIVILEGE_ADMIN)
+    @Transactional(Transactional.TxType.REQUIRED)
+    @Override
+    public void save(final PageModel pageModel) {
+        super.save(pageModel);
+    }
+
+    /**
+     * Finds the draft version of all {@link PageModel}s for the provided
+     * application.
+     *
+     * @param application The application for which the {@link PageModel}s are
+     *                    retrieved.
+     *
+     * @return A list of the {@link PageModel}s defined for the provided {
+     *
+     * @coded application}.
+     */
     public List<PageModel> findByApplication(final CcmApplication application) {
         if (application == null) {
             throw new IllegalArgumentException(
@@ -77,6 +106,15 @@ public class PageModelRepository extends AbstractEntityRepository<Long, PageMode
         return query.getResultList();
     }
 
+    /**
+     * Counts the {@link PageModel}s (draft version) defined for a application.
+     *
+     * @param application The application for which the {@link PageLink}s are
+     *                    counted.
+     *
+     * @return The number of {@link PageModel}s defined for the provided
+     *         {@code application}.
+     */
     public long countByApplication(final CcmApplication application) {
         if (application == null) {
             throw new IllegalArgumentException(
@@ -90,6 +128,19 @@ public class PageModelRepository extends AbstractEntityRepository<Long, PageMode
         return query.getSingleResult();
     }
 
+    /**
+     * Finds a {@link PageModel} (draft version) by the application and its
+     * {@code name}.
+     *
+     * @param application The application for which the {@link PageModel} is
+     *                    defined.
+     * @param name        The name of the {@link PageModel}.
+     *
+     * @return An {@link Optional} containing the {@link PageModel} for the
+     *         provided {@code application} with the provided {@code name}. If
+     *         there is no {@link PageModel} matching the criteria an empty
+     *         {@link Optional} is returned.
+     */
     public Optional<PageModel> findByApplicationAndName(
         final CcmApplication application,
         final String name) {
@@ -117,6 +168,17 @@ public class PageModelRepository extends AbstractEntityRepository<Long, PageMode
         return Optional.of(query.getSingleResult());
     }
 
+    /**
+     * Counts the number of {@link PageModel} (draft version) defined for the
+     * provided application with the provided name.
+     *
+     * @param application The application for which the {@link PageModel} is
+     *                    defined.
+     * @param name        The name of the {@link PageModel}.
+     *
+     * @return The number of {@link PageModel}s matching the criteria. Should be
+     *         0 or 1.
+     */
     public long countByApplicationAndName(final CcmApplication application,
                                           final String name) {
 

ccm-core/src/main/java/org/libreccm/pagemodel/PageModelVersion.java

@@ -19,6 +19,7 @@
 package org.libreccm.pagemodel;
 
 /**
+ * Enumeration for the possible values for the version of a {@link PageModel}.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */