CCM NG: JavaDoc for Sites and PageModel

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

Former-commit-id: 8a4fed4311

ccm-cms/src/main/java/org/librecms/pagemodel/AbstractContentItemComponentRenderer.java

@@ -42,8 +42,13 @@ import javax.ws.rs.core.Response;
 import static org.librecms.pages.PagesConstants.*;
 
 import org.libreccm.pagemodel.ComponentRenderer;
+import org.librecms.pagemodel.contentitems.ContentItemRenderer;
 
 /**
+ *
+ * Abstract base class for rendering an {@link ContentItemComponent} which
+ * provides some logic useful for most implementations of
+ * {@link ContentItemComponentRenderer}.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  * @param <T>
@@ -53,7 +58,7 @@ public abstract class AbstractContentItemComponentRenderer<T extends ContentItem
 
     @Inject
     private ConfigurationManager confManager;
-    
+
     @Inject
     private ContentItemRenderers contentItemRenderers;
 
@@ -66,15 +71,46 @@ public abstract class AbstractContentItemComponentRenderer<T extends ContentItem
     @Inject
     private PermissionChecker permissionChecker;
 
+    /**
+     * Retrieves the content item to render.
+     *
+     * @param componentModel The {@link ComponentModel} which is rendered.
+     * @param parameters     Additional parameters.
+     *
+     * @return The {@link ContentItem} to render.
+     */
     protected abstract ContentItem getContentItem(
         T componentModel, final Map<String, Object> parameters);
 
+    /**
+     * Renders the provided {@link ContentItemComponent} and the
+     * {@link ContentItem} retrieved by
+     * {@link #getContentItem(org.librecms.pagemodel.ContentItemComponent, java.util.Map)}.
+     *
+     * The {@link ContentItem} is rendered using an appropriate implementation
+     * of {@link ContentItemRenderer}. This method use the draft version of the
+     * item there is an parameters {@code showDraftItem} in the
+     * {@code parameters} map with the value {@code true}. If
+     * {@code showDraftItem} is set to {@code true} and the current user is not
+     * permitted to new the draft version of the item an
+     * {@link WebApplicationException} with the correct HTTP response code is
+     * thrown.
+     *
+     * Likewise of the current user is not permitted to view the view version of
+     * the item an {@link WebApplicationException} with the correct HTTP
+     * response code is thrown.
+     *
+     * @param componentModel The {@link ComponentModel} to render.
+     * @param parameters     Additional parameters.
+     *
+     * @return The rendered component.
+     */
     @Transactional(Transactional.TxType.REQUIRED)
     @Override
     public Map<String, Object> renderComponent(
         final T componentModel,
         final Map<String, Object> parameters) {
-        
+
         Objects.requireNonNull(componentModel);
         Objects.requireNonNull(parameters);
 
@@ -121,6 +157,17 @@ public abstract class AbstractContentItemComponentRenderer<T extends ContentItem
         }
     }
 
+    /**
+     * A helper method for rendering the {@link ContentItem}. There should be no
+     * need to overwrite this method, but maybe there are scenarios where this
+     * is necessary.
+     *
+     * @param componentModel The component model to render.
+     * @param parameters Additional parameters.
+     * @param item The item to render.
+     * 
+     * @return The rendered content item.
+     */
     protected Map<String, Object> generateItem(
         final T componentModel,
         final Map<String, Object> parameters,
@@ -136,13 +183,14 @@ public abstract class AbstractContentItemComponentRenderer<T extends ContentItem
         }
 
         if (iteml10nManager.hasLanguage(item, language)) {
-            
+
             final AbstractContentItemRenderer renderer = contentItemRenderers
-            .findRenderer(item.getClass(), componentModel.getMode());
+                .findRenderer(item.getClass(), componentModel.getMode());
-            
+
-            return renderer.render(item, language);            
+            return renderer.render(item, language);
         } else {
             throw new NotFoundException("Requested language is not available.");
         }
     }
+
 }

ccm-cms/src/main/java/org/librecms/pagemodel/CategorizedItemComponentRenderer.java

@@ -43,7 +43,8 @@ import javax.ws.rs.NotFoundException;
 import static org.librecms.pages.PagesConstants.*;
 
 /**
- *
+ * Renderer for the {@link CategorizedItemComponent}.
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped

ccm-cms/src/main/java/org/librecms/pagemodel/CategoryTreeComponentRenderer.java

@@ -23,10 +23,8 @@ import com.arsdigita.kernel.KernelConfig;
 import org.libreccm.categorization.Category;
 import org.libreccm.categorization.CategoryManager;
 import org.libreccm.categorization.CategoryRepository;
-import org.libreccm.categorization.DomainRepository;
 import org.libreccm.configuration.ConfigurationManager;
 import org.libreccm.core.CcmObject;
-import org.libreccm.l10n.GlobalizationHelper;
 import org.libreccm.pagemodel.ComponentModelType;
 
 import java.util.HashMap;
@@ -45,7 +43,8 @@ import static org.librecms.pages.PagesConstants.*;
 import org.libreccm.pagemodel.ComponentRenderer;
 
 /**
- *
+ * Renderer for the {@link CategoryTreeComponent}.
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped

ccm-cms/src/main/java/org/librecms/pagemodel/FixedContentItemComponent.java

@@ -30,7 +30,8 @@ import javax.persistence.Table;
 import static org.librecms.CmsConstants.*;
 
 /**
- *
+ * Component for showing a specific {@link ContentItem}. 
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @Entity

ccm-cms/src/main/java/org/librecms/pagemodel/FixedContentItemComponentRenderer.java

@@ -30,7 +30,8 @@ import javax.inject.Inject;
 import javax.ws.rs.NotFoundException;
 
 /**
- *
+ * Renderer for the {@link FixedContentItemComponent}.
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped

ccm-cms/src/main/java/org/librecms/pagemodel/GreetingItemComponentRenderer.java

@@ -36,7 +36,8 @@ import javax.ws.rs.NotFoundException;
 import static org.librecms.pages.PagesConstants.*;
 
 /**
- *
+ * Renderer for the {@link GreetingItemComponent}.
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped

ccm-cms/src/main/java/org/librecms/pagemodel/ItemListComponentRenderer.java

@@ -22,8 +22,6 @@ import com.arsdigita.kernel.KernelConfig;
 
 import org.libreccm.categorization.Categorization;
 import org.libreccm.categorization.Category;
-import org.libreccm.categorization.CategoryManager;
-import org.libreccm.categorization.CategoryRepository;
 import org.libreccm.configuration.ConfigurationManager;
 import org.libreccm.core.UnexpectedErrorException;
 import org.libreccm.pagemodel.ComponentModelType;
@@ -57,7 +55,8 @@ import javax.servlet.http.HttpServletRequest;
 import static org.librecms.pages.PagesConstants.*;
 
 /**
- *
+ * Renderer for the {@link ItemListComponent}.
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped
@@ -166,7 +165,10 @@ public class ItemListComponentRenderer
         final Join<? extends ContentItem, Categorization> catJoin = from
             .join("categories");
 
-        criteriaQuery.where(catJoin.get("category").in(categories));
+        criteriaQuery
+            .where(criteriaBuilder
+                .and(catJoin.get("category").in(categories),
+                     criteriaBuilder.equal(catJoin.get("index"), false)));
 
         criteriaQuery
             .orderBy(listOrder

ccm-cms/src/main/java/org/librecms/pagemodel/assets/AbstractAssetRenderer.java

@@ -25,11 +25,33 @@ import java.util.Locale;
 import java.util.Map;
 
 /**
+ * Abstract base class for rendering {@link Asset}s.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 public abstract class AbstractAssetRenderer {
 
+    /**
+     * Basic implementation rendering the common properties of an asset. For
+     * rendering the specific properties of the asset this method calls
+     * {@link #renderAsset(org.librecms.contentsection.Asset, java.util.Locale, java.util.Map)}.
+     *
+     * The common properties put into {@code result} are:
+     * 
+     * <pre>
+     *  {
+     *      "objectId": {@link Asset#getObjectId()}
+     *      "uuid": {@link Asset#getUuid()}
+     *      "displayName": {@link Asset#getDisplayName()}
+     *      "title": {@link Asset#getTitle()}
+     *  }
+     * </pre>
+     *
+     * @param asset    The {@link Asset} to render.
+     * @param language The current language.
+     *
+     * @return The rendered asset.
+     */
     public Map<String, Object> render(final Asset asset,
                                       final Locale language) {
 
@@ -45,6 +67,15 @@ public abstract class AbstractAssetRenderer {
         return result;
     }
 
+    /**
+     * Renders the special properties of an specific asset type. If the provided
+     * asset is not of the correct type for the renderer this an implementation
+     * of this method should return without doing anything.
+     *
+     * @param asset    The {@link Asset} to render.
+     * @param language The current language.
+     * @param result   The map in which the rendered properties are stored.
+     */
     protected abstract void renderAsset(final Asset asset,
                                         final Locale language,
                                         final Map<String, Object> result);

ccm-cms/src/main/java/org/librecms/pagemodel/assets/AssetRenderer.java

@@ -28,7 +28,8 @@ import java.lang.annotation.Target;
 import javax.inject.Qualifier;
 
 /**
- *
+ * Annotation for marking asset renderers.
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @Qualifier

ccm-cms/src/main/java/org/librecms/pagemodel/assets/AssetRenderers.java

@@ -31,6 +31,8 @@ import javax.enterprise.util.AnnotationLiteral;
 import javax.inject.Inject;
 
 /**
+ * Provides access to all available implementations of
+ * {@link AbstractAssetRenderer}.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -43,6 +45,17 @@ public class AssetRenderers {
     @Inject
     private Instance<AbstractAssetRenderer> renderers;
 
+    /**
+     * Tries to find an implementation of {@link AbstractAssetRenderer} for the
+     * provided asset type. If no renderer is found for the provided
+     * {@code assetType} an noop implementation of {@link AbstractAssetRenderer}
+     * is returned. This means that only the common properties of the asset are
+     * rendered.
+     *
+     * @param assetType The asset type.
+     *
+     * @return An renderer for the provided asset type.
+     */
     public AbstractAssetRenderer findRenderer(
         final Class<? extends Asset> assetType) {
 

ccm-cms/src/main/java/org/librecms/pagemodel/assets/AudioAssetRenderer.java

@@ -29,6 +29,7 @@ import javax.enterprise.context.RequestScoped;
 import javax.inject.Inject;
 
 /**
+ * Renderer for {@link AudioAsset}s.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -39,23 +40,42 @@ public class AudioAssetRenderer extends BinaryAssetRenderer {
     @Inject
     @AssetRenderer(renders = LegalMetadata.class)
     private AbstractAssetRenderer legalMetadataRenderer;
-    
+
+    /**
+     * Renders to provided {@link AudioAsset}. The following properties are put
+     * into {@code result}:
+     *
+     * <pre>
+     *  {
+     *      "legamMetadata": {@link AudioAsset#getLegalMetadata()}.
+     *  }
+     * </pre>
+     *
+     * The associated {@link LegalMetadata} asset is rendered using
+     * {@link LegalMetadataRenderer} and the result is put {@code result} under
+     * the key {@code legalMetadata}.
+     *
+     * @param asset    The asset to render.
+     * @param language The current language.
+     * @param result   The map into which the result is placed.
+     */
     @Override
-    protected void renderAsset(final Asset asset, 
+    protected void renderAsset(final Asset asset,
                                final Locale language,
                                final Map<String, Object> result) {
-        
+
         super.renderAsset(asset, language, result);
-        
+
         final AudioAsset audioAsset;
         if (asset instanceof AudioAsset) {
             audioAsset = (AudioAsset) asset;
         } else {
             return;
         }
-        
+
-        result.put("legalMetadata", 
+        result.put("legalMetadata",
-                   legalMetadataRenderer.render(audioAsset.getLegalMetadata(), language));
+                   legalMetadataRenderer.render(audioAsset.getLegalMetadata(),
+                                                language));
     }
-    
+
 }

ccm-cms/src/main/java/org/librecms/pagemodel/assets/BinaryAssetRenderer.java

@@ -26,28 +26,52 @@ import java.util.Map;
 import java.util.Objects;
 
 /**
+ * A renderer for {@link BinaryAsset}s. Please note that the binary data is
+ * usually not included into the render result. Instead an URL to a service
+ * which provides the binary data is included. For more details see the
+ * documentation of the specific renderers.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 public class BinaryAssetRenderer extends AbstractAssetRenderer {
 
+    /**
+     * Renders the common properties of all {@link BinaryAssets}. These are the
+     * following properties:
+     *
+     * <pre>
+     *  {
+     *      "description": {@link BinaryAsset#getDescription()}
+     *      "fileName": {@link BinaryAsset#getFileName()}
+     *      "mimeType": {@link BinaryAsset#getMimeType()}
+     *      "size": {@link BinaryAsset#getSize()}.
+     *  }
+     * </pre>
+     *
+     * The mime type is converted to a string using
+     * {@link Objects#toString(java.lang.Object)}.
+     *
+     * @param asset    The asset to render.
+     * @param language The current language.
+     * @param result   The map into which the result is put.
+     */
     @Override
-    protected void renderAsset(final Asset asset, 
+    protected void renderAsset(final Asset asset,
                                final Locale language,
                                final Map<String, Object> result) {
-        
+
         final BinaryAsset binaryAsset;
         if (asset instanceof BinaryAsset) {
             binaryAsset = (BinaryAsset) asset;
         } else {
             return;
         }
-        
+
-        result.put("description", 
+        result.put("description",
                    binaryAsset.getDescription().getValue(language));
         result.put("fileName", binaryAsset.getFileName());
         result.put("mimeType", Objects.toString(binaryAsset.getMimeType()));
         result.put("size", binaryAsset.getSize());
     }
-    
+
 }

ccm-cms/src/main/java/org/librecms/pagemodel/assets/BookmarkRenderer.java

@@ -19,8 +19,6 @@
 package org.librecms.pagemodel.assets;
 
 import org.librecms.contentsection.Asset;
-import org.librecms.pagemodel.assets.AbstractAssetRenderer;
-import org.librecms.pagemodel.assets.AssetRenderer;
 
 import java.util.Locale;
 import java.util.Map;
@@ -30,6 +28,7 @@ import javax.enterprise.context.RequestScoped;
 import org.librecms.assets.Bookmark;
 
 /**
+ * Renderer for {@link Bookmark} assets.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -37,20 +36,35 @@ import org.librecms.assets.Bookmark;
 @AssetRenderer(renders = Bookmark.class)
 public class BookmarkRenderer extends AbstractAssetRenderer {
 
+    /**
+     * Renders the provided {@link BookmarkAsset}. The following properties
+     * are put into {@code result}:
+     * 
+     * <pre>
+     *  {
+     *      "description": {@link Bookmark#getDescription()}
+     *      "url": {@link Bookmark#getUrl()}.
+     *  }
+     * </pre>
+     *
+     * @param asset    The asset to render.
+     * @param language The current language.
+     * @param result   The map into which the result is placed.
+     */
     @Override
-    protected void renderAsset(final Asset asset, 
+    protected void renderAsset(final Asset asset,
                                final Locale language,
                                final Map<String, Object> result) {
-        
+
         final Bookmark bookmark;
         if (asset instanceof Bookmark) {
             bookmark = (Bookmark) asset;
         } else {
             return;
         }
-        
+
         result.put("description", bookmark.getDescription().getValue(language));
         result.put("url", bookmark.getUrl());
     }
-    
+
 }

ccm-cms/src/main/java/org/librecms/pagemodel/assets/ExternalAudioAssetRenderer.java

@@ -29,7 +29,8 @@ import javax.enterprise.context.RequestScoped;
 import javax.inject.Inject;
 
 /**
- *
+ * Renderer for {@link ExternalAudioAsset}s.
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped
@@ -40,6 +41,25 @@ public class ExternalAudioAssetRenderer extends BookmarkRenderer {
     @AssetRenderer(renders = LegalMetadata.class)
     private AbstractAssetRenderer legalMetadataRenderer;
 
+    /**
+     * Renders the provided {@link ExternalVideoAsset}. In addition to the data
+     * put into {@code result} by the {@link BookmarkRenderer} the following
+     * properties are put into the map:
+     *
+     * <pre>
+     *  {
+     *      "legalMetadata": {@link ExternalVideoAsset#getLegalMetadata()}
+     *  }
+     * </pre>
+     *
+     * The associated {@link LegalMetadata} asset is rendered using the
+     * {@link LegalMetadata} and the result is put into the map under the key
+     * {@code legalMetadata}.
+     *
+     * @param asset    The asset to render.
+     * @param language The current language
+     * @param result   The map into which the result is put.
+     */
     @Override
     protected void renderAsset(final Asset asset,
                                final Locale language,

ccm-cms/src/main/java/org/librecms/pagemodel/assets/ExternalVideoAssetRenderer.java

@@ -29,6 +29,7 @@ import javax.enterprise.context.RequestScoped;
 import javax.inject.Inject;
 
 /**
+ * Renderer for {@link ExternalVideoAsset}s.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -40,12 +41,31 @@ public class ExternalVideoAssetRenderer extends BookmarkRenderer {
     @AssetRenderer(renders = LegalMetadata.class)
     private AbstractAssetRenderer legalMetadataRenderer;
 
+    /**
+     * Renders the provided {@link ExternalVideoAsset}. In addition to the data
+     * put into {@code result} by the {@link BookmarkRenderer} the following
+     * properties are put into the map:
+     *
+     * <pre>
+     *  {
+     *      "legalMetadata": {@link ExternalVideoAsset#getLegalMetadata()}
+     *  }
+     * </pre>
+     *
+     * The associated {@link LegalMetadata} asset is rendered using the
+     * {@link LegalMetadata} and the result is put into the map under the key
+     * {@code legalMetadata}.
+     *
+     * @param asset    The asset to render.
+     * @param language The current language
+     * @param result   The map into which the result is put.
+     */
     @Override
     protected void renderAsset(final Asset asset,
-                               final Locale locale,
+                               final Locale language,
                                final Map<String, Object> result) {
 
-        super.renderAsset(asset, locale, result);
+        super.renderAsset(asset, language, result);
 
         final ExternalVideoAsset externalVideoAsset;
         if (asset instanceof ExternalVideoAsset) {
@@ -56,7 +76,7 @@ public class ExternalVideoAssetRenderer extends BookmarkRenderer {
 
         result.put("legalMetadata",
                    legalMetadataRenderer
-                       .render(externalVideoAsset.getLegalMetadata(), locale));
+                       .render(externalVideoAsset.getLegalMetadata(), language));
     }
 
 }

ccm-cms/src/main/java/org/librecms/pagemodel/assets/FileAssetRenderer.java

@@ -27,21 +27,29 @@ import java.util.Map;
 import javax.enterprise.context.RequestScoped;
 
 /**
+ * Renderer for {@link FileAsset}s.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped
 @AssetRenderer(renders = FileAsset.class)
 public class FileAssetRenderer extends BinaryAssetRenderer {
-    
+
+    /**
+     * Renders the provided {@link FileAsset}. No additional data.
+     *
+     * @param asset
+     * @param locale
+     * @param result
+     */
     @Override
     protected void renderAsset(final Asset asset,
                                final Locale locale,
                                final Map<String, Object> result) {
-        
+
         super.renderAsset(asset, locale, result);
-        
+
         //Nothing more yet
     }
-    
+
 }

ccm-cms/src/main/java/org/librecms/pagemodel/assets/ImageRenderer.java

@@ -29,6 +29,7 @@ import javax.enterprise.context.RequestScoped;
 import javax.inject.Inject;
 
 /**
+ * Renderer for {@link ImageRenderer}.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -40,6 +41,26 @@ public class ImageRenderer extends BinaryAssetRenderer {
     @AssetRenderer(renders = LegalMetadata.class)
     private AbstractAssetRenderer legalMetadataRenderer;
 
+    /**
+     * Renders the provided {@link ImageAsset}. The following data is put into
+     * the map:
+     *
+     * <pre>
+     *  {
+     *      "width": {@link Image#getWidth()}
+     *      "height": {@link Image#getHeight()}
+     *      "legalMetadata": {@link LegalMetadataRenderer#render(org.librecms.contentsection.Asset, java.util.Locale)} using {@link Image#getLegalMetadata()}.
+     *  }
+     * </pre>
+     *
+     * The associated {@link LegalMetadata} asset is rendered using
+     * {@link LegalMetadataRenderer} and the result is put into map under the
+     * key {@code legalMetadata}.
+     *
+     * @param asset    The asset to render.
+     * @param language The current language.
+     * @param result   The map into which the result is put.
+     */
     @Override
     protected void renderAsset(final Asset asset,
                                final Locale language,

ccm-cms/src/main/java/org/librecms/pagemodel/assets/LegalMetadataRenderer.java

@@ -28,6 +28,7 @@ import java.util.Map;
 import javax.enterprise.context.RequestScoped;
 
 /**
+ * Renderer for {@link LegalMetadata} assets.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -35,24 +36,40 @@ import javax.enterprise.context.RequestScoped;
 @AssetRenderer(renders = LegalMetadata.class)
 public class LegalMetadataRenderer extends AbstractAssetRenderer {
 
+    /**
+     * Render the provided {@link LegalMetadata} asset. The following properties
+     * are added to the {@code result} map:
+     *
+     * <pre>
+     *      "rightsHolder": {@link LegalMetadata#getRightsHolder()}
+     *      "rights": {@link LegalMetadata#getRights()}
+     *      "publisher": {@link LegalMetadata#getPublisher()}
+     *      "creator": {@link LegalMetadata#getCreator()}
+     *      "contributors": {@link LegalMetadata#getContributors()}
+     * </pre>
+     *
+     * @param asset    The asset to renderer.
+     * @param language The current language.
+     * @param result   The map into which the result is placed.
+     */
     @Override
-    protected void renderAsset(final Asset asset, 
+    protected void renderAsset(final Asset asset,
                                final Locale language,
                                final Map<String, Object> result) {
-        
+
         final LegalMetadata legalMetadata;
         if (asset instanceof LegalMetadata) {
             legalMetadata = (LegalMetadata) asset;
         } else {
             return;
         }
-        
+
         result.put("rightsHolder", legalMetadata.getRightsHolder());
         result.put("rights", legalMetadata.getRights().getValue(language));
         result.put("publisher", legalMetadata.getPublisher());
         result.put("creator", legalMetadata.getCreator());
-        result.put("contributors", 
+        result.put("contributors",
                    new ArrayList<>(legalMetadata.getContributors()));
     }
-    
+
 }

ccm-cms/src/main/java/org/librecms/pagemodel/assets/RelatedLinkRenderer.java

@@ -31,6 +31,7 @@ import javax.enterprise.context.RequestScoped;
 import javax.inject.Inject;
 
 /**
+ * Renderer for {@link RelatedLink} assets.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -42,6 +43,36 @@ public class RelatedLinkRenderer extends AbstractAssetRenderer {
     @AssetRenderer(renders = Bookmark.class)
     private AbstractAssetRenderer bookmarkRenderer;
 
+    /**
+     * Render the provided {@link RelatedLink}.
+     *
+     * Depending on the type of the {@link RelatedLink} (internal or external)
+     * different properties are placed into {@code result}.
+     *
+     * For internal links: An entry with the key {@code targetItem} and a map
+     * containing the following properties of the target item:
+     *
+     * <pre>
+     *      {
+     *          "objectId": {@link ContentItem#getObjectId()}
+     *          "itemUuid": {@link ContentItem#getItemUuid()}
+     *          "displayName": {@link ContentItem#getDisplayName()}
+     *          "name": {@link ContentItem#getName()}
+     *          "title": {@link ContentItem#getTitle()}
+     *          "description": {@link ContentItem#getDescription()}
+     *      }
+     * </pre>
+     *
+     * For external links an {@link RelatedLink} uses a association with a
+     * {@link Bookmark}. The {@code Bookmark} is rendered using the
+     * {@link BookmarkRenderer}. The result is put into {@code result} with the
+     * key {@code bookmark}.
+     *
+     *
+     * @param asset    The asset to render.
+     * @param language The current language.
+     * @param result   The map is which to result is stored.
+     */
     @Override
     protected void renderAsset(final Asset asset,
                                final Locale language,

ccm-cms/src/main/java/org/librecms/pagemodel/assets/SideNoteRenderer.java

@@ -27,6 +27,7 @@ import java.util.Map;
 import javax.enterprise.context.RequestScoped;
 
 /**
+ * Renderer for {@link SideNote} assets.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -34,21 +35,33 @@ import javax.enterprise.context.RequestScoped;
 @AssetRenderer(renders = SideNote.class)
 public class SideNoteRenderer extends AbstractAssetRenderer {
 
+    /**
+     * Renderer to provided {@link SideNote}. The only property put into
+     * {@code result} by this renderer is {@code text}:
+     *
+     * <pre>
+     *  {
+     *      "text": {@link SideNote#getText()}
+     *  }
+     * </pre>
+     *
+     * @param asset    The {@link SideNote} to render.
+     * @param language The current language.
+     * @param result   The into which the result is placed.
+     */
     @Override
-    protected void renderAsset(final Asset asset, 
+    protected void renderAsset(final Asset asset,
                                final Locale language,
                                final Map<String, Object> result) {
-        
+
         final SideNote siteNote;
         if (asset instanceof SideNote) {
             siteNote = (SideNote) asset;
         } else {
             return;
         }
-        
+
         result.put("text", siteNote.getText().getValue(language));
     }
-    
+
-    
-    
 }

ccm-cms/src/main/java/org/librecms/pagemodel/assets/VideoAssetRenderer.java

@@ -29,36 +29,53 @@ import javax.enterprise.context.RequestScoped;
 import javax.inject.Inject;
 
 /**
+ * Renderer for {@link VideoAsset}s.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped
 @AssetRenderer(renders = VideoAsset.class)
 public class VideoAssetRenderer extends BinaryAssetRenderer {
-    
+
     @Inject
     @AssetRenderer(renders = LegalMetadata.class)
     private AbstractAssetRenderer legalMetadataRenderer;
-    
+
+    /**
+     * Renders the provided {@link VideoAsset}. The following properties a put
+     * into {@code result}:
+     *
+     * <pre>
+     *  {
+     *      width: {@link VideoAsset#getWidth()}
+     *      height: {@link VideoAsset#getHeight()}
+     *      legalMetadata: {@link VideoAsset#getLegalMetadata()}
+     *  }
+     * </pre>
+     *
+     * @param asset    The asset to render.
+     * @param language The current language.
+     * @param result   The map into which the result is put.
+     */
     @Override
     protected void renderAsset(final Asset asset,
-                               final Locale locale,
+                               final Locale language,
                                final Map<String, Object> result) {
-        
+
-        super.renderAsset(asset, locale, result);
+        super.renderAsset(asset, language, result);
-        
+
         final VideoAsset videoAsset;
         if (asset instanceof VideoAsset) {
             videoAsset = (VideoAsset) asset;
         } else {
             return;
         }
-        
+
         result.put("width", videoAsset.getWidth());
         result.put("height", videoAsset.getHeight());
         result.put("legalMetadata",
-                   legalMetadataRenderer.render(videoAsset.getLegalMetadata(), 
+                   legalMetadataRenderer.render(videoAsset.getLegalMetadata(),
-                                                locale));
+                                                language));
     }
-    
+
 }

ccm-cms/src/main/java/org/librecms/pagemodel/contentitems/AbstractContentItemRenderer.java

@@ -18,11 +18,13 @@
  */
 package org.librecms.pagemodel.contentitems;
 
+import org.libreccm.messaging.Attachment;
 import org.librecms.pagemodel.assets.AbstractAssetRenderer;
 import org.librecms.contentsection.AttachmentList;
 import org.librecms.contentsection.ContentItem;
 import org.librecms.contentsection.ContentType;
 import org.librecms.contentsection.ItemAttachment;
+import org.librecms.contentsection.rs.ContentItems;
 import org.librecms.pagemodel.assets.AssetRenderers;
 
 import java.util.HashMap;
@@ -33,6 +35,7 @@ import java.util.stream.Collectors;
 import javax.inject.Inject;
 
 /**
+ * Base class for the renderers for {@link ContentItems}.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -41,6 +44,44 @@ public abstract class AbstractContentItemRenderer {
     @Inject
     private AssetRenderers assetRenderers;
 
+    /**
+     * This method should be called to render a {@link ContentItem}. The method
+     * puts the common properties for {@link ContentItem}s into {@code result}
+     * and than calls
+     * {@link #renderItem(org.librecms.contentsection.ContentItem, java.util.Locale, java.util.Map)}
+     * to put the special properties of provided item into {@code result}.
+     *
+     * The common properties put into {@code result} are:
+     *
+     * <pre>
+     *  {
+     *      "objectId": {@link ContentItem#getObjectId()}
+     *      "uuid": {@link ContentItem#getUuid()}
+     *      "displayName": {@link ContentItem#getDisplayName()}
+     *      "itemUuid": {@link ContentItem#getItemUuid()}
+     *      "name": {@link ContentItem#getName()}
+     *      "title": {@link ContentItem#getTitle()}
+     *      "contentType": {@link ContentItem#getContentType()}
+     *      "description": {@link ContentItem#getDescription()}
+     *      "creationDate": {@link ContentItem#getCreationDate()}
+     *      "lastModified": {@link ContentItem#getLastModified()}
+     *      "creationUserName": {@link ContentItem#getCreationUserName()}
+     *      "lastModifyingUserName": {@link ContentItem#getLastModifyingUserName()}
+     *      "attachments": {@link ContentItem#getAttachments()}.
+     *  }
+     * </pre>
+     *
+     * The value of {@link ContentItem#getContentType} is rendered by
+     * {@link #renderContentType(org.librecms.contentsection.ContentType, java.util.Locale)}.
+     *
+     * The value of {@link ContentItem#getAttachments()} is rendered using
+     * {@link #renderAttachmentList(org.librecms.contentsection.AttachmentList, java.util.Locale)}.
+     *
+     * @param item     The item to render.
+     * @param language The current language.
+     *
+     * @return A map with the data of the provided {@link ContentItem}.
+     */
     public Map<String, Object> render(final ContentItem item,
                                       final Locale language) {
 
@@ -75,6 +116,24 @@ public abstract class AbstractContentItemRenderer {
                                        final Locale language,
                                        final Map<String, Object> result);
 
+    /**
+     * Renders the {@link ContentType} of an {@link ContentItem}. The generated
+     * map contains the following values:
+     *
+     * <pre>
+     *  {
+     *      "objectId": {@link ContentType#getObjectId()}
+     *      "uuid": {@link ContentType#getUuid()}
+     *      "displayName": {@link ContentType#getDisplayName()}
+     *      "label": {@link ContentType#getLabel()}
+     *  }
+     * </pre>
+     *
+     * @param contentType The {@link ContentType} to render.
+     * @param language    The current language.
+     *
+     * @return A map with the properties of the {@link ContentType}.
+     */
     protected Map<String, Object> renderContentType(
         final ContentType contentType, final Locale language) {
 
@@ -88,6 +147,31 @@ public abstract class AbstractContentItemRenderer {
         return result;
     }
 
+    /**
+     * Renders a {@link AttachmentList} and all {@link ItemAttachment}s. in the
+     * list. The map contains the following values:
+     *
+     * <pre>
+     *  {
+     *      "listId": {@link AttachmentList#getListId()}
+     *      "uuid": {@link AttachmentList#getUuid()}
+     *      "name": {@link AttachmentList#getName()}
+     *      "order": {@link AttachmentList#getOrder()}
+     *      "title": {@link AttachmentList#getTitle()}
+     *      "description": {@link AttachmentList#getDescription()}
+     *      "attachments": {@link AttachmentList#getAttachments()}
+     *  }
+     * </pre>
+     *
+     * The attachments of the list are rendered using
+     * {@link #renderAttachment(org.librecms.contentsection.ItemAttachment, java.util.Locale)}.
+     *
+     * @param attachmentList The {@link AttachmentList} to render.
+     * @param language       The current language.
+     *
+     * @return A map containing the data of the {@link AttachmentList} and its
+     *         {@link Attachment}s.
+     */
     protected Map<String, Object> renderAttachmentList(
         final AttachmentList attachmentList,
         final Locale language) {
@@ -112,6 +196,29 @@ public abstract class AbstractContentItemRenderer {
         return result;
     }
 
+    /**
+     * Renders an {@link ItemAttachment}. The generated map contains the
+     * following values:
+     *
+     * <pre>
+     *  {
+     *      "attachmentId": {@link ItemAttachment#getAttachmentId()}
+     *      "uuid": {@link ItemAttachment#getUuid()}
+     *      "sortKey": {@link ItemAttachment#getSortKey()}
+     *      "asset": {@link ItemAttachment#getAsset()}
+     *  }
+     * </pre>
+     *
+     * The associated {@link Asset} is rendered using the appropriate
+     * {@link AbstractAssetRenderer} implementation. The
+     * {@link AbstractAssetRenderer} to use is retrieved using
+     * {@link AssetRenderers#findRenderer(java.lang.Class)}.
+     *
+     * @param attachment The {@link ItemAttachment} to render.
+     * @param language   The current language.
+     *
+     * @return A map with the data of the {@link ItemAttachment}.
+     */
     protected Map<String, Object> renderAttachment(
         final ItemAttachment<?> attachment,
         final Locale language) {

ccm-cms/src/main/java/org/librecms/pagemodel/contentitems/ArticleRenderer.java

@@ -27,13 +27,28 @@ import java.util.Map;
 import javax.enterprise.context.RequestScoped;
 
 /**
- *
+ * Renderer for {@link Article} items.
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @ContentItemRenderer(renders = Article.class)
 @RequestScoped
 public class ArticleRenderer extends AbstractContentItemRenderer {
 
+    /**
+     * Render the provided {@link Article}. The following values are put into 
+     * the map: 
+     * 
+     * <pre>
+     *  {
+     *      "text": {@link Article#getText()}
+     *  }
+     * </pre>
+     * 
+     * @param item The item to render.
+     * @param language The current language.
+     * @param result The map into which the result is placed. 
+     */
     @Override
     public void renderItem(final ContentItem item,
                            final Locale language,

ccm-cms/src/main/java/org/librecms/pagemodel/contentitems/ContentItemRenderers.java

@@ -31,6 +31,9 @@ import javax.enterprise.util.AnnotationLiteral;
 import javax.inject.Inject;
 
 /**
+ * Provides access to all available implementations of
+ * {@link AbstractContentItemRenderer}.
+ *
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -43,6 +46,13 @@ public class ContentItemRenderers {
     @Inject
     private Instance<AbstractContentItemRenderer> renderers;
 
+    /**
+     * Tries to find the renderer for provided type and the default mode.
+     *
+     * @param itemType The type for which the renderer is retrieved.
+     *
+     * @return The renderer for the provided type.
+     */
     public AbstractContentItemRenderer findRenderer(
         final Class<? extends ContentItem> itemType) {
 
@@ -51,6 +61,18 @@ public class ContentItemRenderers {
         return findRenderer(itemType, "--DEFAULT--");
     }
 
+    /**
+     * Tries to find the renderer for provided type and the provided mode. If a
+     * appropriate renderer is found an default renderer with an empty
+     * implementation of
+     * {@link AbstractContentItemRenderer#renderItem(org.librecms.contentsection.ContentItem, java.util.Locale, java.util.Map)}
+     * is returned.
+     *
+     * @param itemType The type for which the renderer is retrieved.
+     * @param mode The render mode.
+     *
+     * @return The renderer for the provided type.
+     */
     public AbstractContentItemRenderer findRenderer(
         final Class<? extends ContentItem> itemType, final String mode) {
 

ccm-cms/src/main/java/org/librecms/pagemodel/contentitems/EventRenderer.java

@@ -25,12 +25,35 @@ import java.util.Locale;
 import java.util.Map;
 
 /**
+ * Renderer for {@link Event} items.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @ContentItemRenderer(renders = Event.class)
 public class EventRenderer extends AbstractContentItemRenderer {
 
+    /**
+     * Render the provided {@link Event}. The following values are put into
+     * {@code result}:
+     * 
+     * <pre>
+     *  {
+     *      "text": {@link Event#getText()}
+     *      "startDate": {@link Event#getStartDate()}
+     *      "endDate": {@link Event#getEndDate()}
+     *      "eventDate": {@link Event#getEventType()}
+     *      "location": {@link Event#getLocation()}
+     *      "mainContributor": {@link Event#getMainContributor()}
+     *      "eventType": {@link Event#getEventType()}
+     *      "mapLink": {@link Event#getMapLink()}
+     *      "cost": {@link Event#getCost()}
+     *  }
+     * </pre>
+     *
+     * @param item     The item to render.
+     * @param language The current language.
+     * @param result   The map into which the result is placed.
+     */
     @Override
     public void renderItem(final ContentItem item,
                            final Locale language,

ccm-cms/src/main/java/org/librecms/pagemodel/contentitems/MultiPartArticleRenderer.java

@@ -28,12 +28,33 @@ import java.util.Map;
 import java.util.stream.Collectors;
 
 /**
+ * Renderer for {@link MultiPartArticle} items.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @ContentItemRenderer(renders = MultiPartArticle.class)
-public class MultiPartArticleRenderer    extends AbstractContentItemRenderer {
+public class MultiPartArticleRenderer extends AbstractContentItemRenderer {
 
+    /**
+     * Renders the provided {@link MultiPartArticle}. The following values are
+     * put into {@code result}:
+     *
+     * <pre>
+     *  {
+     *      "summary": {@link MultiPartArticle#getSummary()}
+     *      "sections": {@link MultiPartArticle#getSections()}
+     *  }
+     * </pre>
+     *
+     * The value of {@code sections} is a list containing a {@link Map}
+     * generated by
+     * {@link #renderSection(org.librecms.contenttypes.MultiPartArticleSection, java.util.Locale)}
+     * for each section.
+     *
+     * @param item     The item to render.
+     * @param language The current language.
+     * @param result   The map into which the result is placed.
+     */
     @Override
     public void renderItem(final ContentItem item,
                            final Locale language,
@@ -45,7 +66,7 @@ public class MultiPartArticleRenderer    extends AbstractContentItemRenderer {
         } else {
             return;
         }
-        
+
         result.put("summary", article.getSummary().getValue(language));
         result.put("sections",
                    article
@@ -56,6 +77,25 @@ public class MultiPartArticleRenderer    extends AbstractContentItemRenderer {
 
     }
 
+    /**
+     * Renders a {@link MultiPartArticleSection}. The generated map contains the
+     * following values:
+     *
+     * <pre>
+     *  {
+     *      "sectionId": {@link MultiPartArticleSection#getSectionId()}
+     *      "title": {@link MultiPartArticleSection#getTitle()}
+     *      "rank": {@link MultiPartArticleSection#getRank()}
+     *      "pageBreak": {@link MultiPartArticleSection#isPageBreak()}
+     *      "text": {@link MultiPartArticleSection#getText()}
+     *  }
+     * </pre>
+     *
+     * @param section  The section to render.
+     * @param language The current language.
+     *
+     * @return A map with the data of the section.
+     */
     protected Map<String, Object> renderSection(
         final MultiPartArticleSection section, final Locale language) {
 

ccm-cms/src/main/java/org/librecms/pagemodel/contentitems/NewsRenderer.java

@@ -27,13 +27,28 @@ import java.util.Map;
 import javax.enterprise.context.RequestScoped;
 
 /**
- *
+ * Renderer for {@link News} items.
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @ContentItemRenderer(renders = News.class)
 @RequestScoped
 public class NewsRenderer extends AbstractContentItemRenderer {
 
+    /**
+     * Renders the provided {@link News} item. The following values are put into {@code result}:
+     * 
+     * <pre>
+     *  {
+     *      "text": {@link News#getText()}
+     *      "releaseDate": {@link News#getReleaseDate()}
+     *  }
+     * </pre>
+     * 
+     * @param item     The item to render.
+     * @param language The current language.
+     * @param result   The map into which the result is placed.
+     */
     @Override
     public void renderItem(final ContentItem item,
                            final Locale language,
@@ -45,7 +60,7 @@ public class NewsRenderer extends AbstractContentItemRenderer {
         } else {
             return;
         }
-        
+
         result.put("text", news.getText().getValue(language));
         result.put("releaseDate", news.getReleaseDate());
     }

ccm-cms/src/main/java/org/librecms/pages/Page.java

@@ -30,13 +30,10 @@ import java.util.Objects;
 
 import javax.persistence.CollectionTable;
 import javax.persistence.ElementCollection;
-import javax.persistence.Embedded;
 import javax.persistence.Entity;
 import javax.persistence.JoinColumn;
-import javax.persistence.JoinTable;
 import javax.persistence.ManyToOne;
 import javax.persistence.MapKeyColumn;
-import javax.persistence.MapKeyJoinColumn;
 import javax.persistence.NamedQueries;
 import javax.persistence.NamedQuery;
 import javax.persistence.Table;
@@ -45,7 +42,8 @@ import static org.librecms.CmsConstants.*;
 import static org.librecms.pages.PagesConstants.*;
 
 /**
- *
+ * A CMS page is a container which contains several data how a page is displayed.
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @Entity
@@ -64,20 +62,24 @@ public class Page extends CcmObject implements Serializable {
 
     private static final long serialVersionUID = 5108486858438122008L;
 
+    /**
+     * The page model for the index item of the associated category.
+     */
     @ManyToOne
     @JoinColumn(name = "INDEX_PAGE_MODEL_ID")
     private PageModel indexPageModel;
 
+    /**
+     * The page model for other items in the associated category.
+     */
     @ManyToOne
     @JoinColumn(name = "ITEM_PAGE_MODEL_ID")
     private PageModel itemPageModel;
 
+    /**
+     * The configurations for this page.
+     */
     @ElementCollection
-//    @JoinTable(name = "PAGE_THEME_CONFIGURATIONS",
-//               schema = DB_SCHEMA,
-//               joinColumns = {
-//                   @JoinColumn(name = "PAGE_ID")
-//               })
     @CollectionTable(name = "PAGE_THEME_CONFIGURATIONS", 
                      schema = DB_SCHEMA,
                      joinColumns = {

ccm-cms/src/main/java/org/librecms/pages/PageManager.java

@@ -28,7 +28,10 @@ import javax.enterprise.context.RequestScoped;
 import javax.inject.Inject;
 import javax.transaction.Transactional;
 
+import static org.librecms.pages.PagesConstants.*;
+
 /**
+ * Manager for {@link Page} entities.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -37,13 +40,22 @@ public class PageManager {
 
     @Inject
     private CategoryManager categoryManager;
-    
+
     @Inject
     private CategoryRepository categoryRepo;
-    
+
     @Inject
     private PageRepository pageRepo;
 
+    /**
+     * Finds the {@link Page} associated with an {@link Category}. If there is
+     * no {@link Page} associated with the provided {@link Category} this method
+     * will return the {@link Page} associated with the parent category.
+     *
+     * @param category The {@link Category} which is associated with the {@link Page}.
+     *
+     * @return The {@link Page} associated with the provided {@code category}.
+     */
     @Transactional(Transactional.TxType.REQUIRED)
     public Page findPageForCategory(final Category category) {
 
@@ -66,12 +78,19 @@ public class PageManager {
         }
     }
 
+    /**
+     * Create 
+     * @param category
+     * @return 
+     */
     @Transactional(Transactional.TxType.REQUIRED)
     public Page createPageForCategory(final Category category) {
 
         final Page page = new Page();
         pageRepo.save(page);
-        categoryManager.addObjectToCategory(page, category);
+        categoryManager.addObjectToCategory(page, 
+                                            category, 
+                                            CATEGORIZATION_TYPE_PAGE_CONF);
 
         return page;
     }

ccm-cms/src/main/java/org/librecms/pages/PageRepository.java

@@ -30,12 +30,19 @@ import javax.persistence.NoResultException;
 import javax.persistence.TypedQuery;
 
 /**
- *
+ * Repository for {@link Page} entities.
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped
 public class PageRepository extends AbstractEntityRepository<Long, Page>{
 
+    /**
+     * Find the {@link Page} associated with a {@link Category}.
+     * 
+     * @param category The {@link Category} associated with the {@link Page}.
+     * @return 
+     */
     public Optional<Page> findPageForCategory(final Category category) {
         
         final TypedQuery<Page> query = getEntityManager()

ccm-cms/src/main/java/org/librecms/pages/Pages.java

@@ -35,7 +35,9 @@ import javax.persistence.Table;
 import static org.librecms.CmsConstants.*;
 
 /**
- *
+ * The {@code Pages} application. Each instance of this application provides
+ * the page tree for specific site.
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @Entity
@@ -68,10 +70,16 @@ public class Pages extends CcmApplication implements Serializable {
 
     private static final long serialVersionUID = -352205318143692477L;
 
+    /**
+     * The {@link Site} to which this pages instance belongs.
+     */
     @OneToOne
     @JoinColumn(name = "SITE_ID")
     private Site site;
 
+    /**
+     * The category {@link Domain} which is used the model the page tree.
+     */
     @OneToOne
     @JoinColumn(name = "CATEGORY_DOMAIN_ID")
     private Domain categoryDomain;

ccm-cms/src/main/java/org/librecms/pages/PagesApplication.java

@@ -25,7 +25,7 @@ import javax.ws.rs.ApplicationPath;
 import javax.ws.rs.core.Application;
 
 /**
- *
+ * JAX-RS application for {@link Pages}.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-cms/src/main/java/org/librecms/pages/PagesConstants.java

@@ -19,7 +19,8 @@
 package org.librecms.pages;
 
 /**
- *
+ * Constants used by the classes in the package.
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 public final class PagesConstants {

ccm-cms/src/main/java/org/librecms/pages/PagesManager.java

@@ -24,7 +24,8 @@ import javax.enterprise.context.RequestScoped;
 import javax.inject.Inject;
 
 /**
- *
+ * Manager class for {@link Pages}.
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped

ccm-cms/src/main/java/org/librecms/pages/PagesRepository.java

@@ -18,7 +18,6 @@
  */
 package org.librecms.pages;
 
-
 import org.libreccm.core.AbstractEntityRepository;
 import org.libreccm.core.CoreConstants;
 import org.libreccm.security.RequiresPrivilege;
@@ -33,6 +32,7 @@ import javax.persistence.TypedQuery;
 import javax.transaction.Transactional;
 
 /**
+ * Repository for {@link Pages}.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -42,6 +42,14 @@ public class PagesRepository extends AbstractEntityRepository<Long, Pages> {
     @Inject
     private SiteRepository siteRepo;
 
+    /**
+     * Retrieves the {@link Pages} instance for the site identified by the
+     * provided domain.
+     *
+     * @param domainOfSite The domain of the site.
+     *
+     * @return The {@link Pages} instance for the site if any.
+     */
     @Transactional(Transactional.TxType.REQUIRED)
     public Optional<Pages> findPagesForSite(final String domainOfSite) {
 

ccm-cms/src/main/java/org/librecms/pages/PagesRouter.java

@@ -56,6 +56,7 @@ import javax.ws.rs.core.UriInfo;
 import static org.librecms.pages.PagesConstants.*;
 
 /**
+ * JAX-RS class providing access to the pages.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -99,6 +100,15 @@ public class PagesRouter {
         defaultLocale = kernelConfig.getDefaultLocale();
     }
 
+    /**
+     * Retrieve the index page of a category. Redirects to
+     * {@link #getCategoryIndexPageAsHtml(javax.ws.rs.core.UriInfo, java.lang.String)}.
+     *
+     * @param uriInfo
+     * @param page
+     *
+     * @return
+     */
     @Path("/")
     public Response getCategoryIndexPage(
         @Context
@@ -127,6 +137,15 @@ public class PagesRouter {
         return Response.temporaryRedirect(uri).build();
     }
 
+    /**
+     * Retrieves the category index page. Redirects to
+     * {@link #getCategoryIndexPageAsHtml(javax.ws.rs.core.UriInfo, java.lang.String)}.
+     *
+     * @param uriInfo
+     * @param page
+     *
+     * @return
+     */
     @Path("/index.html")
     public Response getCategoryIndexPageAsHtml(
         @Context
@@ -156,6 +175,18 @@ public class PagesRouter {
         return Response.temporaryRedirect(uri).build();
     }
 
+    /**
+     * Retrieves the category index page.
+     *
+     * @param uriInfo          Data about the URI called.
+     * @param page             The path of the category to show.
+     * @param language         The selected language.
+     * @param theme            The theme to use.
+     * @param themeVersion     The version of the theme to use.
+     * @param pageModelVersion The version of the page model to use.
+     *
+     * @return The HTML representation of the index page.
+     */
     @Path("/index.{lang}.html")
     @Produces("text/html")
     @Transactional(Transactional.TxType.REQUIRED)
@@ -184,6 +215,16 @@ public class PagesRouter {
         return themes.process(buildResult, themeInfo);
     }
 
+    /**
+     * Retrieves the category index page as JSON:
+     *
+     * @param uriInfo
+     * @param page
+     * @param language
+     * @param pageModelVersion
+     *
+     * @return
+     */
     @Path("/index.{lang}.json")
     @Produces("text/html")
     @Transactional(Transactional.TxType.REQUIRED)
@@ -201,6 +242,16 @@ public class PagesRouter {
         return getCategoryIndexPage(uriInfo, page, language, pageModelVersion);
     }
 
+    /**
+     * Retrieves the category index page as XML.
+     *
+     * @param uriInfo
+     * @param page
+     * @param language
+     * @param pageModelVersion
+     *
+     * @return
+     */
     @Path("/index.{lang}.xml")
     @Produces("text/html")
     @Transactional(Transactional.TxType.REQUIRED)
@@ -218,6 +269,19 @@ public class PagesRouter {
         return getCategoryIndexPage(uriInfo, page, language, pageModelVersion);
     }
 
+    /**
+     * Retrieve the item page for a category and the content item associated
+     * with the category and identified by {@code itemName}.
+     *
+     * Redirects to
+     * {@link #getItemPageAsHtml(javax.ws.rs.core.UriInfo, java.lang.String, java.lang.String)}.
+     *
+     * @param uriInfo
+     * @param page
+     * @param itemName
+     *
+     * @return
+     */
     @Path("/{name}")
     public Response getItemPage(
         @Context final UriInfo uriInfo,
@@ -245,6 +309,17 @@ public class PagesRouter {
         return Response.temporaryRedirect(uri).build();
     }
 
+    /**
+     * Retrieve the item page for a category and the content item associated
+     * with the category and identified by {@code itemName}. Redirects to
+     * {@link #getItemPageAsHtml(javax.ws.rs.core.UriInfo, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String)}.
+     *
+     * @param uriInfo
+     * @param page
+     * @param itemName
+     *
+     * @return
+     */
     @Path("/{name},html")
     public Response getItemPageAsHtml(
         @Context final UriInfo uriInfo,
@@ -276,6 +351,20 @@ public class PagesRouter {
         return Response.temporaryRedirect(uri).build();
     }
 
+    /**
+     * Retrieve the item page as HTML for a category and the content item
+     * associated with the category and identified by {@code itemName}.
+     *
+     * @param uriInfo
+     * @param page
+     * @param itemName
+     * @param language
+     * @param theme
+     * @param themeVersion
+     * @param pageModelVersion
+     *
+     * @return
+     */
     @Path("/{name}.{lang}.html")
     public String getItemPageAsHtml(
         @Context
@@ -304,6 +393,18 @@ public class PagesRouter {
         return themes.process(buildResult, themeInfo);
     }
 
+    /**
+     * Retrieve the item page as JSON for a category and the content item
+     * associated with the category and identified by {@code itemName}.
+     *
+     * @param uriInfo
+     * @param page
+     * @param itemName
+     * @param language
+     * @param pageModelVersion
+     *
+     * @return
+     */
     @Path("/{name}.{lang}.html")
     public Map<String, Object> getItemPageAsJson(
         @Context
@@ -325,6 +426,18 @@ public class PagesRouter {
                                    pageModelVersion);
     }
 
+    /**
+     * Retrieve the item page as XML for a category and the content item
+     * associated with the category and identified by {@code itemName}.
+     *
+     * @param uriInfo
+     * @param page
+     * @param itemName
+     * @param language
+     * @param pageModelVersion
+     *
+     * @return
+     */
     @Path("/{name}.{lang}.html")
     public Map<String, Object> getItemPageAsXml(
         @Context

ccm-cms/src/main/java/org/librecms/pages/ThemeConfiguration.java

@@ -25,7 +25,8 @@ import javax.persistence.Column;
 import javax.persistence.Embeddable;
 
 /**
- *
+ * Configuration for the {@link Page} and a {@link Site}.
+ * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @Embeddable
@@ -33,12 +34,21 @@ public class ThemeConfiguration implements Serializable {
 
     private static final long serialVersionUID = -989896906728810984L;
 
+    /**
+     * The theme associated with this configuration.
+     */
     @Column(name = "THEME")
     private String theme;
 
+    /**
+     * The template provided by the theme to use for index pages.
+     */
     @Column(name = "INDEX_PAGE_TEMPLATE")
     private String indexPageTemplate;
 
+    /**
+     * The template provided by the theme to use for item pages.
+     */
     @Column(name = "ITEM_PAGE_TEMPLATE")
     private String itemPageTemplate;
 

ccm-cms/src/test/resources-wildfly-remote-h2-mem/scripts/create_ccm_cms_schema.sql

@@ -219,6 +219,23 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         primary key (OBJECT_ID, REV)
     );
 
+    create table CCM_CMS.CATEGORIZED_ITEM_COMPONENTS (
+        COMPONENT_MODEL_ID bigint not null,
+        primary key (COMPONENT_MODEL_ID)
+    );
+
+    create table CCM_CMS.CATEGORY_TREE_COMPONENTS (
+        SHOW_FULL_TREE boolean,
+        COMPONENT_MODEL_ID bigint not null,
+        primary key (COMPONENT_MODEL_ID)
+    );
+
+    create table CCM_CMS.CONTENT_ITEM_COMPONENTS (
+        MODE varchar(255),
+        COMPONENT_MODEL_ID bigint not null,
+        primary key (COMPONENT_MODEL_ID)
+    );
+
     create table CCM_CMS.CONTENT_ITEM_DESCRIPTIONS (
         OBJECT_ID bigint not null,
         LOCALIZED_VALUE varchar(2147483647),
@@ -509,6 +526,12 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         primary key (OBJECT_ID, REV)
     );
 
+    create table CCM_CMS.FIXED_CONTENT_ITEM_COMPONENTS (
+        COMPONENT_MODEL_ID bigint not null,
+        CONTENT_ITEM_ID bigint,
+        primary key (COMPONENT_MODEL_ID)
+    );
+
     create table CCM_CMS.FOLDER_CONTENT_SECTION_MAP (
         CONTENT_SECTION_ID bigint,
         FOLDER_ID bigint not null,
@@ -521,6 +544,11 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         primary key (OBJECT_ID)
     );
 
+    create table CCM_CMS.GREETING_ITEM_COMPONENTS (
+        COMPONENT_MODEL_ID bigint not null,
+        primary key (COMPONENT_MODEL_ID)
+    );
+
     create table CCM_CMS.IMAGES (
         HEIGHT bigint,
         WIDTH bigint,
@@ -538,6 +566,19 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         primary key (OBJECT_ID, REV)
     );
 
+    create table CCM_CMS.ITEM_LIST_COMPONENTS (
+        DESCINDING boolean,
+        LIMIT_TO_TYPE varchar(255),
+        PAGE_SIZE integer,
+        COMPONENT_MODEL_ID bigint not null,
+        primary key (COMPONENT_MODEL_ID)
+    );
+
+    create table CCM_CMS.ITEM_LIST_ORDER (
+        ITEM_LIST_ID bigint not null,
+        LIST_ORDER varchar(255)
+    );
+
     create table CCM_CMS.LEGAL_METADATA (
         CREATOR varchar(255),
         PUBLISHER varchar(255),
@@ -1392,11 +1433,11 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         SETTING_ID bigint not null,
         CONFIGURATION_CLASS varchar(512) not null,
         NAME varchar(512) not null,
+        SETTING_VALUE_DOUBLE double,
         SETTING_VALUE_BIG_DECIMAL decimal(19,2),
         SETTING_VALUE_STRING varchar(1024),
-        SETTING_VALUE_DOUBLE double,
-        SETTING_VALUE_LONG bigint,
         SETTING_VALUE_BOOLEAN boolean,
+        SETTING_VALUE_LONG bigint,
         primary key (SETTING_ID)
     );
 
@@ -1744,6 +1785,21 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         foreign key (OBJECT_ID, REV) 
         references CCM_CMS.ASSETS_AUD;
 
+    alter table CCM_CMS.CATEGORIZED_ITEM_COMPONENTS 
+        add constraint FKlraxqtl9cnntdo0qovq340y7b 
+        foreign key (COMPONENT_MODEL_ID) 
+        references CCM_CMS.CONTENT_ITEM_COMPONENTS;
+
+    alter table CCM_CMS.CATEGORY_TREE_COMPONENTS 
+        add constraint FKfhc51tkdf705o0sy8sndqpkqa 
+        foreign key (COMPONENT_MODEL_ID) 
+        references CCM_CORE.PAGE_MODEL_COMPONENT_MODELS;
+
+    alter table CCM_CMS.CONTENT_ITEM_COMPONENTS 
+        add constraint FKp83o82kxo2ipa0xo03wxp4dcr 
+        foreign key (COMPONENT_MODEL_ID) 
+        references CCM_CORE.PAGE_MODEL_COMPONENT_MODELS;
+
     alter table CCM_CMS.CONTENT_ITEM_DESCRIPTIONS 
         add constraint FK6mt4tjnenr79o52wcj99tpeu4 
         foreign key (OBJECT_ID) 
@@ -2029,6 +2085,16 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         foreign key (OBJECT_ID, REV) 
         references CCM_CMS.BINARY_ASSETS_AUD;
 
+    alter table CCM_CMS.FIXED_CONTENT_ITEM_COMPONENTS 
+        add constraint FKlfv2clu7ubk18unio8fyvlbnf 
+        foreign key (CONTENT_ITEM_ID) 
+        references CCM_CMS.CONTENT_ITEMS;
+
+    alter table CCM_CMS.FIXED_CONTENT_ITEM_COMPONENTS 
+        add constraint FKkpiuth8e994phxy1x1drh2wf5 
+        foreign key (COMPONENT_MODEL_ID) 
+        references CCM_CMS.CONTENT_ITEM_COMPONENTS;
+
     alter table CCM_CMS.FOLDER_CONTENT_SECTION_MAP 
         add constraint FKnof2m7o4f0ufrugeh4g5wt3g9 
         foreign key (CONTENT_SECTION_ID) 
@@ -2044,6 +2110,11 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         foreign key (OBJECT_ID) 
         references CCM_CORE.CATEGORIES;
 
+    alter table CCM_CMS.GREETING_ITEM_COMPONENTS 
+        add constraint FK3fble8pmmolb7lmsca8akmb94 
+        foreign key (COMPONENT_MODEL_ID) 
+        references CCM_CMS.CONTENT_ITEM_COMPONENTS;
+
     alter table CCM_CMS.IMAGES 
         add constraint FK51ja1101epvl74auenv6sqyev 
         foreign key (LEGAL_METADATA_ID) 
@@ -2059,6 +2130,16 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         foreign key (OBJECT_ID, REV) 
         references CCM_CMS.BINARY_ASSETS_AUD;
 
+    alter table CCM_CMS.ITEM_LIST_COMPONENTS 
+        add constraint FKje8r8nvkqv8fj7i0eo1pew2yq 
+        foreign key (COMPONENT_MODEL_ID) 
+        references CCM_CORE.PAGE_MODEL_COMPONENT_MODELS;
+
+    alter table CCM_CMS.ITEM_LIST_ORDER 
+        add constraint FKisnil2ibh98y2ws8or6guij21 
+        foreign key (ITEM_LIST_ID) 
+        references CCM_CMS.ITEM_LIST_COMPONENTS;
+
     alter table CCM_CMS.LEGAL_METADATA 
         add constraint FKnxl7uyv1ks0qabgeienx2t9d1 
         foreign key (OBJECT_ID) 

ccm-cms/src/test/resources-wildfly-remote-pgsql/scripts/create_ccm_cms_schema.sql

@@ -218,6 +218,23 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         primary key (OBJECT_ID, REV)
     );
 
+    create table CCM_CMS.CATEGORIZED_ITEM_COMPONENTS (
+        COMPONENT_MODEL_ID int8 not null,
+        primary key (COMPONENT_MODEL_ID)
+    );
+
+    create table CCM_CMS.CATEGORY_TREE_COMPONENTS (
+        SHOW_FULL_TREE boolean,
+        COMPONENT_MODEL_ID int8 not null,
+        primary key (COMPONENT_MODEL_ID)
+    );
+
+    create table CCM_CMS.CONTENT_ITEM_COMPONENTS (
+        MODE varchar(255),
+        COMPONENT_MODEL_ID int8 not null,
+        primary key (COMPONENT_MODEL_ID)
+    );
+
     create table CCM_CMS.CONTENT_ITEM_DESCRIPTIONS (
         OBJECT_ID int8 not null,
         LOCALIZED_VALUE text,
@@ -508,6 +525,12 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         primary key (OBJECT_ID, REV)
     );
 
+    create table CCM_CMS.FIXED_CONTENT_ITEM_COMPONENTS (
+        COMPONENT_MODEL_ID int8 not null,
+        CONTENT_ITEM_ID int8,
+        primary key (COMPONENT_MODEL_ID)
+    );
+
     create table CCM_CMS.FOLDER_CONTENT_SECTION_MAP (
         CONTENT_SECTION_ID int8,
         FOLDER_ID int8 not null,
@@ -520,6 +543,11 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         primary key (OBJECT_ID)
     );
 
+    create table CCM_CMS.GREETING_ITEM_COMPONENTS (
+        COMPONENT_MODEL_ID int8 not null,
+        primary key (COMPONENT_MODEL_ID)
+    );
+
     create table CCM_CMS.IMAGES (
         HEIGHT int8,
         WIDTH int8,
@@ -537,6 +565,19 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         primary key (OBJECT_ID, REV)
     );
 
+    create table CCM_CMS.ITEM_LIST_COMPONENTS (
+        DESCINDING boolean,
+        LIMIT_TO_TYPE varchar(255),
+        PAGE_SIZE int4,
+        COMPONENT_MODEL_ID int8 not null,
+        primary key (COMPONENT_MODEL_ID)
+    );
+
+    create table CCM_CMS.ITEM_LIST_ORDER (
+        ITEM_LIST_ID int8 not null,
+        LIST_ORDER varchar(255)
+    );
+
     create table CCM_CMS.LEGAL_METADATA (
         CREATOR varchar(255),
         PUBLISHER varchar(255),
@@ -1391,11 +1432,11 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         SETTING_ID int8 not null,
         CONFIGURATION_CLASS varchar(512) not null,
         NAME varchar(512) not null,
+        SETTING_VALUE_DOUBLE float8,
         SETTING_VALUE_BIG_DECIMAL numeric(19, 2),
         SETTING_VALUE_STRING varchar(1024),
-        SETTING_VALUE_DOUBLE float8,
-        SETTING_VALUE_LONG int8,
         SETTING_VALUE_BOOLEAN boolean,
+        SETTING_VALUE_LONG int8,
         primary key (SETTING_ID)
     );
 
@@ -1743,6 +1784,21 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         foreign key (OBJECT_ID, REV) 
         references CCM_CMS.ASSETS_AUD;
 
+    alter table CCM_CMS.CATEGORIZED_ITEM_COMPONENTS 
+        add constraint FKlraxqtl9cnntdo0qovq340y7b 
+        foreign key (COMPONENT_MODEL_ID) 
+        references CCM_CMS.CONTENT_ITEM_COMPONENTS;
+
+    alter table CCM_CMS.CATEGORY_TREE_COMPONENTS 
+        add constraint FKfhc51tkdf705o0sy8sndqpkqa 
+        foreign key (COMPONENT_MODEL_ID) 
+        references CCM_CORE.PAGE_MODEL_COMPONENT_MODELS;
+
+    alter table CCM_CMS.CONTENT_ITEM_COMPONENTS 
+        add constraint FKp83o82kxo2ipa0xo03wxp4dcr 
+        foreign key (COMPONENT_MODEL_ID) 
+        references CCM_CORE.PAGE_MODEL_COMPONENT_MODELS;
+
     alter table CCM_CMS.CONTENT_ITEM_DESCRIPTIONS 
         add constraint FK6mt4tjnenr79o52wcj99tpeu4 
         foreign key (OBJECT_ID) 
@@ -2028,6 +2084,16 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         foreign key (OBJECT_ID, REV) 
         references CCM_CMS.BINARY_ASSETS_AUD;
 
+    alter table CCM_CMS.FIXED_CONTENT_ITEM_COMPONENTS 
+        add constraint FKlfv2clu7ubk18unio8fyvlbnf 
+        foreign key (CONTENT_ITEM_ID) 
+        references CCM_CMS.CONTENT_ITEMS;
+
+    alter table CCM_CMS.FIXED_CONTENT_ITEM_COMPONENTS 
+        add constraint FKkpiuth8e994phxy1x1drh2wf5 
+        foreign key (COMPONENT_MODEL_ID) 
+        references CCM_CMS.CONTENT_ITEM_COMPONENTS;
+
     alter table CCM_CMS.FOLDER_CONTENT_SECTION_MAP 
         add constraint FKnof2m7o4f0ufrugeh4g5wt3g9 
         foreign key (CONTENT_SECTION_ID) 
@@ -2043,6 +2109,11 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         foreign key (OBJECT_ID) 
         references CCM_CORE.CATEGORIES;
 
+    alter table CCM_CMS.GREETING_ITEM_COMPONENTS 
+        add constraint FK3fble8pmmolb7lmsca8akmb94 
+        foreign key (COMPONENT_MODEL_ID) 
+        references CCM_CMS.CONTENT_ITEM_COMPONENTS;
+
     alter table CCM_CMS.IMAGES 
         add constraint FK51ja1101epvl74auenv6sqyev 
         foreign key (LEGAL_METADATA_ID) 
@@ -2058,6 +2129,16 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         foreign key (OBJECT_ID, REV) 
         references CCM_CMS.BINARY_ASSETS_AUD;
 
+    alter table CCM_CMS.ITEM_LIST_COMPONENTS 
+        add constraint FKje8r8nvkqv8fj7i0eo1pew2yq 
+        foreign key (COMPONENT_MODEL_ID) 
+        references CCM_CORE.PAGE_MODEL_COMPONENT_MODELS;
+
+    alter table CCM_CMS.ITEM_LIST_ORDER 
+        add constraint FKisnil2ibh98y2ws8or6guij21 
+        foreign key (ITEM_LIST_ID) 
+        references CCM_CMS.ITEM_LIST_COMPONENTS;
+
     alter table CCM_CMS.LEGAL_METADATA 
         add constraint FKnxl7uyv1ks0qabgeienx2t9d1 
         foreign key (OBJECT_ID) 

ccm-core/src/main/java/org/libreccm/modules/Module.java

@@ -20,6 +20,8 @@ package org.libreccm.modules;
 
 import org.libreccm.configuration.Configuration;
 import org.libreccm.configuration.ConfigurationManager;
+import org.libreccm.pagemodel.ComponentModel;
+import org.libreccm.pagemodel.PageModel;
 import org.libreccm.pagemodel.PageModelComponentModel;
 import org.libreccm.web.ApplicationType;
 
@@ -84,12 +86,19 @@ public @interface Module {
      *
      * @return An array containing all configuration classes provided by the
      *         module.
-     * 
+     *
      * @see Configuration
      * @see ConfigurationManager
      */
     Class<?>[] configurations() default {};
 
+    /**
+     * Components for use in {@link PageModel}s provided by the annotated
+     * module.
+     *
+     * @return An array containing all {@link ComponentModel}s provided by the
+     *         annotated module.
+     */
     PageModelComponentModel[] pageModelComponentModels() default {};
-    
+
 }

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

@@ -44,12 +44,13 @@ public abstract class AbstractPageRenderer implements PageRenderer {
      * the component objects created by the {@link ComponentRenderer}s are added
      * to the page.
      *
-     * @param pageModel  The {@link PageModel} to process.
+     * @param pageModel  The {@link PageModel} to render.
      * @param parameters Parameters provided by application which wants to
      *                   render a {@link PageModel}. The parameters are passed
      *                   the {@link ComponentRenderer}s.
      *
-     * @return A page containing all components from the {@link PageModel}.
+     * @return A map containing the results from rendering the components of the
+     *         page model.
      */
     @Override
     public Map<String, Object> renderPage(final PageModel pageModel,
@@ -73,22 +74,24 @@ public abstract class AbstractPageRenderer implements PageRenderer {
     /**
      * Helper method for rendering the components.
      *
-     * @param <M>                 Generics variable for the type the component
+     * @param <M>                 Generics variable for the type of rendered
-     *                            created.
+     *                            component
      * @param componentModel      The {@link ComponentModel} to process.
      * @param componentModelClass The class of the {@link ComponentModel}.
      * @param parameters          Parameters provided by application which wants
      *                            to render a {@link PageModel}. The parameters
      *                            are passed the {@link ComponentRenderer}s.
      *
-     * @return The components described by the {@code componentModel}.
+     * @return A map containing the results from rendering the components of the
+     *         page model.
      */
     protected <M extends ComponentModel> Optional<Object> renderComponent(
         final ComponentModel componentModel,
         final Class<M> componentModelClass,
         final Map<String, Object> parameters) {
 
-        componentRendererManager.findComponentRenderer(componentModel.getClass());
+        componentRendererManager
+            .findComponentRenderer(componentModel.getClass());
 
         final Optional<ComponentRenderer<M>> renderer = componentRendererManager
             .findComponentRenderer(componentModelClass);
@@ -96,7 +99,8 @@ public abstract class AbstractPageRenderer implements PageRenderer {
         if (renderer.isPresent()) {
             @SuppressWarnings("unchecked")
             final M model = (M) componentModel;
-            return Optional.of(renderer.get().renderComponent(model, parameters));
+            return Optional
+                .of(renderer.get().renderComponent(model, parameters));
         } else {
             return Optional.empty();
         }

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

@@ -19,6 +19,7 @@
 package org.libreccm.pagemodel;
 
 import org.libreccm.core.CoreConstants;
+import org.libreccm.modules.Module;
 
 import javax.validation.constraints.NotNull;
 
@@ -37,9 +38,12 @@ import javax.persistence.ManyToOne;
 import javax.persistence.Table;
 
 /**
- * Base class for the components model for use in a {@link PageModel}. This
+ * Base class for the component models for use in a {@link PageModel}. This
  * class is not designed for direct use. Instead the classes for concrete
- * components have be used. A component must be annotation with
+ * components have to be used. A component model must be registered by adding it
+ * to list of component models provided by a module by adding it the the list
+ * provided by {@link Module#pageModelComponentModels() } using the
+ * {@link PageModelComponentModel} annotation.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -50,32 +54,63 @@ public class ComponentModel implements Serializable {
 
     private static final long serialVersionUID = 8585775139379396806L;
 
+    /**
+     * ID in the database for this instance.
+     */
     @Id
     @Column(name = "COMPONENT_MODEL_ID")
     @GeneratedValue(strategy = GenerationType.AUTO)
     private long componentModelId;
 
+    /**
+     * The UUID of the instance.
+     */
     @Column(name = "UUID", length = 255, nullable = false)
     @NotNull
     private String uuid;
 
+    /**
+     * The UUID of the {@code ComponentModel} which is the same for the draft
+     * and live version.
+     */
     @Column(name = "MODEL_UUID", length = 255, nullable = false)
     @NotNull
     private String modelUuid;
-    
+
+    /**
+     * The {@link PageModel} to which the {@code ComponentModel} belongs.
+     */
     @ManyToOne
     @JoinColumn(name = "PAGE_MODEL_ID")
     private PageModel pageModel;
 
+    /**
+     * ID of the component. Must be unique inside a {@link PageModel}.
+     */
     @Column(name = "ID_ATTRIBUTE", length = 255)
     private String idAttribute;
 
+    /**
+     * CSS Style classes to add to the HTML element representing the component
+     * in the HTML generated from the rendered component model.
+     */
     @Column(name = "CLASS_ATTRIBUTE", length = 512)
     private String classAttribute;
 
+    /**
+     * CSS styles to add to the HTML element representing the component in the
+     * HTML generated from the rendered component model. Avoid using this as it
+     * will add inline styles to the HTML.
+     */
     @Column(name = "STYLE_ATTRIBUTE", length = 1024)
     private String styleAttribute;
 
+    /**
+     * Key for identifying the component in a {@link PageModel}. The will be
+     * used as key in the map generated by
+     * {@link PageRenderer#renderPage(java.util.Map)} and
+     * {@link PageRenderer#renderPage(org.libreccm.pagemodel.PageModel, java.util.Map)}.
+     */
     @Column(name = "COMPONENT_KEY", length = 255)
     private String key;
 
@@ -98,11 +133,11 @@ public class ComponentModel implements Serializable {
     public String getModelUuid() {
         return modelUuid;
     }
-    
+
     protected void setModelUuid(final String modelUuid) {
         this.modelUuid = modelUuid;
     }
-    
+
     public PageModel getPageModel() {
         return pageModel;
     }

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

@@ -25,7 +25,7 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Specifies which type of components a {@link ComponentRenderer} implenentation
+ * Specifies which type of components a {@link ComponentRenderer} implementation
  * renders.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>

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

@@ -18,6 +18,7 @@
  */
 package org.libreccm.pagemodel;
 
+import java.util.Collection;
 import java.util.Map;
 
 /**
@@ -30,7 +31,36 @@ import java.util.Map;
  */
 public interface ComponentRenderer<M extends ComponentModel> {
 
+    /**
+     * Renders a {@link ComponentModel}.
+     *
+     * The result of the rendering process is a map which uses strings as key.
+     * The values are either Java primitive types or Collections. More exactly
+     * the values are objects of one the following types:
+     *
+     * <ul>
+     * <li>{@link Double}</li>
+     * <li>{@link Float}</li>
+     * <li>{@link Integer}</li>
+     * <li>{@link Long}</li>
+     * <li>{@link Short}</li>
+     * <li>{@link String}</li>
+     * <li>{@link List}</li>
+     * <li>{@link Map}</li>
+     * </ul>
+     *
+     * Other subtypes {@link Collection} are might be supported but there is no
+     * grantee for that. The values in a collection must be one of the types in
+     * the list above. Collections might contain multiple types from the list
+     * above. The keys for a map should always be strings.
+     *
+     * @param componentModel The component model to render.
+     * @param parameters     Parameters provided by the calling
+     *                       {@link PageRenderer}.
+     *
+     * @return A map representing the rendered component.
+     */
     Map<String, Object> renderComponent(M componentModel,
-                                       final Map<String, Object> parameters);
+                                        Map<String, Object> parameters);
 
 }

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

@@ -91,6 +91,9 @@ public class ComponentRendererManager {
 
     }
 
+    /**
+     * Annotation literal for the {@link ComponentModelType} annotation.
+     */
     private class ComponentModelTypeLiteral
         extends AnnotationLiteral<ComponentModelType>
         implements ComponentModelType {

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

@@ -137,7 +137,7 @@ public class PageModel implements Serializable {
     private String uuid;
 
     /**
-     * The UUID of the model. Same for draft and live version.
+     * The UUID of the model. Same for draft and live versions.
      */
     @Column(name = "MODEL_UUID", length = 255, nullable = false)
     @NotNull

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

@@ -34,13 +34,21 @@ import javax.inject.Inject;
 import javax.persistence.EntityManager;
 import javax.persistence.TypedQuery;
 import javax.transaction.Transactional;
+
 import java.beans.BeanInfo;
 import java.beans.IntrospectionException;
 import java.beans.Introspector;
 import java.beans.PropertyDescriptor;
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
-import java.util.*;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Optional;
+import java.util.ServiceLoader;
+import java.util.Set;
 
 /**
  * Provides several methods for managing {@link PageModel}s.
@@ -95,8 +103,8 @@ public class PageModelManager {
     }
 
     /**
-     * Creates a new {@link PageModel} for the provided application. The tries
+     * Creates a new {@link PageModel} for the provided application. The method
-     * to retrieve the appropriate page model by using
+     * tries to retrieve the appropriate page model by using
      * {@link PageModelRepository#findByApplicationAndName(org.libreccm.web.CcmApplication, java.lang.String)}.
      * Please note that this method will always return the <strong>live</strong>
      * version of the page model.
@@ -105,7 +113,7 @@ public class PageModelManager {
      *                    application.
      * @param application The application for which the {@link PageModel} is
      *                    created.
-     * @param type        Type of the page model (view technology).
+     * @param type        Type of the page model.
      *
      * @return The new {@link PageModel}.
      */

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

@@ -35,10 +35,13 @@ import java.util.Map;
 public interface PageRenderer {
 
     /**
-     * Render a page for the view technology supported by this page renderer
+     * Render a page with the default components for a application. An
-     * without any additional components.
+     * implementation of {@link #renderPage(org.libreccm.pagemodel.PageModel)}
-     * {@link #renderPage(org.libreccm.pagemodel.PageModel)} should use this
+     * should use this method for creating the default page.
-     * method for creating the default page.
+     *
+     * The result of the rendering process is a map with the values of the
+     * {@link ComponentModel#key} property as key and the result of rendering
+     * the component as value.
      *
      * @param parameters Parameters provided by application which wants to
      *                   render a {@link PageModel}. The parameters are passed
@@ -49,10 +52,15 @@ public interface PageRenderer {
     Map<String, Object> renderPage(Map<String, Object> parameters);
 
     /**
-     * Render a page of type {@code P} using the provided {@link PageModel}.
+     * Render a page using the provided {@link PageModel}.
      * Implementations should call the implementation of {@link #renderPage()}
      * for creating the basic page with the default components.
      *
+     * The result of the rendering process is a map with the values of the
+     * {@link ComponentModel#key} property as key and the result of rendering
+     * the component as value.
+     *
+     *
      * @param pageModel  The {@link PageModel} from which the page is generated.
      * @param parameters Parameters provided by application which wants to
      *                   render a {@link PageModel}. The parameters are passed

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

@@ -20,15 +20,14 @@
  * <p>
  * The {@code pagemodel} packages provides an abstraction layer between the data
  * model of page and its generating components. This layer replaces the JSP
- * templates which were used in previous versions for this purpose.
+ * templates which were used in previous versions of CCM for this purpose.
  * </p>
  * <p>
  * The Page Model system allows it to specify which components are used on a
  * page and therefore which information is displayed on a page. It is intended
  * to be used for public pages (like the item page of a content item category
- * page in ccm-cms. The Page Model system uses data containers which are read by
+ * page in ccm-cms module. The Page Model system uses data containers which are
- * a renderer class. Because we are not using any active code in the page
+ * read by a renderer class.
- * models this avoids a potential attack point.
  * </p>
  * <p>
  * The central interface is the {@link org.libreccm.pagemodel.PageRenderer}
@@ -36,8 +35,9 @@
  * {@link org.libreccm.pagemodel.PageModel} and process it and create a page
  * from it using the view technology supported by the implementation.
  * {@code PageRenderer}s are CDI beans. Implementations can be retrieved using
- * the {@link org.libreccm.pagemodel.PageRendererManager#findPageRenderer(String, Class)} method.
+ * the
+ * {@link org.libreccm.pagemodel.PageRendererManager#findPageRenderer(String, Class)}
+ * method.
  * </p>
- *
  */
 package org.libreccm.pagemodel;

ccm-core/src/test/resources-wildfly-remote-h2-mem/scripts/create_ccm_core_schema.sql

@@ -530,10 +530,10 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         SETTING_ID bigint not null,
         CONFIGURATION_CLASS varchar(512) not null,
         NAME varchar(512) not null,
-        SETTING_VALUE_LONG bigint,
-        SETTING_VALUE_BIG_DECIMAL decimal(19,2),
-        SETTING_VALUE_DOUBLE double,
         SETTING_VALUE_STRING varchar(1024),
+        SETTING_VALUE_DOUBLE double,
+        SETTING_VALUE_BIG_DECIMAL decimal(19,2),
+        SETTING_VALUE_LONG bigint,
         SETTING_VALUE_BOOLEAN boolean,
         primary key (SETTING_ID)
     );

ccm-core/src/test/resources-wildfly-remote-pgsql/scripts/create_ccm_core_schema.sql

@@ -529,11 +529,11 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         SETTING_ID int8 not null,
         CONFIGURATION_CLASS varchar(512) not null,
         NAME varchar(512) not null,
-        SETTING_VALUE_BOOLEAN boolean,
+        SETTING_VALUE_STRING varchar(1024),
+        SETTING_VALUE_DOUBLE float8,
         SETTING_VALUE_BIG_DECIMAL numeric(19, 2),
         SETTING_VALUE_LONG int8,
-        SETTING_VALUE_DOUBLE float8,
+        SETTING_VALUE_BOOLEAN boolean,
-        SETTING_VALUE_STRING varchar(1024),
         primary key (SETTING_ID)
     );
 
@@ -554,6 +554,14 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         value varchar(255)
     );
 
+    create table CCM_CORE.SITES (
+        DEFAULT_SITE boolean,
+        DEFAULT_THEME varchar(255),
+        DOMAIN_OF_SITE varchar(255),
+        OBJECT_ID int8 not null,
+        primary key (OBJECT_ID)
+    );
+
     create table CCM_CORE.THREADS (
         OBJECT_ID int8 not null,
         ROOT_ID int8,
@@ -679,6 +687,9 @@ drop sequence if exists HIBERNATE_SEQUENCE;
     alter table CCM_CORE.SETTINGS 
         add constraint UK5whinfxdaepqs09e5ia9y71uk unique (CONFIGURATION_CLASS, NAME);
 
+    alter table CCM_CORE.SITES 
+        add constraint UK_kou1h4y4st2m173he44yy8grx unique (DOMAIN_OF_SITE);
+
     alter table CCM_CORE.WORKFLOW_TASK_COMMENTS 
         add constraint UK_4nnedf08odyjxalfkg16fmjoi unique (UUID);
 
@@ -1105,6 +1116,11 @@ drop sequence if exists HIBERNATE_SEQUENCE;
         foreign key (LIST_ID) 
         references CCM_CORE.SETTINGS;
 
+    alter table CCM_CORE.SITES 
+        add constraint FKrca95c6p023men53b8ayu26kp 
+        foreign key (OBJECT_ID) 
+        references CCM_CORE.CCM_OBJECTS;
+
     alter table CCM_CORE.THREADS 
         add constraint FKsx08mpwvwnw97uwdgjs76q39g 
         foreign key (ROOT_ID) 
@@ -1203,3 +1219,4 @@ drop sequence if exists HIBERNATE_SEQUENCE;
     alter table CCM_CORE.WORKFLOWS 
         add constraint FK9ray5beiny6wm2mi0uwyecay2 
         foreign key (TEMPLATE_ID) 
+        references CCM_CORE.WORKFLOWS;