Applied community feedback, javadocs

dspace-api/src/test/data/dspaceFolder/config/entities/relationship-types.xml

@@ -116,7 +116,6 @@
         <rightLabel>isJournalIssueOfPublication</rightLabel>
         <leftCardinality>
             <min>0</min>
-            <max>2147483647</max>
         </leftCardinality>
         <rightCardinality>
             <min>0</min>

dspace-spring-rest/src/main/java/org/dspace/app/rest/RelationshipRestController.java

@@ -38,6 +38,9 @@ import org.springframework.web.bind.annotation.RequestMethod;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+/**
+ * This will be the entry point for the api/core/relationships endpoint with additional paths to it
+ */
 @RestController
 @RequestMapping("/api/core/relationships")
 public class RelationshipRestController {
@@ -67,6 +70,20 @@ public class RelationshipRestController {
     @Autowired
     private HalLinkService halLinkService;
 
+    /**
+     * This method will retrieve all the Relationships that have a RelationshipType which has a left or right label
+     * equal to the one passed along in the pathvariable.
+     * This is further filtered by an optional dso parameter to filter on only the relationships for the given dso
+     * if this is applicable
+     *
+     * @param response  The response object
+     * @param request   The request object
+     * @param label     The label on which the Relationship's RelationshipType will be matched
+     * @param dsoId     The ID of the dso on which we'll search for relationships if applicable
+     * @param pageable  The page object
+     * @return          A Resource containing all the relationships that meet the criteria
+     * @throws Exception    If something goes wrong
+     */
     @RequestMapping(method = RequestMethod.GET, value = REGEX_REQUESTMAPPING_LABEL)
     public RelationshipResourceWrapper retrieveByLabel(HttpServletResponse response,
                                                        HttpServletRequest request, @PathVariable String label,

dspace-spring-rest/src/main/java/org/dspace/app/rest/RelationshipTypeRestController.java

@@ -31,6 +31,11 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestMethod;
 import org.springframework.web.bind.annotation.RestController;
 
+/**
+ * This controller will handle all the incoming calls on the api/core/entitytypes/{id}/relationshiptypes endpoint
+ * where the id parameter can be filled in to match a specific entityType and then get all the relationshipTypes
+ * for the given EntityType
+ */
 @RestController
 @RequestMapping("/api/core/entitytypes/{id}/relationshiptypes")
 public class RelationshipTypeRestController {
@@ -51,6 +56,16 @@ public class RelationshipTypeRestController {
     @Autowired
     private HalLinkService halLinkService;
 
+    /**
+     * This method will retrieve all the RelationshipTypes that conform to the given EntityType by the given ID and
+     * it will return this in a wrapped resource.
+     *
+     * @param id        The ID of the EntityType objects that we'll use to retrieve the RelationshipTypes
+     * @param response  The response object
+     * @param request   The request object
+     * @return          The wrapped resource containing the list of RelationshipType objects as defined above
+     * @throws SQLException If something goes wrong
+     */
     @RequestMapping(method = RequestMethod.GET)
     public RelationshipTypeResourceWrapper retrieve(@PathVariable Integer id, HttpServletResponse response,
                                                     HttpServletRequest request) throws SQLException {

dspace-spring-rest/src/main/java/org/dspace/app/rest/link/relation/EntityTypeHalLinkFactory.java

@@ -16,16 +16,26 @@ import org.springframework.data.domain.Pageable;
 import org.springframework.hateoas.Link;
 import org.springframework.stereotype.Component;
 
+/**
+ * This class' purpose is to add the links to the EntityTypeResource. This function and class will be called
+ * and used
+ * when the HalLinkService addLinks methods is called as it'll iterate over all the different factories and check
+ * whether
+ * these are allowed to create links for said resource or not.
+ */
 @Component
 public class EntityTypeHalLinkFactory extends HalLinkFactory<EntityTypeResource, RelationshipTypeRestController> {
+    @Override
     protected void addLinks(EntityTypeResource halResource, Pageable pageable, LinkedList<Link> list) throws Exception {
         list.add(buildLink("relationshiptypes", getMethodOn().retrieve(halResource.getContent().getId(), null, null)));
     }
 
+    @Override
     protected Class<RelationshipTypeRestController> getControllerClass() {
         return RelationshipTypeRestController.class;
     }
 
+    @Override
     protected Class<EntityTypeResource> getResourceClass() {
         return EntityTypeResource.class;
     }

dspace-spring-rest/src/main/java/org/dspace/app/rest/link/relation/RelationshipResourceWrapperHalLinkFactory.java

@@ -21,9 +21,17 @@ import org.springframework.hateoas.Link;
 import org.springframework.stereotype.Component;
 import org.springframework.web.util.UriComponentsBuilder;
 
+/**
+ * This class' purpose is to add the links to the RelationshipResourceWrapper. This function and class will be called
+ * and used
+ * when the HalLinkService addLinks methods is called as it'll iterate over all the different factories and check
+ * whether
+ * these are allowed to create links for said resource or not.
+ */
 @Component
 public class RelationshipResourceWrapperHalLinkFactory
     extends HalLinkFactory<RelationshipResourceWrapper, RelationshipRestController> {
+    @Override
     protected void addLinks(RelationshipResourceWrapper halResource, Pageable pageable, LinkedList<Link> list)
         throws Exception {
 
@@ -35,6 +43,15 @@ public class RelationshipResourceWrapperHalLinkFactory
                                                    true, "relationships"));
     }
 
+    /**
+     * This method will construct a self link to the RelationshipRestController.retrieveByLabel method.
+     * This will be constructed so that the RelationshipResourceWrapper resource can contain this selflink
+     * and immediately point to the correct endpoint with it.
+     * @param content   The RelationshipRestWrapper from which we'll retrieve variables to construct the link
+     * @param pageable  The page object
+     * @return  The String determining the link to the correct endpoint
+     * @throws Exception    If something goes wrong
+     */
     public String getSelfLink(RelationshipRestWrapper content, Pageable pageable) throws Exception {
         if (content != null) {
             UriComponentsBuilder uriBuilderSelfLink = uriBuilder(getMethodOn()
@@ -46,10 +63,12 @@ public class RelationshipResourceWrapperHalLinkFactory
         return null;
     }
 
+    @Override
     protected Class<RelationshipRestController> getControllerClass() {
         return RelationshipRestController.class;
     }
 
+    @Override
     protected Class<RelationshipResourceWrapper> getResourceClass() {
         return RelationshipResourceWrapper.class;
     }

dspace-spring-rest/src/main/java/org/dspace/app/rest/link/relation/RelationshipTypeResourceWrapperHalLinkFactory.java

@@ -16,19 +16,29 @@ import org.springframework.data.domain.Pageable;
 import org.springframework.hateoas.Link;
 import org.springframework.stereotype.Component;
 
+/**
+ * This class' purpose is to add the links to the RelationshipTypeResourceWrapper.
+ * This function and class will be called and used
+ * when the HalLinkService addLinks methods is called as it'll iterate over all the different factories and check
+ * whether
+ * these are allowed to create links for said resource or not.
+ */
 @Component
 public class RelationshipTypeResourceWrapperHalLinkFactory
     extends HalLinkFactory<RelationshipTypeResourceWrapper, RelationshipTypeRestController> {
+    @Override
     protected void addLinks(RelationshipTypeResourceWrapper halResource, Pageable pageable, LinkedList<Link> list)
         throws Exception {
         list.add(buildLink(Link.REL_SELF, getMethodOn()
             .retrieve(halResource.getContent().getEntityTypeId(), null, null)));
     }
 
+    @Override
     protected Class<RelationshipTypeRestController> getControllerClass() {
         return RelationshipTypeRestController.class;
     }
 
+    @Override
     protected Class<RelationshipTypeResourceWrapper> getResourceClass() {
         return RelationshipTypeResourceWrapper.class;
     }

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

@@ -12,6 +12,11 @@ import java.util.List;
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import org.dspace.app.rest.RelationshipRestController;
 
+/**
+ * This is the RestWrapper object for the RelationshipRestResource class. This will contain all the data that is
+ * used in that resource and more specifically, the label, dsoid and list of RelationshipRest objects
+ * The other methods are generic getters and setters
+ */
 public class RelationshipRestWrapper implements RestAddressableModel {
 
     @JsonIgnore

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

@@ -12,6 +12,12 @@ import java.util.List;
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import org.dspace.app.rest.RelationshipTypeRestController;
 
+/**
+ * This is the RestWrapper object for the RelationshipTypeRestResource class. This will contain all the data that is
+ * used in that resource and more specifically, the entityTypeLabel, entityTypeId and list of
+ * RelationshipTypeRest objects
+ * The other methods are generic getters and setters
+ */
 public class RelationshipTypeRestWrapper implements RestAddressableModel {
 
     @JsonIgnore

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

@@ -15,8 +15,20 @@ import org.dspace.app.rest.model.RelationshipRestWrapper;
 import org.dspace.app.rest.utils.Utils;
 import org.springframework.data.domain.Pageable;
 
+/**
+ * This is the RelationshipResourceWrapper class which will take the RelationshipRestWrapper's data and transform
+ * this into a resource with the data, embeds and links.
+ */
 public class RelationshipResourceWrapper extends HALResource<RelationshipRestWrapper> {
 
+    /**
+     * The constructor for the RelationshipResourceWrapper
+     * This will call the HALResource constructor and additionally add embeds to the resource
+     * @param content           The RelationshipRestWrapper object that contains the data
+     * @param utils             The Util object
+     * @param totalElements     The total amount of elements to be included in the list
+     * @param pageable          The pageable object
+     */
     public RelationshipResourceWrapper(RelationshipRestWrapper content, Utils utils, Integer totalElements,
                                        Pageable pageable) {
         super(content);

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

@@ -14,8 +14,18 @@ import org.dspace.app.rest.model.RelationshipTypeRest;
 import org.dspace.app.rest.model.RelationshipTypeRestWrapper;
 import org.dspace.app.rest.utils.Utils;
 
+/**
+ * This is the RelationshipTypeResourceWrapper class which will take the
+ * RelationshipTypeRestWrapper's data and transform this into a resource with the data, embeds and links.
+ */
 public class RelationshipTypeResourceWrapper extends HALResource<RelationshipTypeRestWrapper> {
 
+    /**
+     * The constructor for the RelationshipTypeResourceWrapper
+     * This will call the HALResource constructor and additionally add embeds to the resource
+     * @param content           The RelationshipTypeRestWrapper object that contains the data
+     * @param utils             The Util object
+     */
     public RelationshipTypeResourceWrapper(RelationshipTypeRestWrapper content, Utils utils) {
         super(content);
         addEmbeds(content, utils);