WIP: MetadataBlock refactoring

src/main/java/edu/harvard/iq/dataverse/DatasetField.java

@@ -5,10 +5,6 @@
  */
 package edu.harvard.iq.dataverse;
 
-/**
- *
- * @author skraffmiller
- */
 import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -35,6 +31,21 @@
 import jakarta.persistence.Transient;
 import org.apache.commons.lang3.StringUtils;
 
+/**
+ * A DatasetField describes a metadata property of a DatasetVersion (c.f. @DatasetVersion) (or Template (c.f. @Template)).
+ *
+ * A DatasetField has a unique identifier, a type (c.f @DatasetFieldType) and depending on the type none, one or multiple
+ * values. Possible values are single or multiple string values (c.f. @DatasetFieldValue) and single or multiple controlled
+ * vocabulary (c.f. @ControlledVocabularyValue) values (like enums). Furthermore, a DatasetField can be a compound
+ * (c.f. @DatasetFieldCompoundValue) and acts as a container for child DatasetField. Compounds do not carry a value
+ * themselves, values are encoded within the children (DatasetFields). More Information on the type definition can be
+ * found here (c.f @DatasetFieldType)
+ *
+ * DatasetFields and corresponding values (DatasetFieldValue, DatasetFieldCompoundValue, ControlledVocabularyValue) build
+ * the low level metadata storage API. Semantic meaning and structure are defined by DatasetFieldType and MetadataBlock.
+ *
+ * @author skraffmiller
+ */
 @Entity
 @ValidateDatasetFieldType
 @Table(indexes = {@Index(columnList="datasetfieldtype_id"),@Index(columnList="datasetversion_id"),

src/main/java/edu/harvard/iq/dataverse/DatasetFieldServiceBean.java

@@ -249,6 +249,13 @@ public DatasetFieldType save(DatasetFieldType dsfType) {
         return em.merge(dsfType);
     }
 
+    /**
+     * Not sure why this method is here, better use the metadataBlockServiceBean
+     * @param mdb
+     * @deprecated
+     * @return
+     */
+    @Deprecated
     public MetadataBlock save(MetadataBlock mdb) {
         return em.merge(mdb);
     }

src/main/java/edu/harvard/iq/dataverse/DatasetFieldType.java

@@ -17,7 +17,21 @@
 import jakarta.persistence.*;
 
 /**
- * Defines the meaning and constraints of a metadata field and its values.
+ * A DatasetFieldType belongs to a MetadataBlock (c.f. @MetadataBlock) and defines semantic meaning and constraints of a
+ * metadata property.
+ *
+ * Each DatasetFieldType is uniquely identifiable by an identifier and name (beware: globally unique name!) and defines
+ * instance-wide properties of a metadata item, like descriptive information and allowed values. DatasetFieldType allow
+ * the definition of tree like metadata structure via parent-child relationships. The domain model does not contain the
+ * nesting level. Nodes with children are called `compound` and act as a container, while leaves are named `primitive`.
+ * Only for the latter data capture and storage (c.f. @DatasetField) is possible, for the former not.
+ *
+ * The DatasetFieldType obligation (mandatory data capture or not) [c.f. #isRequired] and activation [c.f. #isIncluded]
+ * can be configured on a per dataverse level (c.f. @DataverseFieldTypeInputLevel). If configured this has precedence over
+ * the instance-wide DatasetFieldType definition. Similarly, search facet configuration can be overridden (c.f. DataverseFacet).
+ *
+ *
+ *
  * @author Stephen Kraffmiller
  */
 @NamedQueries({
@@ -87,9 +101,18 @@ public void setId(Long id) {
 
     private String validationFormat;
 
+    /**
+     * The user can configure facets and their order on a per dataverse basis.
+     * This member setups the needed connection in the domain model.
+     */
     @OneToMany(mappedBy = "datasetFieldType")
     private Set<DataverseFacet> dataverseFacets;
-
+
+    /**
+     * If the definition of the DatasetFieldType does not already define `required` the user can change the obligation per dataverse.
+     * Furthermore, the user can `hide` DatasetFields on a per dataverse basis.
+     * This member setups the needed connection in the domain model.
+     */
     @OneToMany(mappedBy = "datasetFieldType")
     private Set<DataverseFieldTypeInputLevel> dataverseFieldTypeInputLevels;
 
@@ -322,10 +345,10 @@ public JsonLDTerm getJsonLDTerm() {
     public void setUri(String uri) {
     	this.uri=uri;
     }
-    
+
     /**
-     * The list of controlled vocabulary terms that may be used as values for
-     * fields of this field type.
+     * If the definition of the DatasetFieldType includes a definition for a controlled Vocabulary, i.e. a list of allowed values.
+     * This member setups the needed connection in the domain model.
      */
    @OneToMany(mappedBy = "datasetFieldType", cascade = {CascadeType.REMOVE, CascadeType.MERGE, CascadeType.PERSIST})
    @OrderBy("displayOrder ASC")
@@ -356,6 +379,7 @@ public ControlledVocabularyValue getControlledVocabularyValue( String strValue )
      * Collection of field types that are children of this field type.
      * A field type may consist of one or more child field types, but only one
      * parent.
+     * Definition of the value via `parentDatasetFieldType`
      */
     @OneToMany(mappedBy = "parentDatasetFieldType", cascade = {CascadeType.REMOVE, CascadeType.MERGE, CascadeType.PERSIST})
     @OrderBy("displayOrder ASC")
@@ -369,6 +393,9 @@ public void setChildDatasetFieldTypes(Collection<DatasetFieldType> childDatasetF
         this.childDatasetFieldTypes = childDatasetFieldTypes;
     }
 
+    /**
+     * Defines the parent of this DatasetFieldType, if no parent is defined `null` is used.
+     */
     @ManyToOne(cascade = CascadeType.MERGE)
     private DatasetFieldType parentDatasetFieldType;
 
@@ -490,8 +517,8 @@ public boolean equals(Object object) {
     }
 
     /**
-     * List of fields that use this field type. If this field type is removed,
-     * these fields will be removed too.
+     * If DatasetFieldType is used by a DatasetField to gather metadata we reference the type.
+     * This member setups the needed connection in the domain model, but is not activilty used.
      */
     @OneToMany(mappedBy = "datasetFieldType", cascade = {CascadeType.REMOVE, CascadeType.MERGE, CascadeType.PERSIST})
     private List<DatasetField> datasetFields;
@@ -504,17 +531,6 @@ public void setDatasetFields(List<DatasetField> datasetFieldValues) {
         this.datasetFields = datasetFieldValues;
     }
 
-    @OneToMany(mappedBy = "datasetField", cascade = {CascadeType.REMOVE, CascadeType.MERGE, CascadeType.PERSIST})
-    private List<DatasetFieldDefaultValue> datasetFieldDefaultValues;
-
-    public List<DatasetFieldDefaultValue> getDatasetFieldDefaultValues() {
-        return datasetFieldDefaultValues;
-    }
-
-    public void setDatasetFieldDefaultValues(List<DatasetFieldDefaultValue> datasetFieldDefaultValues) {
-        this.datasetFieldDefaultValues = datasetFieldDefaultValues;
-    }
-
     @Override
     public int compareTo(DatasetFieldType o) {
         return Integer.compare(this.getDisplayOrder(), (o.getDisplayOrder()));