org.apache.commons.geometry.io.core

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 type

B - Boundary source type

R - Read handler type

W - Write handler type

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).

As a result, any 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:

BoundaryReadHandler, BoundaryWriteHandler, Boundary representations

Constructor Summary

Constructors

Constructor and Description
BoundaryIOManager()

Method Summary

Modifier and Type	Method and Description
Stream<H>	boundaries(GeometryInput in, GeometryFormat fmt, Precision.DoubleEquivalence precision) Return a Stream providing access to all boundaries from the given input.
List<GeometryFormat>	getReadFormats() Get the list of formats supported by the currently registered read handlers.
R	getReadHandlerForFileExtension(String fileExt) Get the read handler for the given file extension or null if no such handler has been registered.
R	getReadHandlerForFormat(GeometryFormat fmt) Get the read handler for the given format or null if no such handler has been registered.
List<R>	getReadHandlers() Get all registered read handlers.
List<GeometryFormat>	getWriteFormats() Get the list of formats supported by the currently registered write handlers.
W	getWriteHandlerForFileExtension(String fileExt) Get the write handler for the given file extension or null if no such handler has been registered.
W	getWriteHandlerForFormat(GeometryFormat fmt) Get the write handler for the given format or null if no such handler has been registered.
List<W>	getWriteHandlers() Get all registered write handlers.
B	read(GeometryInput in, GeometryFormat fmt, Precision.DoubleEquivalence precision) Return a BoundarySource containing all boundaries from the given input.
void	registerReadHandler(R handler) Register a read handler with the instance, replacing any handler previously registered for the argument's supported data format, as returned by BoundaryReadHandler.getFormat().
void	registerWriteHandler(W handler) Register a write handler with the instance, replacing any handler previously registered for the argument's supported data format, as returned by BoundaryWriteHandler.getFormat().
protected R	requireReadHandler(GeometryInput in, GeometryFormat fmt) Get the read handler matching the arguments, throwing an exception on failure.
protected W	requireWriteHandler(GeometryOutput out, GeometryFormat fmt) Get the write handler matching the arguments, throwing an exception on failure.
void	unregisterReadHandler(R handler) Unregister a previously registered read handler; does nothing if the argument is null or is not currently registered.
void	unregisterWriteHandler(W handler) Unregister a previously registered write handler; does nothing if the argument is null or is not currently registered.
void	write(B src, GeometryOutput out, GeometryFormat fmt) Write all boundaries from src to the given output.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BoundaryIOManager

public BoundaryIOManager()

Method Detail

registerReadHandler

public void registerReadHandler(R handler)

Register a read handler with the instance, replacing any handler previously registered for the argument's supported data format, as returned by BoundaryReadHandler.getFormat().

Parameters:

handler - handler to register

Throws:

NullPointerException - if handler, its format, or the format's name are null

unregisterReadHandler

public void unregisterReadHandler(R handler)

Unregister a previously registered read handler; does nothing if the argument is null or is not currently registered.

Parameters:

handler - handler to unregister; may be null

getReadHandlers

public List<R> getReadHandlers()

Get all registered read handlers.

Returns:

list containing all registered read handlers

getReadFormats

public List<GeometryFormat> getReadFormats()

Get the list of formats supported by the currently registered read handlers.

Returns:

list of read formats

See Also:

BoundaryReadHandler.getFormat()

getReadHandlerForFormat

public R getReadHandlerForFormat(GeometryFormat fmt)

Get the read 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(String fileExt)

Get the read 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 a write handler with the instance, replacing any handler previously registered for the argument's supported data format, as returned by BoundaryWriteHandler.getFormat().

Parameters:

handler - handler to register

Throws:

NullPointerException - if handler, its format, or the format's name are null

unregisterWriteHandler

public void unregisterWriteHandler(W handler)

Unregister a previously registered write handler; does nothing if the argument is null or is not currently registered.

Parameters:

handler - handler to unregister; may be null

getWriteHandlers

public List<W> getWriteHandlers()

Get all registered write handlers.

Returns:

list containing all registered write handlers

getWriteFormats

public List<GeometryFormat> getWriteFormats()

Get the list of formats supported by the currently registered write handlers.

Returns:

list of write formats

See Also:

BoundaryWriteHandler.getFormat()

getWriteHandlerForFormat

public W getWriteHandlerForFormat(GeometryFormat fmt)

Get the write 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(String fileExt)

Get the write 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,
              Precision.DoubleEquivalence precision)

Return a BoundarySource 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 from

fmt - format of the input; if null, the format is determined implicitly from the file extension of the input file 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 no read handler can be found for the input format

IllegalStateException - if a data format error occurs

UncheckedIOException - if an I/O error occurs

boundaries

public Stream<H> boundaries(GeometryInput in,
                            GeometryFormat fmt,
                            Precision.DoubleEquivalence precision)

Return a Stream 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 encountered
• IllegalStateException if a data format error occurs
• UncheckedIOException if an I/O error occurs

Parameters:

in - input to read boundaries from

fmt - format of the input; if null, the format is determined implicitly from the file extension of the input file name

precision - precision context used for floating point comparisons

Returns:

stream providing access to all boundaries from the input

Throws:

IllegalArgumentException - if no read handler can be found for the input format

IllegalStateException - if a data format error occurs during stream creation

UncheckedIOException - if an I/O error occurs during stream creation

write

public void write(B src,
                  GeometryOutput out,
                  GeometryFormat fmt)

Write all boundaries from src to the given output.

Parameters:

src - object containing boundaries to write

out - output to write boundaries to

fmt - format of the output; if null, the format is determined implicitly from the file extension of the output GeometryIOMetadata.getFileName()

Throws:

IllegalArgumentException - if no write handler can be found for the output format

UncheckedIOException - if an I/O error occurs

requireReadHandler

protected R requireReadHandler(GeometryInput in,
                               GeometryFormat fmt)

Get the read handler matching the arguments, throwing an exception on failure. If fmt is given, the handler registered for that format is returned and the input object is not examined. If fmt is null, the file extension of the input file name is used to implicitly determine the format and locate the handler.

Parameters:

in - input object

fmt - format; may be null

Returns:

the read handler for fmt or, if fmt is null, the read handler for the file extension indicated by the input

Throws:

NullPointerException - if in is null

IllegalArgumentException - if no matching handler can be found

requireWriteHandler

protected W requireWriteHandler(GeometryOutput out,
                                GeometryFormat fmt)

Get the write handler matching the arguments, throwing an exception on failure. If fmt is given, the handler registered for that format is returned and the input object is not examined. If fmt is null, the file extension of the output file name is used to implicitly determine the format and locate the handler.

Parameters:

out - output object

fmt - format; may be null

Returns:

the write handler for fmt or, if fmt is null, the write handler for the file extension indicated by the output

Throws:

NullPointerException - if out is null

IllegalArgumentException - if no matching handler can be found