From 15e3e3a164dc6c8061d4925ad02c4dd0ca6bc9c5 Mon Sep 17 00:00:00 2001 From: Andrea Bollini Date: Sat, 27 Jan 2024 21:57:39 +0100 Subject: [PATCH] CST-5249 add javadoc --- .../app/suggestion/SuggestionEvidence.java | 6 +- .../app/suggestion/SuggestionSource.java | 3 +- .../app/suggestion/SuggestionTarget.java | 5 +- .../app/suggestion/openaire/DateScorer.java | 58 ++++++++++++++----- 4 files changed, 54 insertions(+), 18 deletions(-) diff --git a/dspace-api/src/main/java/org/dspace/app/suggestion/SuggestionEvidence.java b/dspace-api/src/main/java/org/dspace/app/suggestion/SuggestionEvidence.java index daa257c8d652..d7f04929a19a 100644 --- a/dspace-api/src/main/java/org/dspace/app/suggestion/SuggestionEvidence.java +++ b/dspace-api/src/main/java/org/dspace/app/suggestion/SuggestionEvidence.java @@ -8,7 +8,9 @@ package org.dspace.app.suggestion; /** - * + * This DTO class is returned by an {@link org.dspace.app.suggestion.openaire.EvidenceScorer} to model the concept of + * an evidence / fact that has been used to evaluate the precision of a suggestion increasing or decreasing the score + * of the suggestion. * * @author Andrea Bollini (andrea.bollini at 4science.it) */ @@ -17,7 +19,7 @@ public class SuggestionEvidence { /** name of the evidence */ private String name; - /** score of the evidence */ + /** positive or negative value to influence the score of the suggestion */ private double score; /** additional notes */ diff --git a/dspace-api/src/main/java/org/dspace/app/suggestion/SuggestionSource.java b/dspace-api/src/main/java/org/dspace/app/suggestion/SuggestionSource.java index 4a6f8dd7352f..6dcc3f7e1e4c 100644 --- a/dspace-api/src/main/java/org/dspace/app/suggestion/SuggestionSource.java +++ b/dspace-api/src/main/java/org/dspace/app/suggestion/SuggestionSource.java @@ -8,7 +8,8 @@ package org.dspace.app.suggestion; /** - * + * This DTO class is used to pass around the number of items interested by suggestion provided by a specific source + * (i.e. openaire) * * @author Andrea Bollini (andrea.bollini at 4science.it) */ diff --git a/dspace-api/src/main/java/org/dspace/app/suggestion/SuggestionTarget.java b/dspace-api/src/main/java/org/dspace/app/suggestion/SuggestionTarget.java index 7666379f7a86..db82aa8081ba 100644 --- a/dspace-api/src/main/java/org/dspace/app/suggestion/SuggestionTarget.java +++ b/dspace-api/src/main/java/org/dspace/app/suggestion/SuggestionTarget.java @@ -10,7 +10,8 @@ import org.dspace.content.Item; /** - * + * This DTO class is used to pass around the number of suggestions available from a specific source for a target + * repository item * * @author Andrea Bollini (andrea.bollini at 4science.it) */ @@ -29,7 +30,7 @@ public SuggestionTarget() { } /** - * Wrap a target person into a suggestion target. + * Wrap a target repository item (usually a person item) into a suggestion target. * * @param item must be not null */ diff --git a/dspace-api/src/main/java/org/dspace/app/suggestion/openaire/DateScorer.java b/dspace-api/src/main/java/org/dspace/app/suggestion/openaire/DateScorer.java index 3b3457b217fc..ae7bb89f3228 100644 --- a/dspace-api/src/main/java/org/dspace/app/suggestion/openaire/DateScorer.java +++ b/dspace-api/src/main/java/org/dspace/app/suggestion/openaire/DateScorer.java @@ -8,12 +8,15 @@ package org.dspace.app.suggestion.openaire; import java.util.Calendar; +import java.util.Collections; import java.util.Date; import java.util.GregorianCalendar; +import java.util.List; import org.dspace.app.suggestion.SuggestionEvidence; import org.dspace.app.suggestion.SuggestionUtils; import org.dspace.content.Item; +import org.dspace.content.MetadataValue; import org.dspace.content.service.ItemService; import org.dspace.external.model.ExternalDataObject; import org.dspace.util.MultiFormatDateParser; @@ -28,23 +31,60 @@ */ public class DateScorer implements EvidenceScorer { + /** + * if available it should contains the metadata field key in the form (schema.element[.qualifier]) that contains + * the birth date of the researcher + */ private String birthDateMetadata; - //private String educationDateMetadata; + /** + * if available it should contains the metadata field key in the form (schema.element[.qualifier]) that contains + * the date of graduation of the researcher. If the metadata has multiple values the min will be used + */ + private String educationDateMetadata; + /** + * Force the scorer to reject any publication that was issued before the specified date + */ private String minDateMetadata; + /** + * Force the scorer to reject any publication that was issued after the specified date + */ private String maxDateMetadata; + /** + * The minimal age that is expected for a researcher to be a potential author of a scholarly contribution + * (i.e. the minimum delta from the publication date and the birth date) + */ private int birthDateDelta = 20; + + /** + * The maximum age that is expected for a researcher to be a potential author of a scholarly contribution + * (i.e. the maximum delta from the publication date and the birth date) + */ private int birthDateRange = 50; + /** + * The number of year from/before the graduation that is expected for a researcher to be a potential + * author of a scholarly contribution (i.e. the minimum delta from the publication date and the first + * graduation date) + */ private int educationDateDelta = -3; + + /** + * The maximum scientific longevity that is expected for a researcher from its graduation to be a potential + * author of a scholarly contribution (i.e. the maximum delta from the publication date and the first + * graduation date) + */ private int educationDateRange = 50; @Autowired private ItemService itemService; + /** + * the metadata used in the publication to track the publication date (i.e. dc.date.issued) + */ private String publicationDateMetadata; public void setItemService(ItemService itemService) { @@ -58,7 +98,7 @@ public void setBirthDateMetadata(String birthDate) { public String getBirthDateMetadata() { return birthDateMetadata; } - /* + public void setEducationDateMetadata(String educationDate) { this.educationDateMetadata = educationDate; } @@ -66,7 +106,6 @@ public void setEducationDateMetadata(String educationDate) { public String getEducationDateMetadata() { return educationDateMetadata; } - */ public void setBirthDateDelta(int birthDateDelta) { this.birthDateDelta = birthDateDelta; @@ -99,6 +138,7 @@ public void setPublicationDateMetadata(String publicationDateMetadata) { /** * Method which is responsible to evaluate ImportRecord based on the publication date. * ImportRecords which have a date outside the defined or calculated expected range will be discarded. + * {@link DateScorer#birthDateMetadata}, {@link DateScorer#educationDateMetadata} * * @param importRecord the ExternalDataObject to check * @param researcher DSpace item @@ -153,14 +193,8 @@ private Integer[] calculateRange(Item researcher) { } else { String birthDateStr = getSingleValue(researcher, birthDateMetadata); int birthDateYear = getYear(birthDateStr); - int educationDateYear = -1; - /* - getListMetadataValues(researcher, educationDateMetadata) - .stream() - .mapToInt(x -> getYear(x.getValue())) - .filter(d -> d > 0) - .min().orElse(-1); - */ + int educationDateYear = getListMetadataValues(researcher, educationDateMetadata).stream() + .mapToInt(x -> getYear(x.getValue())).filter(d -> d > 0).min().orElse(-1); if (educationDateYear > 0) { return new Integer[] { minYear > 0 ? minYear : educationDateYear + educationDateDelta, @@ -177,7 +211,6 @@ private Integer[] calculateRange(Item researcher) { } } - /* private List getListMetadataValues(Item researcher, String metadataKey) { if (metadataKey != null) { return itemService.getMetadataByMetadataString(researcher, metadataKey); @@ -185,7 +218,6 @@ private List getListMetadataValues(Item researcher, String metada return Collections.EMPTY_LIST; } } - */ private String getSingleValue(Item researcher, String metadataKey) { if (metadataKey != null) {