De-brand the wordnet lexicon contract: WordNetLexicon -> LexicalKnowledgeBase

Renames the public seam interface so consumers describe what they are
injecting (a lexical knowledge base) rather than naming the WordNet
brand in a public API type. Concrete implementations that genuinely
are WordNet-format readers (InMemoryWordNetLexicon, WnLmfReader,
WndbReader) keep the WordNet name, since they describe the data
format they read, not the contract itself.

Author: krickert

…pennlp/tools/wordnet/WordNetLexicon.java …/tools/wordnet/LexicalKnowledgeBase.javaopennlp-api/src/main/java/opennlp/tools/wordnet/WordNetLexicon.java renamed to opennlp-api/src/main/java/opennlp/tools/wordnet/LexicalKnowledgeBase.java opennlp-api/src/main/java/opennlp/tools/wordnet/WordNetLexicon.java renamed to opennlp-api/src/main/java/opennlp/tools/wordnet/LexicalKnowledgeBase.java

@@ -20,15 +20,16 @@
 import java.util.Optional;
 
 /**
- * The wordnet lexicon seam: lemma and synset lookup over a loaded wordnet-style resource.
+ * The lexical knowledge base seam: lemma and synset lookup over a loaded lexical-semantic
+ * resource in the WordNet family.
  *
  * <p>This interface is the contract every wordnet-shaped dataset sits behind. A legacy Princeton
  * WNDB directory, a WN-LMF XML document (the Global WordNet Association interchange format used
  * by Open English WordNet and many other language wordnets), a future bundled
  * permissively-licensed lexicon, and a future user-downloaded CC-BY lexicon are all
- * implementations of this one seam, so a consumer written against {@code WordNetLexicon} never
- * changes when the data tier does. Nothing in the contract names a particular resource; synset
- * identity is opaque and source-qualified (see {@link Synset#id()}).</p>
+ * implementations of this one seam, so a consumer written against {@code LexicalKnowledgeBase}
+ * never changes when the data tier does. Nothing in the contract names a particular resource;
+ * synset identity is opaque and source-qualified (see {@link Synset#id()}).</p>
  *
  * <p>The surface is intentionally minimal but sufficient for the layered features above it:
  * lemma lookup and membership for morphological analysis (Morphy-style lemmatization), and
@@ -44,7 +45,7 @@
  * <p>Implementations must be immutable and thread-safe after loading: one instance is meant to
  * be shared across an application's threads for concurrent lookups.</p>
  */
-public interface WordNetLexicon {
+public interface LexicalKnowledgeBase {
 
   /**
    * Finds the synsets containing a lemma with a part of speech, in the source's sense order

opennlp-api/src/main/java/opennlp/tools/wordnet/Synset.java

@@ -30,7 +30,7 @@
  * <p>The shape is deliberately format-agnostic. The {@link #id() id} is an opaque,
  * source-qualified string minted by whichever reader produced the synset (a WN-LMF document's
  * own synset id, or an id a WNDB reader derives from the file position); consumers must not
- * parse it, only pass it back to {@link WordNetLexicon#synset(String)} and compare it for
+ * parse it, only pass it back to {@link LexicalKnowledgeBase#synset(String)} and compare it for
  * equality. Keeping identity opaque is what lets a bundled lexicon and a user-downloaded
  * lexicon sit behind the same seam, and lets later alignment layers join sources without a
  * contract change.</p>

opennlp-api/src/main/java/opennlp/tools/wordnet/WordNetRelation.java

@@ -22,7 +22,7 @@
  * <p>The value set covers the pointer types documented for the legacy Princeton WNDB format,
  * which is also the common core the WN-LMF interchange format expresses; both readers map their
  * format's names onto these values, so consumers navigate one relation vocabulary regardless of
- * the data tier behind the {@link WordNetLexicon} seam. {@link #PARTICIPLE} is part of that
+ * the data tier behind the {@link LexicalKnowledgeBase} seam. {@link #PARTICIPLE} is part of that
  * documented set (the adjective &quot;participle of verb&quot; pointer) even though it is easy
  * to overlook; without it, real Princeton data would be unreadable. Two values go beyond the
  * WNDB pointer set: {@link #ENTAILED_BY} and {@link #CAUSED_BY} cover the inverse relations

…lp/tools/wordnet/WordNetLexiconTest.java …ls/wordnet/LexicalKnowledgeBaseTest.javaopennlp-api/src/test/java/opennlp/tools/wordnet/WordNetLexiconTest.java renamed to opennlp-api/src/test/java/opennlp/tools/wordnet/LexicalKnowledgeBaseTest.java opennlp-api/src/test/java/opennlp/tools/wordnet/WordNetLexiconTest.java renamed to opennlp-api/src/test/java/opennlp/tools/wordnet/LexicalKnowledgeBaseTest.java

@@ -28,10 +28,10 @@
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 /**
- * Exercises the {@link WordNetLexicon} default methods against a minimal in-memory
+ * Exercises the {@link LexicalKnowledgeBase} default methods against a minimal in-memory
  * implementation, so the defaults are validated independently of any reader.
  */
-public class WordNetLexiconTest {
+public class LexicalKnowledgeBaseTest {
 
   private static final Synset DOG = new Synset("test-1-n", WordNetPos.NOUN, List.of("dog"),
       "a domesticated canid", Map.of(WordNetRelation.HYPERNYM, List.of("test-2-n")));
@@ -40,7 +40,7 @@ public class WordNetLexiconTest {
       "a carnivorous mammal", Map.of(WordNetRelation.HYPONYM, List.of("test-1-n")));
 
   // A deliberately tiny implementation of only the two abstract methods.
-  private static final WordNetLexicon LEXICON = new WordNetLexicon() {
+  private static final LexicalKnowledgeBase LEXICON = new LexicalKnowledgeBase() {
 
     @Override
     public List<Synset> lookup(String lemma, WordNetPos pos) {

opennlp-extensions/opennlp-wordnet/src/main/java/opennlp/wordnet/InMemoryWordNetLexicon.java

@@ -26,15 +26,15 @@
 import java.util.Optional;
 
 import opennlp.tools.commons.ThreadSafe;
+import opennlp.tools.wordnet.LexicalKnowledgeBase;
 import opennlp.tools.wordnet.Synset;
-import opennlp.tools.wordnet.WordNetLexicon;
 import opennlp.tools.wordnet.WordNetPos;
 import opennlp.tools.wordnet.WordNetRelation;
 
 /**
- * The immutable in-memory {@link WordNetLexicon} both readers produce: a synset table plus a
+ * The immutable in-memory {@link LexicalKnowledgeBase} both readers produce: a synset table plus a
  * folded (lemma, part of speech) index. Package-private because it is a reader product, not a
- * public entry point; consumers hold it as {@link WordNetLexicon}.
+ * public entry point; consumers hold it as {@link LexicalKnowledgeBase}.
  *
  * <p>Lemma matching follows the recommended seam semantics: keys are folded by lowercasing with
  * the root locale and treating the underscore some formats store in multiword lemmas as a
@@ -45,7 +45,7 @@
  * After construction all state is immutable, making instances safe for concurrent lookups.</p>
  */
 @ThreadSafe
-final class InMemoryWordNetLexicon implements WordNetLexicon {
+final class InMemoryWordNetLexicon implements LexicalKnowledgeBase {
 
   private final Map<String, Synset> synsetsById;
   private final Map<LemmaKey, List<Synset>> senseIndex;

opennlp-extensions/opennlp-wordnet/src/main/java/opennlp/wordnet/MorphyLemmatizer.java

@@ -22,13 +22,13 @@
 
 import opennlp.tools.commons.ThreadSafe;
 import opennlp.tools.lemmatizer.Lemmatizer;
-import opennlp.tools.wordnet.WordNetLexicon;
+import opennlp.tools.wordnet.LexicalKnowledgeBase;
 import opennlp.tools.wordnet.WordNetPos;
 
 /**
  * A clean-room implementation of the documented Morphy algorithm as a {@link Lemmatizer}:
  * exception-list lookup first, then the per-part-of-speech iterative detachment rules, with
- * every rule-derived candidate validated against a {@link WordNetLexicon} before it is
+ * every rule-derived candidate validated against a {@link LexicalKnowledgeBase} before it is
  * returned.
  *
  * <p><b>Algorithm.</b> For each token the part-of-speech tag is mapped to a
@@ -90,7 +90,7 @@ public final class MorphyLemmatizer implements Lemmatizer {
 
   private static final String[][] NO_RULES = {};
 
-  private final WordNetLexicon lexicon;
+  private final LexicalKnowledgeBase lexicon;
   private final MorphyExceptions exceptions;
 
   /**
@@ -102,7 +102,7 @@ public final class MorphyLemmatizer implements Lemmatizer {
    * @throws IllegalArgumentException Thrown if {@code lexicon} or {@code exceptions} is
    *     {@code null}.
    */
-  public MorphyLemmatizer(WordNetLexicon lexicon, MorphyExceptions exceptions) {
+  public MorphyLemmatizer(LexicalKnowledgeBase lexicon, MorphyExceptions exceptions) {
     if (lexicon == null) {
       throw new IllegalArgumentException("Lexicon must not be null");
     }

opennlp-extensions/opennlp-wordnet/src/main/java/opennlp/wordnet/WndbReader.java

@@ -28,14 +28,14 @@
 import java.util.List;
 import java.util.Map;
 
+import opennlp.tools.wordnet.LexicalKnowledgeBase;
 import opennlp.tools.wordnet.Synset;
-import opennlp.tools.wordnet.WordNetLexicon;
 import opennlp.tools.wordnet.WordNetPos;
 import opennlp.tools.wordnet.WordNetRelation;
 
 /**
  * Reads a legacy Princeton WNDB database directory ({@code index.noun}, {@code data.noun}, and
- * the corresponding pairs for verbs, adjectives, and adverbs) into a {@link WordNetLexicon}.
+ * the corresponding pairs for verbs, adjectives, and adverbs) into a {@link LexicalKnowledgeBase}.
  *
  * <p>The reader is clean-room, built from the published {@code wndb(5WN)} and
  * {@code wninput(5WN)} format documentation, with no third-party WordNet library involved. All
@@ -80,7 +80,7 @@ private WndbReader() {
    *     file and line.
    * @throws UncheckedIOException Thrown if reading a file fails.
    */
-  public static WordNetLexicon read(Path directory) {
+  public static LexicalKnowledgeBase read(Path directory) {
     if (directory == null) {
       throw new IllegalArgumentException("Directory must not be null");
     }

opennlp-extensions/opennlp-wordnet/src/test/java/opennlp/wordnet/LexiconConcurrencyTest.java

@@ -24,7 +24,7 @@
 
 import org.junit.jupiter.api.Test;
 
-import opennlp.tools.wordnet.WordNetLexicon;
+import opennlp.tools.wordnet.LexicalKnowledgeBase;
 import opennlp.tools.wordnet.WordNetPos;
 import opennlp.tools.wordnet.WordNetRelation;
 
@@ -42,7 +42,7 @@ public class LexiconConcurrencyTest {
 
   @Test
   void testConcurrentLookupsSeeConsistentResults() throws InterruptedException {
-    final WordNetLexicon lexicon = WndbReaderTest.fixture();
+    final LexicalKnowledgeBase lexicon = WndbReaderTest.fixture();
     final CountDownLatch start = new CountDownLatch(1);
     final CountDownLatch done = new CountDownLatch(THREADS);
     final Queue<String> problems = new ConcurrentLinkedQueue<>();
@@ -70,7 +70,7 @@ void testConcurrentLookupsSeeConsistentResults() throws InterruptedException {
     assertEquals(List.of(), List.copyOf(problems));
   }
 
-  private static void verifyOnce(WordNetLexicon lexicon, Queue<String> problems) {
+  private static void verifyOnce(LexicalKnowledgeBase lexicon, Queue<String> problems) {
     if (!"wndb-00001075-n".equals(lexicon.lookup("dog", WordNetPos.NOUN).get(0).id())) {
       problems.add("Wrong dog lookup");
     }

opennlp-extensions/opennlp-wordnet/src/test/java/opennlp/wordnet/ReaderEquivalenceTest.java

@@ -24,8 +24,8 @@
 
 import org.junit.jupiter.api.Test;
 
+import opennlp.tools.wordnet.LexicalKnowledgeBase;
 import opennlp.tools.wordnet.Synset;
-import opennlp.tools.wordnet.WordNetLexicon;
 import opennlp.tools.wordnet.WordNetPos;
 import opennlp.tools.wordnet.WordNetRelation;
 
@@ -61,7 +61,7 @@ void testBothReadersProduceEquivalentViews() {
 
   @Test
   void testLookupAgreesForEveryLemmaAndPos() {
-    final WordNetLexicon lmf = WnLmfReaderTest.fixture();
+    final LexicalKnowledgeBase lmf = WnLmfReaderTest.fixture();
     final InMemoryWordNetLexicon wndb = (InMemoryWordNetLexicon) WndbReaderTest.fixture();
     final Set<String> checked = new HashSet<>();
     for (final Synset synset : wndb.synsets()) {
@@ -82,8 +82,8 @@ void testLookupAgreesForEveryLemmaAndPos() {
 
   @Test
   void testSenseOrderAgreesForMultiSenseLemma() {
-    final WordNetLexicon lmf = WnLmfReaderTest.fixture();
-    final WordNetLexicon wndb = WndbReaderTest.fixture();
+    final LexicalKnowledgeBase lmf = WnLmfReaderTest.fixture();
+    final LexicalKnowledgeBase wndb = WndbReaderTest.fixture();
     final List<String> lmfOrder = glosses(lmf.lookup("run", WordNetPos.NOUN));
     final List<String> wndbOrder = glosses(wndb.lookup("run", WordNetPos.NOUN));
     assertEquals(2, lmfOrder.size());
@@ -102,7 +102,7 @@ private static Map<String, Synset> byGloss(InMemoryWordNetLexicon lexicon) {
 
   // A synset's relations with targets replaced by their glosses, id-scheme independent.
   private static Map<WordNetRelation, Set<String>> relationsByGloss(Synset synset,
-                                                                    WordNetLexicon lexicon) {
+                                                                    LexicalKnowledgeBase lexicon) {
     final Map<WordNetRelation, Set<String>> result = new HashMap<>();
     for (final Map.Entry<WordNetRelation, List<String>> relation :
         synset.relations().entrySet()) {

opennlp-extensions/opennlp-wordnet/src/test/java/opennlp/wordnet/WndbReaderTest.java

@@ -28,8 +28,8 @@
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 
+import opennlp.tools.wordnet.LexicalKnowledgeBase;
 import opennlp.tools.wordnet.Synset;
-import opennlp.tools.wordnet.WordNetLexicon;
 import opennlp.tools.wordnet.WordNetPos;
 import opennlp.tools.wordnet.WordNetRelation;
 
@@ -53,7 +53,7 @@ static Path fixtureDirectory() {
     }
   }
 
-  static WordNetLexicon fixture() {
+  static LexicalKnowledgeBase fixture() {
     return WndbReader.read(fixtureDirectory());
   }
 
@@ -71,7 +71,7 @@ void testLookupReturnsSynsetWithAllComponents() {
 
   @Test
   void testLookupFoldsCaseAndUnderscore() {
-    final WordNetLexicon lexicon = fixture();
+    final LexicalKnowledgeBase lexicon = fixture();
     assertEquals(DOG_ID, lexicon.lookup("Domestic_Dog", WordNetPos.NOUN).get(0).id());
     assertEquals(DOG_ID, lexicon.lookup("DOG", WordNetPos.NOUN).get(0).id());
   }
@@ -84,7 +84,7 @@ void testLookupKeepsIndexSenseOrder() {
 
   @Test
   void testRelationNavigation() {
-    final WordNetLexicon lexicon = fixture();
+    final LexicalKnowledgeBase lexicon = fixture();
     assertEquals(List.of(DOG_ID), lexicon.related(CANID_ID, WordNetRelation.HYPONYM));
     assertEquals(List.of("wndb-00001075-v", "wndb-00001171-v"),
         lexicon.related("wndb-00001324-v", WordNetRelation.HYPONYM));
@@ -94,7 +94,7 @@ void testRelationNavigation() {
 
   @Test
   void testLexicalPointersSurfaceAtSynsetLevel() {
-    final WordNetLexicon lexicon = fixture();
+    final LexicalKnowledgeBase lexicon = fixture();
     assertEquals(List.of("wndb-00001141-a"),
         lexicon.related("wndb-00001075-a", WordNetRelation.ANTONYM));
     assertEquals(List.of("wndb-00001075-a"),
@@ -103,7 +103,7 @@ void testLexicalPointersSurfaceAtSynsetLevel() {
 
   @Test
   void testSatelliteNormalizesToAdjectiveAndMarkerIsStripped() {
-    final WordNetLexicon lexicon = fixture();
+    final LexicalKnowledgeBase lexicon = fixture();
     final Synset large = lexicon.lookup("large", WordNetPos.ADJECTIVE).get(0);
     assertEquals(WordNetPos.ADJECTIVE, large.pos());
     assertEquals(List.of("wndb-00001211-a"), large.related(WordNetRelation.SIMILAR_TO));
@@ -114,7 +114,7 @@ void testSatelliteNormalizesToAdjectiveAndMarkerIsStripped() {
 
   @Test
   void testUnknownLemmaOrSynsetIsEmpty() {
-    final WordNetLexicon lexicon = fixture();
+    final LexicalKnowledgeBase lexicon = fixture();
     assertTrue(lexicon.lookup("zebra", WordNetPos.NOUN).isEmpty());
     assertTrue(lexicon.synset("wndb-99999999-n").isEmpty());
   }