Additional javadoc

dspace-api/src/main/java/org/dspace/importer/external/MetadataSourceException.java

@@ -12,18 +12,59 @@ package org.dspace.importer.external;
  * @author Roeland Dillen (roeland at atmire dot com)
  */
 public class MetadataSourceException extends Exception {
+
+    /**
+     * Constructs a new exception with {@code null} as its detail message.
+     * The cause is not initialized, and may subsequently be initialized by a
+     * call to {@link #initCause}.
+     */
     public MetadataSourceException() {
+        super();
     }
 
-    public MetadataSourceException(String s) {
+    /**
-        super(s);
+     * Constructs a new exception with the specified detail message.  The
+     * cause is not initialized, and may subsequently be initialized by
+     * a call to {@link #initCause}.
+     *
+     * @param   message   the detail message. The detail message is saved for
+     *          later retrieval by the {@link #getMessage()} method.
+     */
+    public MetadataSourceException(String message) {
+        super(message);
     }
 
-    public MetadataSourceException(String s, Throwable throwable) {
+    /**
-        super(s, throwable);
+     * Constructs a new exception with the specified detail message and
+     * cause.  <p>Note that the detail message associated with
+     * {@code cause} is <i>not</i> automatically incorporated in
+     * this exception's detail message.
+     *
+     * @param  message the detail message (which is saved for later retrieval
+     *         by the {@link #getMessage()} method).
+     * @param  cause the cause (which is saved for later retrieval by the
+     *         {@link #getCause()} method).  (A <tt>null</tt> value is
+     *         permitted, and indicates that the cause is nonexistent or
+     *         unknown.)
+     */
+    public MetadataSourceException(String message, Throwable cause) {
+        super(message, cause);
     }
 
-    public MetadataSourceException(Throwable throwable) {
+    /**
-        super(throwable);
+     * Constructs a new exception with the specified cause and a detail
+     * message of <tt>(cause==null ? null : cause.toString())</tt> (which
+     * typically contains the class and detail message of <tt>cause</tt>).
+     * This constructor is useful for exceptions that are little more than
+     * wrappers for other throwables (for example, {@link
+     * java.security.PrivilegedActionException}).
+     *
+     * @param  cause the cause (which is saved for later retrieval by the
+     *         {@link #getCause()} method).  (A <tt>null</tt> value is
+     *         permitted, and indicates that the cause is nonexistent or
+     *         unknown.)
+     */
+    public MetadataSourceException(Throwable cause) {
+        super(cause);
     }
 }

dspace-api/src/main/java/org/dspace/importer/external/Query.java

@@ -16,21 +16,49 @@ import java.util.Collection;
  * @author Roeland Dillen (roeland at atmire dot com)
  */
 public class Query {
-    private MultiValueMap parameters = new MultiValueMap();
 
+    private MultiValueMap parameters = new MultiValueMap();
+    /**
+     * Retrieve the parameters set to this Query object
+     *
+     * @return the {@link org.apache.commons.collections.map.MultiValueMap} set to this object
+     */
     public MultiValueMap getParameters() {
         return parameters;
     }
 
+    /**
+     * In the parameters variable, adds the value to the collection associated with the specified key.
+     * <p>
+     * Unlike a normal <code>Map</code> the previous value is not replaced.
+     * Instead the new value is added to the collection stored against the key.
+     *
+     * @param key  the key to store against
+     * @param value  the value to add to the collection at the key
+     */
     public void addParameter(String key,Object value){
         parameters.put(key,value);
     }
 
+    /**
+     * In the parameters variable, adds the value to the collection associated with the specified key.
+     * <p>
+     * Unlike {@link #addParameter(String, Object)} the previous value is overridden.
+     * First, any existing values are removed, then the new value is added to the collection at the specified key
+     *
+     * @param key  the key to store against
+     * @param value  the value to add to the collection at the key
+     */
     protected void addSingletonParameter(String key,Object value){
         parameters.remove(key);
         parameters.put(key,value);
     }
 
+    /**
+     * Retrieve a parameter as a certain given class
+     * @param key  the key to retrieve the parameter from
+     * @param clazz  The classtype to retrieve. (If no parameter with that class is found, a  <tt>null</tt> value is returned
+     */
     public <T> T getParameterAsClass(String key, Class<T> clazz){
         Collection c=parameters.getCollection(key);
         if(c==null||c.isEmpty()) return null;
@@ -42,11 +70,22 @@ public class Query {
         }
 
     }
-
+    /**
+     * Gets the collection mapped to the specified key.
+     * This method is a convenience method to typecast the result of <code>get(key)</code>.
+     *
+     * @param key  the key used to retrieve the collection
+     * @return the collection mapped to the key, null if no mapping
+     */
     public Collection getParameter(String key){
         return parameters.getCollection(key);
     }
 
+
+    /**
+     *  Set the parameters of this query object based on a given {@link org.apache.commons.collections.map.MultiValueMap}
+     * @param parameters a {@link org.apache.commons.collections.map.MultiValueMap} to set to this Query object
+     */
     public void setParameters(MultiValueMap parameters) {
         this.parameters = parameters;
     }

dspace-api/src/main/java/org/dspace/importer/external/SourceExceptionHandler.java

@@ -11,11 +11,16 @@ package org.dspace.importer.external;
 import org.dspace.importer.external.service.other.MetadataSource;
 
 /**
+ * Represent a  handler that forces implementations to define their own behaviour for exceptions originating from
  * @author: Antoine Snyers (antoine at atmire dot com)
- * Date: 27 Oct 2014
  */
 public abstract interface SourceExceptionHandler<T extends MetadataSource> {
 
+    /**
+     * Represents a method contract to handle Exceptions originating from the source in a specific way
+     * Implementations define their own desired behaviour
+     * @param   source   The source of the exception
+     */
     public abstract void handle(T source);
 
 }

dspace-api/src/main/java/org/dspace/importer/external/datamodel/ImportRecord.java

@@ -16,21 +16,34 @@ import java.util.List;
 
 /**
  * @author Roeland Dillen (roeland at atmire dot com)
- * Date: 17/09/12
- * Time: 14:03
  */
 public class ImportRecord {
     private List<MetadatumDTO> valueList = null;
 
+    /**
+     * Retrieve an unmodifiableList of MetadatumDTO
+     * @return List of MetadatumDTO
+     */
     public List<MetadatumDTO> getValueList() {
         return Collections.unmodifiableList(valueList);
     }
 
+    /**
+     * Create an ImportRecord instance initialized with a List of MetadatumDTO objects
+     * @param valueList
+     */
     public ImportRecord(List<MetadatumDTO> valueList) {
         //don't want to alter the original list. Also now I can control the type of list
         this.valueList = new LinkedList<>(valueList);
     }
 
+    /**
+     * Build a string based on the values in the valueList object
+     * The syntax will be
+     * Record{valueList={"schema"; "element" ; "qualifier"; "value"}}
+     *
+     * @return a concatenated string containing all values of the MetadatumDTO objects in valueList
+     */
     @Override
     public String toString() {
         final StringBuilder sb = new StringBuilder();
@@ -55,7 +68,13 @@ public class ImportRecord {
         return sb.toString();
     }
 
-    /* Return the MetadatumDTO's that are related to a given schema/element/qualifier pair/triplet */
+    /**
+     * Return the MetadatumDTO's that are related to a given schema/element/qualifier pair/triplet
+     * @param schema
+     * @param element
+     * @param qualifier
+     * @return the MetadatumDTO's that are related to a given schema/element/qualifier pair/triplet
+     */
     public Collection<MetadatumDTO> getValue(String schema, String element, String qualifier){
         List<MetadatumDTO> values=new LinkedList<MetadatumDTO>();
         for(MetadatumDTO value:valueList){
@@ -70,6 +89,10 @@ public class ImportRecord {
         return values;
     }
 
+    /**
+     * Add a value to the valueList
+     * @param value The MetadatumDTO to add to the valueList
+     */
     public void addValue(MetadatumDTO value){
         this.valueList.add(value);
     }

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/AbstractMetadataFieldMapping.java

@@ -19,8 +19,6 @@ import java.util.Map;
 
 /**
  * @author Roeland Dillen (roeland at atmire dot com)
- * Date: 19/09/12
- * Time: 10:09
  */
 public abstract class AbstractMetadataFieldMapping<RecordType> implements MetadataFieldMapping<RecordType, MetadataContributor<RecordType>> {
 
@@ -36,11 +34,20 @@ public abstract class AbstractMetadataFieldMapping<RecordType> implements Metada
      */
     private Map<MetadataFieldConfig, MetadataProcessorService> metadataProcessorMap;
 
+    /**
+     * Set a map of metadataprocessors. This map is used to process metadata to make it more compliant for certain metadata fields
+     * @param metadataProcessorMap
+     */
     public void setMetadataProcessorMap(Map<MetadataFieldConfig, MetadataProcessorService> metadataProcessorMap)
     {
         this.metadataProcessorMap = metadataProcessorMap;
     }
 
+    /**
+     * Return the metadataProcessor used to update values to make them more compliant for certain goals
+     * @param metadataField to retrieve processor for
+     * @return metadataProcessor
+     */
     public MetadataProcessorService getMetadataProcessor(MetadataFieldConfig metadataField)
     {
         if(metadataProcessorMap != null)
@@ -51,11 +58,14 @@ public abstract class AbstractMetadataFieldMapping<RecordType> implements Metada
         }
     }
 
+    /**
+     * @param field MetadataFieldConfig representing what to map the value to
+     * @param value The value to map to a MetadatumDTO
+     * @return A metadatumDTO created from the field and value
+     */
     public MetadatumDTO toDCValue(MetadataFieldConfig field, String value) {
         MetadatumDTO dcValue = new MetadatumDTO();
 
-
-
         if (field == null) return null;
         MetadataProcessorService metadataProcessor = getMetadataProcessor(field);
         if(metadataProcessor != null)
@@ -69,48 +79,31 @@ public abstract class AbstractMetadataFieldMapping<RecordType> implements Metada
         return dcValue;
     }
 
-    private boolean reverseDifferent = false;
+    /**
-
+     * Retrieve the metadataFieldMap set to this class
-    private String AND = "AND";
+     * @return Map<MetadataFieldConfig, MetadataContributor<RecordType>> representing the metadataFieldMap
-    private String OR = "OR";
+     */
-    private String NOT = "NOT";
-
-    public String getAND() {
-        return AND;
-    }
-
-    public void setAND(String AND) {
-        this.AND = AND;
-    }
-
-    public String getOR() {
-        return OR;
-    }
-
-    public void setOR(String OR) {
-        this.OR = OR;
-    }
-
-    public String getNOT() {
-        return NOT;
-    }
-
-    public void setNOT(String NOT) {
-        this.NOT = NOT;
-    }
-
     public Map<MetadataFieldConfig, MetadataContributor<RecordType>> getMetadataFieldMap() {
         return metadataFieldMap;
     }
 
+    /** Defines which metadatum is mapped on which metadatum. Note that while the key must be unique it
+     * only matters here for postprocessing of the value. The mapped MetadatumContributor has full control over
+     * what metadatafield is generated.
+     * @param metadataFieldMap The map containing the link between retrieve metadata and metadata that will be set to the item.
+     */
     public void setMetadataFieldMap(Map<MetadataFieldConfig, MetadataContributor<RecordType>> metadataFieldMap) {
         this.metadataFieldMap = metadataFieldMap;
         for(MetadataContributor<RecordType> mc:metadataFieldMap.values()){
             mc.setMetadataFieldMapping(this);
         }
-
     }
 
+    /**
+     * Loop over the MetadataContributors and return their concatenated retrieved metadatumDTO objects
+     * @param record Used to retrieve the MetadatumDTO
+     * @return Lit of metadatumDTO
+     */
     @Override
     public Collection<MetadatumDTO> resultToDCValueMapping(RecordType record) {
         List<MetadatumDTO> values=new LinkedList<MetadatumDTO>();

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/MetadataFieldConfig.java

@@ -9,8 +9,6 @@ package org.dspace.importer.external.metadatamapping;
 
 /**
  * @author Roeland Dillen (roeland at atmire dot com)
- * Date: 19/09/12
- * Time: 10:11
  *
  * A generalised configuration for metadatafields.
  * This is used to make the link between values and the actual MetadatumDTO object.
@@ -21,6 +19,12 @@ public class MetadataFieldConfig {
     private String qualifier;
 
 
+    /**
+     * Indicates whether some other object is "equal to" this one.
+     * @param o the reference object with which to compare.
+     * @return  {@code true} if this object is the same as the obj
+     *          argument; {@code false} otherwise.
+     */
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;
@@ -35,6 +39,10 @@ public class MetadataFieldConfig {
         return true;
     }
 
+    /**
+     * Create the String representation of the MetadataFieldConfig
+     * @return a string representation of the MetadataFieldConfig
+     */
     @Override
     public String toString() {
         final StringBuilder sb = new StringBuilder();
@@ -46,6 +54,12 @@ public class MetadataFieldConfig {
         return sb.toString();
     }
 
+    /**
+     * Returns a hash code value for the object. This method is
+     * supported for the benefit of hash tables such as those provided by
+     * {@link java.util.HashMap}.
+     * @return  a hash code value for this object.
+     */
     @Override
     public int hashCode() {
         int result = schema.hashCode();
@@ -54,26 +68,41 @@ public class MetadataFieldConfig {
         return result;
     }
 
-    public String getSchema() {
-
-        return schema;
-    }
 
+    /**
+     * Create a MetadataFieldConfig based on a given MetadatumDTO
+     * This MetadatumDTO object contains the schema, element and qualifier needed to initialize the MetadataFieldConfig
+     * @param value
+     */
     public MetadataFieldConfig(MetadatumDTO value) {
         this.schema = value.getSchema();
         this.element = value.getElement();
         this.qualifier = value.getQualifier();
     }
 
+    /**
+     * An empty initialization of MetadataFieldConfig
+     */
     public MetadataFieldConfig() {
     }
 
+    /**
+     * Create a MetadataFieldConfig using a schema,element and qualifier
+     * @param schema The schema to set to this object
+     * @param element The element to set to this object
+     * @param qualifier The qualifier to set to this object
+     */
     public MetadataFieldConfig(String schema, String element, String qualifier) {
         this.schema = schema;
         this.element = element;
         this.qualifier = qualifier;
     }
 
+    /**
+     * Create a MetadataFieldConfig using a single value.
+     * This value is split up into schema, element and qualifier, based on a dot(.)
+     * @param full A string representing the schema.element.qualifier triplet
+     */
     public MetadataFieldConfig(String full) {
         String elements[]=full.split("\\.");
         if(elements.length==2){
@@ -86,34 +115,75 @@ public class MetadataFieldConfig {
         }
 
     }
-
+    /**
+     * Create a MetadataFieldConfig using a schema and element
+     * qualifier will be set to <code>null</code>
+     * @param schema The schema to set to this object
+     * @param element The element to set to this object
+     */
     public MetadataFieldConfig(String schema, String element) {
         this.schema = schema;
         this.element = element;
         this.qualifier = null;
     }
 
+    /**
+     * Set the schema to this MetadataFieldConfig
+     * @param schema The schema to set to this object
+     */
     public void setSchema(String schema) {
         this.schema = schema;
 
     }
 
+    /**
+     * Return the schema set to this object.
+     * <code>null</code> if nothing is set
+     * @return The schema of this object
+     */
+    public String getSchema() {
+
+        return schema;
+    }
+
+    /**
+     * Return a string representing the field of this object
+     * @return The field that is set to this object, in the form of schema.element.qualifier
+     */
     public String getField() {
         return schema + "." + element + (qualifier==null?"":("." + qualifier));
     }
 
+    /**
+     * Return the qualifier set to this object.
+     * <code>null</code> if nothing is set
+     * @return The qualifier of this object
+     */
     public String getElement() {
         return element;
     }
 
+    /**
+     * Set the element to this MetadataFieldConfig
+     * @param element The element to set to this object
+     */
     public void setElement(String element) {
         this.element = element;
     }
 
+    /**
+     * Return the qualifier set to this object.
+     * <code>null</code> if nothing is set
+     * @return The qualifier of this object
+     */
     public String getQualifier() {
         return qualifier;
     }
 
+    /**
+     * Set the qualifier to this MetadataFieldConfig
+     * @param qualifier The qualifier to set to this object
+     */
     public void setQualifier(String qualifier) {
         this.qualifier = qualifier;
     }

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/MetadataFieldMapping.java

@@ -11,17 +11,24 @@ import java.util.Collection;
 
 /**
  * @author Roeland Dillen (roeland at atmire dot com)
- * Date: 18/09/12
- * Time: 14:41
  */
 
-public interface  MetadataFieldMapping<RecordType,QueryType> {
+public interface MetadataFieldMapping<RecordType,QueryType> {
 
-        /* Using a given MetadataFieldConfig, return a MetadatumDTO retrieved from a value. */
+    /**
-        public MetadatumDTO toDCValue(MetadataFieldConfig field, String value);
+     * @param field MetadataFieldConfig representing what to map the value to
+     * @param value The value to map to a MetadatumDTO
+     * @return A metadatumDTO created from the field and value
+     */
+    public MetadatumDTO toDCValue(MetadataFieldConfig field, String value);
 
-        /* Implementations need to handle how the result is processed,filtered and returned. */
+
-        public Collection<MetadatumDTO> resultToDCValueMapping(RecordType record);
+    /**
+     * Create a collection of MetadatumDTO retrieved from a given RecordType
+     * @param record Used to retrieve the MetadatumDTO
+     * @return Collectio of MetadatumDTO
+     */
+    public Collection<MetadatumDTO> resultToDCValueMapping(RecordType record);
 
 
 

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/MetadatumDTO.java

@@ -9,8 +9,6 @@ package org.dspace.importer.external.metadatamapping;
 
 /**
  * @author Philip Vissenaekens (philip at atmire dot com)
- * Date: 21/10/15
- * Time: 09:52
  *
  * This class is used to cary data between processes.
  * Using this class, we have a uniform, generalised single Object type containing the information used by different classes.
@@ -24,33 +22,68 @@ public class MetadatumDTO {
     private String qualifier;
     private String value;
 
+    /**
+     * An empty MetadatumDTO constructor
+     */
     public MetadatumDTO() {
     }
 
+    /**
+     * Retrieve the schema set to this MetadatumDTO.
+     * Returns <tt>null</tt> of no schema is set
+     * @return schema
+     */
     public String getSchema() {
         return schema;
     }
 
+    /**
+     * Set the schema to this MetadatumDTO
+     * @param schema
+     */
     public void setSchema(String schema) {
         this.schema = schema;
     }
 
+    /**
+     * Retrieve the element set to this MetadatumDTO.
+     * Returns <tt>null</tt> of no element is set
+     * @return element
+     */
     public String getElement() {
         return element;
     }
 
+    /**
+     * Set the element to this MetadatumDTO
+     * @param element
+     */
     public void setElement(String element) {
         this.element = element;
     }
 
+    /**
+     * Retrieve the qualifier set to this MetadatumDTO.
+     * Returns <tt>null</tt> of no qualifier is set
+     * @return qualifier
+     */
     public String getQualifier() {
         return qualifier;
     }
 
+    /**
+     * Set the qualifier to this MetadatumDTO
+     * @param qualifier
+     */
     public void setQualifier(String qualifier) {
         this.qualifier = qualifier;
     }
 
+    /**
+     * Retrieve the value set to this MetadatumDTO.
+     * Returns <tt>null</tt> of no value is set
+     * @return value
+     */
     public String getValue() {
         return value;
     }

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/contributor/CombinedMetadatumContributor.java

@@ -16,9 +16,8 @@ import java.util.LinkedList;
 import java.util.List;
 
 /**
+ * Wrapper class used to accommodate for the possibility of correlations between multiple MetadatumContributor objects
  * @author Philip Vissenaekens (philip at atmire dot com)
- * Date: 17/06/15
- * Time: 11:02
  */
 public class CombinedMetadatumContributor<T> implements MetadataContributor<T> {
     private MetadataFieldConfig field;
@@ -29,15 +28,28 @@ public class CombinedMetadatumContributor<T> implements MetadataContributor<T> {
 
     private MetadataFieldMapping<T,MetadataContributor<T>> metadataFieldMapping;
 
+    /**
+     * Initialize an empty CombinedMetadatumContributor object
+     */
     public CombinedMetadatumContributor() {
     }
 
+    /**
+     *
+     * @param field {@link org.dspace.importer.external.metadatamapping.MetadataFieldConfig} used in mapping
+     * @param metadatumContributors A list of MetadataContributor
+     * @param separator A separator used to differentiate between different values
+     */
     public CombinedMetadatumContributor(MetadataFieldConfig field, List<MetadataContributor> metadatumContributors, String separator) {
         this.field = field;
         this.metadatumContributors = (LinkedList<MetadataContributor>) metadatumContributors;
         this.separator = separator;
     }
 
+    /**
+     * Set the metadatafieldMapping used in the transforming of a record to actual metadata
+     * @param metadataFieldMapping
+     */
     @Override
     public void setMetadataFieldMapping(MetadataFieldMapping<T, MetadataContributor<T>> metadataFieldMapping) {
         this.metadataFieldMapping = metadataFieldMapping;
@@ -47,8 +59,6 @@ public class CombinedMetadatumContributor<T> implements MetadataContributor<T> {
         }
     }
 
-
-
     /**
      * a separate Metadatum object is created for each index of Metadatum returned from the calls to
      * MetadatumContributor.contributeMetadata(t) for each MetadatumContributor in the metadatumContributors list.
@@ -84,26 +94,50 @@ public class CombinedMetadatumContributor<T> implements MetadataContributor<T> {
         return values;
     }
 
+    /**
+     * Return the MetadataFieldConfig used while retrieving MetadatumDTO
+     * @return MetadataFieldConfig
+     */
     public MetadataFieldConfig getField() {
         return field;
     }
 
+    /**
+     * Setting the MetadataFieldConfig
+     * @param field MetadataFieldConfig used while retrieving MetadatumDTO
+     */
     public void setField(MetadataFieldConfig field) {
         this.field = field;
     }
 
+    /**
+     * Return the List of MetadataContributor objects set to this class
+     * @return metadatumContributors, list of MetadataContributor
+     */
     public LinkedList<MetadataContributor> getMetadatumContributors() {
         return metadatumContributors;
     }
 
+    /**
+     * Set the List of MetadataContributor objects set to this class
+     * @param metadatumContributors A list of MetadatumContributor classes
+     */
     public void setMetadatumContributors(LinkedList<MetadataContributor> metadatumContributors) {
         this.metadatumContributors = metadatumContributors;
     }
 
+    /**
+     * Return the separator used to differentiate between distinct values
+     * @return the separator used to differentiate between distinct values
+     */
     public String getSeparator() {
         return separator;
     }
 
+    /**
+     * Set the separator used to differentiate between distinct values
+     * @param separator
+     */
     public void setSeparator(String separator) {
         this.separator = separator;
     }

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/contributor/MetadataContributor.java

@@ -14,16 +14,20 @@ import java.util.Collection;
 
 /**
  * @author Roeland Dillen (roeland at atmire dot com)
- * Date: 11/01/13
- * Time: 09:18
  */
 public interface MetadataContributor<RecordType> {
 
+    /**
+     * Set the metadataFieldMapping
+     * @param rt the MetadataFieldMapping object to set to the MetadataContributor
+     */
     public void setMetadataFieldMapping(MetadataFieldMapping<RecordType, MetadataContributor<RecordType>> rt);
 
     /**
-     *  Implementations have the responsibility to process/map their own type of metadata based on a given record
+     * Implementations have the responsibility to process/map their own type of metadata based on a given record
      * and return a collection of the generalised MetadatumDTO objects
+     * @param t The recordType object to retrieve metadata from
+     * @return A collection of MetadatumDTO objects, retrieve from the recordtype
      */
     public Collection<MetadatumDTO> contributeMetadata(RecordType t);
 }

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/contributor/SimpleXpathMetadatumContributor.java

@@ -24,26 +24,42 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * Metadata contributor that takes an axiom OMElement and turns it into a metadayum
+ * Metadata contributor that takes an axiom OMElement and turns it into a metadatum
  * @author Roeland Dillen (roeland at atmire dot com)
  */
 public class SimpleXpathMetadatumContributor implements MetadataContributor<OMElement> {
     private MetadataFieldConfig field;
 
+    /**
+     * Return prefixToNamespaceMapping
+     * @return Map<String, String> prefixToNamespaceMapping
+     */
     public Map<String, String> getPrefixToNamespaceMapping() {
         return prefixToNamespaceMapping;
     }
 
     private MetadataFieldMapping<OMElement,MetadataContributor<OMElement>> metadataFieldMapping;
 
+    /**
+     * Return metadataFieldMapping
+     * @return MetadataFieldMapping<OMElement,MetadataContributor<OMElement>> metadataFieldMapping
+     */
     public MetadataFieldMapping<OMElement,MetadataContributor<OMElement>> getMetadataFieldMapping() {
         return metadataFieldMapping;
     }
 
+    /**
+     * Set the metadataFieldMapping of this SimpleXpathMetadatumContributor
+     * @param metadataFieldMapping
+     */
     public void setMetadataFieldMapping(MetadataFieldMapping<OMElement,MetadataContributor<OMElement>> metadataFieldMapping) {
         this.metadataFieldMapping = metadataFieldMapping;
     }
 
+    /**
+     * Set the prefixToNamespaceMapping for this object,
+     * @param prefixToNamespaceMapping
+     */
     @Resource(name="isiFullprefixMapping")
     public void setPrefixToNamespaceMapping(Map<String, String> prefixToNamespaceMapping) {
         this.prefixToNamespaceMapping = prefixToNamespaceMapping;
@@ -51,26 +67,47 @@ public class SimpleXpathMetadatumContributor implements MetadataContributor<OMEl
 
     private Map<String,String> prefixToNamespaceMapping;
 
+    /**
+     * Initialize SimpleXpathMetadatumContributor with a query, Map<String, String>(prefixToNamespaceMapping) and MetadataFieldConfig(field)
+     * @param query String
+     * @param prefixToNamespaceMapping Map<String, String>
+     * @param field MetadataFieldConfig
+     */
     public SimpleXpathMetadatumContributor(String query, Map<String, String> prefixToNamespaceMapping, MetadataFieldConfig field) {
         this.query = query;
         this.prefixToNamespaceMapping = prefixToNamespaceMapping;
         this.field = field;
     }
 
+    /**
+     * Empty constructor for SimpleXpathMetadatumContributor
+     */
     public SimpleXpathMetadatumContributor() {
 
     }
 
     private String query;
 
+    /**
+     * Return the MetadataFieldConfig used while retrieving MetadatumDTO
+     * @return MetadataFieldConfig
+     */
     public MetadataFieldConfig getField() {
         return field;
     }
+    /**
+     * Setting the MetadataFieldConfig
+     * @param field MetadataFieldConfig used while retrieving MetadatumDTO
+     */
     @Required
     public void setField(MetadataFieldConfig field) {
         this.field = field;
     }
 
+    /**
+     * Return query used to create an xpathExpression on, this query is used to
+     * @return
+     */
     public String getQuery() {
         return query;
     }
@@ -79,9 +116,15 @@ public class SimpleXpathMetadatumContributor implements MetadataContributor<OMEl
         this.query = query;
     }
 
+    /**
+     * Retrieve the metadata associated with the given object.
+     * Depending on the retrieved node (using the query), different types of values will be added to the MetadatumDTO list
+     * @param t A class to retrieve metadata from.
+     * @return a collection of import records. Only the identifier of the found records may be put in the record.
+     */
     @Override
     public Collection<MetadatumDTO> contributeMetadata(OMElement t) {
-        List<MetadatumDTO> values=new LinkedList<MetadatumDTO>();
+        List<MetadatumDTO> values=new LinkedList<>();
         try {
             AXIOMXPath xpath=new AXIOMXPath(query);
             for(String ns:prefixToNamespaceMapping.keySet()){

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/processor/AuthorMetadataProcessorService.java

@@ -14,11 +14,14 @@ import org.dspace.importer.external.metadatamapping.service.MetadataProcessorSer
  * Removes the last point from an author name, this is required for the SAP lookup
  *
  * User: kevin (kevin at atmire.com)
- * Date: 23/10/12
- * Time: 09:50
  */
 public class AuthorMetadataProcessorService implements MetadataProcessorService {
 
+    /**
+     * Strip a given value of its last dot (.)
+     * @param value the value to run the processing over
+     * @return The initial param with its ending dot stripped
+     */
     @Override
     public String processMetadataValue(String value) {
         String ret=value;

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/service/GenerateQueryService.java

@@ -13,8 +13,6 @@ import org.dspace.importer.external.MetadataSourceException;
 
 /**
  * @author Roeland Dillen (roeland at atmire dot com)
- * Date: 14/12/12
- * Time: 11:44
  */
 public interface GenerateQueryService {
 

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/service/MetadataProcessorService.java

@@ -8,9 +8,7 @@
 package org.dspace.importer.external.metadatamapping.service;
 
 /**
- * User: kevin (kevin at atmire.com)
+ * @author kevin (kevin at atmire.com)
- * Date: 23/10/12
- * Time: 09:49
  */
 public interface MetadataProcessorService {
 

dspace-api/src/main/java/org/dspace/importer/external/pubmed/metadatamapping/PubmedDateMetadatumContributor.java

@@ -25,8 +25,6 @@ import java.util.List;
 
 /**
  * @author Philip Vissenaekens (philip at atmire dot com)
- * Date: 06/07/15
- * Time: 13:48
  */
 public class PubmedDateMetadatumContributor<T> implements MetadataContributor<T> {
     Logger log = Logger.getLogger(PubmedDateMetadatumContributor.class);
@@ -50,6 +48,10 @@ public class PubmedDateMetadatumContributor<T> implements MetadataContributor<T>
     private MetadataContributor month;
     private MetadataContributor year;
 
+    /**
+     * Set the metadatafieldMapping used in the transforming of a record to actual metadata
+     * @param metadataFieldMapping
+     */
     @Override
     public void setMetadataFieldMapping(MetadataFieldMapping<T, MetadataContributor<T>> metadataFieldMapping) {
         this.metadataFieldMapping = metadataFieldMapping;
@@ -57,10 +59,19 @@ public class PubmedDateMetadatumContributor<T> implements MetadataContributor<T>
         month.setMetadataFieldMapping(metadataFieldMapping);
         year.setMetadataFieldMapping(metadataFieldMapping);
     }
-
+    /**
+     * Initialize an empty PubmedDateMetadatumContributor object
+     */
     public PubmedDateMetadatumContributor() {
     }
 
+    /**
+     *
+     * @param field {@link org.dspace.importer.external.metadatamapping.MetadataFieldConfig} used in mapping
+     * @param day a MetadataContributor, representing a day
+     * @param month a {@link MetadataContributor}, representing a month
+     * @param year a {@link MetadataContributor}, representing a year
+     */
     public PubmedDateMetadatumContributor(MetadataFieldConfig field, MetadataContributor day, MetadataContributor month, MetadataContributor year) {
         this.field = field;
         this.day = day;
@@ -68,6 +79,13 @@ public class PubmedDateMetadatumContributor<T> implements MetadataContributor<T>
         this.year = year;
     }
 
+    /**
+     * Retrieve the metadata associated with the given object.
+     * The code will loop over the different dates and attempt to format them using the configured dateFormats to attempt.
+     * For each date, once a format is successful, this result is used. Make sure that dateFormatsToAttempt is configured from most restrictive to most lenient to try and get the most precise result
+     * @param t A class to retrieve metadata from.
+     * @return a collection of import records. Only the identifier of the found records may be put in the record.
+     */
     @Override
     public Collection<MetadatumDTO> contributeMetadata(T t) {
         List<MetadatumDTO> values = new LinkedList<>();
@@ -115,34 +133,66 @@ public class PubmedDateMetadatumContributor<T> implements MetadataContributor<T>
         return values;
     }
 
+    /**
+     * Return the MetadataFieldConfig used while retrieving MetadatumDTO
+     * @return MetadataFieldConfig
+     */
     public MetadataFieldConfig getField() {
         return field;
     }
 
+    /**
+     * Setting the MetadataFieldConfig
+     * @param field MetadataFieldConfig used while retrieving MetadatumDTO
+     */
     public void setField(MetadataFieldConfig field) {
         this.field = field;
     }
 
+    /**
+     * Retrieve the day from the object
+     * @return {@link MetadataContributor}, representing a day
+     */
     public MetadataContributor getDay() {
         return day;
     }
 
+    /**
+     * Set a day ({@link MetadataContributor}) to this object
+     * @param day a {@link MetadataContributor}, representing a day
+     */
     public void setDay(MetadataContributor day) {
         this.day = day;
     }
 
+    /**
+     * Retrieve the month from the object
+     * @return {@link MetadataContributor}, representing a month
+     */
     public MetadataContributor getMonth() {
         return month;
     }
 
+    /**
+     * Set a month ({@link MetadataContributor}) to this object
+     * @param month a {@link MetadataContributor}, representing a month
+     */
     public void setMonth(MetadataContributor month) {
         this.month = month;
     }
 
+    /**
+     * Retrieve the year from the object
+     * @return {@link MetadataContributor}, representing a year
+     */
     public MetadataContributor getYear() {
         return year;
     }
 
+    /**
+     * Set a year ({@link MetadataContributor}) to this object
+     * @param year a {@link MetadataContributor}, representing a year
+     */
     public void setYear(MetadataContributor year) {
         this.year = year;
     }

dspace-api/src/main/java/org/dspace/importer/external/pubmed/metadatamapping/PubmedFieldMapping.java

@@ -18,9 +18,10 @@ import java.util.Map;
  */
 public class PubmedFieldMapping extends AbstractMetadataFieldMapping {
 
-    /* Defines which metadatum is mapped on which metadatum. Note that while the key must be unique it
+    /** Defines which metadatum is mapped on which metadatum. Note that while the key must be unique it
      * only matters here for postprocessing of the value. The mapped MetadatumContributor has full control over
      * what metadatafield is generated.
+     * @param metadataFieldMap The map containing the link between retrieve metadata and metadata that will be set to the item.
      */
     @Override
     @Resource (name = "pubmedMetadataFieldMap")

dspace-api/src/main/java/org/dspace/importer/external/pubmed/metadatamapping/PubmedLanguageMetadatumContributor.java

@@ -17,8 +17,6 @@ import java.util.*;
 
 /**
  * @author Philip Vissenaekens (philip at atmire dot com)
- * Date: 07/07/15
- * Time: 15:08
  */
 public class PubmedLanguageMetadatumContributor<T> implements MetadataContributor<T> {
     Logger log = Logger.getLogger(PubmedDateMetadatumContributor.class);
@@ -29,6 +27,9 @@ public class PubmedLanguageMetadatumContributor<T> implements MetadataContributo
     private MetadataFieldConfig field;
     private MetadataContributor language;
 
+    /**
+     * Initialize PubmedLanguageMetadatumContributor and create the iso3toiso2 mapping used in the transforming of language codes
+     */
     public PubmedLanguageMetadatumContributor() {
         iso3toIso2=new HashMap<>();
         // Populate the languageMap with the mapping between iso3 and iso2 language codes
@@ -37,18 +38,31 @@ public class PubmedLanguageMetadatumContributor<T> implements MetadataContributo
         }
     }
 
+    /**
+     * Initialize the PubmedLanguageMetadatumContributor class using a {@link org.dspace.importer.external.metadatamapping.MetadataFieldConfig} and a language -{@link org.dspace.importer.external.metadatamapping.contributor.MetadataContributor}
+     * @param field {@link org.dspace.importer.external.metadatamapping.MetadataFieldConfig} used in mapping
+     * @param language
+     */
     public PubmedLanguageMetadatumContributor(MetadataFieldConfig field, MetadataContributor language) {
         this();
         this.field = field;
         this.language = language;
     }
 
+    /**
+     * Set the metadatafieldMapping used in the transforming of a record to actual metadata
+     * @param metadataFieldMapping
+     */
     @Override
     public void setMetadataFieldMapping(MetadataFieldMapping<T, MetadataContributor<T>> metadataFieldMapping) {
         this.metadataFieldMapping = metadataFieldMapping;
         language.setMetadataFieldMapping(metadataFieldMapping);
     }
 
+    /**
+     * @param t A class to retrieve metadata from.
+     * @return a collection of import records. Only the identifier of the found records may be put in the record.
+     */
     @Override
     public Collection<MetadatumDTO> contributeMetadata(T t) {
         List<MetadatumDTO> values=new LinkedList<MetadatumDTO>();
@@ -67,18 +81,34 @@ public class PubmedLanguageMetadatumContributor<T> implements MetadataContributo
         return values;
     }
 
+    /**
+     * Return the MetadataContributor used while retrieving MetadatumDTO
+     * @return MetadataContributor
+     */
     public MetadataContributor getLanguage() {
         return language;
     }
 
+    /**
+     * Setting the MetadataContributor
+     * @param language MetadataContributor used while retrieving MetadatumDTO
+     */
     public void setLanguage(MetadataContributor language) {
         this.language = language;
     }
 
+    /**
+     * Return the MetadataFieldConfig used while retrieving MetadatumDTO
+     * @return MetadataFieldConfig
+     */
     public MetadataFieldConfig getField() {
         return field;
     }
 
+    /**
+     * Setting the MetadataFieldConfig
+     * @param field MetadataFieldConfig used while retrieving MetadatumDTO
+     */
     public void setField(MetadataFieldConfig field) {
         this.field = field;
     }

dspace-api/src/main/java/org/dspace/importer/external/pubmed/metadatamapping/service/GeneratePubmedQueryService.java

@@ -24,12 +24,13 @@ import java.util.List;
 public class GeneratePubmedQueryService implements GenerateQueryService {
 
 
-    /*
+    /**
-    * Create a Query object based on a given item.
+     * Create a Query object based on a given item.
-    * If the item has at least 1 value for dc.identifier.doi, the first one will be used.
+     * If the item has at least 1 value for dc.identifier.doi, the first one will be used.
-    * If no DOI is found, the title will be used.
+     * If no DOI is found, the title will be used.
-    * When no DOI or title is found, an null object is returned instead.
+     * When no DOI or title is found, an null object is returned instead.
-    */
+     * @param item the Item to create a Query from
+     */
     @Override
     public Query generateQueryForItem(Item item) throws MetadataSourceException {
         Query query = new Query();

dspace-api/src/main/java/org/dspace/importer/external/pubmed/service/other/ImportMetadataSourceServiceImpl.java

@@ -38,71 +38,126 @@ public class ImportMetadataSourceServiceImpl extends org.dspace.importer.externa
 
     private WebTarget pubmedWebTarget;
 
-
+    /** Find the number of records matching a query;
-    // Return the number of records from the pubmedWebTarget based on a query String
+     *
+     * @param query a query string to base the search on.
+     * @return the sum of the matching records over this import source
+     * @throws MetadataSourceException
+     */
     @Override
     public int getNbRecords(String query) throws MetadataSourceException {
         return retry(new GetNbRecords(query));
     }
 
-    // Return the number of records from the pubmedWebTarget based on a query object
+    /** Find the number of records matching a query;
-    @Override
+     *
+     * @param query a query object to base the search on.
+     * @return the sum of the matching records over this import source
+     * @throws MetadataSourceException
+     */    @Override
     public int getNbRecords(Query query) throws MetadataSourceException {
         return retry(new GetNbRecords(query));
     }
 
-    // Return the records from the pubmedWebTarget based on a query string, the start and count
+    /**  Find the number of records matching a string query. Supports pagination
+     *
+     * @param query a query string to base the search on.
+     * @param start offset to start at
+     * @param count number of records to retrieve.
+     * @return a set of records. Fully transformed.
+     * @throws MetadataSourceException
+     */
     @Override
     public Collection<ImportRecord> getRecords(String query, int start, int count) throws MetadataSourceException {
         return retry(new GetRecords(query, start, count));
     }
 
-    // Return the records from the pubmedWebTarget based on a query object
+    /** Find records based on a object query.
+     *
+     * @param query a query object to base the search on.
+     * @return a set of records. Fully transformed.
+     * @throws MetadataSourceException
+     */
     @Override
-    public Collection<ImportRecord> getRecords(Query q) throws MetadataSourceException {
+    public Collection<ImportRecord> getRecords(Query query) throws MetadataSourceException {
-        return retry(new GetRecords(q));
+        return retry(new GetRecords(query));
     }
 
-    // Retrieve a single records based on an id
+    /** Get a single record from the source.
+     * The first match will be returned
+     * @param id identifier for the record
+     * @return a matching record
+     * @throws MetadataSourceException
+     */
     @Override
     public ImportRecord getRecord(String id) throws MetadataSourceException {
         return retry(new GetRecord(id));
     }
 
-    // Retrieve a single records based on q query object
+    /** Get a single record from the source.
+     * The first match will be returned
+     * @param query a query matching a single record
+     * @return a matching record
+     * @throws MetadataSourceException
+     */
     @Override
-    public ImportRecord getRecord(Query q) throws MetadataSourceException {
+    public ImportRecord getRecord(Query query) throws MetadataSourceException {
-        return retry(new GetRecord(q));
+        return retry(new GetRecord(query));
     }
 
-    // Return the configured baseAddress
+    /**
+     * The string that identifies this import implementation. Preferable a URI
+     * @return the identifying uri
+     */
     @Override
     public String getImportSource() {
         return "http://eutils.ncbi.nlm.nih.gov/entrez/eutils/";
     }
 
-    // Return a collection of matching records based on a given item.
+    /** Finds records based on an item
+     * @param item an item to base the search on
+     * @return a collection of import records. Only the identifier of the found records may be put in the record.
+     * @throws MetadataSourceException if the underlying methods throw any exception.
+     */
     @Override
     public Collection<ImportRecord> findMatchingRecords(Item item) throws MetadataSourceException {
         return retry(new FindMatchingRecords(item));
     }
 
-    // Return a collection of matching records based on a given query object.
+    /** Finds records based on query object.
+     *  Delegates to one or more Imports implementations based on the uri.  Results will be aggregated.
+     * @param query a query object to base the search on.
+     * @return a collection of import records. Only the identifier of the found records may be put in the record.
+     * @throws MetadataSourceException
+     */
     @Override
-    public Collection<ImportRecord> findMatchingRecords(Query q) throws MetadataSourceException {
+    public Collection<ImportRecord> findMatchingRecords(Query query) throws MetadataSourceException {
-        return retry(new FindMatchingRecords(q));
+        return retry(new FindMatchingRecords(query));
     }
 
+    /**
+     * Initialize the class
+     * @throws Exception
+     */
     @Override
     public void init() throws Exception {
         Client client = ClientBuilder.newClient();
         WebTarget webTarget = client.target(baseAddress);
         pubmedWebTarget = webTarget.queryParam("db", "pubmed");
     }
+
+    /**
+     * Return the baseAddress set to this object
+     * @return The String object that represents the baseAddress of this object
+     */
     public String getBaseAddress() {
         return baseAddress;
     }
 
+    /**
+     * Set the baseAddress to this object
+     * @param baseAddress The String object that represents the baseAddress of this object
+     */
     public void setBaseAddress(String baseAddress) {
         this.baseAddress = baseAddress;
     }

dspace-api/src/main/java/org/dspace/importer/external/service/AbstractImportMetadataSourceService.java

@@ -29,26 +29,47 @@ public abstract class AbstractImportMetadataSourceService<RecordType> extends Me
 	private GenerateQueryService generateQueryForItem = null;
 	private MetadataFieldMapping<RecordType, MetadataContributor<RecordType>> metadataFieldMapping;
 
+    /**
+     * Retrieve the {@link GenerateQueryService}
+     * @return A GenerateForQueryService object set to this class
+     */
 	public GenerateQueryService getGenerateQueryForItem() {
 		return generateQueryForItem;
 	}
 
-	@Autowired
+    /**
+     * Set the {@link GenerateQueryService} used to create a {@link org.dspace.importer.external.Query}
+     * @param generateQueryForItem
+     */
+    @Autowired
 	public void setGenerateQueryForItem(GenerateQueryService generateQueryForItem) {
 		this.generateQueryForItem = generateQueryForItem;
 	}
 
+    /**
+     * Retrieve the MetadataFieldMapping containing the mapping between RecordType and Metadata
+     * @return The configured MetadataFieldMapping
+     */
 	public MetadataFieldMapping<RecordType, MetadataContributor<RecordType>> getMetadataFieldMapping() {
 		return metadataFieldMapping;
 	}
 
+    /**
+     * Sets the MetadataFieldMapping to base the mapping of RecordType and
+     * @param metadataFieldMapping
+     */
 	@Required
 	public void setMetadataFieldMapping(
 			MetadataFieldMapping<RecordType, MetadataContributor<RecordType>> metadataFieldMapping) {
 		this.metadataFieldMapping = metadataFieldMapping;
 	}
 
-	public ImportRecord transformSourceRecords(RecordType rt){
+    /**
-		 return new ImportRecord(new LinkedList<MetadatumDTO>(getMetadataFieldMapping().resultToDCValueMapping(rt)));
+     *  Return an ImportRecord constructed from the results in a RecordType
+     * @param recordType The recordtype to retrieve the DCValueMapping from
+     * @return An {@link ImportRecord}, This is based on the results retrieved from the recordTypeMapping
+     */
+	public ImportRecord transformSourceRecords(RecordType recordType){
+		 return new ImportRecord(new LinkedList<>(getMetadataFieldMapping().resultToDCValueMapping(recordType)));
 	}
 }

dspace-api/src/main/java/org/dspace/importer/external/service/ImportService.java

@@ -26,16 +26,24 @@ import java.util.*;
  * @author Roeland Dillen (roeland at atmire dot com)
  */
 public class ImportService implements Destroyable {
-    private HashMap<String, Imports> importSources = new HashMap<String, Imports>();
+    private HashMap<String, Imports> importSources = new HashMap<>();
 
     Logger log = Logger.getLogger(ImportService.class);
 
+    /**
+     * Constructs an empty ImportService class object
+     */
     public ImportService() {
 
     }
 
     protected static final String ANY = "*";
 
+    /**
+     * Sets the importsources that will be used to delegate the retrieving and matching of records to
+     * @param importSources A list of {@link org.dspace.importer.external.service.other.Imports} to set to this service
+     * @throws MetadataSourceException
+     */
     @Autowired(required = false)
     public void setImportSources(List<Imports> importSources) throws MetadataSourceException {
         log.info("Loading " + importSources.size() + " import sources.");
@@ -45,6 +53,10 @@ public class ImportService implements Destroyable {
 
     }
 
+    /**
+     * Retrieve the importSources set to this class.
+     * @return  An unmodifiableMap of importSources
+     */
     protected Map<String, Imports> getImportSources() {
         return Collections.unmodifiableMap(importSources);
     }
@@ -154,7 +166,7 @@ public class ImportService implements Destroyable {
 	 */
     public Collection<ImportRecord> getRecords(String uri, String query, int start, int count) throws MetadataSourceException {
 		try {
-			List<ImportRecord> recordList = new LinkedList<ImportRecord>();
+			List<ImportRecord> recordList = new LinkedList<>();
 			for (Imports imports : matchingImports(uri)) {
 				recordList.addAll(imports.getRecords(query, start, count));
 			}
@@ -173,7 +185,7 @@ public class ImportService implements Destroyable {
 	 */
     public Collection<ImportRecord> getRecords(String uri, Query query) throws MetadataSourceException {
 		try {
-			List<ImportRecord> recordList = new LinkedList<ImportRecord>();
+			List<ImportRecord> recordList = new LinkedList<>();
 			for (Imports imports : matchingImports(uri)) {
 				recordList.addAll(imports.getRecords(query));
 			}
@@ -220,11 +232,15 @@ public class ImportService implements Destroyable {
 		}
 	}
 
+    /** Retrieve the importUrls that are set on the importSources .
+     *  @return a Collection of string, representing the configured importUrls
+     */
     public Collection<String> getImportUrls() {
         return importSources.keySet();
     }
 
-
+    /** Call destroy on all {@link Destroyable} {@link Imports} objects set in this ImportService
+     */
     @Override
     public void destroy() throws Exception {
         for (Imports imports : importSources.values()) {

dspace-api/src/main/java/org/dspace/importer/external/service/other/Destroyable.java

@@ -10,9 +10,12 @@ package org.dspace.importer.external.service.other;
 
 /**
  * @author Roeland Dillen (roeland at atmire dot com)
- * Date: 26/09/12
- * Time: 11:09
  */
 public interface Destroyable {
+
+    /**
+     * Destroy the object
+     * @throws Exception
+     */
     public void destroy() throws Exception;
 }

dspace-api/src/main/java/org/dspace/importer/external/service/other/Imports.java

@@ -44,29 +44,29 @@ public interface Imports {
      */
     public Collection<ImportRecord> getRecords(String query, int start, int count)throws MetadataSourceException;
 
-    /**
+    /** Find records based on a object query.
      *
-     * @param q
+     * @param query a query object to base the search on.
-     * @return
+     * @return a set of records. Fully transformed.
      * @throws MetadataSourceException
      */
-    public Collection<ImportRecord> getRecords(Query q)throws MetadataSourceException;
+    public Collection<ImportRecord> getRecords(Query query)throws MetadataSourceException;
 
-    /**
+    /** Get a single record from the source.
-     *
+     * The first match will be returned
-     * @param id
+     * @param id identifier for the record
-     * @return
+     * @return a matching record
      * @throws MetadataSourceException
      */
     public ImportRecord getRecord(String id)throws MetadataSourceException;
 
-    /**
+    /** Get a single record from the source.
-     *
+     * The first match will be returned
-     * @param q
+     * @param query a query matching a single record
-     * @return
+     * @return a matching record
      * @throws MetadataSourceException
      */
-    public ImportRecord getRecord(Query q)throws MetadataSourceException;
+    public ImportRecord getRecord(Query query)throws MetadataSourceException;
 
 	/**
      * The string that identifies this import implementation. Preferable a URI
@@ -74,7 +74,19 @@ public interface Imports {
      */
     public String getImportSource();
 
+    /** Finds records based on an item
+     * Delegates to one or more Imports implementations based on the uri.  Results will be aggregated.
+     * @param item an item to base the search on
+     * @return a collection of import records. Only the identifier of the found records may be put in the record.
+     * @throws MetadataSourceException if the underlying imports throw any exception.
+     */
     public Collection<ImportRecord> findMatchingRecords(Item item) throws MetadataSourceException;
 
-    public Collection<ImportRecord> findMatchingRecords(Query q) throws MetadataSourceException;
+    /** Finds records based on query object.
+     *  Delegates to one or more Imports implementations based on the uri.  Results will be aggregated.
+     * @param query a query object to base the search on.
+     * @return a collection of import records. Only the identifier of the found records may be put in the record.
+     * @throws MetadataSourceException
+     */
+    public Collection<ImportRecord> findMatchingRecords(Query query) throws MetadataSourceException;
 }

dspace-api/src/main/java/org/dspace/importer/external/service/other/MetadataSource.java

@@ -22,7 +22,7 @@ import java.util.concurrent.locks.ReentrantLock;
 
 /**
  * This class contains functionality to handle request timeouts and to retry requests.
- * This is useful in cas the service employs throttling and to deal with general network issues.
+ * This is useful in case the service employs throttling and to deal with general network issues.
  * @author: Antoine Snyers (antoine at atmire dot com)
  */
 public abstract class MetadataSource {
@@ -40,45 +40,82 @@ public abstract class MetadataSource {
     protected Map<Class, List<SourceExceptionHandler>> exceptionHandlersMap;
     protected Exception error;
 
-
+    /**
+     * Constructs an empty MetadataSource class object and initializes the Exceptionhandlers
+     */
     protected MetadataSource() {
         initExceptionHandlers();
     }
 
+    /**
+     *  initialize the exceptionHandlersMap with an empty {@link java.util.LinkedHashMap}
+     */
     protected void initExceptionHandlers() {
-        exceptionHandlersMap = new LinkedHashMap<Class, List<SourceExceptionHandler>>();
+        exceptionHandlersMap = new LinkedHashMap<>();
         // if an exception is thrown that is not in there, it is not recoverable and the retry chain will stop
         // by default all exceptions are fatal, but subclasses can add their own handlers for their own exceptions
     }
 
+    /**
+     * Return the warning message used for logging during exception catching
+     * @return a "warning" String
+     */
     public String getWarning() {
         return warning;
     }
 
+    /**
+     * Set the warning message used for logging
+     * @param warning
+     */
     public void setWarning(String warning) {
         this.warning = warning;
     }
 
+    /**
+     * Return the number of retries that have currently been undertaken
+     * @return the number of retries
+     */
     public int getRetry() {
         return retry;
     }
-
+    /**
+     * Return the number of max retries that can be undertaken before separate functionality kicks in
+     * @return the number of maximum retries
+     */
     public int getMaxRetry() {
         return maxRetry;
     }
+
+    /**
+     * Set the number of maximum retries before throwing on the exception
+     * @param maxRetry
+     */
     @Resource(name="maxRetry")
     public void setMaxRetry(int maxRetry) {
         this.maxRetry = maxRetry;
     }
 
+    /**
+     * Retrieve the operationId
+     * @return A randomly generated UUID. generated during the retry method
+     */
     public String getOperationId() {
         return operationId;
     }
 
+    /**
+     * Retrieve the last encountered exception
+     * @return An Exception object, the last one encountered in the retry method
+     */
     public Exception getError() {
         return error;
     }
 
+    /**
+     * Set the last encountered error
+     * @param error
+     */
     public void setError(Exception error) {
         this.error = error;
     }
@@ -145,34 +182,54 @@ public abstract class MetadataSource {
 
     }
 
-    protected void handleException(int retry, Exception e, String operationId) throws MetadataSourceException {
+    /**
+     * Handles a given exception or throws on a {@link org.dspace.importer.external.MetadataSourceException} if no ExceptionHandler is set
+     * @param retry The number of retries before the exception was thrown on
+     * @param exception The exception to handle
+     * @param operationId The id of the operation that threw the exception
+     * @throws MetadataSourceException if no ExceptionHandler is configured for the given exception
+     */
+    protected void handleException(int retry, Exception exception, String operationId) throws MetadataSourceException {
 
-        List<SourceExceptionHandler> exceptionHandlers = getExceptionHandler(e);
+        List<SourceExceptionHandler> exceptionHandlers = getExceptionHandler(exception);
         if (exceptionHandlers != null && !exceptionHandlers.isEmpty()) {
             for (SourceExceptionHandler exceptionHandler : exceptionHandlers) {
                 exceptionHandler.handle(this);
             }
         }else{
-            throwSourceException(retry, e, operationId);
+            throwSourceException(retry, exception, operationId);
         }
     }
 
-    protected List<SourceExceptionHandler> getExceptionHandler(Exception e) {
+    /** Retrieve a list of SourceExceptionHandler objects that have an instanceof the exception configured to them.
+     * @param exception The exception to base the retrieval of {@link org.dspace.importer.external.SourceExceptionHandler} on
+     * @return a list of {@link org.dspace.importer.external.SourceExceptionHandler} objects
+     */
+    protected List<SourceExceptionHandler> getExceptionHandler(Exception exception) {
         for (Class aClass : exceptionHandlersMap.keySet()) {
-            if (aClass.isInstance(e)) {
+            if (aClass.isInstance(exception)) {
                 return exceptionHandlersMap.get(aClass);
             }
         }
         return null;
     }
 
-    protected void throwSourceException(int retry, Exception e, String operationId) throws MetadataSourceException {
+    /** Throw a {@link MetadataSourceException}
+     * @param retry The number of retries before the exception was thrown on
+     * @param exception The exception to throw
+     * @param operationId The id of the operation that threw the exception
+     * @return a list of {@link org.dspace.importer.external.SourceExceptionHandler} objects
+     * @throws MetadataSourceException
+     */
+    protected void throwSourceException(int retry, Exception exception, String operationId) throws MetadataSourceException {
         throwSourceExceptionHook();
-//        log.error("Source exception", e);
+        log.error("Source exception " + exception.getMessage());
-        log.error("Source exception " + e.getMessage());
+        throw new MetadataSourceException("At retry of operation " + operationId + " " + retry, exception);
-        throw new MetadataSourceException("At retry of operation " + operationId + " " + retry, e);
     }
 
+    /**
+     * A specified point where methods can be specified or callbacks can be executed
+     */
     protected void throwSourceExceptionHook() {
 
     }