You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opennlp.apache.org by ma...@apache.org on 2024/11/25 15:20:06 UTC
(opennlp) branch OPENNLP-1658-Enhance-JavaDoc-of-code-in-opennlp-tools-models created (now 01985797)
This is an automated email from the ASF dual-hosted git repository.
mawiesne pushed a change to branch OPENNLP-1658-Enhance-JavaDoc-of-code-in-opennlp-tools-models
in repository https://gitbox.apache.org/repos/asf/opennlp.git
at 01985797 OPENNLP-1658 Enhance JavaDoc of code in opennlp-tools-models
This branch includes the following new commits:
new 01985797 OPENNLP-1658 Enhance JavaDoc of code in opennlp-tools-models
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(opennlp) 01/01: OPENNLP-1658 Enhance JavaDoc of code in opennlp-tools-models
Posted by ma...@apache.org.
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 <ma...@hs-heilbronn.de>
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();