This is an automated email from the ASF dual-hosted git repository. mawiesne pushed a commit to branch OPENNLP-1728-Improve-JavaDoc-of-opennlp.tools.models-package in repository https://gitbox.apache.org/repos/asf/opennlp.git
commit ebb3de788ccf66d27a53660c23c9f2b67d45e3a7 Author: Martin Wiesner <[email protected]> AuthorDate: Wed Apr 23 21:38:13 2025 +0200 OPENNLP-1728: Improve JavaDoc of opennlp.tools.models package --- .../tools/models/AbstractClassPathModelFinder.java | 17 +++++++++----- .../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, 65 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..44a69a60 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 @@ -23,10 +23,18 @@ import java.util.Objects; import java.util.Optional; import java.util.Set; +import opennlp.tools.models.classgraph.ClassgraphModelFinder; + /** - * 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 ClassgraphModelFinder#ClassgraphModelFinder(String) constructor}. Wildcard search is supported + * by using asterisk symbol. + * + * @see ClassgraphModelFinder */ public abstract class AbstractClassPathModelFinder implements ClassPathModelFinder { @@ -76,8 +84,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();
