improve type safety: Rule.getCorrectExamples() now returns a list o…

…f `CorrectExample`s instead of a list of `String`s.

languagetool-core/src/main/java/org/languagetool/rules/CommaWhitespaceRule.java

@@ -37,7 +37,7 @@
 public class CommaWhitespaceRule extends Rule {
 
   /** @since 3.3 */
-  public CommaWhitespaceRule(ResourceBundle messages, IncorrectExample incorrectExample, String correctExample) {
+  public CommaWhitespaceRule(ResourceBundle messages, IncorrectExample incorrectExample, CorrectExample correctExample) {
     super(messages);
     super.setCategory(Categories.MISC.getCategory(messages));
     setLocQualityIssueType(ITSIssueType.Whitespace);

languagetool-core/src/main/java/org/languagetool/rules/CorrectExample.java

@@ -0,0 +1,32 @@
+/* LanguageTool, a natural language style checker 
+ * Copyright (C) 2016 Daniel Naber (http://www.danielnaber.de)
+ * 
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
+ * USA
+ */
+package org.languagetool.rules;
+
+/**
+ * A text, typically a sentence, that doesn't contain an error,
+ * at least not one for a specific rule.
+ * @since 3.5
+ */
+public final class CorrectExample extends ExampleSentence {
+
+  public CorrectExample(String example) {
+    super(example);
+  }
+
+}

languagetool-core/src/main/java/org/languagetool/rules/Example.java

@@ -39,13 +39,11 @@ public static IncorrectExample wrong(String example) {
 
   /**
    * Create an example text (usually just one sentence) without an error - the fixed error (compared to the text created
-   * with {@link #wrong(String)}) must be marked with {@code <marker>...</marker>}.
-   * @throws IllegalArgumentException if the {@code <marker>...</marker>} is missing
-   * @since 2.5
+   * with {@link #wrong(String)}) can be marked with {@code <marker>...</marker>}.
+   * @since 2.5, return type modified in 3.5
    */
-  public static String fixed(String example) {
-    requireMarkup(example);
-    return example;
+  public static CorrectExample fixed(String example) {
+    return new CorrectExample(example);
   }
 
   private static void requireMarkup(String example) {

languagetool-core/src/main/java/org/languagetool/rules/ExampleSentence.java

@@ -0,0 +1,46 @@
+/* LanguageTool, a natural language style checker 
+ * Copyright (C) 2016 Daniel Naber (http://www.danielnaber.de)
+ * 
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
+ * USA
+ */
+package org.languagetool.rules;
+
+import java.util.Objects;
+
+/**
+ * @since 3.5
+ */
+public abstract class ExampleSentence {
+
+  protected final String example;
+
+  public ExampleSentence(String example) {
+    this.example = Objects.requireNonNull(example);
+  }
+
+  /**
+   * Return the example, typically one sentence.
+   */
+  public String getExample() {
+    return example;
+  }
+
+  @Override
+  public String toString() {
+    return example;
+  }
+
+}

languagetool-core/src/main/java/org/languagetool/rules/IncorrectExample.java

@@ -27,9 +27,8 @@
  * A text, typically a sentence, that contains an error.
  * @since 0.9.2
  */
-public final class IncorrectExample {
+public final class IncorrectExample extends ExampleSentence {
 
-  private final String example;
   private final List<String> corrections;
 
   public IncorrectExample(String example) {
@@ -40,17 +39,10 @@ public IncorrectExample(String example) {
    * @since 2.9
    */
   public IncorrectExample(String example, List<String> corrections) {
-    this.example = Objects.requireNonNull(example);
+    super(example);
     this.corrections = Collections.unmodifiableList(new ArrayList<>(corrections));
   }
 
-  /**
-   * Return the example that contains the error.
-   */
-  public String getExample() {
-    return example;
-  }
-
   /**
    * Return the possible corrections.
    */

languagetool-core/src/main/java/org/languagetool/rules/Rule.java

@@ -48,7 +48,7 @@ public abstract class Rule {
 
   protected final ResourceBundle messages;
 
-  private List<String> correctExamples = new ArrayList<>();
+  private List<CorrectExample> correctExamples = new ArrayList<>();
   private List<IncorrectExample> incorrectExamples = new ArrayList<>();
   private ITSIssueType locQualityIssueType = ITSIssueType.Uncategorized;
   private Category category;
@@ -191,14 +191,14 @@ public boolean useInOffice() {
   /**
    * Set the examples that are correct and thus do not trigger the rule.
    */
-  public final void setCorrectExamples(List<String> correctExamples) {
+  public final void setCorrectExamples(List<CorrectExample> correctExamples) {
     this.correctExamples = Objects.requireNonNull(correctExamples);
   }
 
   /**
    * Get example sentences that are correct and thus will not match this rule.
    */
-  public final List<String> getCorrectExamples() {
+  public final List<CorrectExample> getCorrectExamples() {
     return Collections.unmodifiableList(correctExamples);
   }
 
@@ -300,7 +300,7 @@ public void setLocQualityIssueType(ITSIssueType locQualityIssueType) {
    * with the error corrected.
    * @since 2.5
    */
-  protected void addExamplePair(IncorrectExample incorrectSentence, String correctSentence) {
+  protected void addExamplePair(IncorrectExample incorrectSentence, CorrectExample correctSentence) {
     incorrectExamples.add(incorrectSentence);
     correctExamples.add(correctSentence);
   }

languagetool-core/src/main/java/org/languagetool/rules/UppercaseSentenceStartRule.java

@@ -50,7 +50,7 @@ public class UppercaseSentenceStartRule extends Rule {
   private String lastParagraphString = "";
 
   /** @since 3.3 */
-  public UppercaseSentenceStartRule(ResourceBundle messages, Language language, IncorrectExample incorrectExample, String correctExample) {
+  public UppercaseSentenceStartRule(ResourceBundle messages, Language language, IncorrectExample incorrectExample, CorrectExample correctExample) {
     super(messages);
     super.setCategory(Categories.CASING.getCategory(messages));
     this.language = language;
@@ -61,7 +61,7 @@ public UppercaseSentenceStartRule(ResourceBundle messages, Language language, In
   }
 
   /**
-   * @deprecated use {@link #UppercaseSentenceStartRule(ResourceBundle, Language, IncorrectExample, String)} instead (deprecated since 3.3)
+   * @deprecated use {@link #UppercaseSentenceStartRule(ResourceBundle, Language, IncorrectExample, CorrectExample)} instead (deprecated since 3.3)
    */
   public UppercaseSentenceStartRule(ResourceBundle messages, Language language) {
     this(messages, language, null, null);

languagetool-core/src/main/java/org/languagetool/rules/patterns/FalseFriendRuleHandler.java

@@ -23,6 +23,7 @@
 import org.languagetool.Language;
 import org.languagetool.Languages;
 import org.languagetool.rules.Categories;
+import org.languagetool.rules.CorrectExample;
 import org.languagetool.rules.IncorrectExample;
 import org.xml.sax.Attributes;
 import org.xml.sax.SAXException;
@@ -169,7 +170,7 @@ public void endElement(String namespaceURI, String sName,
         break;
       case EXAMPLE:
         if (inCorrectExample) {
-          correctExamples.add(correctExample.toString());
+          correctExamples.add(new CorrectExample(correctExample.toString()));
         } else if (inIncorrectExample) {
           incorrectExamples.add(new IncorrectExample(incorrectExample.toString()));
         }

languagetool-core/src/main/java/org/languagetool/rules/patterns/PatternRuleHandler.java

@@ -28,10 +28,7 @@
 
 import org.apache.commons.lang.ObjectUtils;
 import org.languagetool.Languages;
-import org.languagetool.rules.Category;
-import org.languagetool.rules.CategoryId;
-import org.languagetool.rules.ITSIssueType;
-import org.languagetool.rules.IncorrectExample;
+import org.languagetool.rules.*;
 import org.languagetool.tagging.disambiguation.rules.DisambiguationPatternRule;
 import org.xml.sax.Attributes;
 import org.xml.sax.SAXException;
@@ -400,7 +397,7 @@ public void endElement(String namespaceURI, String sName,
         break;
       case EXAMPLE:
         if (inCorrectExample) {
-          correctExamples.add(correctExample.toString());
+          correctExamples.add(new CorrectExample(correctExample.toString()));
         } else if (inIncorrectExample) {
           IncorrectExample example;
           List<String> corrections = new ArrayList<>();

languagetool-core/src/main/java/org/languagetool/rules/patterns/XMLRuleHandler.java

@@ -28,6 +28,7 @@
 import org.jetbrains.annotations.Nullable;
 import org.languagetool.Language;
 import org.languagetool.chunking.ChunkTag;
+import org.languagetool.rules.CorrectExample;
 import org.languagetool.rules.IncorrectExample;
 import org.languagetool.tools.StringTools;
 import org.xml.sax.Attributes;
@@ -105,7 +106,7 @@ enum RegexpMode {
   protected StringBuilder elements;
   protected StringBuilder exceptions;
 
-  protected List<String> correctExamples = new ArrayList<>();
+  protected List<CorrectExample> correctExamples = new ArrayList<>();
   protected List<IncorrectExample> incorrectExamples = new ArrayList<>();
 
   protected boolean inPattern;

languagetool-core/src/main/java/org/languagetool/rules/spelling/hunspell/HunspellNoSuggestionRule.java

@@ -24,6 +24,7 @@
 import java.util.ResourceBundle;
 
 import org.languagetool.Language;
+import org.languagetool.rules.CorrectExample;
 import org.languagetool.rules.IncorrectExample;
 
 /**
@@ -41,7 +42,7 @@ public HunspellNoSuggestionRule(ResourceBundle messages, Language language) {
   /**
    * @since 3.3
    */
-  public HunspellNoSuggestionRule(ResourceBundle messages, Language language, IncorrectExample incorrectExample, String correctedExample) {
+  public HunspellNoSuggestionRule(ResourceBundle messages, Language language, IncorrectExample incorrectExample, CorrectExample correctedExample) {
     super(messages, language);
     addExamplePair(incorrectExample, correctedExample);
   }

languagetool-core/src/test/java/org/languagetool/rules/patterns/PatternRuleTest.java

@@ -21,10 +21,7 @@
 import org.junit.Test;
 import org.languagetool.*;
 import org.languagetool.databroker.ResourceDataBroker;
-import org.languagetool.rules.Category;
-import org.languagetool.rules.IncorrectExample;
-import org.languagetool.rules.Rule;
-import org.languagetool.rules.RuleMatch;
+import org.languagetool.rules.*;
 import org.languagetool.rules.spelling.SpellingCheckRule;
 import org.languagetool.tagging.disambiguation.rules.DisambiguationPatternRule;
 
@@ -447,12 +444,12 @@ private void assertSuggestionsDoNotCreateErrors(String badSentence, JLanguageToo
 
   private void testCorrectSentences(JLanguageTool languageTool, JLanguageTool allRulesLanguageTool,
                                     Language lang, AbstractPatternRule rule) throws IOException {
-    List<String> goodSentences = rule.getCorrectExamples();
+    List<CorrectExample> goodSentences = rule.getCorrectExamples();
     // necessary for XML Pattern rules containing <or>
     List<AbstractPatternRule> rules = allRulesLanguageTool.getPatternRulesByIdAndSubId(rule.getId(), rule.getSubId());
-    for (String goodSentence : goodSentences) {
+    for (CorrectExample goodSentenceObj : goodSentences) {
       // enable indentation use
-      goodSentence = goodSentence.replaceAll("[\\n\\t]+", "");
+      String goodSentence = goodSentenceObj.getExample().replaceAll("[\\n\\t]+", "");
       goodSentence = cleanXML(goodSentence);
       assertTrue(lang + ": Empty correct example in rule " + rule.getFullId(), goodSentence.trim().length() > 0);
       boolean isMatched = false;

languagetool-dev/src/main/java/org/languagetool/dev/UselessExampleFinder.java

@@ -22,6 +22,7 @@
 import org.languagetool.JLanguageTool;
 import org.languagetool.Language;
 import org.languagetool.Languages;
+import org.languagetool.rules.CorrectExample;
 import org.languagetool.rules.IncorrectExample;
 import org.languagetool.rules.Rule;
 import org.languagetool.rules.patterns.AbstractPatternRule;
@@ -35,6 +36,7 @@
 import java.util.List;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
+import java.util.stream.Collectors;
 
 /**
  * Finds and removes "useless" examples sentences. "Useless" are sentences
@@ -61,7 +63,7 @@ private void run(Language lang) throws IOException {
       if (!(rule instanceof PatternRule)) {
         continue;
       }
-      List<String> correctExamples = rule.getCorrectExamples();
+      List<CorrectExample> correctExamples = rule.getCorrectExamples();
       List<IncorrectExample> incorrectExamples = rule.getIncorrectExamples();
       for (IncorrectExample incorrectExample : incorrectExamples) {
         checkCorrections(rule, correctExamples, incorrectExample, xmlLines);
@@ -74,7 +76,8 @@ private void run(Language lang) throws IOException {
     }
   }
 
-  private void checkCorrections(Rule rule, List<String> correctExamples, IncorrectExample incorrectExample, List<String> xmlLines) {
+  private void checkCorrections(Rule rule, List<CorrectExample> correctExamplesObjs, IncorrectExample incorrectExample, List<String> xmlLines) {
+    List<String> correctExamples = correctExamplesObjs.stream().map(k -> k.getExample()).collect(Collectors.toList());
     List<String> corrections = incorrectExample.getCorrections();
     for (String correction : corrections) {
       String fixedSentence = incorrectExample.getExample().replaceAll("<marker>.*?</marker>", "<marker>" + correction.replace("$", "\\$") + "</marker>");

languagetool-gui-commons/src/main/java/org/languagetool/gui/Tools.java

@@ -37,6 +37,7 @@
 import org.apache.commons.lang.StringUtils;
 import org.languagetool.JLanguageTool;
 import org.languagetool.rules.Category;
+import org.languagetool.rules.CorrectExample;
 import org.languagetool.rules.IncorrectExample;
 import org.languagetool.rules.Rule;
 import org.languagetool.rules.patterns.FalseFriendPatternRule;
@@ -275,15 +276,15 @@ private static String encodeUrl(Rule rule) {
 
   private static String getExampleSentences(Rule rule, ResourceBundle messages) {
     StringBuilder examples = new StringBuilder(200);
-    java.util.List<IncorrectExample> incorrectExamples = rule.getIncorrectExamples();
+    List<IncorrectExample> incorrectExamples = rule.getIncorrectExamples();
     if (incorrectExamples.size() > 0) {
       String incorrectExample = incorrectExamples.iterator().next().getExample();
       String sentence = incorrectExample.replace("<marker>", "<span style='background-color:#ff8080'>").replace("</marker>", "</span>");
       examples.append("<br/>").append(sentence).append("&nbsp;<span style='color:red;font-style:italic;font-weight:bold'>x</span>");
     }
-    java.util.List<String> correctExamples = rule.getCorrectExamples();
+    List<CorrectExample> correctExamples = rule.getCorrectExamples();
     if (correctExamples.size() > 0) {
-      String correctExample = correctExamples.iterator().next();
+      String correctExample = correctExamples.iterator().next().getExample();
       String sentence = correctExample.replace("<marker>", "<span style='background-color:#80ff80'>").replace("</marker>", "</span>");
       examples.append("<br/>").append(sentence).append("&nbsp;<span style='color:green'>✓</span>");
     } else if (incorrectExamples.size() > 0) {

languagetool-standalone/CHANGES.md

@@ -5,6 +5,10 @@
 #### General
   * Bugfix: avoid repeating the same suggestion
 
+#### Java API
+  * `Rule.getCorrectExamples()` now returns a list of `CorrectExample`s
+    instead of a list of `String`s.
+
 
 ## 3.4 (2016-06-27)
 

languagetool-standalone/src/test/java/org/languagetool/rules/RuleTest.java

@@ -81,9 +81,9 @@ private void testExamples(Rule rule, JLanguageTool lt) throws IOException {
   }
 
   private void testCorrectExamples(Rule rule, JLanguageTool lt) throws IOException {
-    List<String> correctExamples = rule.getCorrectExamples();
-    for (String correctExample : correctExamples) {
-      String input = cleanMarkers(correctExample);
+    List<CorrectExample> correctExamples = rule.getCorrectExamples();
+    for (CorrectExample correctExample : correctExamples) {
+      String input = cleanMarkers(correctExample.getExample());
       enableOnlyOneRule(lt, rule);
       List<RuleMatch> ruleMatches = lt.check(input);
       assertEquals("Got unexpected rule match for correct example sentence:\n"