CCM NG: JavaDoc for Sites and PageModel

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

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

@@ -41,7 +41,7 @@ import javax.ws.rs.NotFoundException;
 
 import static org.librecms.pages.PagesConstants.*;
 
-import org.libreccm.pagemodel.RendersComponentModel;
+import org.libreccm.pagemodel.RendersComponent;
 
 /**
  * Renderer for the {@link CategorizedItemComponent}.
@@ -49,7 +49,7 @@ import org.libreccm.pagemodel.RendersComponentModel;
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped
-@RendersComponentModel(componentModel = CategorizedItemComponent.class)
+@RendersComponent(componentModel = CategorizedItemComponent.class)
 public class CategorizedItemComponentRenderer
     extends AbstractContentItemComponentRenderer<CategorizedItemComponent> {
 

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

@@ -40,7 +40,7 @@ import javax.transaction.Transactional;
 import static org.librecms.pages.PagesConstants.*;
 
 import org.libreccm.pagemodel.ComponentRenderer;
-import org.libreccm.pagemodel.RendersComponentModel;
+import org.libreccm.pagemodel.RendersComponent;
 
 /**
  * Renderer for the {@link CategoryTreeComponent}.
@@ -48,7 +48,7 @@ import org.libreccm.pagemodel.RendersComponentModel;
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped
-@RendersComponentModel(componentModel = CategoryTreeComponent.class)
+@RendersComponent(componentModel = CategoryTreeComponent.class)
 public class CategoryTreeComponentRenderer
     implements ComponentRenderer<CategoryTreeComponent> {
 

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

@@ -28,7 +28,7 @@ import javax.enterprise.context.RequestScoped;
 import javax.inject.Inject;
 import javax.ws.rs.NotFoundException;
 
-import org.libreccm.pagemodel.RendersComponentModel;
+import org.libreccm.pagemodel.RendersComponent;
 
 /**
  * Renderer for the {@link FixedContentItemComponent}.
@@ -36,7 +36,7 @@ import org.libreccm.pagemodel.RendersComponentModel;
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped
-@RendersComponentModel(componentModel = FixedContentItemComponent.class)
+@RendersComponent(componentModel = FixedContentItemComponent.class)
 public class FixedContentItemComponentRenderer
     extends AbstractContentItemComponentRenderer<FixedContentItemComponent> {
 

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

@@ -34,7 +34,7 @@ import javax.ws.rs.NotFoundException;
 
 import static org.librecms.pages.PagesConstants.*;
 
-import org.libreccm.pagemodel.RendersComponentModel;
+import org.libreccm.pagemodel.RendersComponent;
 
 /**
  * Renderer for the {@link GreetingItemComponent}.
@@ -42,7 +42,7 @@ import org.libreccm.pagemodel.RendersComponentModel;
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped
-@RendersComponentModel(componentModel = GreetingItemComponent.class)
+@RendersComponent(componentModel = GreetingItemComponent.class)
 public class GreetingItemComponentRenderer
     extends AbstractContentItemComponentRenderer<GreetingItemComponent> {
 

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

@@ -53,7 +53,7 @@ import javax.servlet.http.HttpServletRequest;
 
 import static org.librecms.pages.PagesConstants.*;
 
-import org.libreccm.pagemodel.RendersComponentModel;
+import org.libreccm.pagemodel.RendersComponent;
 
 /**
  * Renderer for the {@link ItemListComponent}.
@@ -61,7 +61,7 @@ import org.libreccm.pagemodel.RendersComponentModel;
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
 @RequestScoped
-@RendersComponentModel(componentModel = ItemListComponent.class)
+@RendersComponent(componentModel = ItemListComponent.class)
 public class ItemListComponentRenderer
     implements ComponentRenderer<ItemListComponent> {
 

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

@@ -59,7 +59,7 @@ public class PagesManager implements Serializable {
         pages.setCategoryDomain(domain);
         pagesRepo.save(pages);
 
-        siteManager.addApplicationToSite(site, pages);
+        siteManager.addApplicationToSite(pages, site);
 
         return pages;
     }

ccm-core/src/main/java/com/arsdigita/ui/admin/sites/SitesController.java

@@ -30,6 +30,7 @@ import javax.inject.Inject;
 import javax.transaction.Transactional;
 
 /**
+ * Controller for the Admin UI for {@link Site}s.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -41,6 +42,12 @@ class SitesController implements Serializable {
     @Inject
     private SiteRepository sitesRepo;
 
+    /**
+     * Find all sites and transform into {@link SitesTableRow} objects. Also takes
+     * care of loading are required lazily fetched properties.
+     * 
+     * @return A list with the data about all available {@link Site}s.
+     */
     @Transactional(Transactional.TxType.REQUIRED)
     protected List<SitesTableRow> findSites() {
 

ccm-core/src/main/java/com/arsdigita/ui/admin/sites/SitesForm.java

@@ -49,6 +49,7 @@ import java.util.TooManyListenersException;
 import static com.arsdigita.ui.admin.AdminUiConstants.*;
 
 /**
+ * Form for editing/creating a {@link Site}.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/com/arsdigita/ui/admin/sites/SitesTab.java

@@ -30,6 +30,7 @@ import com.arsdigita.toolbox.ui.LayoutPanel;
 import static com.arsdigita.ui.admin.AdminUiConstants.*;
 
 /**
+ * Tab for {@code /ccm/admin} containing the Admin UI for {@link Site}s.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/com/arsdigita/ui/admin/sites/SitesTable.java

@@ -44,6 +44,8 @@ import java.util.List;
 import static com.arsdigita.ui.admin.AdminUiConstants.*;
 
 /**
+ * Table which displays data about all available {@link Site}s and provides
+ * links for editing and deleting them.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

ccm-core/src/main/java/com/arsdigita/ui/admin/sites/SitesTableRow.java

@@ -24,6 +24,7 @@ import java.util.Collections;
 import java.util.List;
 
 /**
+ * Contains all data for one row of the {@link SitesTable}.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */

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

@@ -92,11 +92,11 @@ public class ComponentRendererManager {
     }
 
     /**
-     * Annotation literal for the {@link RendersComponentModel} annotation.
+     * Annotation literal for the {@link RendersComponent} annotation.
      */
     private static class ComponentModelTypeLiteral
-        extends AnnotationLiteral<RendersComponentModel>
+        extends AnnotationLiteral<RendersComponent>
-        implements RendersComponentModel {
+        implements RendersComponent {
 
         private static final long serialVersionUID = -2601632434295178600L;
 

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

@@ -33,7 +33,7 @@ import java.lang.annotation.Target;
 @Qualifier
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
-public @interface RendersComponentModel {
+public @interface RendersComponent {
 
     Class<? extends ComponentModel> componentModel();
 

ccm-core/src/main/java/org/libreccm/sites/Site.java

@@ -21,6 +21,7 @@ package org.libreccm.sites;
 import static org.libreccm.core.CoreConstants.*;
 
 import org.libreccm.core.CcmObject;
+import org.libreccm.theming.Themes;
 
 import java.util.ArrayList;
 import java.util.Collections;
@@ -35,6 +36,7 @@ import javax.persistence.OneToMany;
 import javax.persistence.Table;
 
 /**
+ * An entity for storing the data about a site/virtual host.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -50,7 +52,9 @@ import javax.persistence.Table;
     ,
     @NamedQuery(
         name = "Site.findDefaultSite",
-        query = "SELECT s FROM Site s WHERE s.defaultSite = true"
+        query = "SELECT s FROM Site s "
+                    + "WHERE s.defaultSite = true "
+                    + "ORDER BY s.domain"
     )
     ,
     @NamedQuery(
@@ -63,15 +67,32 @@ public class Site extends CcmObject {
 
     private static final long serialVersionUID = 7993361616050713139L;
 
+    /**
+     * The domain of the site, e.g. {@code www.example.org}.
+     */
     @Column(name = "DOMAIN_OF_SITE", unique = true)
     private String domainOfSite;
 
+    /**
+     * A boolean indicating that the instance is the default site to use if
+     * there is no site with a matching domain.
+     */
     @Column(name = "DEFAULT_SITE")
     private boolean defaultSite;
 
+    /**
+     * The name of the default theme for the site. The default theme is used
+     * when no specific theme is requested. We can't use a reference to some
+     * entity here because not all themes have a representation in the database.
+     *
+     * @see Themes
+     */
     @Column(name = "DEFAULT_THEME")
     private String defaultTheme;
 
+    /**
+     * The applications mapped to this site.
+     */
     @OneToMany(mappedBy = "site")
     private List<SiteAwareApplication> applications;
 

ccm-core/src/main/java/org/libreccm/sites/SiteAwareApplication.java

@@ -31,6 +31,16 @@ import javax.persistence.ManyToOne;
 import javax.persistence.Table;
 
 /**
+ * A subtype of {@link CcmApplication} which can be associated with a
+ * {@link Site}.
+ *
+ * Only applications which are different for each site should extend this class.
+ * For example for the Admin application or the Content Center application
+ * provided by the ccm-cms module it makes to sense to make them site aware.
+ * This applications are used to manage objects which are shared by all sites.
+ * Other applications like the Pages application provided by ccm-cms module are
+ * of course site aware. The Pages application for example manages the page tree
+ * of one specific site.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -40,6 +50,9 @@ public class SiteAwareApplication extends CcmApplication {
 
     private static final long serialVersionUID = -8892544588904174406L;
 
+    /**
+     * The {@link Site} with which the application is associated.
+     */
     @ManyToOne(cascade = {CascadeType.PERSIST, CascadeType.MERGE})
     @JoinColumn(name = "SITE_ID")
     private Site site;

ccm-core/src/main/java/org/libreccm/sites/SiteManager.java

@@ -30,6 +30,7 @@ import javax.inject.Inject;
 import javax.transaction.Transactional;
 
 /**
+ * Manages {@link Site} entities.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -44,10 +45,16 @@ public class SiteManager implements Serializable {
     @Inject
     private SiteRepository siteRepo;
 
+    /**
+     * Adds an instance of {@link SiteAwareApplication} to a {@link Site}.
+     *
+     * @param application The application to associate with the site.
+     * @param site        The site to which the application instance is added.
+     */
     @RequiresPrivilege(PRIVILEGE_ADMIN)
     @Transactional(Transactional.TxType.REQUIRED)
-    public void addApplicationToSite(final Site site, 
+    public void addApplicationToSite(final SiteAwareApplication application,
-                                     final SiteAwareApplication application) {
+                                     final Site site) {
 
         site.addApplication(application);
         application.setSite(site);
@@ -56,10 +63,17 @@ public class SiteManager implements Serializable {
         applicationRepo.save(application);
     }
 
+    /**
+     * Removes an application from a site. The application instance is
+     * <em>not</em> deleted!
+     *
+     * @param application The application to remove from the site.
+     * @param site        The site from which the application is removed.
+     */
     @RequiresPrivilege(PRIVILEGE_ADMIN)
     @Transactional(Transactional.TxType.REQUIRED)
-    public void removeApplicationFromSite(final Site site,
+    public void removeApplicationFromSite(final SiteAwareApplication application,
-                                     final SiteAwareApplication application) {
+                                          final Site site) {
 
         site.removeApplication(application);
         application.setSite(null);

ccm-core/src/main/java/org/libreccm/sites/SiteRepository.java

@@ -22,6 +22,7 @@ import org.libreccm.core.AbstractEntityRepository;
 import org.libreccm.core.CoreConstants;
 import org.libreccm.security.RequiresPrivilege;
 
+import java.util.List;
 import java.util.Optional;
 import java.util.UUID;
 
@@ -31,6 +32,7 @@ import javax.persistence.TypedQuery;
 import javax.transaction.Transactional;
 
 /**
+ * Repository for {@link Site} entities.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -39,6 +41,16 @@ public class SiteRepository extends AbstractEntityRepository<Long, Site> {
 
     private static final long serialVersionUID = 3120528987720524155L;
 
+    /**
+     * Retrieve the {@link Site} for a specific domain.
+     *
+     * @param domain The domain of site to retrieve.
+     *
+     * @return If there is a {@link Site} for the provided domain an
+     *         {@link Optional} containing the {@link Site} is returned. If
+     *         there is not matching {@link Site} an empty {@link Optional} is
+     *         returned.
+     */
     @Transactional(Transactional.TxType.REQUIRED)
     public Optional<Site> findByDomain(final String domain) {
 
@@ -53,18 +65,36 @@ public class SiteRepository extends AbstractEntityRepository<Long, Site> {
         }
     }
 
+    /**
+     * Finds the default site.
+     *
+     * @return An {@link Optional} containing the default site. If there is no
+     *         default site an empty {@link Optional} is returned. If there
+     *         multiple {@link Site}s marked as default site (which should not
+     *         happen) the first result is returned (the list is ordered by the
+     *         domain).
+     */
     @Transactional(Transactional.TxType.REQUIRED)
     public Optional<Site> findDefaultSite() {
         final TypedQuery<Site> query = getEntityManager()
             .createNamedQuery("Site.findDefaultSite", Site.class);
 
-        try {
+        final List<Site> result = query.getResultList();
-            return Optional.of(query.getSingleResult());
+        if (result.isEmpty()) {
-        } catch (NoResultException ex) {
             return Optional.empty();
+        } else {
+            return Optional.of(result.get(0));
         }
     }
 
+    /**
+     * Checks if there is a {@link Site} for a domain.
+     *
+     * @param domain The domain to check for.
+     *
+     * @return {@code true} if there is a {@link Site} for that domain,
+     *         {@code false} otherwise.
+     */
     @Transactional(Transactional.TxType.REQUIRED)
     public boolean hasSiteForDomain(final String domain) {
 

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

@@ -0,0 +1,30 @@
+/*
+ * Copyright (C) 2017 LibreCCM Foundation.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+ * MA 02110-1301  USA
+ */
+/**
+ * This packages provides several classes for managing sites or virtual hosts
+ * in CCM. In some way this replaces the old Subsite module which was available
+ * for previous versions. On the other hand there are several differences.
+ *
+ * The most important difference is that the classes in this package do not hook
+ * into the request/response cycle
+ * like the old Subsite module. Instead a subclass of {@link CcmApplication}
+ * class ({@link SiteAwareApplication}) is provided. The application itself is
+ * responsible for interpreting the site specific parts.
+ */
+package org.libreccm.sites;