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

  • Field Details

  • Constructor Details

    • BoundaryIOManager

      public BoundaryIOManager()

  • Method Details

    • 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:

    • 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:

    • 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:

    • 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:

    • read

      public B read(GeometryInput in, GeometryFormat fmt, org.apache.commons.numbers.core.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, org.apache.commons.numbers.core.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:

      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