docs: add resource ownership documentation for @Owning/@NotOwning annotations

Document resource ownership semantics in Javadocs for methods and
parameters annotated with Eclipse's @owning and @NotOwning annotations:

- @owning: caller owns returned resource, must close it
- @NotOwning: caller does not own resource, must not close it

Updated files across cli-processor, core, databind, and schemagen modules.

Author: david-waltermire

cli-processor/src/main/java/gov/nist/secauto/metaschema/cli/processor/CLIProcessor.java

@@ -164,7 +164,8 @@ public CLIProcessor(@NonNull String exec, @NonNull Map<String, IVersionInfo> ver
    *          the version info to display when the version option is provided
    * @param outputStream
    *          the output stream to write to, or {@code null} to use the default
-   *          console
+   *          console. The caller retains ownership of this stream and is
+   *          responsible for closing it.
    */
   @SuppressWarnings("resource")
   public CLIProcessor(@NonNull String exec, @NonNull Map<String, IVersionInfo> versionInfos,
@@ -278,6 +279,8 @@ static void handleNoColor() {
 
   /**
    * Get the output stream used for writing CLI output.
+   * <p>
+   * The caller does not own this stream and must not close it.
    *
    * @return the output stream
    */

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/antlr/ParseTreePrinter.java

@@ -28,7 +28,8 @@ public class ParseTreePrinter {
    * Construct a new concrete syntax tree (CST) printer.
    *
    * @param outputStream
-   *          the stream to print to
+   *          the stream to print to. The caller retains ownership of this stream
+   *          and is responsible for closing it.
    */
   public ParseTreePrinter(@NotOwning @NonNull PrintStream outputStream) {
     this.outputStream = outputStream;

core/src/main/java/gov/nist/secauto/metaschema/core/model/constraint/ParallelValidationConfig.java

@@ -63,6 +63,8 @@ private ParallelValidationConfig(@Nullable ExecutorService executor, int threadC
    * <p>
    * The executor is NOT shut down by {@link #close()}; the caller retains
    * ownership.
+   * <p>
+   * The caller owns the returned configuration and is responsible for closing it.
    *
    * @param executor
    *          the executor service to use for parallel tasks
@@ -81,6 +83,8 @@ public static ParallelValidationConfig withExecutor(@NonNull ExecutorService exe
    * Create configuration that creates an internal thread pool.
    * <p>
    * The internal pool is shut down when {@link #close()} is called.
+   * <p>
+   * The caller owns the returned configuration and is responsible for closing it.
    *
    * @param threadCount
    *          number of threads (must be &gt;= 1)

core/src/main/java/gov/nist/secauto/metaschema/core/util/AutoCloser.java

@@ -32,6 +32,8 @@ public final class AutoCloser<T, E extends Exception> implements AutoCloseable {
   /**
    * Adapt the the provided {@code resource} to be {@link AutoCloseable}, using a
    * provided closer {@code lambda}.
+   * <p>
+   * The caller owns the returned wrapper and is responsible for closing it.
    *
    * @param <T>
    *          the resource's type
@@ -110,6 +112,8 @@ public interface Closer<T, E extends Exception> {
    * <p>
    * This is useful for protecting standard streams. i.e. {@link System#out},
    * {@link System#err}.
+   * <p>
+   * The caller owns the returned stream and is responsible for closing it.
    *
    * @param out
    *          the stream to wrap

databind/src/main/java/gov/nist/secauto/metaschema/databind/IBindingContext.java

@@ -456,12 +456,14 @@ <CLASS extends IBoundObject> CLASS deepCopy(@NonNull CLASS other, IBoundObject p
 
   /**
    * Get a new single use constraint validator.
+   * <p>
+   * The caller owns the returned validator and is responsible for closing it to
+   * release any resources (such as thread pools) when validation is complete.
    *
    * @param handler
    *          the validation handler to use to process the validation results
    * @param config
    *          the validation configuration
-   *
    * @return the validator
    */
   @SuppressWarnings("resource")

databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/ModuleCompilerHelper.java

@@ -47,6 +47,8 @@ private ModuleCompilerHelper() {
   /**
    * Create a new classloader capable of loading Java classes generated in the
    * provided {@code classDir}.
+   * <p>
+   * The caller owns the returned class loader and is responsible for closing it.
    *
    * @param classDir
    *          the directory where generated Java classes have been compiled

databind/src/main/java/gov/nist/secauto/metaschema/databind/io/IBoundLoader.java

@@ -140,6 +140,8 @@ default Format detectFormat(@NonNull URL url) throws IOException {
    * <p>
    * This method will not close any {@link InputStream} provided by the
    * {@link InputSource}, since it does not own the stream.
+   * <p>
+   * The caller owns the returned result and is responsible for closing it.
    *
    * @param is
    *          an input stream for the resource

databind/src/main/java/gov/nist/secauto/metaschema/databind/io/IParsingContext.java

@@ -22,6 +22,8 @@
 public interface IParsingContext<READER, PROBLEM_HANDLER extends IProblemHandler> {
   /**
    * The parser used for reading data associated with the supported format.
+   * <p>
+   * The caller does not own this reader and must not close it.
    *
    * @return the parser
    */

databind/src/main/java/gov/nist/secauto/metaschema/databind/io/ModelDetector.java

@@ -99,12 +99,14 @@ private IConfiguration<DeserializationFeature<?>> getConfiguration() {
    * model.
    *
    * @param inputStream
-   *          the resource stream to analyze
+   *          the resource stream to analyze. The caller retains ownership of this
+   *          stream and is responsible for closing it.
    * @param resource
    *          the resource being parsed
    * @param format
    *          the expected format of the data to read
-   * @return the analysis result
+   * @return the analysis result. The caller owns this result and is responsible
+   *         for closing it.
    * @throws IOException
    *           if an error occurred while reading the resource
    */
@@ -250,6 +252,8 @@ public Class<? extends IBoundObject> getBoundClass() {
     /**
      * Get an {@link InputStream} that can be used to read the analyzed data from
      * the start.
+     * <p>
+     * The caller owns this stream and is responsible for closing it.
      *
      * @return the stream
      */

schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/AbstractSchemaGenerator.java

@@ -42,6 +42,8 @@ public abstract class AbstractSchemaGenerator<
 
   /**
    * Create a new writer to use to write the schema.
+   * <p>
+   * The caller owns the returned writer and is responsible for closing it.
    *
    * @param out
    *          the {@link Writer} to write the schema content to