CCM NG: More JavaDoc for PageModel

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

Former-commit-id: 5fd3824c46

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

@@ -50,6 +50,10 @@ import javax.validation.constraints.NotNull;
  * a page. The {@code PageModel} specifics which components are used on a page.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
+ *
+ * @see PageModelRepository
+ * @see PageModelManager
+ * @see PageBuilder
  */
 @Entity
 @Table(name = "PAGE_MODELS", schema = CoreConstants.DB_SCHEMA)
@@ -76,49 +80,77 @@ import javax.validation.constraints.NotNull;
     ,
     @NamedQuery(
             name = "PageModel.findByApplication",
-        query = "SELECT p FROM PageModel p WHERE p.application = :application")
+            query = "SELECT p FROM PageModel p "
+                            + "WHERE p.application = :application "
+                            + "AND p.version = org.libreccm.pagemodel.PageModelVersion.LIVE")
     ,
     @NamedQuery(
             name = "PageModel.countByApplication",
             query = "SELECT COUNT(p) FROM PageModel p "
-                    + "WHERE p.application = :application")
+                            + "WHERE p.application = :application "
+                            + "AND p.version = org.libreccm.pagemodel.PageModelVersion.LIVE")
     ,
     @NamedQuery(
             name = "PageModel.findByApplicationAndName",
             query = "SELECT p FROM PageModel p "
-                    + "WHERE p.name = :name AND p.application = :application"
+                            + "WHERE p.name = :name "
+                            + "AND p.application = :application "
+                            + "AND p.version = org.libreccm.pagemodel.PageModelVersion.LIVE"
     )
     ,
     @NamedQuery(
             name = "PageModel.countByApplicationAndName",
             query = "SELECT COUNT(p) FROM PageModel p "
-                    + "WHERE p.name = :name AND p.application = :application"
+                            + "WHERE p.name = :name "
+                            + "AND p.application = :application "
+                            + "AND p.version = org.libreccm.pagemodel.PageModelVersion.LIVE"
     )
 })
 public class PageModel implements Serializable {
 
     private static final long serialVersionUID = 7252512839926020978L;
 
+    /**
+     * The ID of the entity in the database.
+     */
     @Id
     @Column(name = "PAGE_MODEL_ID")
     @GeneratedValue(strategy = GenerationType.AUTO)
     private long pageModelId;
 
+    /**
+     * The UUID of this {@code PageModel}. Please note that this UUID identifies
+     * the dataset not the model. Therefore the draft and the live version have
+     * different values for this field.
+     */
     @Column(name = "UUID", length = 255, nullable = false)
     @NotNull
     private String uuid;
 
+    /**
+     * The UUID of the model. Same for draft and live version.
+     */
     @Column(name = "MODEL_UUID", length = 255, nullable = false)
     @NotNull
     private String modelUuid;
 
+    /**
+     * The name of this {@code PageModel}. Not localised, for use in URLs.
+     */
     @Column(name = "NAME", length = 255)
     private String name;
 
+    /**
+     * The version of this {@code PageModel}.
+     */
     @Column(name = "VERSION", length = 255, nullable = false)
     @Enumerated(EnumType.STRING)
     private PageModelVersion version;
 
+    /**
+     * The localised title of this {@code PageModel} (shown in the
+     * administration UI),
+     */
     @Embedded
     @AssociationOverride(
             name = "values",
@@ -129,6 +161,9 @@ public class PageModel implements Serializable {
                                    }))
     private LocalizedString title;
 
+    /**
+     * A description of this {@code PageModel} describing its purpose.
+     */
     @Embedded
     @AssociationOverride(
             name = "values",
@@ -139,14 +174,23 @@ public class PageModel implements Serializable {
                                    }))
     private LocalizedString description;
 
+    /**
+     * The application with which this {@code PageModel} is associated.
+     */
     @ManyToOne
     @JoinColumn(name = "APPLICATION_ID")
     private CcmApplication application;
 
+    /**
+     * The type of this {@code PageModel}.
+     */
     @Column(name = "TYPE", length = 255, nullable = false)
     @NotNull
     private String type;
 
+    /**
+     * The components of the page described by this {@code PageModel}.
+     */
     @OneToMany(mappedBy = "pageModel")
     private List<ComponentModel> components;
 

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

@@ -24,8 +24,11 @@ import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
+import java.util.ResourceBundle;
 
 /**
+ * Used in the description of {@link CcmModule} to specify which
+ * {@link ComponentModel}s are provided by an module.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -33,14 +36,44 @@ import java.lang.annotation.Target;
 @Target(ElementType.TYPE)
 public @interface PageModelComponentModel {
 
+    /**
+     * Fully qualified name of a resource bundle providing the title and
+     * description of the {@link ComponentModel}.
+     *
+     * @return The fully qualified name of the {@link ResourceBundle} which
+     * provides the title and description of the {@link ComponentModel}.
+     */
     String descBundle() default "";
 
+    /**
+     * Key for the title of the {@link ComponentModel} in the
+     * {@link ResourceBundle} specified by {@link #descBundle()}.
+     *
+     * @return The key for the title of the {@link ComponentModel}.
+     */
     String titleKey() default "component_model_title";
 
+    /**
+     * Key for the description of the {@link ComponentModel} in the
+     * {@link ResourceBundle} specified by {@link #descBundle()}.
+     *
+     * @return The key for the description of the {@link ComponentModel}.
+     */
     String descKey() default "component_model_desc";
 
+    /**
+     * The class which provides the {@link ComponentModel}.
+     *
+     * @return The class which provides the {@link ComponentModel}.
+     */
     Class<? extends ComponentModel> modelClass();
 
+    /**
+     * A (Bebop) form for editing the properties of an instance of the
+     * {@link ComponentModel}.
+     *
+     * @return A (Bebop) form for editing the {@code ComponentModel}.
+     */
     Class<? extends Form> editor();
 
 }

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

@@ -41,8 +41,6 @@ import java.util.Map;
 import java.util.Optional;
 import java.util.ServiceLoader;
 import java.util.Set;
-import java.util.logging.Level;
-import java.util.logging.Logger;
 
 import javax.annotation.PostConstruct;
 import javax.enterprise.context.RequestScoped;
@@ -52,6 +50,7 @@ import javax.persistence.TypedQuery;
 import javax.transaction.Transactional;
 
 /**
+ * Provides several methods for managing {@link PageModel}s.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -70,6 +69,11 @@ public class PageModelManager {
     private final Map<String, PageModelComponentModel> components
                                                        = new HashMap<>();
 
+    /**
+     * Called by CDI after an instance of this class is created. Initialises the
+     * {@link #components} by retrieving the data about all available
+     * {@link ComponentModel}s.
+     */
     @PostConstruct
     private void init() {
         final ServiceLoader<CcmModule> modules = ServiceLoader.load(
@@ -90,7 +94,11 @@ public class PageModelManager {
     }
 
     /**
-     * Creates a new {@link PageModel} for the provided application.
+     * Creates a new {@link PageModel} for the provided application. The 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.
      *
      * @param name The name of the new page model. Must be unique for the
      * application.
@@ -138,6 +146,15 @@ public class PageModelManager {
         return pageModel;
     }
 
+    /**
+     * Retrieves the draft version of a {@link PageModel}. To invoke this method
+     * the current user needs a permission granting the
+     * {@link CoreConstants#PRIVILEGE_ADMIN} privilege.
+     *
+     * @param pageModel The {@link PageModel} for which the draft version is
+     * retrieved.
+     * @return The draft version of the provided {@link PageModel}.
+     */
     @AuthorizationRequired
     @Transactional(Transactional.TxType.REQUIRED)
     public PageModel getDraftVersion(
@@ -156,6 +173,13 @@ public class PageModelManager {
         return query.getSingleResult();
     }
 
+    /**
+     * Checks if a {@link PageModel} has a live version.
+     *
+     * @param pageModel The {@link PageModel} to check for a live version.
+     * @return {@code true} if there is a live version for the provided
+     * {@link PageModel}, {@code false} otherwise.
+     */
     @Transactional(Transactional.TxType.REQUIRED)
     public boolean isLive(final PageModel pageModel) {
         final TypedQuery<Boolean> query = entityManager.createNamedQuery(
@@ -165,10 +189,13 @@ public class PageModelManager {
         return query.getSingleResult();
     }
 
-    @AuthorizationRequired
+    /**
+     *
+     * @param pageModel
+     * @return
+     */
     @Transactional(Transactional.TxType.REQUIRED)
-    public Optional<PageModel> getLiveVersion(
+    public Optional<PageModel> getLiveVersion(final PageModel pageModel) {
-        @RequiresPrivilege(CoreConstants.PRIVILEGE_ADMIN) PageModel pageModel) {
 
         if (isLive(pageModel)) {
             final TypedQuery<PageModel> query = entityManager.createNamedQuery(
@@ -208,9 +235,8 @@ public class PageModelManager {
         liveModel.setApplication(draftModel.getApplication());
         liveModel.setType(draftModel.getType());
 
-        
         liveModel.clearComponents();
-        for(final ComponentModel draft : draftModel.getComponents()) {
+        for (final ComponentModel draft : draftModel.getComponents()) {
             final ComponentModel live = publishComponentModel(draft);
             addComponentModel(liveModel, live);
         }
@@ -235,11 +261,12 @@ public class PageModelManager {
         final BeanInfo beanInfo;
         try {
             beanInfo = Introspector.getBeanInfo(clazz);
-        } catch(IntrospectionException ex) {
+        } catch (IntrospectionException ex) {
             throw new UncheckedWrapperException(ex);
         }
 
-        for(final PropertyDescriptor propertyDescriptor : beanInfo.getPropertyDescriptors()) {
+        for (final PropertyDescriptor propertyDescriptor : beanInfo.
+                getPropertyDescriptors()) {
             final Class<?> propType = propertyDescriptor.getPropertyType();
             final Method readMethod = propertyDescriptor.getReadMethod();
             final Method writeMethod = propertyDescriptor.getWriteMethod();
@@ -260,14 +287,14 @@ public class PageModelManager {
                 try {
                     source = (List<Object>) readMethod.invoke(draftModel);
                     target = (List<Object>) readMethod.invoke(liveModel);
-                } catch(IllegalAccessException 
+                } catch (IllegalAccessException
                                  | IllegalArgumentException
                                  | InvocationTargetException ex) {
                     throw new UncheckedWrapperException(ex);
                 }
 
                 target.addAll(source);
-            } else if(propType != null
+            } else if (propType != null
                                && propType.isAssignableFrom(Map.class)) {
 
                 final Map<Object, Object> source;
@@ -276,7 +303,7 @@ public class PageModelManager {
                 try {
                     source = (Map<Object, Object>) readMethod.invoke(draftModel);
                     target = (Map<Object, Object>) readMethod.invoke(liveModel);
-                } catch(IllegalAccessException
+                } catch (IllegalAccessException
                                  | IllegalArgumentException
                                  | InvocationTargetException ex) {
                     throw new UncheckedWrapperException(ex);
@@ -284,7 +311,7 @@ public class PageModelManager {
 
                 source.forEach((key, value) -> target.put(key, value));
 
-            } else if(propType != null 
+            } else if (propType != null
                                && propType.isAssignableFrom(Set.class)) {
 
                 final Set<Object> source;
@@ -293,7 +320,7 @@ public class PageModelManager {
                 try {
                     source = (Set<Object>) readMethod.invoke(draftModel);
                     target = (Set<Object>) readMethod.invoke(liveModel);
-                }catch(IllegalAccessException
+                } catch (IllegalAccessException
                                  | IllegalArgumentException
                                  | InvocationTargetException ex) {
                     throw new UncheckedWrapperException(ex);
@@ -305,7 +332,7 @@ public class PageModelManager {
                 try {
                     value = readMethod.invoke(draftModel);
                     writeMethod.invoke(liveModel, value);
-                } catch(IllegalAccessException 
+                } catch (IllegalAccessException
                                  | IllegalArgumentException
                                  | InvocationTargetException ex) {
                     throw new UncheckedWrapperException(ex);
@@ -325,7 +352,7 @@ public class PageModelManager {
         };
 
         boolean result = false;
-        for(final String current : excluded) {
+        for (final String current : excluded) {
             if (current.equals(name)) {
                 result = true;
                 break;
@@ -359,8 +386,7 @@ public class PageModelManager {
     /**
      * Add a {@link ComponentModel} to a {@link PageModel}.
      *
-     * @param pageModel      The {@link PageModel} to which component model is
+     * @param pageModel The {@link PageModel} to which component model is added.
-     *                       added.
      * @param componentModel The {@link ComponentModel} to add.
      */
     public void addComponentModel(final PageModel pageModel,