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  }