From 307999c68b31d85499dbaf17491d015749ceb1c2 Mon Sep 17 00:00:00 2001 From: jensp Date: Fri, 8 May 2015 16:01:21 +0000 Subject: [PATCH] CCM NG: JavaDoc for the Entity classes git-svn-id: https://svn.libreccm.org/ccm/jpa@3385 8810af33-2d31-482b-a856-94f89814c4df --- .../categorization/Categorization.java | 48 +++++++++++- .../org/libreccm/categorization/Category.java | 70 ++++++++++++++++- .../org/libreccm/categorization/Domain.java | 78 ++++++++++++++++++- .../categorization/DomainOwnership.java | 26 ++++++- .../java/org/libreccm/core/CcmObject.java | 41 ++++++++-- 5 files changed, 251 insertions(+), 12 deletions(-) diff --git a/ccm-core/src/main/java/org/libreccm/categorization/Categorization.java b/ccm-core/src/main/java/org/libreccm/categorization/Categorization.java index fd7f82bf4..d358b7e67 100644 --- a/ccm-core/src/main/java/org/libreccm/categorization/Categorization.java +++ b/ccm-core/src/main/java/org/libreccm/categorization/Categorization.java @@ -33,7 +33,10 @@ 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 Jens Pelzetter */ @Entity @@ -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); } } diff --git a/ccm-core/src/main/java/org/libreccm/categorization/Category.java b/ccm-core/src/main/java/org/libreccm/categorization/Category.java index a9b7f39ad..2e554339f 100644 --- a/ccm-core/src/main/java/org/libreccm/categorization/Category.java +++ b/ccm-core/src/main/java/org/libreccm/categorization/Category.java @@ -41,7 +41,15 @@ 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 Jens Pelzetter */ @Entity @@ -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 not + * 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 not + * 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 objects; + /** + * The sub categories of this category. + */ @OneToMany(mappedBy = "parentCategory") private List 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 unmodifiable 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 getObjects() { return Collections.unmodifiableList(objects); } @@ -168,11 +222,23 @@ public class Category extends CcmObject implements Serializable { objects.remove(object); } + /** + * Retrieves an unmodifiable 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 getSubCategories() { return Collections.unmodifiableList(subCategories); } - public void setSubCategories(final List subCategories) { + /** + * Internal setter for the list of sub categories. + * + * @param subCategories The list of sub categories. + */ + protected void setSubCategories(final List subCategories) { this.subCategories = subCategories; } diff --git a/ccm-core/src/main/java/org/libreccm/categorization/Domain.java b/ccm-core/src/main/java/org/libreccm/categorization/Domain.java index 573ddd1d2..97c3c27c9 100644 --- a/ccm-core/src/main/java/org/libreccm/categorization/Domain.java +++ b/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 + * owners of the domain. * * @author Jens Pelzetter */ @@ -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 + * + * 
+     * http://example.org/domains/example-nav
+     *
+ */ + @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 owners; @@ -142,18 +187,47 @@ public class Domain extends CcmObject implements Serializable { this.root = root; } + /** + * Returns an unmodifiable list of the owners of this + * {@code Domain}. To add or remove owners use the methods provided + * by the {@link DomainManager}. + * + * @return An unmodifiable list of the owners of this + * {@Domain} + * + * @see #owners + */ public List getOwners() { return Collections.unmodifiableList(owners); } + /** + * Internal method for setting the list of owners. + * + * @param owners A list of owners. + */ protected void setOwners(final List owners) { this.owners = owners; } + /** + * Internal 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); } + /** + * Internal 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); } diff --git a/ccm-core/src/main/java/org/libreccm/categorization/DomainOwnership.java b/ccm-core/src/main/java/org/libreccm/categorization/DomainOwnership.java index 15133eea3..b13123a98 100644 --- a/ccm-core/src/main/java/org/libreccm/categorization/DomainOwnership.java +++ b/ccm-core/src/main/java/org/libreccm/categorization/DomainOwnership.java @@ -30,7 +30,11 @@ 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 Jens Pelzetter */ @Entity @@ -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; diff --git a/ccm-core/src/main/java/org/libreccm/core/CcmObject.java b/ccm-core/src/main/java/org/libreccm/core/CcmObject.java index b0bf4f1c2..1562189af 100644 --- a/ccm-core/src/main/java/org/libreccm/core/CcmObject.java +++ b/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 unmodifiable 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 { /** * Internal method for adding a domain ownership. - * User should use the appropriate methods of the {@code CategoryManager} - * class. + * Users should use the appropriate methods of the {@link DomainManager} + * 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 { /** * Internal 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 unmodifiable 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 unmodifiable list of the categories of this + * {@code CcmObject}. Might be {@code null} or empty. + */ public List 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 categories) { this.categories = categories; } + /** + * Internal 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); } + /** + * Internal 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); }