CCM NG: JavaDoc for the Pages application and some code cleanup.

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

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

@@ -19,6 +19,7 @@
 package org.librecms.pages;
 
 import org.libreccm.pagemodel.AbstractPageRenderer;
+import org.libreccm.pagemodel.PageRenderer;
 
 import java.util.HashMap;
 import java.util.Map;
@@ -26,11 +27,12 @@ import java.util.Map;
 import javax.enterprise.context.RequestScoped;
 
 /**
+ * Implementation of {@link PageRenderer} for CMS pages.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped
-public class CmsPageBuilder extends AbstractPageRenderer {
+public class CmsPageRenderer extends AbstractPageRenderer {
 
     @Override
     public Map<String, Object> renderPage(final Map<String, Object> parameters) {

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

@@ -52,7 +52,8 @@ public class PageManager {
      * 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}.
+     * @param category The {@link Category} which is associated with the
+     *                 {@link Page}.
      *
      * @return The {@link Page} associated with the provided {@code category}.
      */
@@ -79,20 +80,32 @@ public class PageManager {
     }
 
     /**
-     * Create 
+     * Creates a new {@link Page} entity for a {@link Category} if there is no
-     * @param category
+     * page for that category yet.
-     * @return 
+     *
+     * @param category The category for which the new {@link Page} is created.
+     *
+     * @return A new {@link Page} if there is no {@link Page} for the provided 
+     * {@code category}. If there is already a {@link Page} for that category
+     * the existing {@link Page} is returned.
      */
     @Transactional(Transactional.TxType.REQUIRED)
     public Page createPageForCategory(final Category category) {
 
-        final Page page = new Page();
+        final Optional<Page> pageForCategory = pageRepo
-        pageRepo.save(page);
+            .findPageForCategory(category);
-        categoryManager.addObjectToCategory(page, 
-                                            category, 
-                                            CATEGORIZATION_TYPE_PAGE_CONF);
 
-        return page;
+        if (pageForCategory.isPresent()) {
+            return pageForCategory.get();
+        } else {
+            final Page page = new Page();
+            pageRepo.save(page);
+            categoryManager.addObjectToCategory(page,
+                                                category,
+                                                CATEGORIZATION_TYPE_PAGE_CONF);
+
+            return page;
+        }
     }
 
 }

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

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

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

@@ -26,6 +26,9 @@ import org.libreccm.web.CcmApplication;
 import javax.inject.Inject;
 
 /**
+ * Implementation of {@link ApplicationCreator} for the {@link Pages} application.
+ * 
+ * Used in by the administration UI.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

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

@@ -24,6 +24,7 @@ import org.libreccm.sites.Site;
 import org.libreccm.sites.SiteManager;
 
 import java.io.Serializable;
+import java.util.Objects;
 
 import javax.enterprise.context.RequestScoped;
 import javax.inject.Inject;
@@ -45,12 +46,31 @@ public class PagesManager implements Serializable {
     @Inject
     private SiteManager siteManager;
 
+    /**
+     * Creates a new {@link Pages} instance.
+     *
+     * @param primaryUrl The primary URL under which the Admin UI for the
+     *                   instance will be available ({@code /ccm/{primaryUrl})
+     * @param site       The {@link Site} with which the new {@link Pages} is associated.
+     * @param domain     The category system which used to model the page tree
+     *                   of the new {@link Pages} instance.
+     *
+     * @return The new {@link Pages} instance.
+     */
     @RequiresPrivilege(PagesPrivileges.ADMINISTER_PAGES)
     @Transactional(Transactional.TxType.REQUIRED)
     public Pages createPages(final String primaryUrl,
                              final Site site,
                              final Domain domain) {
 
+        Objects.requireNonNull(primaryUrl);
+        Objects.requireNonNull(site);
+        Objects.requireNonNull(domain);
+
+        if (primaryUrl.isEmpty() || primaryUrl.matches("\\s*")) {
+            throw new IllegalArgumentException("The primaryUrl can't be empty.");
+        }
+
         final Pages pages = new Pages();
         pages.setPrimaryUrl(primaryUrl);
 

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

@@ -74,7 +74,7 @@ public class PagesRouter {
     private GlobalizationHelper globalizationHelper;
 
     @Inject
-    private CmsPageBuilder pageBuilder;
+    private CmsPageRenderer pageBuilder;
 
     @Inject
     private PagesRepository pagesRepo;
@@ -226,7 +226,7 @@ public class PagesRouter {
      * @return
      */
     @Path("/index.{lang}.json")
-    @Produces("text/html")
+    @Produces("text/json")
     @Transactional(Transactional.TxType.REQUIRED)
     public Map<String, Object> getCategoryIndexPageAsJson(
         @Context
@@ -253,7 +253,7 @@ public class PagesRouter {
      * @return
      */
     @Path("/index.{lang}.xml")
-    @Produces("text/html")
+    @Produces("text/xml")
     @Transactional(Transactional.TxType.REQUIRED)
     public Map<String, Object> getCategoryIndexPageAsXml(
         @Context
@@ -320,7 +320,7 @@ public class PagesRouter {
      *
      * @return
      */
-    @Path("/{name},html")
+    @Path("/{name}.html")
     public Response getItemPageAsHtml(
         @Context final UriInfo uriInfo,
         @PathParam("page") final String page,
@@ -405,7 +405,8 @@ public class PagesRouter {
      *
      * @return
      */
-    @Path("/{name}.{lang}.html")
+    @Path("/{name}.{lang}.json")
+    @Produces("text/json")
     public Map<String, Object> getItemPageAsJson(
         @Context
         final UriInfo uriInfo,
@@ -438,7 +439,8 @@ public class PagesRouter {
      *
      * @return
      */
-    @Path("/{name}.{lang}.html")
+    @Path("/{name}.{lang}.xml")
+    @Produces("text/xml")
     public Map<String, Object> getItemPageAsXml(
         @Context
         final UriInfo uriInfo,

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

@@ -40,6 +40,8 @@ import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
 /**
+ * Servlet for the Admin UI for pages a {@link /ccm/{primaryUrl}}. The admin UI
+ * itself is implemented by {@link PagesAdminPage}.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -77,25 +79,6 @@ public class PagesServlet extends BaseApplicationServlet {
 
         final PagesAdminPage page = new PagesAdminPage();
 
-//        final URL originalUrl = (URL) request
-//            .getAttribute(BaseServlet.REQUEST_URL_ATTRIBUTE);
-//        final String pathInfo = originalUrl.getPathInfo();
-
-//        final String appPath;
-//        if (pathInfo.startsWith("/") && pathInfo.endsWith("/")) {
-//            appPath = pathInfo.substring(1, pathInfo.length() - 1);
-//        } else if (pathInfo.startsWith("/")) {
-//            appPath = pathInfo.substring(1);
-//        } else if (pathInfo.endsWith("/")) {
-//            appPath = pathInfo.substring(pathInfo.length() - 1);
-//        } else {
-//            appPath = pathInfo;
-//        }
-//
-//        final CcmApplication application = applicationRepo
-//            .retrieveApplicationForPath(appPath)
-//            .orElseThrow(() -> new ServletException(String
-//            .format("No application for path %s", appPath)));
         if (!(application instanceof Pages)) {
             throw new ServletException(
                 "Provided application is not an instance of Pages");

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

@@ -25,7 +25,7 @@ import javax.persistence.Column;
 import javax.persistence.Embeddable;
 
 /**
- * Configuration for the {@link Page} and a {@link Site}.
+ * Theme configuration for the {@link Page} and a {@link Site}.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */