This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-io.git
The following commit(s) were added to refs/heads/master by this push:
new 8508dfb25 Javadoc
8508dfb25 is described below
commit 8508dfb25252bca91c33dfbde75097702cfdda19
Author: Gary D. Gregory <[email protected]>
AuthorDate: Mon Sep 29 06:44:08 2025 -0400
Javadoc
---
.../org/apache/commons/io/build/AbstractOrigin.java | 20 +++++++++++++++++++-
1 file changed, 19 insertions(+), 1 deletion(-)
diff --git a/src/main/java/org/apache/commons/io/build/AbstractOrigin.java
b/src/main/java/org/apache/commons/io/build/AbstractOrigin.java
index ca24d95e3..c003a747f 100644
--- a/src/main/java/org/apache/commons/io/build/AbstractOrigin.java
+++ b/src/main/java/org/apache/commons/io/build/AbstractOrigin.java
@@ -18,6 +18,7 @@
package org.apache.commons.io.build;
import java.io.ByteArrayInputStream;
+import java.io.Closeable;
import java.io.File;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
@@ -67,7 +68,24 @@
* expose only the operations that make sense for the underlying source or
sink; invoking an unsupported operation
* results in {@link UnsupportedOperationException} (see, for example, {@link
#getFile()} and {@link #getPath()}).
* </p>
- *
+ * <p>
+ * An instance doesn't own its origin, it holds on to it to allow conversions.
There are two use cases related to resource management for a Builder:
+ * </p>
+ * <ul>
+ * <li>
+ * A client allocates a {@linkplain Closeable} (or {@linkplain AutoCloseable})
resource, creates a Builder, and gives the Builder that resource by calling a
+ * setter method. No matter what happens next, the client is responsible for
releasing the resource ({@code Closeable.close()}). In this case, the origin
+ * wraps but doesn't own the closeable resource. There is no transfer of
ownership.
+ * </li>
+ * <li>
+ * A client creates a Builder and gives it a non-Closeable object, like a File
or a Path. The client then calls the Builder's factory method
+ * (like {@linkplain #get()}), and that call returns a Closeable or a resource
that requires releasing in some other way. No matter what happens next, the
+ * client is responsible for releasing that resource. In this case, the origin
doesn't wrap a closeable resource.
+ * </li>
+ * </ul>
+ * <p>
+ * In both cases, the client causes the allocation and is responsible for
releasing the resource.
+ * </p>
* <p>
* The table below summarizes which views and conversions are supported for
each origin type.
* Column headers show the target view; cells indicate whether that view is
available from the origin in that row.
