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 java.lang.Object
Class managing IO operations for geometric data formats containing region boundaries. All IO operations are delegated to registered format-specificread handlers
andwrite 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 withUncheckedIOException
. Other common runtime exceptions includeIllegalArgumentException
, which typically indicates mathematically invalid data, andIllegalStateException
, 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.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
BoundaryIOManager.HandlerRegistry<T>
Internal class used to manage handler registration.
-
Field Summary
Fields Modifier and Type Field Description private static java.lang.String
FORMAT_NAME_NULL_ERR
Error message used when a format name is null.private static java.lang.String
FORMAT_NULL_ERR
Error message used when a format is null.private static java.lang.String
HANDLER_NULL_ERR
Error message used when a handler is null.private BoundaryIOManager.HandlerRegistry<R>
readRegistry
Read handler registry.private BoundaryIOManager.HandlerRegistry<W>
writeRegistry
Write handler registry.
-
Constructor Summary
Constructors Constructor Description BoundaryIOManager()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description java.util.stream.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.java.util.List<GeometryFormat>
getReadFormats()
Get the list of formats supported by the currently registeredread handlers
.R
getReadHandlerForFileExtension(java.lang.String fileExt)
Get theread handler
for the given file extension or null if no such handler has been registered.R
getReadHandlerForFormat(GeometryFormat fmt)
Get theread handler
for the given format or null if no such handler has been registered.java.util.List<R>
getReadHandlers()
Get all registeredread handlers
.java.util.List<GeometryFormat>
getWriteFormats()
Get the list of formats supported by the currently registeredwrite handlers
.W
getWriteHandlerForFileExtension(java.lang.String fileExt)
Get thewrite handler
for the given file extension or null if no such handler has been registered.W
getWriteHandlerForFormat(GeometryFormat fmt)
Get thewrite handler
for the given format or null if no such handler has been registered.java.util.List<W>
getWriteHandlers()
Get all registeredwrite handlers
.B
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
requireReadHandler(GeometryInput in, GeometryFormat fmt)
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 Detail
-
HANDLER_NULL_ERR
private static final java.lang.String HANDLER_NULL_ERR
Error message used when a handler is null.- See Also:
- Constant Field Values
-
FORMAT_NULL_ERR
private static final java.lang.String FORMAT_NULL_ERR
Error message used when a format is null.- See Also:
- Constant Field Values
-
FORMAT_NAME_NULL_ERR
private static final java.lang.String FORMAT_NAME_NULL_ERR
Error message used when a format name is null.- See Also:
- Constant Field Values
-
readRegistry
private final BoundaryIOManager.HandlerRegistry<R extends BoundaryReadHandler<H,B>> readRegistry
Read handler registry.
-
writeRegistry
private final BoundaryIOManager.HandlerRegistry<W extends BoundaryWriteHandler<H,B>> writeRegistry
Write handler registry.
-
-
Method Detail
-
registerReadHandler
public 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()
.- Parameters:
handler
- handler to register- Throws:
java.lang.NullPointerException
- ifhandler
, itsformat
, or theformat's name
are null
-
unregisterReadHandler
public void unregisterReadHandler(R handler)
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
public java.util.List<R> getReadHandlers()
Get all registeredread handlers
.- Returns:
- list containing all registered read handlers
-
getReadFormats
public java.util.List<GeometryFormat> getReadFormats()
Get the list of formats supported by the currently registeredread handlers
.- Returns:
- list of read formats
- See Also:
BoundaryReadHandler.getFormat()
-
getReadHandlerForFormat
public R getReadHandlerForFormat(GeometryFormat fmt)
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
public R getReadHandlerForFileExtension(java.lang.String fileExt)
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:
GeometryFormat.getFileExtensions()
-
registerWriteHandler
public 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()
.- Parameters:
handler
- handler to register- Throws:
java.lang.NullPointerException
- ifhandler
, itsformat
, or theformat's name
are null
-
unregisterWriteHandler
public void unregisterWriteHandler(W handler)
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
public java.util.List<W> getWriteHandlers()
Get all registeredwrite handlers
.- Returns:
- list containing all registered write handlers
-
getWriteFormats
public java.util.List<GeometryFormat> getWriteFormats()
Get the list of formats supported by the currently registeredwrite handlers
.- Returns:
- list of write formats
- See Also:
BoundaryWriteHandler.getFormat()
-
getWriteHandlerForFormat
public W getWriteHandlerForFormat(GeometryFormat fmt)
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
public W getWriteHandlerForFileExtension(java.lang.String fileExt)
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:
GeometryFormat.getFileExtensions()
-
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:
java.lang.IllegalArgumentException
- if mathematically invalid data is encountered or noread handler
can be found for the input formatjava.lang.IllegalStateException
- if a data format error occursjava.io.UncheckedIOException
- if an I/O error occurs
-
boundaries
public java.util.stream.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:
java.lang.IllegalArgumentException
- if noread handler
can be found for the input formatjava.lang.IllegalStateException
- if a data format error occurs during stream creationjava.io.UncheckedIOException
- if an I/O error occurs during stream creation
-
write
public void write(B src, GeometryOutput out, GeometryFormat fmt)
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:
java.lang.IllegalArgumentException
- if nowrite handler
can be found for the output formatjava.io.UncheckedIOException
- if an I/O error occurs
-
requireReadHandler
protected R requireReadHandler(GeometryInput in, GeometryFormat fmt)
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:
java.lang.NullPointerException
- ifin
is nulljava.lang.IllegalArgumentException
- if no matching handler can be found
-
requireWriteHandler
protected W requireWriteHandler(GeometryOutput out, GeometryFormat fmt)
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:
java.lang.NullPointerException
- ifout
is nulljava.lang.IllegalArgumentException
- if no matching handler can be found
-
-