Class BoundaryIOManager<H extends HyperplaneConvexSubset<?>,B extends BoundarySource<H>,R extends BoundaryReadHandler<H,B>,W extends BoundaryWriteHandler<H,B>>
java.lang.Object
org.apache.commons.geometry.io.core.BoundaryIOManager<H,B,R,W>
- Type Parameters:
H
- Geometric boundary typeB
- Boundary source typeR
- Read handler typeW
- Write handler type
- Direct Known Subclasses:
BoundaryIOManager3D
public class BoundaryIOManager<H extends HyperplaneConvexSubset<?>,B extends BoundarySource<H>,R extends BoundaryReadHandler<H,B>,W extends BoundaryWriteHandler<H,B>>
extends Object
Class managing IO operations for geometric data formats containing region boundaries.
All IO operations are delegated to registered format-specific
read handlers
and write handlers
.
Exceptions
Despite having functionality related to I/O operations, this class has been designed to not
throw checked exceptions, in particular IOException
. The primary reasons for
this choice are
- convenience,
- compatibility with functional programming, and
- the fact that modern Java practice is moving away from checked exceptions in general (as exemplified
by the JDK's
UncheckedIOException
).
IOException
thrown internally by this or related classes
is wrapped with UncheckedIOException
. Other common runtime exceptions
include IllegalArgumentException
, which typically indicates mathematically invalid data, and
IllegalStateException
, which typically indicates format or parsing errors. See the method-level
documentation for more details.
Implementation note: Instances of this class are thread-safe as long as the registered handler instances are thread-safe.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
Internal class used to manage handler registration. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final String
Error message used when a format name is null.private static final String
Error message used when a format is null.private static final String
Error message used when a handler is null.private final BoundaryIOManager.HandlerRegistry
<R> Read handler registry.private final BoundaryIOManager.HandlerRegistry
<W> Write handler registry. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboundaries
(GeometryInput in, GeometryFormat fmt, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Return aStream
providing access to all boundaries from the given input.Get the list of formats supported by the currently registeredread handlers
.getReadHandlerForFileExtension
(String fileExt) Get theread handler
for the given file extension or null if no such handler has been registered.Get theread handler
for the given format or null if no such handler has been registered.Get all registeredread handlers
.Get the list of formats supported by the currently registeredwrite handlers
.getWriteHandlerForFileExtension
(String fileExt) Get thewrite handler
for the given file extension or null if no such handler has been registered.Get thewrite handler
for the given format or null if no such handler has been registered.Get all registeredwrite handlers
.read
(GeometryInput in, GeometryFormat fmt, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Return aBoundarySource
containing all boundaries from the given input.void
registerReadHandler
(R handler) Register aread handler
with the instance, replacing any handler previously registered for the argument's supported data format, as returned byBoundaryReadHandler.getFormat()
.void
registerWriteHandler
(W handler) Register awrite handler
with the instance, replacing any handler previously registered for the argument's supported data format, as returned byBoundaryWriteHandler.getFormat()
.protected R
Get theread handler
matching the arguments, throwing an exception on failure.protected W
requireWriteHandler
(GeometryOutput out, GeometryFormat fmt) Get thewrite handler
matching the arguments, throwing an exception on failure.void
unregisterReadHandler
(R handler) Unregister a previously registeredread handler
; does nothing if the argument is null or is not currently registered.void
unregisterWriteHandler
(W handler) Unregister a previously registeredwrite handler
; does nothing if the argument is null or is not currently registered.void
write
(B src, GeometryOutput out, GeometryFormat fmt) Write all boundaries fromsrc
to the given output.
-
Field Details
-
HANDLER_NULL_ERR
Error message used when a handler is null.- See Also:
-
FORMAT_NULL_ERR
Error message used when a format is null.- See Also:
-
FORMAT_NAME_NULL_ERR
Error message used when a format name is null.- See Also:
-
readRegistry
Read handler registry. -
writeRegistry
Write handler registry.
-
-
Constructor Details
-
BoundaryIOManager
public BoundaryIOManager()
-
-
Method Details
-
registerReadHandler
Register aread handler
with the instance, replacing any handler previously registered for the argument's supported data format, as returned byBoundaryReadHandler.getFormat()
.- Parameters:
handler
- handler to register- Throws:
NullPointerException
- ifhandler
, itsformat
, or theformat's name
are null
-
unregisterReadHandler
Unregister a previously registeredread handler
; does nothing if the argument is null or is not currently registered.- Parameters:
handler
- handler to unregister; may be null
-
getReadHandlers
Get all registeredread handlers
.- Returns:
- list containing all registered read handlers
-
getReadFormats
Get the list of formats supported by the currently registeredread handlers
.- Returns:
- list of read formats
- See Also:
-
getReadHandlerForFormat
Get theread handler
for the given format or null if no such handler has been registered.- Parameters:
fmt
- format to obtain a handler for- Returns:
- read handler for the given format or null if not found
-
getReadHandlerForFileExtension
Get theread handler
for the given file extension or null if no such handler has been registered. File extension comparisons are not case-sensitive.- Parameters:
fileExt
- file extension to obtain a handler for- Returns:
- read handler for the given file extension or null if not found
- See Also:
-
registerWriteHandler
Register awrite handler
with the instance, replacing any handler previously registered for the argument's supported data format, as returned byBoundaryWriteHandler.getFormat()
.- Parameters:
handler
- handler to register- Throws:
NullPointerException
- ifhandler
, itsformat
, or theformat's name
are null
-
unregisterWriteHandler
Unregister a previously registeredwrite handler
; does nothing if the argument is null or is not currently registered.- Parameters:
handler
- handler to unregister; may be null
-
getWriteHandlers
Get all registeredwrite handlers
.- Returns:
- list containing all registered write handlers
-
getWriteFormats
Get the list of formats supported by the currently registeredwrite handlers
.- Returns:
- list of write formats
- See Also:
-
getWriteHandlerForFormat
Get thewrite handler
for the given format or null if no such handler has been registered.- Parameters:
fmt
- format to obtain a handler for- Returns:
- write handler for the given format or null if not found
-
getWriteHandlerForFileExtension
Get thewrite handler
for the given file extension or null if no such handler has been registered. File extension comparisons are not case-sensitive.- Parameters:
fileExt
- file extension to obtain a handler for- Returns:
- write handler for the given file extension or null if not found
- See Also:
-
read
public B read(GeometryInput in, GeometryFormat fmt, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Return aBoundarySource
containing all boundaries from the given input. A runtime exception may be thrown if mathematically invalid boundaries are encountered.- Parameters:
in
- input to read boundaries fromfmt
- format of the input; if null, the format is determined implicitly from the file extension of the inputfile name
precision
- precision context used for floating point comparisons- Returns:
- object containing all boundaries from the input
- Throws:
IllegalArgumentException
- if mathematically invalid data is encountered or noread handler
can be found for the input formatIllegalStateException
- if a data format error occursUncheckedIOException
- if an I/O error occurs
-
boundaries
public Stream<H> boundaries(GeometryInput in, GeometryFormat fmt, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Return aStream
providing access to all boundaries from the given input. The underlying input stream is closed when the returned stream is closed. Callers should therefore use the returned stream in a try-with-resources statement to ensure that all resources are properly released. Ex:try (Stream<H> stream = manager.boundaries(in, fmt, precision)) { // access stream content }
The following exceptions may be thrown during stream iteration:
IllegalArgumentException
if mathematically invalid data is encounteredIllegalStateException
if a data format error occursUncheckedIOException
if an I/O error occurs
- Parameters:
in
- input to read boundaries fromfmt
- format of the input; if null, the format is determined implicitly from the file extension of the inputfile name
precision
- precision context used for floating point comparisons- Returns:
- stream providing access to all boundaries from the input
- Throws:
IllegalArgumentException
- if noread handler
can be found for the input formatIllegalStateException
- if a data format error occurs during stream creationUncheckedIOException
- if an I/O error occurs during stream creation
-
write
Write all boundaries fromsrc
to the given output.- Parameters:
src
- object containing boundaries to writeout
- output to write boundaries tofmt
- format of the output; if null, the format is determined implicitly from the file extension of the outputGeometryIOMetadata.getFileName()
- Throws:
IllegalArgumentException
- if nowrite handler
can be found for the output formatUncheckedIOException
- if an I/O error occurs
-
requireReadHandler
Get theread handler
matching the arguments, throwing an exception on failure. Iffmt
is given, the handler registered for that format is returned and theinput
object is not examined. Iffmt
is null, the file extension of the inputfile name
is used to implicitly determine the format and locate the handler.- Parameters:
in
- input objectfmt
- format; may be null- Returns:
- the read handler for
fmt
or, iffmt
is null, the read handler for the file extension indicated by the input - Throws:
NullPointerException
- ifin
is nullIllegalArgumentException
- if no matching handler can be found
-
requireWriteHandler
Get thewrite handler
matching the arguments, throwing an exception on failure. Iffmt
is given, the handler registered for that format is returned and theinput
object is not examined. Iffmt
is null, the file extension of the outputfile name
is used to implicitly determine the format and locate the handler.- Parameters:
out
- output objectfmt
- format; may be null- Returns:
- the write handler for
fmt
or, iffmt
is null, the write handler for the file extension indicated by the output - Throws:
NullPointerException
- ifout
is nullIllegalArgumentException
- if no matching handler can be found
-