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,13 +37,24 @@ 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();
 
         for (final ComponentModel componentModel : pageModel.getComponents()) {
             final Optional<Object> component = buildComponent(
-                    componentModel, componentModel.getClass());
+                componentModel, componentModel.getClass());
             if (component.isPresent()) {
                 addComponent(page, component);
             }
@@ -48,15 +63,25 @@ 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 ComponentModel componentModel,
-            final Class<M> componentModelClass) {
+        final Class<M> componentModelClass) {
 
         componentBuilderManager.findComponentBuilder(componentModel.getClass(),
                                                      getType());
 
         final Optional<ComponentBuilder<M, ?>> builder = componentBuilderManager
-                .findComponentBuilder(componentModelClass, getType());
+            .findComponentBuilder(componentModelClass, getType());
 
         if (builder.isPresent()) {
             return Optional.of(builder.get().buildComponent((M) componentModel));
@@ -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>
  */
@@ -35,38 +37,58 @@ import org.apache.logging.log4j.Logger;
 public class ComponentBuilderManager {
 
     private static final Logger LOGGER = LogManager.getLogger(
-            ComponentBuilderManager.class);
+        ComponentBuilderManager.class);
 
     @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 Class<M> componentModelClass,
-            final String type) {
+        final String type) {
 
         LOGGER.debug("Trying to find ComponentBuilder for ComponentModel\"{}\""
-                             + "and type \"{}\"...",
+                         + "and type \"{}\"...",
                      componentModelClass.getName(),
                      type);
 
         final ComponentModelTypeLiteral literal = new ComponentModelTypeLiteral(
-                componentModelClass, type);
+            componentModelClass, type);
 
         final Instance<ComponentBuilder<?, ?>> instance = componentBuilders
-                .select(literal);
+            .select(literal);
         if (instance.isUnsatisfied()) {
             LOGGER.warn("No ComponentBuilder for component model \"%s\" "
-                    + "and type \"%s\". Ignoring component model.");
+                            + "and type \"%s\". Ignoring component model.");
             return Optional.empty();
         } else if (instance.isAmbiguous()) {
             throw new IllegalStateException(String.format(
-                    "Multiple ComponentBuilders for component model \"%s\" and "
+                "Multiple ComponentBuilders for component model \"%s\" and "
-                            + "type \"%s\" available. Something is wrong",
+                    + "type \"%s\" available. Something is wrong",
-                    componentModelClass.getName(),
+                componentModelClass.getName(),
-                    type));
+                type));
         } else {
             final Iterator<ComponentBuilder<?, ?>> iterator = instance.
-                    iterator();
+                iterator();
             final ComponentBuilder<?, ?> componentBuilder = iterator.next();
 
             return Optional.of((ComponentBuilder<M, ?>) componentBuilder);
@@ -75,8 +97,8 @@ public class ComponentBuilderManager {
     }
 
     private class ComponentModelTypeLiteral
-            extends AnnotationLiteral<ComponentModelType>
+        extends AnnotationLiteral<ComponentModelType>
-            implements ComponentModelType {
+        implements ComponentModelType {
 
         private static final long serialVersionUID = -2601632434295178600L;
 
@@ -84,8 +106,8 @@ public class ComponentBuilderManager {
         private final String type;
 
         public ComponentModelTypeLiteral(
-                final Class<? extends ComponentModel> componentModel,
+            final Class<? extends ComponentModel> componentModel,
-                final String type) {
+            final String type) {
             this.componentModel = componentModel;
             this.type = 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,13 +46,27 @@ 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();
 
         componentModel.setUuid(uuid);
         if (componentModel.getModelUuid() == null
-            || componentModel.getModelUuid().isEmpty()) {
+                || componentModel.getModelUuid().isEmpty()) {
             componentModel.setModelUuid(uuid);
         }
     }

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,
-                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>
  */
@@ -48,7 +52,7 @@ public abstract class AbstractBebopPageBuilder extends AbstractPageBuilder<Page>
     public Page buildPage() {
 
         final String application = Web.getWebContext().getApplication().
-                getPrimaryUrl();
+            getPrimaryUrl();
         final Page page = PageFactory.buildPage(application, "");
 
         addDefaultComponents(page);
@@ -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);
+
 }