CCM NG: JavaDoc for the Entity classes

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

ccm-core/src/main/java/org/libreccm/categorization/Categorization.java

@@ -33,6 +33,9 @@ import org.libreccm.core.CcmObject;
 import java.util.Objects;
 
 /**
+ * Association class describing the association between a category and an 
+ * object. Instances of these class should not created manually. 
+ * The methods provided by the {@link CategoryManager} take care of that.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -42,20 +45,44 @@ public class Categorization implements Serializable {
 
     private static final long serialVersionUID = 201504301320L;
 
+    /**
+     * The ID of the categorisation object.
+     */
     @Id
     @Column(name = "categorization_id")
     @GeneratedValue(strategy = GenerationType.AUTO)
     private long categorizationId;
 
+    /**
+     * The category to which this {@code Categorization} object belongs.
+     */
     @ManyToOne
     private Category category;
 
+    /**
+     * The categorised object.
+     */
     @ManyToOne
     private CcmObject categorizedObject;
 
+    /**
+     * If the categorised object is the index object of the category this
+     * property is set to {@code true}.
+     */
+    @Column(name = "index")
+    private boolean index;
+
+    /**
+     * Defines the order in which the categories assigned the the categorised 
+     * object are shown.
+     */
     @Column(name = "category_order")
     private long categoryOrder;
 
+    /**
+     * Defines the order in which the objects assigned to the category are 
+     * shown.
+     */
     @Column(name = "object_order")
     private long objectOrder;
 
@@ -83,6 +110,14 @@ public class Categorization implements Serializable {
         this.categorizedObject = categorizedObject;
     }
 
+    public boolean isIndex() {
+        return index;
+    }
+
+    public void setIndex(final boolean index) {
+        this.index = index;
+    }
+
     public long getCategoryOrder() {
         return categoryOrder;
     }
@@ -106,6 +141,7 @@ public class Categorization implements Serializable {
             = 89 * hash + (int) (categorizationId ^ (categorizationId >>> 32));
         hash = 89 * hash + Objects.hashCode(category);
         hash = 89 * hash + Objects.hashCode(categorizedObject);
+        hash = 89 * hash + (index ? 1 : 0);
         hash = 89 * hash + (int) (categoryOrder ^ (categoryOrder >>> 32));
         hash = 89 * hash + (int) (objectOrder ^ (objectOrder >>> 32));
         return hash;
@@ -133,6 +169,11 @@ public class Categorization implements Serializable {
         if (!Objects.equals(categorizedObject, other.getCategorizedObject())) {
             return false;
         }
+
+        if (index != other.isIndex()) {
+            return false;
+        }
+
         if (categoryOrder != other.getCategoryOrder()) {
             return false;
         }
@@ -153,6 +194,7 @@ public class Categorization implements Serializable {
                                  + "categorizationId = %d, "
                                  + "category = %s, "
                                  + "categorizedObject = %s, "
+                                 + "index = %b,"
                                  + "categoryOrder = %d, "
                                  + "objectOrder = %d"
                                  + "%s }",
@@ -160,8 +202,10 @@ public class Categorization implements Serializable {
                              categorizationId,
                              Objects.toString(category),
                              Objects.toString(categorizedObject),
+                             index,
                              categoryOrder,
-                             objectOrder);
+                             objectOrder,
+                             data);
     }
 
 }

ccm-core/src/main/java/org/libreccm/categorization/Category.java

@@ -41,6 +41,14 @@ import javax.persistence.ManyToOne;
 import javax.persistence.OneToMany;
 
 /**
+ * The category entity represents a single category. Each category is part
+ * of a {@link Domain}. A category can be assigned to multiple 
+ * {@link CcmObject}s.
+ * 
+ * In the old structure the properties of this class were split between the
+ * {@code Category} entity from {@code ccm-core} and the {@code Term} entity 
+ * from {@code ccm-ldn-terms}. This class unifies the properties of these two 
+ * classes.
  * 
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -50,12 +58,23 @@ public class Category extends CcmObject implements Serializable {
 
     private static final long serialVersionUID = -7250208963391878547L;
 
+    /**
+     * A unique ID for the category. This ID will be the same even the same
+     * category system/domain is used in different installations.
+     */
     @Column(name = "unique_id", nullable = false)
     private String uniqueId;
 
+    /**
+     * The name of the category. This is used as URL stub, therefore only 
+     * the characters a to z, A to Z and 0 to 9 are allowed.
+     */
     @Column(name = "name", nullable = false)
     private String name;
 
+    /**
+     * The human readable and localisable title of the category.
+     */
     @Embedded
     @AssociationOverride(
         name = "values",
@@ -65,6 +84,9 @@ public class Category extends CcmObject implements Serializable {
         ))
     private LocalizedString title;
 
+    /**
+     * A localisable description of the category.
+     */
     @Embedded
     @AssociationOverride(
         name = "values",
@@ -74,25 +96,50 @@ public class Category extends CcmObject implements Serializable {
         ))
     private LocalizedString description;
 
+    /**
+     * Defines if the category is enabled. If the category is <em>not</em> 
+     * enabled, the category can't be used in any way.
+     */
     @Column(name = "enabled")
     private boolean enabled;
 
+    /**
+     * Defines if the category is visible. A category which is <em>not</em>
+     * visible should be only visible in the backend but not in the frontend.
+     */
     @Column(name = "visible")
     private boolean visible;
 
+    /**
+     * Defines if the category is abstract. It is not possible to add
+     * objects to an abstract category. 
+     */
     @Column(name = "abstract_category")
     private boolean abstractCategory;
 
+    /**
+     * The objects assigned to this category.
+     */
     @OneToMany(mappedBy = "category")
     private List<Categorization> objects;
 
+    /**
+     * The sub categories of this category.
+     */
     @OneToMany(mappedBy = "parentCategory")
     private List<Category> subCategories;
 
+    /**
+     * The parent category category of this category. Despite the root category
+     * of domain every category has a parent category.
+     */
     @ManyToOne
     @JoinColumn(name = "parent_category_id")
     private Category parentCategory;
 
+    /**
+     * Numeric value to define the order of the categories.
+     */
     @Column(name = "category_order")
     private long categoryOrder;
 
@@ -152,6 +199,13 @@ public class Category extends CcmObject implements Serializable {
         this.abstractCategory = abstractCategory;
     }
 
+    /**
+     * Retrieves an <strong>unmodifiable</strong> list of the objects assigned
+     * to this category. To manage the assigned objects use the methods provided
+     * by the {@link CategoryManager}.
+     * 
+     * @return An unmodifiable list of objects assigned to this category.
+     */
     public List<Categorization> getObjects() {
         return Collections.unmodifiableList(objects);
     }
@@ -168,11 +222,23 @@ public class Category extends CcmObject implements Serializable {
         objects.remove(object);
     }
 
+    /**
+     * Retrieves an <strong>unmodifiable</strong> list of the sub categories of
+     *  this category. To manage the assigned objects use the methods provided
+     * by the {@link CategoryManager}.
+     * 
+     * @return An unmodifiable list of sub categories of this category.
+     */
     public List<Category> getSubCategories() {
         return Collections.unmodifiableList(subCategories);
     }
 
-    public void setSubCategories(final List<Category> subCategories) {
+    /**
+     * <strong>Internal</strong> setter for the list of sub categories.
+     * 
+     * @param subCategories The list of sub categories.
+     */
+    protected void setSubCategories(final List<Category> subCategories) {
         this.subCategories = subCategories;
     }
 

ccm-core/src/main/java/org/libreccm/categorization/Domain.java

@@ -41,6 +41,15 @@ import javax.persistence.Temporal;
 import javax.persistence.TemporalType;
 
 /**
+ * A domain is collection of categories designed a specific purpose. This 
+ * entity replaces the {@code Domain} entity from the old {@code ccm-ldn-terms}
+ * module as well as the {@code CategoryPurpose} entity from the old 
+ * {@code ccm-core module}.
+ * 
+ * A {@code Domain} can be mapped to multiple {@link CcmObject}s. Normally this
+ * is used to make a {@code Domain} available in a application. The 
+ * {@link CcmObject}s to which a {@code Domain} is mapped are called 
+ * <em>owners</em> of the domain.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -50,12 +59,33 @@ public class Domain extends CcmObject implements Serializable {
 
     private static final long serialVersionUID = 4012590760598188732L;
 
-    @Column(name = "domain_key", nullable = false, unique = true)
+    /**
+     * A unique identifier for the {@code Domain}. This should be short string
+     * without special characters or spaces, for example {@code APLAWS-NAV} or
+     * {@code MYNAV}.
+     */
+    @Column(name = "domain_key", nullable = false, unique = true, length = 255)
     private String domainKey;
 
-    @Column(name = "uri", nullable = false, unique = true)
+    /**
+     * An unique URI identifying the domain. It is not required that this domain
+     * points to a real resource, it primary purpose is provide a unique 
+     * identifier. for the domain. If you create your own category system you
+     * should use the top level domain of your organisation. Also the URI should
+     * include the domain key in lower case letters. For example if the domain 
+     * key is {@code EXAMPLE-NAV}, than the URI can be 
+     * 
+     * <pre>
+     * http://example.org/domains/example-nav
+     * </pre>
+     */
+    @Column(name = "uri", nullable = false, unique = true, length = 2048)
     private URI uri;
 
+    /**
+     * A human readable title for the {@code Domain}. The title can be 
+     * localised.
+     */
     @Embedded
     @AssociationOverride(
         name = "values",
@@ -64,6 +94,9 @@ public class Domain extends CcmObject implements Serializable {
                                    @JoinColumn(name = "object_id")}))
     private LocalizedString title;
     
+    /**
+     * A description of the domain. The description can be localised.
+     */
     @Embedded
     @AssociationOverride(
         name = "values",
@@ -72,17 +105,29 @@ public class Domain extends CcmObject implements Serializable {
                                    @JoinColumn(name = "object_id")}))
     private LocalizedString description;
     
+    /**
+     * A version string for the {@code Domain}.
+     */
     @Column(name = "version", nullable = false)
     private String version;
     
+    /**
+     * A timestamp for the release date of the {@code Domain}.
+     */
     @Column(name = "released")
     @Temporal(TemporalType.TIMESTAMP)
     private Date released;
     
+    /**
+     * The root category of the domain.
+     */
     @ManyToOne
     @JoinColumn(name = "root_category_id")
     private Category root;
     
+    /**
+     * The owners of the domain.
+     */
     @OneToMany(mappedBy = "domain")
     private List<DomainOwnership> owners;
 
@@ -142,18 +187,47 @@ public class Domain extends CcmObject implements Serializable {
         this.root = root;
     }
 
+    /**
+     * Returns an <strong>unmodifiable</strong> list of the owners of this
+     * {@code Domain}. To add or remove owners use the methods provided
+     * by the {@link DomainManager}.
+     * 
+     * @return An <strong>unmodifiable</strong> list of the owners of this 
+     * {@Domain}
+     * 
+     * @see #owners
+     */
     public List<DomainOwnership> getOwners() {
         return Collections.unmodifiableList(owners);
     }
 
+    /**
+     * <strong>Internal</strong> method for setting the list of owners.
+     * 
+     * @param owners A list of owners.
+     */
     protected void setOwners(final List<DomainOwnership> owners) {
         this.owners = owners;
     }
     
+    /**
+     * <strong>Internal</strong> method for adding a {@link DomainOwnership}. 
+     * To add or remove owners use the methods provided by the 
+     * {@link DomainManager}.
+     * 
+     * @param owner The domain ownership to add.
+     */
     protected void addOwner(final DomainOwnership owner) {
         owners.add(owner);
     }
     
+    /**
+     * <strong>Internal</strong> method for removing a {@link DomainOwnership}. 
+     * To add or remove owners use the methods provided by the 
+     * {@link DomainManager}.
+     * 
+     * @param owner The domain ownership to add.
+     */
     protected void removeOwner(final DomainOwnership owner) {
         owners.remove(owner);
     }

ccm-core/src/main/java/org/libreccm/categorization/DomainOwnership.java

@@ -30,6 +30,10 @@ import javax.persistence.Table;
 import org.libreccm.core.CcmObject;
 
 /**
+ * Association class for the association between a {@link Domain} and a 
+ * {@link CcmObject}. Instances of this class should not be created manually.
+ * Instead the methods provided by the {@link DomainManager} manager class 
+ * should be used.
  * 
  * @author <a href="jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -39,23 +43,43 @@ public class DomainOwnership implements Serializable {
 
     private static final long serialVersionUID = 201504301305L;
 
+    /**
+     * The ID of this domain ownership.
+     */
     @Id
     @Column(name = "ownership_id")
     @GeneratedValue(strategy = GenerationType.AUTO)
     private long ownershipId;
 
+    /**
+     * The {@link CcmObject} owning the {@link Domain}.
+     */
     @ManyToOne(optional = false)
     private CcmObject owner;
 
+    /**
+     * The {@link Domain} owned by the {@link CcmObject}.
+     */
     @ManyToOne(optional = false)
     private Domain domain;
 
+    /**
+     * The context for the domain mapping.
+     */
     @Column(name = "context")
     private String context;
 
+    /**
+     * Defines the order in which the owning {@link CcmObject}s of a 
+     * {@link Domain} are shown.
+     */
     @Column(name = "owner_order")
     private long ownerOrder;
 
+    /**
+     * Defines the order in which the {@link Domain}s owned by a 
+     * {@link CcmObject} are shown.
+     */
     @Column(name = "domain_order")
     private long domainOrder;
 

ccm-core/src/main/java/org/libreccm/core/CcmObject.java

@@ -112,7 +112,8 @@ public class CcmObject implements Serializable {
     }
     
     /**
-     * Getter for the list of owned domains.
+     * Gets an <strong>unmodifiable</strong> list of the domains which are owned
+     * by the {@code CcmObject}.
      * 
      * @return An unmodifiable list of the domain ownerships of this 
      * {@code CcmObject}. Might be {@code null} or empty.
@@ -132,8 +133,9 @@ public class CcmObject implements Serializable {
     
     /**
      * <strong>Internal</strong> method for  adding a domain ownership. 
-     * User should use the appropriate methods of the {@code CategoryManager} 
+     * Users should use the appropriate methods of the {@link DomainManager} 
-     * class.
+     * class to
+     * manage the {@link Domain}s assigned to {@code CcmObject}.
      * 
      * @param domain The domain ownership to add.
      */
@@ -143,26 +145,55 @@ public class CcmObject implements Serializable {
     
     /**
      * <strong>Internal</strong> method for removing a domain ownership. 
-     * User should use the appropriate methods of the {@code CategoryManager} 
+     * Users should use the appropriate methods of the {@link DomainManager} to
+     * manage the {@link Domain}s assigned to {@code CcmObject}.
      * 
-     * @param domain 
+     * @param domain The domain to remove.
      */
     protected void removeDomain(final DomainOwnership domain) {
         domains.remove(domain);
     }
 
+    /**
+     * Returns a <strong>unmodifiable</strong> list of the categories this 
+     * object is assigned to. To manage the categories of a {@code CcmObject}
+     * use the methods provided by the {@link CategoryManager} class.
+     * 
+     * @return An <strong>unmodifiable</strong> list of the categories of this
+     * {@code CcmObject}. Might be {@code null} or empty.
+     */
     public List<Categorization> getCategories() {
         return Collections.unmodifiableList(categories);
     }
 
+     /**
+     * Setter for the list of categories assigned to this {@code CcmObject}, 
+     * only for use by JPA. 
+     * 
+     * @param categories  A list of domain ownerships. 
+     */
     protected void setCategories(final List<Categorization> categories) {
         this.categories = categories;
     }
     
+    /**
+     * <strong>Internal</strong> method for  adding a category. 
+     * Users should use the appropriate methods of the {@link CategoryManager} 
+     * class to manage the categories assigned to a {@code CcmObject}.
+     * 
+     * @param category  The domain ownership to add.
+     */
     protected void addCategory(final Categorization category) {
         categories.add(category);
     }
     
+    /**
+     * <strong>Internal</strong> method for removing a assigned category. 
+     * Users should use the appropriate methods of the {@link CategoryManager} 
+     * to manage the categories assigned to a {@code CcmObject}.
+     * 
+     * @param category The assigned category to remove.
+     */
     protected void removeCategory(final Categorization category) {
         categories.remove(category);
     }