You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ma...@apache.org on 2021/07/24 10:21:03 UTC
[commons-geometry] 03/03: updating docs to discuss possible runtime
exceptions in IO methods
This is an automated email from the ASF dual-hosted git repository.
mattjuntunen pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-geometry.git
commit b9db536fbd028223cd1a06a2c996da925506ba4b
Author: Matt Juntunen <ma...@apache.org>
AuthorDate: Fri Jul 23 22:10:58 2021 -0400
updating docs to discuss possible runtime exceptions in IO methods
---
.../geometry/io/core/BoundaryIOManager.java | 4 ++-
.../geometry/io/core/BoundaryReadHandler.java | 6 ++--
.../io/euclidean/threed/BoundaryIOManager3D.java | 4 ++-
.../io/euclidean/threed/BoundaryReadHandler3D.java | 3 +-
.../commons/geometry/io/euclidean/threed/IO3D.java | 36 ++++++++++++++--------
5 files changed, 36 insertions(+), 17 deletions(-)
diff --git a/commons-geometry-io-core/src/main/java/org/apache/commons/geometry/io/core/BoundaryIOManager.java b/commons-geometry-io-core/src/main/java/org/apache/commons/geometry/io/core/BoundaryIOManager.java
index 3a2e92e..5e1bb0c 100644
--- a/commons-geometry-io-core/src/main/java/org/apache/commons/geometry/io/core/BoundaryIOManager.java
+++ b/commons-geometry-io-core/src/main/java/org/apache/commons/geometry/io/core/BoundaryIOManager.java
@@ -187,6 +187,7 @@ public class BoundaryIOManager<
}
/** Return a {@link BoundarySource} containing all boundaries from the given input.
+ * A runtime exception may be thrown if mathematically invalid boundaries are encountered.
* @param in input to read boundaries from
* @param fmt format of the input; if null, the format is determined implicitly from the
* file extension of the input {@link GeometryInput#getFileName() file name}
@@ -210,7 +211,8 @@ public class BoundaryIOManager<
* }
* </pre>
* <p>An {@link IOException} is thrown immediately by this method if stream creation fails. Any IO errors
- * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}.</p>
+ * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}. Other runtime
+ * exceptions may be thrown during stream iteration if mathematically invalid boundaries are encountered.</p>
* @param in input to read boundaries from
* @param fmt format of the input; if null, the format is determined implicitly from the
* file extension of the input {@link GeometryInput#getFileName() file name}
diff --git a/commons-geometry-io-core/src/main/java/org/apache/commons/geometry/io/core/BoundaryReadHandler.java b/commons-geometry-io-core/src/main/java/org/apache/commons/geometry/io/core/BoundaryReadHandler.java
index 095c25d..f3b489e 100644
--- a/commons-geometry-io-core/src/main/java/org/apache/commons/geometry/io/core/BoundaryReadHandler.java
+++ b/commons-geometry-io-core/src/main/java/org/apache/commons/geometry/io/core/BoundaryReadHandler.java
@@ -44,7 +44,8 @@ public interface BoundaryReadHandler<H extends HyperplaneConvexSubset<?>, B exte
GeometryFormat getFormat();
/** Return an object containing all boundaries read from {@code input} using the handler's
- * supported data format.
+ * supported data format. Implementations may throw runtime exceptions if mathematically
+ * invalid boundaries are encountered.
* @param input input to read form
* @param precision precision context used for floating point comparisons
* @return object containing all boundaries read from {@code input}
@@ -70,7 +71,8 @@ public interface BoundaryReadHandler<H extends HyperplaneConvexSubset<?>, B exte
* </pre>
*
* <p>An {@link IOException} is thrown immediately by this method if stream creation fails. Any IO errors
- * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}.</p>
+ * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}. Other runtime
+ * exceptions may be thrown during stream iteration if mathematically invalid boundaries are encountered.</p>
* @param in input to read from
* @param precision precision context used for floating point comparisons
* @return stream providing access to the boundary information from the given input
diff --git a/commons-geometry-io-euclidean/src/main/java/org/apache/commons/geometry/io/euclidean/threed/BoundaryIOManager3D.java b/commons-geometry-io-euclidean/src/main/java/org/apache/commons/geometry/io/euclidean/threed/BoundaryIOManager3D.java
index 5b5f194..88de395 100644
--- a/commons-geometry-io-euclidean/src/main/java/org/apache/commons/geometry/io/euclidean/threed/BoundaryIOManager3D.java
+++ b/commons-geometry-io-euclidean/src/main/java/org/apache/commons/geometry/io/euclidean/threed/BoundaryIOManager3D.java
@@ -96,7 +96,8 @@ public class BoundaryIOManager3D extends BoundaryIOManager<
* }
* </pre>
* <p>An {@link IOException} is thrown immediately by this method if stream creation fails. Any IO errors
- * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}.</p>
+ * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}. Other runtime
+ * exceptions may be thrown during stream iteration if mathematically invalid boundaries are encountered.</p>
* @param in input to read from
* @param fmt format of the input; if null, the format is determined implicitly from the
* file extension of the input {@link GeometryInput#getFileName() file name}
@@ -112,6 +113,7 @@ public class BoundaryIOManager3D extends BoundaryIOManager<
}
/** Return a {@link TriangleMesh} containing all triangles from the given input.
+ * A runtime exception may be thrown if mathematically invalid boundaries are encountered.
* @param in input to read from
* @param fmt format of the input; if null, the format is determined implicitly from the
* file extension of the input {@link GeometryInput#getFileName() file name}
diff --git a/commons-geometry-io-euclidean/src/main/java/org/apache/commons/geometry/io/euclidean/threed/BoundaryReadHandler3D.java b/commons-geometry-io-euclidean/src/main/java/org/apache/commons/geometry/io/euclidean/threed/BoundaryReadHandler3D.java
index 87ec69d..8a0138f 100644
--- a/commons-geometry-io-euclidean/src/main/java/org/apache/commons/geometry/io/euclidean/threed/BoundaryReadHandler3D.java
+++ b/commons-geometry-io-euclidean/src/main/java/org/apache/commons/geometry/io/euclidean/threed/BoundaryReadHandler3D.java
@@ -68,7 +68,8 @@ public interface BoundaryReadHandler3D extends BoundaryReadHandler<PlaneConvexSu
*/
Stream<FacetDefinition> facets(GeometryInput in) throws IOException;
- /** Read a triangle mesh from the given input.
+ /** Read a triangle mesh from the given input. Implementations may throw runtime
+ * exceptions if mathematically invalid boundaries are encountered.
* @param in input stream to read from
* @param precision precision context used for floating point comparisons
* @return triangle mesh containing the data from the given input stream
diff --git a/commons-geometry-io-euclidean/src/main/java/org/apache/commons/geometry/io/euclidean/threed/IO3D.java b/commons-geometry-io-euclidean/src/main/java/org/apache/commons/geometry/io/euclidean/threed/IO3D.java
index f78db5d..3651195 100644
--- a/commons-geometry-io-euclidean/src/main/java/org/apache/commons/geometry/io/euclidean/threed/IO3D.java
+++ b/commons-geometry-io-euclidean/src/main/java/org/apache/commons/geometry/io/euclidean/threed/IO3D.java
@@ -191,7 +191,8 @@ public final class IO3D {
* </pre>
*
* <p>An {@link IOException} is thrown immediately by this method if stream creation fails. Any IO errors
- * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}.</p>
+ * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}. Other runtime
+ * exceptions may be thrown during stream iteration if mathematically invalid boundaries are encountered.</p>
* @param path file path to read from
* @param precision precision context used for floating point comparisons
* @return stream providing access to the boundaries in the specified file
@@ -219,7 +220,8 @@ public final class IO3D {
* </pre>
*
* <p>An {@link IOException} is thrown immediately by this method if stream creation fails. Any IO errors
- * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}.</p>
+ * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}. Other runtime
+ * exceptions may be thrown during stream iteration if mathematically invalid boundaries are encountered.</p>
* @param url URL to read from
* @param precision precision context used for floating point comparisons
* @return stream providing access to the boundaries in the specified URL
@@ -242,7 +244,8 @@ public final class IO3D {
* }
* </pre>
* <p>An {@link IOException} is thrown immediately by this method if stream creation fails. Any IO errors
- * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}.</p>
+ * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}. Other runtime
+ * exceptions may be thrown during stream iteration if mathematically invalid boundaries are encountered.</p>
* @param in input to read boundaries from
* @param fmt format of the input; if null, the format is determined implicitly from the
* file extension of the input {@link GeometryInput#getFileName() file name}
@@ -272,7 +275,8 @@ public final class IO3D {
* </pre>
*
* <p>An {@link IOException} is thrown immediately by this method if stream creation fails. Any IO errors
- * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}.</p>
+ * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}. Other runtime
+ * exceptions may be thrown during stream iteration if mathematically invalid boundaries are encountered.</p>
* @param path file path to read from
* @param precision precision context used for floating point comparisons
* @return stream providing access to the triangles in the specified file
@@ -300,7 +304,8 @@ public final class IO3D {
* </pre>
*
* <p>An {@link IOException} is thrown immediately by this method if stream creation fails. Any IO errors
- * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}.</p>
+ * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}. Other runtime
+ * exceptions may be thrown during stream iteration if mathematically invalid boundaries are encountered.</p>
* @param url URL to read from
* @param precision precision context used for floating point comparisons
* @return stream providing access to the triangles from the specified URL
@@ -323,7 +328,8 @@ public final class IO3D {
* }
* </pre>
* <p>An {@link IOException} is thrown immediately by this method if stream creation fails. Any IO errors
- * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}.</p>
+ * occurring during stream iteration are wrapped with {@link java.io.UncheckedIOException}. Other runtime
+ * exceptions may be thrown during stream iteration if mathematically invalid boundaries are encountered.</p>
* @param in input to read from
* @param fmt format of the input; if null, the format is determined implicitly from the
* file extension of the input {@link GeometryInput#getFileName() file name}
@@ -340,7 +346,8 @@ public final class IO3D {
}
/** Return a {@link BoundarySource3D} containing all boundaries from the file at the
- * given path. The data format is determined from the file extension.
+ * given path. The data format is determined from the file extension. A runtime exception may be
+ * thrown if mathematically invalid boundaries are encountered.
* @param path file path to read from
* @param precision precision context used for floating point comparisons
* @return object containing all boundaries from the file at the given path
@@ -355,7 +362,8 @@ public final class IO3D {
}
/** Return a {@link BoundarySource3D} containing all boundaries from the given URL. The data
- * format is determined from the file extension of the URL path.
+ * format is determined from the file extension of the URL path. A runtime exception may be
+ * thrown if mathematically invalid boundaries are encountered.
* @param url URL to read from
* @param precision precision context used for floating point comparisons
* @return object containing all boundaries from the given URL
@@ -369,7 +377,8 @@ public final class IO3D {
return read(new UrlGeometryInput(url), null, precision);
}
- /** Return a {@link BoundarySource3D} containing all boundaries from the given input.
+ /** Return a {@link BoundarySource3D} containing all boundaries from the given input. A runtime
+ * exception may be thrown if mathematically invalid boundaries are encountered.
* @param in input to read boundaries from
* @param fmt format of the input; if null, the format is determined implicitly from the
* file extension of the input {@link GeometryInput#getFileName() file name}
@@ -386,7 +395,8 @@ public final class IO3D {
}
/** Return a {@link TriangleMesh} containing all triangles from the given file path. The data
- * format is determined from the file extension of the path.
+ * format is determined from the file extension of the path. A runtime exception may be
+ * thrown if mathematically invalid boundaries are encountered.
* @param path file path to read from
* @param precision precision context used for floating point comparisons
* @return mesh containing all triangles from the given file path
@@ -401,7 +411,8 @@ public final class IO3D {
}
/** Return a {@link TriangleMesh} containing all triangles from the given URL. The data
- * format is determined from the file extension of the URL path.
+ * format is determined from the file extension of the URL path. A runtime exception may be
+ * thrown if mathematically invalid boundaries are encountered.
* @param url URL to read from
* @param precision precision context used for floating point comparisons
* @return mesh containing all triangles from the given URL
@@ -415,7 +426,8 @@ public final class IO3D {
return readTriangleMesh(new UrlGeometryInput(url), null, precision);
}
- /** Return a {@link TriangleMesh} containing all triangles from the given input.
+ /** Return a {@link TriangleMesh} containing all triangles from the given input. A runtime exception
+ * may be thrown if mathematically invalid boundaries are encountered.
* @param in input to read from
* @param fmt format of the input; if null, the format is determined implicitly from the
* file extension of the input {@link GeometryInput#getFileName() file name}