View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *      http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17  package org.apache.commons.geometry.io.core;
    18
    19  import java.util.stream.Stream;
    20
    21  import org.apache.commons.geometry.core.partitioning.BoundarySource;
    22  import org.apache.commons.geometry.core.partitioning.HyperplaneConvexSubset;
    23  import org.apache.commons.geometry.io.core.input.GeometryInput;
    24  import org.apache.commons.numbers.core.Precision;
    25
    26  /** Basic interface for reading geometric boundary representations
    27   * (<a href="https://en.wikipedia.org/wiki/Boundary_representation">B-reps</a>) from a specific data storage
    28   * format. This interface is intended primarily for use with {@link BoundaryIOManager}.
    29   *
    30   * <p><strong>Implementation note:</strong> implementations of this interface <em>must</em>
    31   * be thread-safe.</p>
    32   * @param <H> Geometric boundary type
    33   * @param <B> Boundary source type
    34   * @see BoundaryWriteHandler
    35   * @see BoundaryIOManager
    36   * @see <a href="https://en.wikipedia.org/wiki/Boundary_representations">Boundary representations</a>
    37   */
    38  public interface BoundaryReadHandler<H extends HyperplaneConvexSubset<?>, B extends BoundarySource<H>> {
    39
    40      /** Get the {@link GeometryFormat data format} supported by this handler.
    41       * @return data format supported by this handler
    42       */
    43      GeometryFormat getFormat();
    44
    45      /** Return an object containing all boundaries read from {@code input} using the handler's
    46       * supported data format.
    47       * @param input input to read from
    48       * @param precision precision context used for floating point comparisons
    49       * @return object containing all boundaries read from {@code input}
    50       * @throws IllegalArgumentException if mathematically invalid data is encountered
    51       * @throws IllegalStateException if a data format error occurs
    52       * @throws java.io.UncheckedIOException if an I/O error occurs
    53       */
    54      B read(GeometryInput input, Precision.DoubleEquivalence precision);
    55
    56      /** Return a {@link Stream} that can be used to access all boundary information from the given input,
    57       * which is expected to contain data in the format supported by this handler. Unlike the
    58       * {@link #read(GeometryInput, Precision.DoubleEquivalence) read} method, this method does not <em>require</em>
    59       * that all input be read immediately and stored in memory (although implementations of this interface are
    60       * still free to do so). Callers may therefore prefer to use this method in cases where memory usage is a
    61       * concern or transformations and/or filters must be applied to the boundaries before use.
    62       *
    63       * <p>Implementing class will usually keep the source input stream open during stream iteration. Callers
    64       * should therefore use the returned stream in a try-with-resources statement to ensure that all resources
    65       * are properly released. Ex:
    66       * </p>
    67       * <pre>
    68       *  try (Stream&lt;H&gt; stream = handler.boundaries(in, precision)) {
    69       *      // access stream content
    70       *  }
    71       * </pre>
    72       *
    73       * <p>The following exceptions may be thrown during stream iteration:
    74       *  <ul>
    75       *      <li>{@link IllegalArgumentException} if mathematically invalid data is encountered</li>
    76       *      <li>{@link IllegalStateException} if a data format error occurs</li>
    77       *      <li>{@link java.io.UncheckedIOException UncheckedIOException} if an I/O error occurs</li>
    78       *  </ul>
    79       * @param in input to read from
    80       * @param precision precision context used for floating point comparisons
    81       * @return stream providing access to the boundary information from the given input
    82       * @throws IllegalStateException if a data format error occurs during stream creation
    83       * @throws java.io.UncheckedIOException if an I/O error occurs during stream creation
    84       */
    85      Stream<H> boundaries(GeometryInput in, Precision.DoubleEquivalence precision);
    86  }