BoundaryIOManager.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.geometry.io.core;

import java.text.MessageFormat;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Objects;
import java.util.stream.Collectors;
import java.util.stream.Stream;

import org.apache.commons.geometry.core.partitioning.BoundarySource;
import org.apache.commons.geometry.core.partitioning.HyperplaneConvexSubset;
import org.apache.commons.geometry.io.core.input.GeometryInput;
import org.apache.commons.geometry.io.core.internal.GeometryIOUtils;
import org.apache.commons.geometry.io.core.output.GeometryOutput;
import org.apache.commons.numbers.core.Precision;

/** Class managing IO operations for geometric data formats containing region boundaries.
 * All IO operations are delegated to registered format-specific {@link BoundaryReadHandler read handlers}
 * and {@link BoundaryWriteHandler write handlers}.
 *
 * <p><strong>Exceptions</strong>
 * <p>Despite having functionality related to I/O operations, this class has been designed to <em>not</em>
 * throw checked exceptions, in particular {@link java.io.IOException IOException}. The primary reasons for
 * this choice are
 * <ul>
 *  <li>convenience,</li>
 *  <li>compatibility with functional programming, and </li>
 *  <li>the fact that modern Java practice is moving away from checked exceptions in general (as exemplified
 *      by the JDK's {@link java.io.UncheckedIOException UncheckedIOException}).</li>
 * </ul>
 * As a result, any {@link java.io.IOException IOException} thrown internally by this or related classes
 * is wrapped with {@link java.io.UncheckedIOException UncheckedIOException}. Other common runtime exceptions
 * include {@link IllegalArgumentException}, which typically indicates mathematically invalid data, and
 * {@link IllegalStateException}, which typically indicates format or parsing errors. See the method-level
 * documentation for more details.
 *
 * <p><strong>Implementation note:</strong> Instances of this class are thread-safe as long as the
 * registered handler instances are thread-safe.</p>
 * @param <H> Geometric boundary type
 * @param <B> Boundary source type
 * @param <R> Read handler type
 * @param <W> Write handler type
 * @see BoundaryReadHandler
 * @see BoundaryWriteHandler
 * @see <a href="https://en.wikipedia.org/wiki/Boundary_representations">Boundary representations</a>
 */
public class BoundaryIOManager<
    H extends HyperplaneConvexSubset<?>,
    B extends BoundarySource<H>,
    R extends BoundaryReadHandler<H, B>,
    W extends BoundaryWriteHandler<H, B>> {

    /** Error message used when a handler is null. */
    private static final String HANDLER_NULL_ERR = "Handler cannot be null";

    /** Error message used when a format is null. */
    private static final String FORMAT_NULL_ERR = "Format cannot be null";

    /** Error message used when a format name is null. */
    private static final String FORMAT_NAME_NULL_ERR = "Format name cannot be null";

    /** Read handler registry. */
    private final HandlerRegistry<R> readRegistry = new HandlerRegistry<>();

    /** Write handler registry. */
    private final HandlerRegistry<W> writeRegistry = new HandlerRegistry<>();

    /** Register a {@link BoundaryReadHandler read handler} with the instance, replacing
     * any handler previously registered for the argument's supported data format, as returned
     * by {@link BoundaryReadHandler#getFormat()}.
     * @param handler handler to register
     * @throws NullPointerException if {@code handler}, its {@link BoundaryReadHandler#getFormat() format},
     *      or the {@link GeometryFormat#getFormatName() format's name} are null
     */
    public void registerReadHandler(final R handler) {
        Objects.requireNonNull(handler, HANDLER_NULL_ERR);
        readRegistry.register(handler.getFormat(), handler);
    }

    /** Unregister a previously registered {@link BoundaryReadHandler read handler};
     * does nothing if the argument is null or is not currently registered.
     * @param handler handler to unregister; may be null
     */
    public void unregisterReadHandler(final R handler) {
        readRegistry.unregister(handler);
    }

    /** Get all registered {@link BoundaryReadHandler read handlers}.
     * @return list containing all registered read handlers
     */
    public List<R> getReadHandlers() {
        return readRegistry.getHandlers();
    }

    /** Get the list of formats supported by the currently registered
     * {@link BoundaryReadHandler read handlers}.
     * @return list of read formats
     * @see BoundaryReadHandler#getFormat()
     */
    public List<GeometryFormat> getReadFormats() {
        return readRegistry.getHandlers().stream()
                .map(BoundaryReadHandler::getFormat)
                .collect(Collectors.toList());
    }

    /** Get the {@link BoundaryReadHandler read handler} for the given format or
     * null if no such handler has been registered.
     * @param fmt format to obtain a handler for
     * @return read handler for the given format or null if not found
     */
    public R getReadHandlerForFormat(final GeometryFormat fmt) {
        return readRegistry.getByFormat(fmt);
    }

    /** Get the {@link BoundaryReadHandler read handler} for the given file extension
     * or null if no such handler has been registered. File extension comparisons are
     * not case-sensitive.
     * @param fileExt file extension to obtain a handler for
     * @return read handler for the given file extension or null if not found
     * @see GeometryFormat#getFileExtensions()
     */
    public R getReadHandlerForFileExtension(final String fileExt) {
        return readRegistry.getByFileExtension(fileExt);
    }

    /** Register a {@link BoundaryWriteHandler write handler} with the instance, replacing
     * any handler previously registered for the argument's supported data format, as returned
     * by {@link BoundaryWriteHandler#getFormat()}.
     * @param handler handler to register
     * @throws NullPointerException if {@code handler}, its {@link BoundaryWriteHandler#getFormat() format},
     *      or the {@link GeometryFormat#getFormatName() format's name} are null
     */
    public void registerWriteHandler(final W handler) {
        Objects.requireNonNull(handler, HANDLER_NULL_ERR);
        writeRegistry.register(handler.getFormat(), handler);
    }

    /** Unregister a previously registered {@link BoundaryWriteHandler write handler};
     * does nothing if the argument is null or is not currently registered.
     * @param handler handler to unregister; may be null
     */
    public void unregisterWriteHandler(final W handler) {
        writeRegistry.unregister(handler);
    }

    /** Get all registered {@link BoundaryWriteHandler write handlers}.
     * @return list containing all registered write handlers
     */
    public List<W> getWriteHandlers() {
        return writeRegistry.getHandlers();
    }

    /** Get the list of formats supported by the currently registered
     * {@link BoundaryWriteHandler write handlers}.
     * @return list of write formats
     * @see BoundaryWriteHandler#getFormat()
     */
    public List<GeometryFormat> getWriteFormats() {
        return writeRegistry.getHandlers().stream()
                .map(BoundaryWriteHandler::getFormat)
                .collect(Collectors.toList());
    }

    /** Get the {@link BoundaryWriteHandler write handler} for the given format or
     * null if no such handler has been registered.
     * @param fmt format to obtain a handler for
     * @return write handler for the given format or null if not found
     */
    public W getWriteHandlerForFormat(final GeometryFormat fmt) {
        return writeRegistry.getByFormat(fmt);
    }

    /** Get the {@link BoundaryWriteHandler write handler} for the given file extension
     * or null if no such handler has been registered. File extension comparisons are
     * not case-sensitive.
     * @param fileExt file extension to obtain a handler for
     * @return write handler for the given file extension or null if not found
     * @see GeometryFormat#getFileExtensions()
     */
    public W getWriteHandlerForFileExtension(final String fileExt) {
        return writeRegistry.getByFileExtension(fileExt);
    }

    /** Return a {@link BoundarySource} containing all boundaries from the given input.
     * A runtime exception may be thrown if mathematically invalid boundaries are encountered.
     * @param in input to read boundaries from
     * @param fmt format of the input; if null, the format is determined implicitly from the
     *      file extension of the input {@link GeometryInput#getFileName() file name}
     * @param precision precision context used for floating point comparisons
     * @return object containing all boundaries from the input
     * @throws IllegalArgumentException if mathematically invalid data is encountered or no
     *      {@link BoundaryReadHandler read handler} can be found for the input format
     * @throws IllegalStateException if a data format error occurs
     * @throws java.io.UncheckedIOException if an I/O error occurs
     */
    public B read(final GeometryInput in, final GeometryFormat fmt, final Precision.DoubleEquivalence precision) {
        return requireReadHandler(in, fmt).read(in, precision);
    }

    /** Return a {@link 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:
     * <pre>
     *  try (Stream&lt;H&gt; stream = manager.boundaries(in, fmt, precision)) {
     *      // access stream content
     *  }
     *  </pre>
     * <p>The following exceptions may be thrown during stream iteration:
     *  <ul>
     *      <li>{@link IllegalArgumentException} if mathematically invalid data is encountered</li>
     *      <li>{@link IllegalStateException} if a data format error occurs</li>
     *      <li>{@link java.io.UncheckedIOException UncheckedIOException} if an I/O error occurs</li>
     *  </ul>
     * @param in input to read boundaries from
     * @param fmt format of the input; if null, the format is determined implicitly from the
     *      file extension of the input {@link GeometryInput#getFileName() file name}
     * @param precision precision context used for floating point comparisons
     * @return stream providing access to all boundaries from the input
     * @throws IllegalArgumentException if no {@link BoundaryReadHandler read handler} can be found for
     *      the input format
     * @throws IllegalStateException if a data format error occurs during stream creation
     * @throws java.io.UncheckedIOException if an I/O error occurs during stream creation
     */
    public Stream<H> boundaries(final GeometryInput in, final GeometryFormat fmt,
            final Precision.DoubleEquivalence precision) {
        return requireReadHandler(in, fmt).boundaries(in, precision);
    }

    /** Write all boundaries from {@code src} to the given output.
     * @param src object containing boundaries to write
     * @param out output to write boundaries to
     * @param fmt format of the output; if null, the format is determined implicitly from the
     *      file extension of the output {@link GeometryOutput#getFileName()}
     * @throws IllegalArgumentException if no {@link BoundaryWriteHandler write handler} can be found
     *      for the output format
     * @throws java.io.UncheckedIOException if an I/O error occurs
     */
    public void write(final B src, final GeometryOutput out, final GeometryFormat fmt) {
        requireWriteHandler(out, fmt).write(src, out);
    }

    /** Get the {@link BoundaryReadHandler read handler} matching the arguments, throwing an exception
     * on failure. If {@code fmt} is given, the handler registered for that format is returned and the
     * {@code input} object is not examined. If {@code fmt} is null, the file extension of the input
     * {@link GeometryInput#getFileName() file name} is used to implicitly determine the format and locate
     * the handler.
     * @param in input object
     * @param fmt format; may be null
     * @return the read handler for {@code fmt} or, if {@code fmt} is null, the read handler for the
     *      file extension indicated by the input
     * @throws NullPointerException if {@code in} is null
     * @throws IllegalArgumentException if no matching handler can be found
     */
    protected R requireReadHandler(final GeometryInput in, final GeometryFormat fmt) {
        Objects.requireNonNull(in, "Input cannot be null");
        return readRegistry.requireHandlerByFormatOrFileName(fmt, in.getFileName());
    }

    /** Get the {@link BoundaryWriteHandler write handler} matching the arguments, throwing an exception
     * on failure. If {@code fmt} is given, the handler registered for that format is returned and the
     * {@code input} object is not examined. If {@code fmt} is null, the file extension of the output
     * {@link GeometryOutput#getFileName() file name} is used to implicitly determine the format and locate
     * the handler.
     * @param out output object
     * @param fmt format; may be null
     * @return the write handler for {@code fmt} or, if {@code fmt} is null, the write handler for the
     *      file extension indicated by the output
     * @throws NullPointerException if {@code out} is null
     * @throws IllegalArgumentException if no matching handler can be found
     */
    protected W requireWriteHandler(final GeometryOutput out, final GeometryFormat fmt) {
        Objects.requireNonNull(out, "Output cannot be null");
        return writeRegistry.requireHandlerByFormatOrFileName(fmt, out.getFileName());
    }

    /** Internal class used to manage handler registration. Instances of this class
     * are thread-safe.
     * @param <T> Handler type
     */
    private static final class HandlerRegistry<T> {

        /** List of registered handlers. */
        private final List<T> handlers = new ArrayList<>();

        /** Handlers keyed by lower-case format name. */
        private final Map<String, T> handlersByFormatName = new HashMap<>();

        /** Handlers keyed by lower-case file extension. */
        private final Map<String, T> handlersByFileExtension = new HashMap<>();

        /** Register a handler for the given {@link GeometryFormat format}.
         * @param fmt format for the handler
         * @param handler handler to register
         * @throws NullPointerException if either argument is null
         */
        public synchronized void register(final GeometryFormat fmt, final T handler) {
            Objects.requireNonNull(fmt, FORMAT_NULL_ERR);
            Objects.requireNonNull(handler, HANDLER_NULL_ERR);

            if (!handlers.contains(handler)) {
                // remove any previously registered handler
                unregisterFormat(fmt);

                // add the new handler
                addToFormat(fmt.getFormatName(), handler);
                addToFileExtensions(fmt.getFileExtensions(), handler);

                handlers.add(handler);
            }
        }

        /** Unregister the given handler.
         * @param handler handler to unregister
         */
        public synchronized void unregister(final T handler) {
            if (handler != null && handlers.remove(handler)) {
                removeValue(handlersByFormatName, handler);
                removeValue(handlersByFileExtension, handler);
            }
        }

        /** Unregister the current handler for the given format and return it.
         * Null is returned if no handler was registered.
         * @param fmt format to unregister
         * @return handler instance previously registered for the format or null
         *      if not found
         */
        public synchronized T unregisterFormat(final GeometryFormat fmt) {
            final T handler = getByFormat(fmt);
            if (handler != null) {
                unregister(handler);
            }
            return handler;
        }

        /** Get all registered handlers.
         * @return list of all registered handlers
         */
        public synchronized List<T> getHandlers() {
            return Collections.unmodifiableList(new ArrayList<>(handlers));
        }

        /** Get the first handler registered for the given format, or null if
         * not found.
         * @param fmt format to obtain a handler for
         * @return first handler registered for the format
         */
        public synchronized T getByFormat(final GeometryFormat fmt) {
            if (fmt != null) {
                return getByNormalizedKey(handlersByFormatName, fmt.getFormatName());
            }
            return null;
        }

        /** Get the first handler registered for the given file extension or null if not found.
         * @param fileExt file extension
         * @return first handler registered for the given file extension or null if not found
         */
        public synchronized T getByFileExtension(final String fileExt) {
            return getByNormalizedKey(handlersByFileExtension, fileExt);
        }

        /** Get the handler for the given format or file extension, throwing an exception if one
         * cannot be found. If {@code fmt} is not null, it is used to directly look up the handler
         * and the {@code fileName} argument is ignored. Otherwise, the file extension is extracted
         * from {@code fileName} and used to look up the handler.
         * @param fmt format to look up; if present, {@code fileName} is ignored
         * @param fileName file name to use for the look up if {@code fmt} is null
         * @return the handler matching the arguments
         * @throws IllegalArgumentException if a handler cannot be found
         */
        public synchronized T requireHandlerByFormatOrFileName(final GeometryFormat fmt, final String fileName) {
            T handler = null;
            if (fmt != null) {
                handler = getByFormat(fmt);

                if (handler == null) {
                    throw new IllegalArgumentException(MessageFormat.format(
                            "Failed to find handler for format \"{0}\"", fmt.getFormatName()));
                }
            } else {
                final String fileExt = GeometryIOUtils.getFileExtension(fileName);
                if (fileExt != null && !fileExt.isEmpty()) {
                    handler = getByFileExtension(fileExt);

                    if (handler == null) {
                        throw new IllegalArgumentException(MessageFormat.format(
                               "Failed to find handler for file extension \"{0}\"", fileExt));
                    }
                } else {
                    throw new IllegalArgumentException(
                            "Failed to find handler: no format specified and no file extension available");
                }
            }

            return handler;
        }

        /** Add the handler to the internal format name map.
         * @param fmtName format name
         * @param handler handler to add
         * @throws NullPointerException if {@code fmtName} is null
         */
        private void addToFormat(final String fmtName, final T handler) {
            Objects.requireNonNull(fmtName, FORMAT_NAME_NULL_ERR);
            handlersByFormatName.put(normalizeString(fmtName), handler);
        }

        /** Add the handler to the internal file extension map under each file extension.
         * @param fileExts file extensions to map to the handler
         * @param handler handler to add to the file extension map
         */
        private void addToFileExtensions(final List<String> fileExts, final T handler) {
            if (fileExts != null) {
                for (final String fileExt : fileExts) {
                    addToFileExtension(fileExt, handler);
                }
            }
        }

        /** Add the handler to the internal file extension map.
         * @param fileExt file extension to map to the handler
         * @param handler handler to add to the file extension map
         */
        private void addToFileExtension(final String fileExt, final T handler) {
            if (fileExt != null) {
                handlersByFileExtension.put(normalizeString(fileExt), handler);
            }
        }

        /** Normalize the given key and return its associated value in the map, or null
         * if not found.
         * @param <V> Value type
         * @param map map to search
         * @param key unnormalized map key
         * @return the value associated with the key after normalization, or null if not found
         */
        private static <V> V getByNormalizedKey(final Map<String, V> map, final String key) {
            if (key != null) {
                return map.get(normalizeString(key));
            }
            return null;
        }

        /** Remove all keys that map to {@code value}.
         * @param <V> Value type
         * @param map map to remove keys from
         * @param value value to remove from all entries in the map
         */
        private static <V> void removeValue(final Map<String, V> map, final V value) {
            final Iterator<Map.Entry<String, V>> it = map.entrySet().iterator();
            while (it.hasNext()) {
                if (value.equals(it.next().getValue())) {
                    it.remove();
                }
            }
        }

        /** Normalize the given string for use as a registry identifier.
         * @param str string to normalize
         * @return normalized string
         */
        private static String normalizeString(final String str) {
            return str.toLowerCase(Locale.ROOT);
        }
    }
}