CCM NG: JavaDoc for PageModel

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

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

@@ -22,8 +22,12 @@ import java.util.Optional;
 import javax.inject.Inject;
 
 /**
+ * An abstract base class for implementations of the {@link PageBuilder}
+ * interface providing some functionality needed by all implementations of the
+ * {@link PageBuilder} interface.
  *
- * @param <P> Page class
+ * @param <P> Generics variable for the class which represents the page created
+ *            by the {@link PageBuilder}.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  *
@@ -33,6 +37,17 @@ public abstract class AbstractPageBuilder<P> implements PageBuilder<P> {
     @Inject
     private ComponentBuilderManager componentBuilderManager;
 
+    /**
+     * Build a {@code Page} based on a {@link PageModel}. This implementation
+     * first calls {@link #buildPage()} to create the page object. After that
+     * all {@link ComponentModel}s of the {@link PageModel} are processed and
+     * the component objects created by the {@link ComponentBuilder}s are added
+     * to the page.
+     *
+     * @param pageModel The {@link PageModel\ to process.
+     *
+     * @return A page containing all components from the {@link PageModel}.
+     */
     @Override
     public P buildPage(final PageModel pageModel) {
         final P page = buildPage();
@@ -48,6 +63,16 @@ public abstract class AbstractPageBuilder<P> implements PageBuilder<P> {
         return page;
     }
 
+    /**
+     * Helper method for building the components.
+     *
+     * @param <M>                 Generics variable for the type the component
+     *                            created.
+     * @param componentModel      The {@link ComponentModel} to process.
+     * @param componentModelClass The class of the {@link ComponentModel}.
+     *
+     * @return The components described by the {@code componentModel}.
+     */
     protected <M extends ComponentModel> Optional<Object> buildComponent(
         final ComponentModel componentModel,
         final Class<M> componentModelClass) {
@@ -65,7 +90,22 @@ public abstract class AbstractPageBuilder<P> implements PageBuilder<P> {
         }
     }
 
+    /**
+     * Abstract method returning the type (view technology) for which the
+     * {@link PageBuilder} processes {@link PageModel}s.
+     *
+     * @return
+     */
     protected abstract String getType();
 
+    /**
+     * A helper method for adding components to the page. How this is done
+     * depends on the view technology, therefore this method must be implemented
+     * by the implementations of this abstract class.
+     *
+     * @param page The page to which the component is added.
+     * @param component The component to add to the page.
+     */
     protected abstract void addComponent(P page, Object component);
+
 }

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

@@ -28,6 +28,8 @@ import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 
 /**
+ * Provides access to all available implementations of the
+ * {@link ComponentBuilder} interface.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -40,6 +42,26 @@ public class ComponentBuilderManager {
     @Inject
     private Instance<ComponentBuilder<?, ?>> componentBuilders;
 
+    /**
+     * Find an implementation of the {@link ComponentBuilder} interface for a
+     * specific {@link ComponentModel} and type.
+     *
+     * @param <M>                 Generic variable for the subtype of
+     *                            {@link ComponentModel} which is produced by
+     *                            the {@link ComponentBuilder} implementation.
+     * @param componentModelClass The sub class of the {@link ComponentModel}
+     *                            for which is processed by the
+     *                            {@link ComponentBuilder}.
+     * @param type                The type for which the
+     *                            {@link ComponentBuilder} produces the
+     *                            component(s).
+     *
+     * @return An {@link Optional} containing the implementation of the
+     *         {@link ComponentBuilder} interface for the specified parameters.
+     *         If there is no implementation of the specified parameters an
+     *         empty {@link Optional} is returned.
+     */
+    @SuppressWarnings("unchecked")
     public <M extends ComponentModel> Optional<ComponentBuilder<M, ?>> findComponentBuilder(
         final Class<M> componentModelClass,
         final String type) {

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

@@ -19,12 +19,17 @@
 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 java.util.UUID;
 
 import javax.enterprise.context.RequestScoped;
+import javax.transaction.Transactional;
 
 /**
+ * Repository class for managing {@link ComponentModel} entities.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -41,6 +46,20 @@ public class ComponentModelRepository extends AbstractEntityRepository<Long, Com
         return componentModel.getComponentModelId() == 0;
     }
 
+    @AuthorizationRequired
+    @RequiresPrivilege(CoreConstants.PRIVILEGE_ADMIN)
+    @Transactional(Transactional.TxType.REQUIRED)
+    @Override
+    public void save(final ComponentModel componentModel) {
+        super.save(componentModel);
+    }
+
+    /**
+     * Initialises a new entity.
+     *
+     * @param componentModel The new {@link ComponentModel} entity to
+     *                       initialise.
+     */
     @Override
     public void initNewEntity(final ComponentModel componentModel) {
         final String uuid = UUID.randomUUID().toString();

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

@@ -18,9 +18,12 @@
  */
 package org.libreccm.pagemodel;
 
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
 import org.libreccm.web.CcmApplication;
 
 import java.util.Iterator;
+import java.util.Optional;
 
 import javax.enterprise.context.RequestScoped;
 import javax.enterprise.inject.Instance;
@@ -28,29 +31,50 @@ import javax.enterprise.util.AnnotationLiteral;
 import javax.inject.Inject;
 
 /**
+ * Provides access to all available {@link PageBuilder} implementations.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped
 public class PageBuilderManager {
 
+    private static final Logger LOGGER = LogManager.getLogger(
+        PageBuilderManager.class);
+
     @Inject
     private Instance<PageBuilder<?>> pageBuilders;
 
-    public PageBuilder<?> findPageBuilder(
+    /**
+     * Find a {@link PageBuilder} for a specific type and application type.
+     *
+     * @param type            The type of the {@link PageBuilder}.
+     * @param applicationType The application type for which the
+     *                        {@link PageBuilder} builds pages.
+     *
+     * @return An {@link Optional} containing the {@link PageBuilder}
+     *         implementation for the specified {@code type} and
+     *         {@code applicationType}. If there is no {@code PageBuilder} for
+     *         the specified parameters an empty {@link Optional} is returned.
+     */
+    public Optional<PageBuilder<?>> findPageBuilder(
         final String type,
         final Class<? extends CcmApplication> applicationType) {
 
+        LOGGER.debug("Trying to find PageBuilder for type \"{}\" and "
+                         + "application type \"{}\"...",
+                     type,
+                     applicationType);
+
         final PageModelTypeLiteral literal = new PageModelTypeLiteral(
             type, applicationType);
 
         final Instance<PageBuilder<?>> instance = pageBuilders.select(literal);
         if (instance.isUnsatisfied()) {
-            throw new IllegalArgumentException(String.format(
+            LOGGER.warn("No PageBuilder for type \"{}\" and application type "
-                "No PageBuilder for type \"%s\" and application type \"%s\" "
+                            + "\"{}\"  available.",
-                    + "available.",
                         type,
-                applicationType));
+                        applicationType);
+            return Optional.empty();
         } else if (instance.isAmbiguous()) {
             throw new IllegalArgumentException(String.format(
                 "Multiple PageBuilders for type \"%s\" and "
@@ -58,10 +82,14 @@ public class PageBuilderManager {
                 type,
                 applicationType));
         } else {
+            LOGGER.debug("Found PageBuilder for type \"{}\" and application "
+                             + "type \"{}\"...",
+                         type,
+                         applicationType);
             final Iterator<PageBuilder<?>> iterator = instance.iterator();
             final PageBuilder<?> pageBuilder = iterator.next();
 
-            return pageBuilder;
+            return Optional.of(pageBuilder);
         }
     }
 

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

@@ -36,6 +36,8 @@ import javax.persistence.Enumerated;
 import javax.persistence.GeneratedValue;
 import javax.persistence.GenerationType;
 import javax.persistence.Id;
+import javax.persistence.Inheritance;
+import javax.persistence.InheritanceType;
 import javax.persistence.JoinColumn;
 import javax.persistence.JoinTable;
 import javax.persistence.ManyToOne;
@@ -56,6 +58,7 @@ import javax.validation.constraints.NotNull;
  * @see PageBuilder
  */
 @Entity
+@Inheritance(strategy = InheritanceType.JOINED)
 @Table(name = "PAGE_MODELS", schema = CoreConstants.DB_SCHEMA)
 @NamedQueries({
     @NamedQuery(

ccm-core/src/main/java/org/libreccm/pagemodel/bebop/AbstractBebopPageBuilder.java

@@ -25,6 +25,10 @@ import com.arsdigita.web.Web;
 import org.libreccm.pagemodel.AbstractPageBuilder;
 
 /**
+ * Basic implementation of a {@link PageBuilder} for Bebop {@link Page}s.
+ * Applications must provided an implementation of the {@link PageBuilder}.
+ * These implementations must override the
+ * {@link #addDefaultComponents(com.arsdigita.bebop.Page)} method.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -56,5 +60,11 @@ public abstract class AbstractBebopPageBuilder extends AbstractPageBuilder<Page>
         return page;
     }
 
+    /**
+     * Add the default components which are present on every page.
+     * 
+     * @param page The page to which the components are added.
+     */
     public abstract void addDefaultComponents(final Page page);
+
 }