JPlagOptions.java 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251
  1. package de.jplag.options;
  2. import static de.jplag.options.Verbosity.LONG;
  3. import static de.jplag.strategy.ComparisonMode.NORMAL;
  4. import java.io.BufferedReader;
  5. import java.io.FileReader;
  6. import java.io.IOException;
  7. import java.nio.charset.Charset;
  8. import java.nio.charset.StandardCharsets;
  9. import java.util.*;
  10. import java.util.stream.Collectors;
  11. import org.slf4j.Logger;
  12. import org.slf4j.LoggerFactory;
  13. import de.jplag.JPlag;
  14. import de.jplag.Language;
  15. import de.jplag.clustering.ClusteringOptions;
  16. import de.jplag.strategy.ComparisonMode;
  17. /**
  18. * This record defines the options to configure {@link JPlag}.
  19. * @param language Language to use when parsing the submissions.
  20. * @param minimumTokenMatch Tunes the comparison sensitivity by adjusting the minimum token required to be counted as
  21. * matching section. A smaller {@code <n>} increases the sensitivity but might lead to more false-positives.
  22. * @param submissionDirectories Directories with new submissions. These must be checked for plagiarism.
  23. * @param oldSubmissionDirectories Directories with old submissions to check against.
  24. * @param baseCodeSubmissionName Path name of the directory containing the base code.
  25. * @param subdirectoryName Example: If the subdirectoryName is 'src', only the code inside submissionDir/src of each
  26. * submission will be used for comparison.
  27. * @param fileSuffixes List of file suffixes that should be included.
  28. * @param exclusionFileName Name of the file that contains the names of files to exclude from comparison.
  29. * @param similarityMetric The similarity metric determines how the minimum similarity threshold required for a
  30. * comparison (of two submissions) is calculated. This affects which comparisons are stored and thus make it into the
  31. * result object.
  32. * @param similarityThreshold Percentage value (must be between 0 and 100). Comparisons (of submissions pairs) with a
  33. * similarity below this threshold will be ignored. The default value of 0 allows all matches to be stored. This affects
  34. * which comparisons are stored and thus make it into the result object. See also {@link #similarityMetric()}.
  35. * @param maximumNumberOfComparisons The maximum number of comparisons that will be shown in the generated report. If
  36. * set to {@link #SHOW_ALL_COMPARISONS} all comparisons will be shown.
  37. * @param clusteringOptions Clustering options
  38. * @param comparisonMode Determines which strategy to use for the comparison of submissions.
  39. * @param verbosity Level of output verbosity.
  40. * @param debugParser If true, submissions that cannot be parsed will be stored in a separate directory.
  41. */
  42. public record JPlagOptions(Language language, Integer minimumTokenMatch, List<String> submissionDirectories, List<String> oldSubmissionDirectories,
  43. String baseCodeSubmissionName, String subdirectoryName, List<String> fileSuffixes, String exclusionFileName,
  44. SimilarityMetric similarityMetric, float similarityThreshold, int maximumNumberOfComparisons, ClusteringOptions clusteringOptions,
  45. ComparisonMode comparisonMode, Verbosity verbosity, boolean debugParser) {
  46. public static final ComparisonMode DEFAULT_COMPARISON_MODE = NORMAL;
  47. public static final float DEFAULT_SIMILARITY_THRESHOLD = 0;
  48. public static final int DEFAULT_SHOWN_COMPARISONS = 30;
  49. public static final int SHOW_ALL_COMPARISONS = 0;
  50. public static final SimilarityMetric DEFAULT_SIMILARITY_METRIC = SimilarityMetric.AVG;
  51. public static final Charset CHARSET = StandardCharsets.UTF_8;
  52. private static final Logger logger = LoggerFactory.getLogger(JPlag.class);
  53. public JPlagOptions(Language language, List<String> submissionDirectories, List<String> oldSubmissionDirectories) {
  54. this(language, null, submissionDirectories, oldSubmissionDirectories, null, null, null, null, DEFAULT_SIMILARITY_METRIC,
  55. DEFAULT_SIMILARITY_THRESHOLD, DEFAULT_SHOWN_COMPARISONS, new ClusteringOptions.Builder().build(), DEFAULT_COMPARISON_MODE, null,
  56. false);
  57. }
  58. public JPlagOptions(Language language, Integer minimumTokenMatch, List<String> submissionDirectories, List<String> oldSubmissionDirectories,
  59. String baseCodeSubmissionName, String subdirectoryName, List<String> fileSuffixes, String exclusionFileName,
  60. SimilarityMetric similarityMetric, float similarityThreshold, int maximumNumberOfComparisons, ClusteringOptions clusteringOptions,
  61. ComparisonMode comparisonMode, Verbosity verbosity, boolean debugParser) {
  62. this.language = language;
  63. this.comparisonMode = comparisonMode;
  64. this.debugParser = debugParser;
  65. this.fileSuffixes = fileSuffixes == null || fileSuffixes.isEmpty() ? null : Collections.unmodifiableList(fileSuffixes);
  66. this.similarityThreshold = normalizeSimilarityThreshold(similarityThreshold);
  67. this.maximumNumberOfComparisons = normalizeMaximumNumberOfComparisons(maximumNumberOfComparisons);
  68. this.similarityMetric = similarityMetric;
  69. this.minimumTokenMatch = normalizeMinimumTokenMatch(minimumTokenMatch);
  70. this.exclusionFileName = exclusionFileName;
  71. this.submissionDirectories = submissionDirectories == null ? null : Collections.unmodifiableList(submissionDirectories);
  72. this.oldSubmissionDirectories = oldSubmissionDirectories == null ? null : Collections.unmodifiableList(oldSubmissionDirectories);
  73. this.baseCodeSubmissionName = (baseCodeSubmissionName == null || baseCodeSubmissionName.isBlank()) ? null : baseCodeSubmissionName;
  74. this.subdirectoryName = subdirectoryName;
  75. this.verbosity = verbosity;
  76. this.clusteringOptions = clusteringOptions;
  77. }
  78. public JPlagOptions withLanguageOption(Language language) {
  79. return new JPlagOptions(language, minimumTokenMatch, submissionDirectories, oldSubmissionDirectories, baseCodeSubmissionName,
  80. subdirectoryName, fileSuffixes, exclusionFileName, similarityMetric, similarityThreshold, maximumNumberOfComparisons,
  81. clusteringOptions, comparisonMode, verbosity, debugParser);
  82. }
  83. public JPlagOptions withComparisonMode(ComparisonMode comparisonMode) {
  84. return new JPlagOptions(language, minimumTokenMatch, submissionDirectories, oldSubmissionDirectories, baseCodeSubmissionName,
  85. subdirectoryName, fileSuffixes, exclusionFileName, similarityMetric, similarityThreshold, maximumNumberOfComparisons,
  86. clusteringOptions, comparisonMode, verbosity, debugParser);
  87. }
  88. public JPlagOptions withDebugParser(boolean debugParser) {
  89. return new JPlagOptions(language, minimumTokenMatch, submissionDirectories, oldSubmissionDirectories, baseCodeSubmissionName,
  90. subdirectoryName, fileSuffixes, exclusionFileName, similarityMetric, similarityThreshold, maximumNumberOfComparisons,
  91. clusteringOptions, comparisonMode, verbosity, debugParser);
  92. }
  93. public JPlagOptions withFileSuffixes(List<String> fileSuffixes) {
  94. return new JPlagOptions(language, minimumTokenMatch, submissionDirectories, oldSubmissionDirectories, baseCodeSubmissionName,
  95. subdirectoryName, fileSuffixes, exclusionFileName, similarityMetric, similarityThreshold, maximumNumberOfComparisons,
  96. clusteringOptions, comparisonMode, verbosity, debugParser);
  97. }
  98. public JPlagOptions withSimilarityThreshold(float similarityThreshold) {
  99. return new JPlagOptions(language, minimumTokenMatch, submissionDirectories, oldSubmissionDirectories, baseCodeSubmissionName,
  100. subdirectoryName, fileSuffixes, exclusionFileName, similarityMetric, similarityThreshold, maximumNumberOfComparisons,
  101. clusteringOptions, comparisonMode, verbosity, debugParser);
  102. }
  103. public JPlagOptions withMaximumNumberOfComparisons(int maximumNumberOfComparisons) {
  104. return new JPlagOptions(language, minimumTokenMatch, submissionDirectories, oldSubmissionDirectories, baseCodeSubmissionName,
  105. subdirectoryName, fileSuffixes, exclusionFileName, similarityMetric, similarityThreshold, maximumNumberOfComparisons,
  106. clusteringOptions, comparisonMode, verbosity, debugParser);
  107. }
  108. public JPlagOptions withSimilarityMetric(SimilarityMetric similarityMetric) {
  109. return new JPlagOptions(language, minimumTokenMatch, submissionDirectories, oldSubmissionDirectories, baseCodeSubmissionName,
  110. subdirectoryName, fileSuffixes, exclusionFileName, similarityMetric, similarityThreshold, maximumNumberOfComparisons,
  111. clusteringOptions, comparisonMode, verbosity, debugParser);
  112. }
  113. public JPlagOptions withMinimumTokenMatch(Integer minimumTokenMatch) {
  114. return new JPlagOptions(language, minimumTokenMatch, submissionDirectories, oldSubmissionDirectories, baseCodeSubmissionName,
  115. subdirectoryName, fileSuffixes, exclusionFileName, similarityMetric, similarityThreshold, maximumNumberOfComparisons,
  116. clusteringOptions, comparisonMode, verbosity, debugParser);
  117. }
  118. public JPlagOptions withExclusionFileName(String exclusionFileName) {
  119. return new JPlagOptions(language, minimumTokenMatch, submissionDirectories, oldSubmissionDirectories, baseCodeSubmissionName,
  120. subdirectoryName, fileSuffixes, exclusionFileName, similarityMetric, similarityThreshold, maximumNumberOfComparisons,
  121. clusteringOptions, comparisonMode, verbosity, debugParser);
  122. }
  123. public JPlagOptions withSubmissionDirectories(List<String> submissionDirectories) {
  124. return new JPlagOptions(language, minimumTokenMatch, submissionDirectories, oldSubmissionDirectories, baseCodeSubmissionName,
  125. subdirectoryName, fileSuffixes, exclusionFileName, similarityMetric, similarityThreshold, maximumNumberOfComparisons,
  126. clusteringOptions, comparisonMode, verbosity, debugParser);
  127. }
  128. public JPlagOptions withOldSubmissionDirectories(List<String> oldSubmissionDirectories) {
  129. return new JPlagOptions(language, minimumTokenMatch, submissionDirectories, oldSubmissionDirectories, baseCodeSubmissionName,
  130. subdirectoryName, fileSuffixes, exclusionFileName, similarityMetric, similarityThreshold, maximumNumberOfComparisons,
  131. clusteringOptions, comparisonMode, verbosity, debugParser);
  132. }
  133. public JPlagOptions withBaseCodeSubmissionName(String baseCodeSubmissionName) {
  134. return new JPlagOptions(language, minimumTokenMatch, submissionDirectories, oldSubmissionDirectories, baseCodeSubmissionName,
  135. subdirectoryName, fileSuffixes, exclusionFileName, similarityMetric, similarityThreshold, maximumNumberOfComparisons,
  136. clusteringOptions, comparisonMode, verbosity, debugParser);
  137. }
  138. public JPlagOptions withSubdirectoryName(String subdirectoryName) {
  139. return new JPlagOptions(language, minimumTokenMatch, submissionDirectories, oldSubmissionDirectories, baseCodeSubmissionName,
  140. subdirectoryName, fileSuffixes, exclusionFileName, similarityMetric, similarityThreshold, maximumNumberOfComparisons,
  141. clusteringOptions, comparisonMode, verbosity, debugParser);
  142. }
  143. public JPlagOptions withVerbosity(Verbosity verbosity) {
  144. return new JPlagOptions(language, minimumTokenMatch, submissionDirectories, oldSubmissionDirectories, baseCodeSubmissionName,
  145. subdirectoryName, fileSuffixes, exclusionFileName, similarityMetric, similarityThreshold, maximumNumberOfComparisons,
  146. clusteringOptions, comparisonMode, verbosity, debugParser);
  147. }
  148. public JPlagOptions withClusteringOptions(ClusteringOptions clusteringOptions) {
  149. return new JPlagOptions(language, minimumTokenMatch, submissionDirectories, oldSubmissionDirectories, baseCodeSubmissionName,
  150. subdirectoryName, fileSuffixes, exclusionFileName, similarityMetric, similarityThreshold, maximumNumberOfComparisons,
  151. clusteringOptions, comparisonMode, verbosity, debugParser);
  152. }
  153. public boolean hasBaseCode() {
  154. return baseCodeSubmissionName != null;
  155. }
  156. public Set<String> excludedFiles() {
  157. return Optional.ofNullable(exclusionFileName()).map(this::readExclusionFile).orElse(Collections.emptySet());
  158. }
  159. @Override
  160. public List<String> fileSuffixes() {
  161. var language = language();
  162. if (fileSuffixes == null && language != null)
  163. return Arrays.stream(language.suffixes()).toList();
  164. return fileSuffixes == null ? null : Collections.unmodifiableList(fileSuffixes);
  165. }
  166. /**
  167. * Path name of the directory containing the base code.<br>
  168. * For backwards compatibility it may also be a directory name inside the root directory. Condition for the latter is
  169. * <ul>
  170. * <li>Specified path does not exist.</li>
  171. * <li>Name has not have a separator character after trimming them from both ends (leaving at least a one-character
  172. * name).</li>
  173. * <li>A submission with the specified name exists in the root directory.</li>
  174. * </ul>
  175. * It's an error if a string has been provided, but it is neither an existing path nor does it fulfill all the
  176. * conditions of the compatibility fallback listed above.
  177. */
  178. @Override
  179. public String baseCodeSubmissionName() {
  180. return baseCodeSubmissionName;
  181. }
  182. @Override
  183. public Integer minimumTokenMatch() {
  184. var language = language();
  185. if (minimumTokenMatch == null && language != null)
  186. return language.minimumTokenMatch();
  187. return minimumTokenMatch;
  188. }
  189. private Set<String> readExclusionFile(final String exclusionFileName) {
  190. try (BufferedReader reader = new BufferedReader(new FileReader(exclusionFileName, JPlagOptions.CHARSET))) {
  191. final var excludedFileNames = reader.lines().collect(Collectors.toSet());
  192. if (verbosity() == LONG && logger.isInfoEnabled()) {
  193. logger.info("Excluded files:\n{}", String.join("\n", excludedFileNames));
  194. }
  195. return excludedFileNames;
  196. } catch (IOException e) {
  197. logger.error("Could not read exclusion file: " + e.getMessage(), e);
  198. return Collections.emptySet();
  199. }
  200. }
  201. private static float normalizeSimilarityThreshold(float similarityThreshold) {
  202. if (similarityThreshold > 100) {
  203. logger.warn("Maximum threshold of 100 used instead of {}", similarityThreshold);
  204. return 100;
  205. } else if (similarityThreshold < 0) {
  206. logger.warn("Minimum threshold of 0 used instead of {}", similarityThreshold);
  207. return 0;
  208. } else {
  209. return similarityThreshold;
  210. }
  211. }
  212. private Integer normalizeMaximumNumberOfComparisons(Integer maximumNumberOfComparisons) {
  213. return Math.max(maximumNumberOfComparisons, SHOW_ALL_COMPARISONS);
  214. }
  215. private Integer normalizeMinimumTokenMatch(Integer minimumTokenMatch) {
  216. return (minimumTokenMatch != null && minimumTokenMatch < 1) ? Integer.valueOf(1) : minimumTokenMatch;
  217. }
  218. }