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

  • 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 java.lang.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 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:
        java.lang.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 java.util.List<R> getReadHandlers()
        Get all registered read handlers.
        Returns:
        list containing all registered read handlers

      • 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​(java.lang.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:
        java.lang.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 java.util.List<W> getWriteHandlers()
        Get all registered write handlers.
        Returns:
        list containing all registered write handlers

      • 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​(java.lang.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,
              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:
        java.lang.IllegalArgumentException - if mathematically invalid data is encountered or no read handler can be found for the input format
        java.lang.IllegalStateException - if a data format error occurs
        java.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 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:
        java.lang.IllegalArgumentException - if no read handler can be found for the input format
        java.lang.IllegalStateException - if a data format error occurs during stream creation
        java.io.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:
        java.lang.IllegalArgumentException - if no write handler can be found for the output format
        java.io.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:
        java.lang.NullPointerException - if in is null
        java.lang.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:
        java.lang.NullPointerException - if out is null
        java.lang.IllegalArgumentException - if no matching handler can be found