Add javadocs: community feedback from https://github.com/4Science/DSpace/pull/37

dspace-api/src/main/java/org/dspace/browse/BrowsableDSpaceObject.java

@@ -13,32 +13,73 @@ import java.util.Map;
 
 import org.dspace.core.Constants;
 
+/**
+ * This is the basic interface that a data model entity need to implement to support browsing/retrieval
+ * 
+ * @author Andrea Bollini (andrea.bollini at 4science.it)
+ *
+ * @param <PK>
+ *            the Class of the primary key
+ */
 public interface BrowsableDSpaceObject<PK extends Serializable> {
     Map<String, Object> extraInfo = new HashMap<String, Object>();
 
+    /**
+     * A map of additional information exposed by the Entity to the browse/retrieve system
+     * 
+     * @return a map of extra information, by default an empty map is returned
+     */
     default public Map<String, Object> getExtraInfo() {
         return extraInfo;
     }
 
+    /**
+     * 
+     * @return true if the Entity should be considered finalized (archived in terms of DSpace Item)
+     */
     default public boolean isArchived() {
         return false;
     }
 
+    /**
+     * 
+     * @return true if the Entity should be included in the public discovery system (search/browse)
+     */
     default public boolean isDiscoverable() {
         return false;
     }
 
+    /**
+     * 
+     * @return the integer constant representing the Entity Type, @see {@link Constants}
+     */
     public int getType();
 
+    /**
+     * 
+     * @return the primary key of the Entity instance
+     */
     public PK getID();
 
+    /**
+     * 
+     * @return an unique id to index
+     */
     default String getUniqueIndexID() {
         return getType() + "-" + getID().toString();
     }
 
+    /**
+     * 
+     * @return a textual alias of the Entity Type @see {@link #getType()}
+     */
     default public String getTypeText() {
         return Constants.typeText[getType()];
     };
 
+    /**
+     * 
+     * @return the handle, if any of the object
+     */
     public String getHandle();
 }

dspace-api/src/main/java/org/dspace/content/Bitstream.java

@@ -23,7 +23,6 @@ import javax.persistence.Table;
 import javax.persistence.Transient;
 
 import org.apache.log4j.Logger;
-import org.dspace.browse.BrowsableDSpaceObject;
 import org.dspace.content.factory.ContentServiceFactory;
 import org.dspace.content.service.BitstreamService;
 import org.dspace.core.Constants;
@@ -435,17 +434,4 @@ public class Bitstream extends DSpaceObject implements DSpaceObjectLegacySupport
             .setMetadataSingleValue(context, this, "dcterms", "accessRights", null, null, acceptanceDate.toString());
     }
 
-    public BrowsableDSpaceObject getParentObject() {
-        Context context = new Context();
-        try {
-            return (BrowsableDSpaceObject) (getBitstreamService().getParentObject(context, this));
-        } catch (SQLException e) {
-            log.error(e.getMessage(), e);
-        }
-        return null;
-    }
-
-    public String getMetadata(String field) {
-        return getBitstreamService().getMetadata(this, field);
-    }
 }

dspace-api/src/main/java/org/dspace/content/Collection.java

@@ -350,7 +350,7 @@ public class Collection extends DSpaceObject implements DSpaceObjectLegacySuppor
         return legacyId;
     }
 
-    public CollectionService getCollectionService() {
+    private CollectionService getCollectionService() {
         if (collectionService == null) {
             collectionService = ContentServiceFactory.getInstance().getCollectionService();
         }

dspace-api/src/main/java/org/dspace/content/DSpaceObject.java

@@ -201,7 +201,4 @@ public abstract class DSpaceObject implements Serializable, ReloadableEntity<jav
         this.modified = true;
     }
 
-    public String getUniqueIndexID() {
-        return getType() + "-" + getID().toString();
-    }
 }

dspace-api/src/main/java/org/dspace/content/Item.java

@@ -377,6 +377,7 @@ public class Item extends DSpaceObject implements DSpaceObjectLegacySupport, Bro
         return itemService;
     }
 
+    @Override
     public String getTypeText() {
         return getItemService().getTypeText(this);
     }

dspace-api/src/main/java/org/dspace/content/WorkspaceItem.java

@@ -261,12 +261,7 @@ public class WorkspaceItem
 
     @Override
     public String getHandle() {
-        return getType() + "-" + getID();
+        return null;
-    }
-
-    @Override
-    public String getTypeText() {
-        return "workspaceitem";
     }
 
     @Override

dspace-api/src/main/java/org/dspace/content/dao/ItemDAO.java

@@ -132,6 +132,16 @@ public interface ItemDAO extends DSpaceObjectLegacySupportDAO<Item> {
      */
     int countItems(Context context, boolean includeArchived, boolean includeWithdrawn) throws SQLException;
 
+    /**
+     * Count number of items from the specified submitter based on specific status flags
+     *
+     * @param context          context
+     * @param submitter        the submitter
+     * @param includeArchived  whether to include archived items in count
+     * @param includeWithdrawn whether to include withdrawn items in count
+     * @return count of items
+     * @throws SQLException if database error
+     */
     public int countItems(Context context, EPerson submitter, boolean includeArchived, boolean includeWithdrawn)
         throws SQLException;
 

dspace-api/src/main/java/org/dspace/content/factory/ContentServiceFactoryImpl.java

@@ -37,9 +37,6 @@ import org.springframework.beans.factory.annotation.Autowired;
  */
 public class ContentServiceFactoryImpl extends ContentServiceFactory {
 
-//    @Autowired(required = true)
-//    private List<BrowsableObjectService<? extends BrowsableDSpaceObject<? extends Serializable>, Serializable>>
-//        browsableDSpaceObjectServices;
     @Autowired(required = true)
     private List<DSpaceObjectService<? extends DSpaceObject>> dSpaceObjectServices;
     @Autowired(required = true)

dspace-api/src/main/java/org/dspace/content/service/DSpaceObjectService.java

@@ -239,12 +239,56 @@ public interface DSpaceObjectService<T extends DSpaceObject> extends BrowsableOb
     public void addMetadata(Context context, T dso, MetadataField metadataField, String lang, List<String> values,
             List<String> authorities, List<Integer> confidences) throws SQLException;
 
+    /**
+     * Add metadata fields. These are appended to existing values.
+     * Use <code>clearDC</code> to remove values. The values are insert in the
+     * positions passed in the places argument.
+     *
+     * @param context       DSpace context
+     * @param dso           DSpaceObject
+     * @param metadataField the metadata field to which the value is to be set
+     * @param lang          the ISO639 language code, optionally followed by an underscore
+     *                      and the ISO3166 country code. <code>null</code> means the
+     *                      value has no language (for example, a date).
+     * @param values        the values to add.
+     * @param authorities   the external authority key for this value (or null)
+     * @param confidences   the authority confidence (default 0)
+     * @param places        the places to use for the supplied values
+     * @throws SQLException if database error
+     */
     public void addMetadata(Context context, T dso, MetadataField metadataField, String lang, List<String> values,
             List<String> authorities, List<Integer> confidences, List<Integer> places) throws SQLException;
 
+    /**
+     * Shortcut for {@link #addMetadata(Context, DSpaceObject, MetadataField, String, List, List, List)} when a single
+     * value need to be added
+     * 
+     * @param context
+     * @param dso
+     * @param metadataField
+     * @param language
+     * @param value
+     * @param authority
+     * @param confidence
+     * @throws SQLException
+     */
     public void addMetadata(Context context, T dso, MetadataField metadataField, String language, String value,
             String authority, int confidence) throws SQLException;
 
+    /**
+     * Shortcut for {@link #addMetadata(Context, DSpaceObject, MetadataField, String, List, List, List, List)} when a
+     * single value need to be added
+     * 
+     * @param context
+     * @param dso
+     * @param metadataField
+     * @param language
+     * @param value
+     * @param authority
+     * @param confidence
+     * @param place
+     * @throws SQLException
+     */
     public void addMetadata(Context context, T dso, MetadataField metadataField, String language, String value,
             String authority, int confidence, int place) throws SQLException;
 

dspace-api/src/main/java/org/dspace/content/service/ItemService.java

@@ -38,8 +38,6 @@ import org.dspace.eperson.Group;
  */
 public interface ItemService extends DSpaceObjectService<Item>, DSpaceObjectLegacySupportService<Item> {
 
-    public Item find(Context context, UUID id) throws SQLException;
-
     public Thumbnail getThumbnail(Context context, Item item, boolean requireOriginal) throws SQLException;
 
     /**
@@ -619,18 +617,25 @@ public interface ItemService extends DSpaceObjectService<Item>, DSpaceObjectLega
      * counts all items not in archive
      *
      * @param context DSpace context object
-     * @return total items
+     * @return total items NOT in archive
      * @throws SQLException if database error
      */
     int countNotArchivedItems(Context context) throws SQLException;
 
+    /**
+     * counts all items in archive
+     *
+     * @param context DSpace context object
+     * @return total items in archive
+     * @throws SQLException if database error
+     */
     int countArchivedItems(Context context) throws SQLException;
 
     /**
      * counts all withdrawn items
      *
      * @param context DSpace context object
-     * @return total items
+     * @return total items withdrawn
      * @throws SQLException if database error
      */
     int countWithdrawnItems(Context context) throws SQLException;
@@ -645,6 +650,17 @@ public interface ItemService extends DSpaceObjectService<Item>, DSpaceObjectLega
      */
     boolean isInProgressSubmission(Context context, Item item) throws SQLException;
 
+    /**
+     * counts all items regardless of their status (workspace, workflow, archived, withdrawn) from a specified submitter
+     *
+     * @param context
+     *            DSpace context object
+     * @param ep
+     *            the eperson to lookup as submitter
+     * @return total items from the ep eperson
+     * @throws SQLException
+     *             if database error
+     */
     public int countBySubmitter(Context context, EPerson ep) throws SQLException;
 
 }

dspace-api/src/main/java/org/dspace/workflowbasic/BasicWorkflowItem.java

@@ -202,11 +202,6 @@ public class BasicWorkflowItem implements WorkflowItem {
         }
     }
 
-    @Override
-    public String getTypeText() {
-        return "workflowitem";
-    }
-
     @Override
     public int getType() {
         return Constants.WORKFLOWITEM;
@@ -214,6 +209,6 @@ public class BasicWorkflowItem implements WorkflowItem {
 
     @Override
     public String getHandle() {
-        return getType() + "-" + getID();
+        return null;
     }
 }

dspace-api/src/main/java/org/dspace/xmlworkflow/XmlWorkflowServiceImpl.java

@@ -7,14 +7,10 @@
  */
 package org.dspace.xmlworkflow;
 
-import java.io.ByteArrayInputStream;
 import java.io.IOException;
-import java.io.InputStream;
-import java.nio.charset.StandardCharsets;
 import java.sql.SQLException;
 import java.util.ArrayList;
 import java.util.Collections;
-import java.util.Date;
 import java.util.HashMap;
 import java.util.Iterator;
 import java.util.List;
@@ -32,7 +28,6 @@ import org.dspace.authorize.AuthorizeException;
 import org.dspace.authorize.ResourcePolicy;
 import org.dspace.authorize.service.AuthorizeService;
 import org.dspace.content.Bitstream;
-import org.dspace.content.BitstreamFormat;
 import org.dspace.content.Bundle;
 import org.dspace.content.Collection;
 import org.dspace.content.DCDate;
@@ -892,10 +887,6 @@ public class XmlWorkflowServiceImpl implements XmlWorkflowService {
 
         itemService.update(context, myitem);
 
-        //send an internal message to the submitter
-        createMessage(context, myitem, rejection_message,
-                      I18nUtil.getMessage("message.subject.xmlworkflow.rejected.item", context));
-
         // convert into personal workspace
         WorkspaceItem wsi = returnToWorkspace(context, wi);
 
@@ -1059,41 +1050,6 @@ public class XmlWorkflowServiceImpl implements XmlWorkflowService {
         return ConfigurationManager.getProperty("dspace.url") + "/mydspace";
     }
 
-    public void createMessage(Context context, Item item, String description, String subject)
-        throws SQLException, IOException, AuthorizeException {
-        Bundle message = null;
-        for (Bundle bnd : item.getBundles()) {
-            if ("MESSAGE".equals(bnd.getName())) {
-                message = bnd;
-                break;
-            }
-        }
-        if (message == null) {
-            message = bundleService.create(context, item, "MESSAGE");
-        }
-
-        BitstreamFormat bitstreamFormat = bitstreamFormatService.findByMIMEType(context, "text/plain");
-
-        InputStream is = new ByteArrayInputStream(description.getBytes(StandardCharsets.UTF_8));
-        Bitstream bitMessage = bitstreamService.create(context, message, is);
-        bitMessage.setFormat(context, bitstreamFormat);
-        bitstreamService.addMetadata(context, bitMessage, "dc", "title", null, null, subject);
-        bitstreamService.addMetadata(context, bitMessage, "dc", "creator", null, null,
-                                     context.getCurrentUser().getFullName() + " <" + context.getCurrentUser()
-                                                                                            .getEmail() + ">");
-        bitstreamService.addMetadata(context, bitMessage, "dc", "date", "issued", null,
-                                     new DCDate(new Date()).toString());
-        bitstreamService.addMetadata(context, bitMessage, "dc", "type", null, null, "outbound");
-        bitstreamService.update(context, bitMessage);
-        authorizeService.addPolicy(context, bitMessage, Constants.READ, context.getCurrentUser());
-
-        Group controllers = groupService.findByName(context, "Controllers");
-        if (controllers != null) {
-            authorizeService.addPolicy(context, bitMessage, Constants.READ, controllers);
-        }
-    }
-
-
     protected void revokeReviewerPolicies(Context context, Item item) throws SQLException, AuthorizeException {
         // get bundle "ORIGINAL"
         Bundle originalBundle;

dspace-api/src/main/java/org/dspace/xmlworkflow/storedcomponents/ClaimedTask.java

@@ -124,11 +124,6 @@ public class ClaimedTask implements ReloadableEntity<Integer>, BrowsableDSpaceOb
         return workflowId;
     }
 
-    @Override
-    public String getTypeText() {
-        return "claimedtask";
-    }
-
     @Override
     public int getType() {
         return Constants.WORKFLOW_CLAIMED;

dspace-api/src/main/java/org/dspace/xmlworkflow/storedcomponents/PoolTask.java

@@ -139,11 +139,6 @@ public class PoolTask implements ReloadableEntity<Integer>, BrowsableDSpaceObjec
         return this.actionId;
     }
 
-    @Override
-    public String getTypeText() {
-        return "pooltask";
-    }
-
     @Override
     public int getType() {
         return Constants.WORKFLOW_POOL;

dspace-api/src/main/java/org/dspace/xmlworkflow/storedcomponents/XmlWorkflowItem.java

@@ -155,7 +155,8 @@ public class XmlWorkflowItem implements WorkflowItem, ReloadableEntity<Integer>,
 
     @Override
     public int getState() {
-        // FIXME
+        // FIXME not used by the xml workflow, should be removed when the basic workflow is removed and the interfaces
+        // simplified
         return 0;
     }
 

dspace-spring-rest/src/main/java/org/dspace/app/rest/converter/BrowsableDSpaceObjectConverter.java

@@ -20,6 +20,12 @@ import org.dspace.browse.BrowsableDSpaceObject;
 public abstract class BrowsableDSpaceObjectConverter<M extends BrowsableDSpaceObject,
     R extends org.dspace.app.rest.model.RestAddressableModel> extends DSpaceConverter<M, R> {
 
+    /**
+     * 
+     * @param bdso
+     *            the browsableDSpaceObject to check
+     * @return true if the actual converter implementation is able to manage the supplied BrowsableDSpaceObject
+     */
     public abstract boolean supportsModel(BrowsableDSpaceObject bdso);
 
 }

dspace-spring-rest/src/main/java/org/dspace/app/rest/converter/WorkflowItemConverter.java

@@ -136,7 +136,7 @@ public class WorkflowItemConverter
     }
 
 
-    public void addError(List<ErrorRest> errors, ErrorRest toAdd) {
+    private void addError(List<ErrorRest> errors, ErrorRest toAdd) {
 
         boolean found = false;
         String i18nKey = toAdd.getMessage();

dspace-spring-rest/src/main/java/org/dspace/app/rest/converter/WorkspaceItemConverter.java

@@ -138,7 +138,7 @@ public class WorkspaceItemConverter
     }
 
 
-    public void addError(List<ErrorRest> errors, ErrorRest toAdd) {
+    private void addError(List<ErrorRest> errors, ErrorRest toAdd) {
 
         boolean found = false;
         String i18nKey = toAdd.getMessage();

dspace-spring-rest/src/main/java/org/dspace/app/rest/model/ClaimedTaskRest.java

@@ -9,9 +9,10 @@ package org.dspace.app.rest.model;
 
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import org.dspace.app.rest.RestResourceController;
+import org.dspace.xmlworkflow.storedcomponents.ClaimedTask;
 
 /**
- * The WorkflowItem REST Resource
+ * The ClaimedTask REST Resource
  *
  * @author Andrea Bollini (andrea.bollini at 4science.it)
  */
@@ -41,6 +42,10 @@ public class ClaimedTaskRest extends BaseObjectRest<Integer> {
         return RestResourceController.class;
     }
 
+    /**
+     * @see ClaimedTask#getStepID()
+     * @return the step
+     */
     public String getStep() {
         return step;
     }
@@ -49,6 +54,10 @@ public class ClaimedTaskRest extends BaseObjectRest<Integer> {
         this.step = step;
     }
 
+    /**
+     * @see ClaimedTaskRest#getAction()
+     * @return the action
+     */
     public String getAction() {
         return action;
     }
@@ -57,6 +66,10 @@ public class ClaimedTaskRest extends BaseObjectRest<Integer> {
         this.action = action;
     }
 
+    /**
+     * 
+     * @return the WorkflowItemRest that belong to this claimed task
+     */
     public WorkflowItemRest getWorkflowitem() {
         return workflowitem;
     }

dspace-spring-rest/src/main/java/org/dspace/app/rest/model/PoolTaskRest.java

@@ -9,6 +9,7 @@ package org.dspace.app.rest.model;
 
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import org.dspace.app.rest.RestResourceController;
+import org.dspace.xmlworkflow.storedcomponents.PoolTask;
 
 /**
  * The PoolTask REST Resource
@@ -41,6 +42,10 @@ public class PoolTaskRest extends BaseObjectRest<Integer> {
         return RestResourceController.class;
     }
 
+    /**
+     * @see PoolTask#getStepID()
+     * @return
+     */
     public String getStep() {
         return step;
     }
@@ -49,6 +54,10 @@ public class PoolTaskRest extends BaseObjectRest<Integer> {
         this.step = step;
     }
 
+    /**
+     * @see PoolTask#getActionID()
+     * @return
+     */
     public String getAction() {
         return action;
     }
@@ -57,6 +66,10 @@ public class PoolTaskRest extends BaseObjectRest<Integer> {
         this.action = action;
     }
 
+    /**
+     * 
+     * @return the WorkflowItemRest that belong to this pool task
+     */
     public WorkflowItemRest getWorkflowitem() {
         return workflowitem;
     }

dspace-spring-rest/src/main/java/org/dspace/app/rest/model/WorkflowItemRest.java

@@ -50,6 +50,10 @@ public class WorkflowItemRest extends BaseObjectRest<Integer> {
         return NAME;
     }
 
+    /**
+     * 
+     * @return the timestamp of the last modification done to the workflowitem
+     */
     public Date getLastModified() {
         return lastModified;
     }
@@ -58,6 +62,10 @@ public class WorkflowItemRest extends BaseObjectRest<Integer> {
         this.lastModified = lastModified;
     }
 
+    /**
+     * 
+     * @return the item wrapped by the workflowitem
+     */
     public ItemRest getItem() {
         return item;
     }
@@ -66,6 +74,10 @@ public class WorkflowItemRest extends BaseObjectRest<Integer> {
         this.item = item;
     }
 
+    /**
+     * 
+     * @return the SubmissionDefinition used by the workflowitem
+     */
     public SubmissionDefinitionRest getSubmissionDefinition() {
         return submissionDefinition;
     }
@@ -74,6 +86,10 @@ public class WorkflowItemRest extends BaseObjectRest<Integer> {
         this.submissionDefinition = submissionDefinition;
     }
 
+    /**
+     * 
+     * @return the submitter
+     */
     public EPersonRest getSubmitter() {
         return submitter;
     }
@@ -87,6 +103,10 @@ public class WorkflowItemRest extends BaseObjectRest<Integer> {
         return RestResourceController.class;
     }
 
+    /**
+     * 
+     * @return the data of the workflowitem organized according to the submission definition
+     */
     public Map<String, Serializable> getSections() {
         if (sections == null) {
             sections = new HashMap<String, Serializable>();
@@ -98,6 +118,10 @@ public class WorkflowItemRest extends BaseObjectRest<Integer> {
         this.sections = sections;
     }
 
+    /**
+     * 
+     * @return the collection where the workflow is in progress
+     */
     public CollectionRest getCollection() {
         return collection;
     }

dspace-spring-rest/src/main/java/org/dspace/app/rest/model/hateoas/ClaimedTaskResource.java

@@ -12,7 +12,7 @@ import org.dspace.app.rest.model.hateoas.annotations.RelNameDSpaceResource;
 import org.dspace.app.rest.utils.Utils;
 
 /**
- * PooledTask Rest HAL Resource. The HAL Resource wraps the REST Resource
+ * ClaimedTask Rest HAL Resource. The HAL Resource wraps the REST Resource
  * adding support for the links and embedded resources
  *
  * @author Andrea Bollini (andrea.bollini at 4science.it)