This is an automated email from the ASF dual-hosted git repository. mawiesne pushed a commit to branch OPENNLP-1658-Enhance-JavaDoc-of-code-in-opennlp-tools-models in repository https://gitbox.apache.org/repos/asf/opennlp.git
commit 01985797ae04b6dc7a13e4ca06316eb232ebdaee Author: Martin Wiesner <[email protected]> AuthorDate: Mon Nov 25 16:19:55 2024 +0100 OPENNLP-1658 Enhance JavaDoc of code in opennlp-tools-models --- .../tools/models/AbstractClassPathModelFinder.java | 15 +++---- .../java/opennlp/tools/models/ClassPathModel.java | 16 +++++++ .../opennlp/tools/models/ClassPathModelEntry.java | 7 ++++ .../opennlp/tools/models/ClassPathModelFinder.java | 5 ++- .../opennlp/tools/models/ClassPathModelLoader.java | 4 +- .../models/classgraph/ClassgraphModelFinder.java | 17 +++++--- .../models/simple/SimpleClassPathModelFinder.java | 49 +++++++++++++--------- 7 files changed, 77 insertions(+), 36 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 eeaa43d9..ea2b4c4c 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 @@ -36,7 +36,7 @@ public abstract class AbstractClassPathModelFinder implements ClassPathModelFind private Set<ClassPathModelEntry> models; /** - * By default, it scans for "opennlp-models-*.jar". + * By default, it scans for {@link #OPENNLP_MODEL_JAR_PREFIX}. */ public AbstractClassPathModelFinder() { this(OPENNLP_MODEL_JAR_PREFIX); @@ -47,7 +47,7 @@ public abstract class AbstractClassPathModelFinder implements ClassPathModelFind * May contain a wildcard glob ("opennlp-*.jar"). It must not be {@code null}. */ public AbstractClassPathModelFinder(String jarModelPrefix) { - Objects.requireNonNull(jarModelPrefix, "modelJarPrefix must not be null"); + Objects.requireNonNull(jarModelPrefix, "jarModelPrefix must not be null"); this.jarModelPrefix = jarModelPrefix; } @@ -76,19 +76,20 @@ public abstract class AbstractClassPathModelFinder implements ClassPathModelFind } /** + * @apiNote * Subclasses can implement this method to provide additional context to * {@link AbstractClassPathModelFinder#getMatchingURIs(String, Object)}. * - * @return a context information. May be {@code null}. + * @return A context information object. May be {@code null}. */ protected abstract Object getContext(); /** - * Return matching classpath URIs for the given pattern. + * Retrieve matching classpath {@link URI URIs} for the given {@code wildcardPattern}. * - * @param wildcardPattern the pattern. Must not be {@code null}. - * @param context an object holding context information. It might be {@code null}. - * @return a list of matching classpath URIs. + * @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 URIs. */ protected abstract List<URI> getMatchingURIs(String wildcardPattern, Object context); 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 97c21438..58e9fa66 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 @@ -20,18 +20,34 @@ import java.util.Properties; public record ClassPathModel(Properties properties, byte[] model) { + /** + * @return Retrieves the value of the {@code model.version} property + * or {@code "unknown"} if it could be read. + */ public String getModelVersion() { return properties != null ? properties.getProperty("model.version", "unknown") : "unknown"; } + /** + * @return Retrieves the value of the {@code model.name} property + * or {@code "unknown"} if it could be read. + */ public String getModelName() { return properties != null ? properties.getProperty("model.name", "unknown") : "unknown"; } + /** + * @return Retrieves the value of the {@code model.sha256} property + * or {@code "unknown"} if it could be read. + */ public String getModelSHA256() { return properties != null ? properties.getProperty("model.sha256", "unknown") : "unknown"; } + /** + * @return Retrieves the value of the {@code model.language} property + * or {@code "unknown"} if it could be read. + */ public String getModelLanguage() { return properties != null ? properties.getProperty("model.language", "unknown") : "unknown"; } 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 ef09f414..7a34432e 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 @@ -19,6 +19,13 @@ package opennlp.tools.models; import java.net.URI; import java.util.Optional; +/** + * Encapsulates a classpath entry that is associated with an {@link URI model URI} + * and optional {@code properties}. + * + * @param model A valid {@link URI} associated with the model's location. + * @param properties Optional properties to use. + */ public record ClassPathModelEntry(URI model, Optional<URI> properties) { } 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 5603d325..6b0358ff 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 @@ -25,8 +25,9 @@ public interface ClassPathModelFinder { /** * Finds OpenNLP models within the classpath. * - * @param reloadCache {@code true}, if the internal cache should explicitly be reloaded - * @return A Set of {@link ClassPathModelEntry ClassPathModelEntries}. It might be empty. + * @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. */ 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 a236fa34..1b67bb2d 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 @@ -29,8 +29,8 @@ public class ClassPathModelLoader { /** * Loads a {@link ClassPathModel} from a {@link ClassPathModelEntry} * - * @param entry must not be {@code null}. - * @return a {@link ClassPathModel} containing the model resources. + * @param entry A valid {@link ClassPathModelEntry}, it must not be {@code null}. + * @return A {@link ClassPathModel} containing the model resources. * @throws IOException thrown if something went wrong during reading resources from the classpath. */ public ClassPathModel load(ClassPathModelEntry entry) throws IOException { 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 642dc20b..13dae921 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 @@ -31,6 +31,10 @@ 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. + * + * @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>. */ public class ClassgraphModelFinder extends AbstractClassPathModelFinder implements ClassPathModelFinder { @@ -50,7 +54,9 @@ public class ClassgraphModelFinder extends AbstractClassPathModelFinder implemen } /** - * @return a {@link ScanResult} ready for consumption. Caller is responsible for closing it. + * @apiNote The caller is responsible for closing it. + * + * @return A {@link ScanResult} ready for consumption. */ @Override protected Object getContext() { @@ -58,9 +64,11 @@ public class ClassgraphModelFinder extends AbstractClassPathModelFinder implemen } /** - * @param wildcardPattern the pattern. Must not be {@code null}. - * @param context an object holding context information. It might be {@code null}. - * @return a list of matching classpath uris. + * Attempts to obtain {@link URI URIs} from the classpath. + * + * @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. */ @Override protected List<URI> getMatchingURIs(String wildcardPattern, Object context) { @@ -71,5 +79,4 @@ public class ClassgraphModelFinder extends AbstractClassPathModelFinder implemen } return Collections.emptyList(); } - } 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 8e158952..bfe9902a 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 @@ -45,19 +45,25 @@ import opennlp.tools.models.ClassPathModelFinder; * Enables the detection of OpenNLP models in the classpath via JDK classes * 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. - * <p> + * + * @implNote * It is a rather simple implementation of scanning the classpath by trying to obtain {@link URL urls} * from the actual classpath via a chain of possible options. It might not work for every use-case * since it relies on JDK internals only and doesn't account for classloader hierarchies or edge-cases. * <p> - * It will - * (1) Try to see if we have a {@link URLClassLoader} available in the current thread. - * (2) Try to obtain URLs via the build in classloader via reflections - * (requires {@code --add-opens java.base/jdk.internal.loader=ALL-UNNAMED} as JVM argument) - * (3) Try to use the bootstrap classpath via {@code java.class.path}. + * It will: + * <ol> + * <li>Try to see if we have a {@link URLClassLoader} available in the current thread.</li> + * <li>Try to obtain URLs via the build in classloader via reflections. + * <br/>(requires {@code --add-opens java.base/jdk.internal.loader=ALL-UNNAMED} as JVM argument)</li> + * <li>Try to use the bootstrap classpath via {@code java.class.path}.</li> + * </ol> + * * <p> - * If you need a more sophisticated solution, + * If you need a more sophisticated implementation, * use {@link opennlp.tools.models.classgraph.ClassgraphModelFinder}. + * + * @see ClassPathModelFinder */ public class SimpleClassPathModelFinder extends AbstractClassPathModelFinder implements ClassPathModelFinder { @@ -68,7 +74,7 @@ public class SimpleClassPathModelFinder extends AbstractClassPathModelFinder imp // ; for Windows, : for Linux/OSX /** - * By default, it scans for "opennlp-models-*.jar". + * By default, it scans for {@link #OPENNLP_MODEL_JAR_PREFIX}. */ public SimpleClassPathModelFinder() { this(OPENNLP_MODEL_JAR_PREFIX); @@ -83,7 +89,7 @@ public class SimpleClassPathModelFinder extends AbstractClassPathModelFinder imp } /** - * @return always {@code NULL} as it is not needed for the simple case. + * @return Always {@code null} as it is not needed for the simple case. */ @Override protected Object getContext() { @@ -91,10 +97,10 @@ public class SimpleClassPathModelFinder extends AbstractClassPathModelFinder imp } /** - * @param wildcardPattern the pattern. Must not be {@code null}. - * @param context an object holding context information. + * @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}. * It is unused within this implementation. - * @return a list of matching classpath uris. + * @return A list of matching classpath {@link URI URIs}. It may be an empty list if nothing is found. */ @Override protected List<URI> getMatchingURIs(String wildcardPattern, Object context) { @@ -126,10 +132,10 @@ public class SimpleClassPathModelFinder extends AbstractClassPathModelFinder imp } /** - * Escapes a wildcard expressions for usage as a Java regular expression. + * Escapes a {@code wildcard} expressions for usage as a Java regular expression. * - * @param wildcard must not be {@code null}. - * @return the escaped regex. + * @param wildcard A valid expression. It must not be {@code null}. + * @return The escaped regex. */ private String asRegex(String wildcard) { return wildcard @@ -173,13 +179,16 @@ public class SimpleClassPathModelFinder extends AbstractClassPathModelFinder imp } /** - * Try to obtain URLs from the classpath in the following order: + * Attempts to obtain {@link URL URLs} from the classpath in the following order: * <p> - * (1) Try to see if we have a {@link URLClassLoader}. - * (2) Try to obtain URLs via the build in classloader via reflections (requires an add opens JVM argument) - * (3) Try to use the bootstrap classpath via {@code java.class.path}. + * <ol> + * <li>Try to see if we have a {@link URLClassLoader} available in the current thread.</li> + * <li>Try to obtain URLs via the build in classloader via reflections. + * <br/>(requires {@code --add-opens java.base/jdk.internal.loader=ALL-UNNAMED} as JVM argument)</li> + * <li>Try to use the bootstrap classpath via {@code java.class.path}.</li> + * </ol> * - * @return a list of URLs within the classpath. + * @return A list of {@link URL URLs} within the classpath. */ private List<URL> getClassPathElements() { final ClassLoader cl = Thread.currentThread().getContextClassLoader();
