(hugegraph) branch master updated: fix(struct): exclude optional word from runtime (#3295)

[ji...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

imbajin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/hugegraph.git


The following commit(s) were added to refs/heads/master by this push:
     new 688551990 fix(struct): exclude optional word from runtime (#3295)
688551990 is described below

commit 68855199031d5801edb4fe41b2bacbacffe8fe68
Author: imbajin <ji...@apache.org>
AuthorDate: Fri Oct 9 14:52:10 2026 +0800

    fix(struct): exclude optional word from runtime (#3295)
    
    - keep word as a provided compile and test dependency
    - omit word and its unused runtime transitives from packages
    - report a missing optional analyzer dependency clearly
    - document external installation and test both classpaths
---
 docs/BUILDING.md                                   | 24 +++++++++++++
 .../apache/hugegraph/unit/core/AnalyzerTest.java   | 10 ++++++
 hugegraph-struct/pom.xml                           |  2 ++
 .../apache/hugegraph/analyzer/AnalyzerFactory.java |  8 ++++-
 .../hugegraph/analyzer/AnalyzerFactoryTest.java    | 39 ++++++++++++++++++++++
 .../scripts/dependency/known-dependencies.txt      |  7 ----
 6 files changed, 82 insertions(+), 8 deletions(-)

diff --git a/docs/BUILDING.md b/docs/BUILDING.md
index 26e5aa9f4..3501f174d 100644
--- a/docs/BUILDING.md
+++ b/docs/BUILDING.md
@@ -20,6 +20,30 @@ upgraded runtime, client configuration and compatibility checks.
 
 To build without executing tests: `mvn clean package -Dmaven.test.skip=true`
 
+## Optional word analyzer
+
+The standard distribution does not include `org.apdplat:word:1.3`. It is a
+provided dependency used to compile and test the optional `word` analyzer.
+The default analyzer remains `ikanalyzer`; the shipped graph configurations
+use `jieba`, and neither requires the word library.
+
+Obtain the GPLv3-licensed external component from
+[Maven Central](https://repo.maven.apache.org/maven2/org/apdplat/word/1.3/word-1.3.jar).
+
+To use `word`, supply `word-1.3.jar` separately in the Server's `lib/` directory
+and restart the Server. Select it in the graph configuration with a supported
+mode, for example:
+
+```properties
+search.text_analyzer=word
+search.text_analyzer_mode=PureEnglish
+```
+
+Selecting `word` without its external library fails with a configuration error
+identifying the missing optional dependency. Other analyzers remain available.
+Applications using Struct directly must add the same dependency to their
+runtime classpath when selecting `word`.
+
 ## Building in IDEA
 
 To build without executing tests:
diff --git a/hugegraph-server/hugegraph-test/src/main/java/org/apache/hugegraph/unit/core/AnalyzerTest.java b/hugegraph-server/hugegraph-test/src/main/java/org/apache/hugegraph/unit/core/AnalyzerTest.java
index f2b2f02b1..47027e434 100644
--- a/hugegraph-server/hugegraph-test/src/main/java/org/apache/hugegraph/unit/core/AnalyzerTest.java
+++ b/hugegraph-server/hugegraph-test/src/main/java/org/apache/hugegraph/unit/core/AnalyzerTest.java
@@ -23,6 +23,7 @@ import java.util.Set;
 
 import org.apache.hugegraph.analyzer.Analyzer;
 import org.apache.hugegraph.analyzer.AnalyzerFactory;
+import org.apache.hugegraph.config.ConfigException;
 import org.apache.hugegraph.testutil.Assert;
 import org.junit.After;
 import org.junit.Before;
@@ -44,6 +45,15 @@ public class AnalyzerTest {
         // pass
     }
 
+    @Test
+    public void testWordAnalyzerRequiresOptionalDependency() {
+        ConfigException exception = Assert.assertThrows(ConfigException.class, () -> {
+            AnalyzerFactory.analyzer("word", "PureEnglish");
+        });
+        Assert.assertTrue(exception.getMessage().contains("org.apdplat:word:1.3"));
+        Assert.assertTrue(exception.getCause() instanceof NoClassDefFoundError);
+    }
+
     @Test
     public void testAnsjAnalyzer() {
         // BaseAnalysis mode
diff --git a/hugegraph-struct/pom.xml b/hugegraph-struct/pom.xml
index 763036833..b283fa9fb 100644
--- a/hugegraph-struct/pom.xml
+++ b/hugegraph-struct/pom.xml
@@ -138,6 +138,8 @@
             <groupId>org.apdplat</groupId>
             <artifactId>word</artifactId>
             <version>1.3</version>
+            <!-- External optional analyzer; compile/test it without shipping it. -->
+            <scope>provided</scope>
             <exclusions>
                 <exclusion>
                     <groupId>ch.qos.logback</groupId>
diff --git a/hugegraph-struct/src/main/java/org/apache/hugegraph/analyzer/AnalyzerFactory.java b/hugegraph-struct/src/main/java/org/apache/hugegraph/analyzer/AnalyzerFactory.java
index 2cf1dc1b0..61568c177 100644
--- a/hugegraph-struct/src/main/java/org/apache/hugegraph/analyzer/AnalyzerFactory.java
+++ b/hugegraph-struct/src/main/java/org/apache/hugegraph/analyzer/AnalyzerFactory.java
@@ -20,6 +20,7 @@ package org.apache.hugegraph.analyzer;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 
+import org.apache.hugegraph.config.ConfigException;
 import org.apache.hugegraph.exception.HugeException;
 
 public class AnalyzerFactory {
@@ -34,7 +35,12 @@ public class AnalyzerFactory {
         name = name.toLowerCase();
         switch (name) {
             case "word":
-                return new WordAnalyzer(mode);
+                try {
+                    return new WordAnalyzer(mode);
+                } catch (NoClassDefFoundError e) {
+                    throw new ConfigException("The word analyzer requires the optional " +
+                                              "org.apdplat:word:1.3 dependency on the runtime classpath", e);
+                }
             case "ansj":
                 return new AnsjAnalyzer(mode);
             case "hanlp":
diff --git a/hugegraph-struct/src/test/java/org/apache/hugegraph/analyzer/AnalyzerFactoryTest.java b/hugegraph-struct/src/test/java/org/apache/hugegraph/analyzer/AnalyzerFactoryTest.java
new file mode 100644
index 000000000..7f6a0de15
--- /dev/null
+++ b/hugegraph-struct/src/test/java/org/apache/hugegraph/analyzer/AnalyzerFactoryTest.java
@@ -0,0 +1,39 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hugegraph.analyzer;
+
+import org.apache.hugegraph.config.ConfigException;
+import org.junit.Assert;
+import org.junit.Test;
+
+public class AnalyzerFactoryTest {
+
+    @Test
+    public void testWordAnalyzerWithProvidedDependency() {
+        Analyzer analyzer = AnalyzerFactory.analyzer("word", "PureEnglish");
+        Assert.assertFalse(analyzer.segment("hello world").isEmpty());
+    }
+
+    @Test
+    public void testWordAnalyzerKeepsModeValidation() {
+        ConfigException exception = Assert.assertThrows(ConfigException.class, () -> {
+            AnalyzerFactory.analyzer("word", "invalid");
+        });
+        Assert.assertTrue(exception.getMessage().contains("Unsupported segment mode"));
+    }
+}
diff --git a/install-dist/scripts/dependency/known-dependencies.txt b/install-dist/scripts/dependency/known-dependencies.txt
index 30fb50a89..af5b2427a 100644
--- a/install-dist/scripts/dependency/known-dependencies.txt
+++ b/install-dist/scripts/dependency/known-dependencies.txt
@@ -62,7 +62,6 @@ commons-lang3-3.13.0.jar
 commons-lang3-3.18.0.jar
 commons-logging-1.1.1.jar
 commons-logging-1.2.jar
-commons-pool2-2.0.jar
 commons-text-1.10.0.jar
 commons-text-1.11.0.jar
 cucumber-core-7.21.1.jar
@@ -225,7 +224,6 @@ jcodings-1.0.58.jar
 jcommander-1.30.jar
 jcseg-core-2.6.2.jar
 jctools-core-2.1.1.jar
-jedis-2.5.1.jar
 jersey-apache-connector-3.0.3.jar
 jersey-client-3.0.3.jar
 jersey-common-3.0.3.jar
@@ -342,16 +340,13 @@ lombok-1.18.30.jar
 lookout-api-1.4.1.jar
 lucene-analyzers-common-8.11.2.jar
 lucene-analyzers-smartcn-8.11.2.jar
-lucene-backward-codecs-5.2.1.jar
 lucene-core-8.11.2.jar
-lucene-misc-5.2.1.jar
 lucene-queries-4.7.2.jar
 lucene-queries-5.2.1.jar
 lucene-queryparser-4.7.2.jar
 lucene-queryparser-5.2.1.jar
 lucene-sandbox-4.7.2.jar
 lucene-sandbox-5.2.1.jar
-lucene-suggest-5.2.1.jar
 lz4-java-1.4.0.jar
 lz4-java-1.8.1.jar
 messages-27.2.0.jar
@@ -433,7 +428,6 @@ parboiled-scala_2.12-1.2.0.jar
 parser-9.0-9.0.20190305.jar
 perfmark-api-0.25.0.jar
 picocli-4.7.6.jar
-pinyin4j-2.5.0.jar
 proto-google-common-protos-2.9.0.jar
 protobuf-java-3.22.3.jar
 protobuf-java-util-3.22.3.jar
@@ -516,7 +510,6 @@ websocket-client-9.4.51.v20230217.jar
 websocket-common-9.4.51.v20230217.jar
 websocket-server-9.4.51.v20230217.jar
 websocket-servlet-9.4.51.v20230217.jar
-word-1.3.jar
 xmlunit-core-2.8.4.jar
 zjsonpatch-0.3.0.jar
 zookeeper-3.8.6.jar