This is an automated email from the ASF dual-hosted git repository.
mawiesne pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/opennlp.git
The following commit(s) were added to refs/heads/main by this push:
new 2720a1b5 OPENNLP-1728: Improve JavaDoc of opennlp.tools.models package
(#772)
2720a1b5 is described below
commit 2720a1b545733db1a798362ee83ff1df9e34ec18
Author: Martin Wiesner <[email protected]>
AuthorDate: Fri Apr 25 17:32:20 2025 +0200
OPENNLP-1728: Improve JavaDoc of opennlp.tools.models package (#772)
---
.../tools/models/AbstractClassPathModelFinder.java | 15 ++++++++-----
.../java/opennlp/tools/models/ClassPathModel.java | 18 +++++++++++++++
.../opennlp/tools/models/ClassPathModelEntry.java | 2 +-
.../opennlp/tools/models/ClassPathModelFinder.java | 10 +++++++--
.../opennlp/tools/models/ClassPathModelLoader.java | 8 ++++++-
.../models/classgraph/ClassgraphModelFinder.java | 26 ++++++++++++++--------
.../models/simple/SimpleClassPathModelFinder.java | 6 ++---
7 files changed, 63 insertions(+), 22 deletions(-)
diff --git
a/opennlp-tools-models/src/main/java/opennlp/tools/models/AbstractClassPathModelFinder.java
b/opennlp-tools-models/src/main/java/opennlp/tools/models/AbstractClassPathModelFinder.java
index ea2b4c4c..b31128dd 100644
---
a/opennlp-tools-models/src/main/java/opennlp/tools/models/AbstractClassPathModelFinder.java
+++
b/opennlp-tools-models/src/main/java/opennlp/tools/models/AbstractClassPathModelFinder.java
@@ -24,9 +24,15 @@ import java.util.Optional;
import java.util.Set;
/**
- * Enables the detection of OpenNLP models in the classpath. By default, this
class will search
- * for JAR files starting with "opennlp-models-*". This wildcard pattern can
be adjusted by
- * using the alternative constructor of this class.
+ * A base implementation of a {@link ClassPathModelFinder} for the detection of
+ * OpenNLP models in the classpath. By default, {@link
AbstractClassPathModelFinder} will scan for
+ * JAR files starting with "opennlp-models-*".
+ * <p>
+ * This search mask can be adjusted by using the one argument
+ * {@link AbstractClassPathModelFinder#AbstractClassPathModelFinder(String)
constructor}.
+ * Wildcard search is supported by using asterisk symbol.
+ *
+ * @see ClassPathModelFinder
*/
public abstract class AbstractClassPathModelFinder implements
ClassPathModelFinder {
@@ -76,8 +82,7 @@ public abstract class AbstractClassPathModelFinder implements
ClassPathModelFind
}
/**
- * @apiNote
- * Subclasses can implement this method to provide additional context to
+ * @apiNote Subclasses can implement this method to provide additional
context to
* {@link AbstractClassPathModelFinder#getMatchingURIs(String, Object)}.
*
* @return A context information object. May be {@code null}.
diff --git
a/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModel.java
b/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModel.java
index f22fb901..d50f4580 100644
---
a/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModel.java
+++
b/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModel.java
@@ -18,6 +18,24 @@ package opennlp.tools.models;
import java.util.Properties;
+/**
+ * A record that holds the binary representation of an OpenNLP model and
related properties.
+ *
+ * @param properties The common and specific properties of a model.
+ * @param model The binary form of a model read from the classpath.
+ *
+ * @implNote To convert a model back to its object form, the {@code model
bytes} can be read
+ * via a {@link java.io.ByteArrayInputStream}:
+ * <pre>{@code
+ * try (InputStream baos = new ByteArrayInputStream(model)) {
+ * SentenceModel sModel = new SentenceModel(baos);
+ * }
+ * }</pre>
+ * as long as you make sure the model matches its type by using
+ * its name or other, more specific properties.
+ *
+ * @see opennlp.tools.util.model.BaseModel
+ */
public record ClassPathModel(Properties properties, byte[] model) {
/**
diff --git
a/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModelEntry.java
b/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModelEntry.java
index 7a34432e..3fa04a4c 100644
---
a/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModelEntry.java
+++
b/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModelEntry.java
@@ -20,7 +20,7 @@ import java.net.URI;
import java.util.Optional;
/**
- * Encapsulates a classpath entry that is associated with an {@link URI model
URI}
+ * Encapsulates a classpath entry that is associated with a {@link URI model
URI}
* and optional {@code properties}.
*
* @param model A valid {@link URI} associated with the model's location.
diff --git
a/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModelFinder.java
b/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModelFinder.java
index 6b0358ff..9e502e4a 100644
---
a/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModelFinder.java
+++
b/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModelFinder.java
@@ -18,16 +18,22 @@ package opennlp.tools.models;
import java.util.Set;
+/**
+ * Describes a scanner which detects OpenNLP specific model files in an
applications's classpath.
+ * If compatible models are present at runtime, each discovered element is
made available
+ * as {@link ClassPathModelEntry}.
+ */
public interface ClassPathModelFinder {
String OPENNLP_MODEL_JAR_PREFIX = "opennlp-models-*.jar";
/**
- * Finds OpenNLP models within the classpath.
+ * Finds OpenNLP models available within an applications's classpath.
*
* @param reloadCache {@code true}, if the internal cache should explicitly
be reloaded,
* {@code false} otherwise.
- * @return A Set of {@link ClassPathModelEntry model entries}. It might be
empty if none were found.
+ * @return A {@link Set} of {@link ClassPathModelEntry model entries}.
+ * It might be empty, if none were found.
*/
Set<ClassPathModelEntry> findModels(boolean reloadCache);
}
diff --git
a/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModelLoader.java
b/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModelLoader.java
index 1b67bb2d..2e51b664 100644
---
a/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModelLoader.java
+++
b/opennlp-tools-models/src/main/java/opennlp/tools/models/ClassPathModelLoader.java
@@ -22,7 +22,11 @@ import java.util.Objects;
import java.util.Properties;
/**
- * Responsible for loading OpenNLP models from the classpath.
+ * Responsible for loading OpenNLP models from the classpath via {@link
ClassPathModelEntry entries}.
+ * If models could be loaded successfully, those are provided as {@link
ClassPathModel model references}.
+ *
+ * @see ClassPathModel
+ * @see ClassPathModelEntry
*/
public class ClassPathModelLoader {
@@ -30,6 +34,8 @@ public class ClassPathModelLoader {
* Loads a {@link ClassPathModel} from a {@link ClassPathModelEntry}
*
* @param entry A valid {@link ClassPathModelEntry}, it must not be {@code
null}.
+ * Moreover, it is validated that the {@link
ClassPathModelEntry#model() binary data}
+ * and {@link ClassPathModelEntry#properties() meta-data} are
not {@code null}.
* @return A {@link ClassPathModel} containing the model resources.
* @throws IOException thrown if something went wrong during reading
resources from the classpath.
*/
diff --git
a/opennlp-tools-models/src/main/java/opennlp/tools/models/classgraph/ClassgraphModelFinder.java
b/opennlp-tools-models/src/main/java/opennlp/tools/models/classgraph/ClassgraphModelFinder.java
index 13dae921..c440945c 100644
---
a/opennlp-tools-models/src/main/java/opennlp/tools/models/classgraph/ClassgraphModelFinder.java
+++
b/opennlp-tools-models/src/main/java/opennlp/tools/models/classgraph/ClassgraphModelFinder.java
@@ -28,13 +28,20 @@ import opennlp.tools.models.AbstractClassPathModelFinder;
import opennlp.tools.models.ClassPathModelFinder;
/**
- * Enables the detection of OpenNLP models in the classpath via classgraph.
- * By default, this class will search for JAR files starting with
"opennlp-models-*".
- * This wildcard pattern can be adjusted by using the alternative constructor
of this class.
+ * Enables the detection of OpenNLP models in the classpath via
+ * <a href="https://github.com/classgraph/classgraph";>Classgraph</a>.
+ * <p>
+ * By default, this implementation will search for JAR files starting with
"opennlp-models-*".
+ * This search mask can be adjusted by using the one argument
+ * {@link ClassgraphModelFinder#ClassgraphModelFinder(String) constructor}.
Wildcard search is supported
+ * by using asterisk symbol.
*
- * @implNote This implementation relies on the <a
href="https://github.com/classgraph/classgraph";>Classgraph</a> library.
- * When using this class, you have to take care of <i>Classgraph</i> being in
the classpath
- * of your application, as it is declared as an optional dependency for
<i>opennlp-tools-models</i>.
+ * @implNote {@link ClassgraphModelFinder} relies on the <a
href="https://github.com/classgraph/classgraph";>
+ * Classgraph</a> library. For this reason, you have to take care of
<i>Classgraph</i> being present
+ * in the classpath of your application, as - by default - it is declared as
{@code optional} dependency of
+ * <i>opennlp-tools-models</i>.
+ *
+ * @see ClassPathModelFinder
*/
public class ClassgraphModelFinder extends AbstractClassPathModelFinder
implements ClassPathModelFinder {
@@ -46,7 +53,7 @@ public class ClassgraphModelFinder extends
AbstractClassPathModelFinder implemen
}
/**
- * @param modelJarPrefix The leafnames of the jars that should be canned
(e.g. "opennlp.jar").
+ * @param modelJarPrefix The leafnames of the jars that should be scanned
(e.g. "opennlp.jar").
* May contain a wildcard glob ("opennlp-*.jar"). It
must not be {@code null}.
*/
public ClassgraphModelFinder(String modelJarPrefix) {
@@ -64,11 +71,12 @@ public class ClassgraphModelFinder extends
AbstractClassPathModelFinder implemen
}
/**
- * Attempts to obtain {@link URI URIs} from the classpath.
+ * Attempts to obtain {@link URI URIs} from the classpath for the specified
{@code wildcardPattern}
+ * and {@code context}.
*
* @param wildcardPattern The pattern to use for scanning. Must not be
{@code null}.
* @param context An object holding context information. It might be
{@code null}.
- * @return A list of matching classpath {@link URI URIs}. It may be empty if
nothing is found.
+ * @return A list of matching classpath {@link URI URIs} which may be empty
if nothing is found.
*/
@Override
protected List<URI> getMatchingURIs(String wildcardPattern, Object context) {
diff --git
a/opennlp-tools-models/src/main/java/opennlp/tools/models/simple/SimpleClassPathModelFinder.java
b/opennlp-tools-models/src/main/java/opennlp/tools/models/simple/SimpleClassPathModelFinder.java
index bfe9902a..ebc7da9f 100644
---
a/opennlp-tools-models/src/main/java/opennlp/tools/models/simple/SimpleClassPathModelFinder.java
+++
b/opennlp-tools-models/src/main/java/opennlp/tools/models/simple/SimpleClassPathModelFinder.java
@@ -151,10 +151,8 @@ public class SimpleClassPathModelFinder extends
AbstractClassPathModelFinder imp
private List<URI> getURIsFromJar(URL fileUrl, boolean isWindows) throws
IOException {
final List<URI> uris = new ArrayList<>();
final URL jarUrl = new URL(JAR + ":" +
- (isWindows
- ? fileUrl.toString().replace("\\", "/")
- : fileUrl.toString())
- + "!/");
+ (isWindows ? fileUrl.toString().replace("\\", "/")
+ : fileUrl.toString()) + "!/");
final JarURLConnection jarConnection = (JarURLConnection)
jarUrl.openConnection();
try (JarFile jarFile = jarConnection.getJarFile()) {
final Enumeration<JarEntry> entries = jarFile.entries();
