config/src/main/java/org/apache/tuweni/config/Configuration.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.tuweni.config;

import static java.util.Objects.requireNonNull;
import static org.apache.tuweni.toml.Toml.canonicalDottedKey;

import org.apache.tuweni.toml.Toml;

import java.io.IOException;
import java.io.InputStream;
import java.io.UncheckedIOException;
import java.io.Writer;
import java.nio.file.Files;
import java.nio.file.NoSuchFileException;
import java.nio.file.Path;
import java.util.List;
import java.util.Map;
import java.util.Set;
import javax.annotation.Nullable;

/**
 * Represents collection of configuration properties, optionally validated against a schema.
 */
public interface Configuration {

  /**
   * Read a configuration from a TOML-formatted string.
   *
   * @param toml A TOML-formatted string.
   * @return A Configuration loaded from the TOML file.
   */
  static Configuration fromToml(String toml) {
    return fromToml(toml, null);
  }

  /**
   * Read a configuration from a TOML-formatted string, associated with a validation schema.
   *
   * @param toml A TOML-formatted string.
   * @param schema The validation schema for the configuration.
   * @return A Configuration loaded from the TOML file.
   */
  static Configuration fromToml(String toml, @Nullable Schema schema) {
    requireNonNull(toml);
    return new TomlBackedConfiguration(Toml.parse(toml), schema);
  }

  /**
   * Loads a configuration from a TOML-formatted file.
   *
   * @param file The path of the TOML-formatted configuration file.
   * @return A Configuration loaded from the TOML file.
   * @throws NoSuchFileException If the file could not be found.
   * @throws IOException If an IO error occurs.
   */
  static Configuration fromToml(Path file) throws IOException {
    return fromToml(file, null);
  }

  /**
   * Loads a configuration from a file, associated with a validation schema.
   *
   * @param file The path of the TOML-formatted configuration file.
   * @param schema The validation schema for the configuration.
   * @return A Configuration loaded from the TOML file.
   * @throws NoSuchFileException If the file could not be found.
   * @throws IOException If an IO error occurs.
   */
  static Configuration fromToml(Path file, @Nullable Schema schema) throws IOException {
    requireNonNull(file);
    return new TomlBackedConfiguration(Toml.parse(file), schema);
  }

  /**
   * Loads a configuration from a TOML-formatted file.
   *
   * @param is An input stream providing TOML-formatted configuration.
   * @return A Configuration loaded from the TOML file.
   * @throws IOException If an IO error occurs.
   */
  static Configuration fromToml(InputStream is) throws IOException {
    return fromToml(is, null);
  }

  /**
   * Loads a configuration from a file, associated with a validation schema.
   *
   * @param is An input stream providing TOML-formatted configuration.
   * @param schema The validation schema for the configuration.
   * @return A Configuration loaded from the TOML file.
   * @throws IOException If an IO error occurs.
   */
  static Configuration fromToml(InputStream is, @Nullable Schema schema) throws IOException {
    requireNonNull(is);
    return new TomlBackedConfiguration(Toml.parse(is), schema);
  }

  /**
   * Get an empty configuration, with no values.
   *
   * @return An empty configuration, with no values.
   */
  static Configuration empty() {
    return EmptyConfiguration.EMPTY;
  }

  /**
   * Get an empty configuration, associated with a validation schema.
   *
   * @param schema The validation schema for the configuration.
   * @return An empty configuration.
   */
  static Configuration empty(@Nullable Schema schema) {
    return new EmptyConfiguration(schema);
  }

  /**
   * @return {@code true} if the TOML document contained errors.
   */
  default boolean hasErrors() {
    return !(errors().isEmpty());
  }

  /**
   * The errors that occurred during parsing.
   *
   * @return A list of errors.
   */
  List<ConfigurationError> errors();

  /**
   * Get a TOML-formatted representation of this configuration.
   *
   * @return A TOML-formatted representation.
   */
  default String toToml() {
    StringBuilder builder = new StringBuilder();
    try {
      toToml(builder);
    } catch (IOException e) {
      // Not reachable
      throw new UncheckedIOException(e);
    }
    return builder.toString();
  }

  /**
   * Save a configuration to a TOML-formatted file.
   *
   * <p>
   * If necessary, parent directories for the output file will be created.
   *
   * @param path The file path to write the TOML-formatted output to.
   * @throws IOException If the file cannot be written.
   */
  default void toToml(Path path) throws IOException {
    Files.createDirectories(path.getParent());
    try (Writer writer = Files.newBufferedWriter(path)) {
      toToml(writer);
    }
  }

  /**
   * Writes a configuration in TOML format.
   *
   * @param appendable The output to write to.
   * @throws IOException If the file cannot be written.
   */
  void toToml(Appendable appendable) throws IOException;

  /**
   * The keys of all entries present in this configuration.
   *
   * @return The keys of all entries in this configuration.
   */
  Set<String> keySet();

  /**
   * Check if a key is set in this configuration.
   *
   * @param key A configuration key (e.g. {@code "server.address.hostname"}).
   * @return {@code true} if the entry is present in this configuration.
   * @throws IllegalArgumentException If the key cannot be parsed.
   */
  boolean contains(String key);

  /**
   * Get an object from this configuration.
   *
   * @param key A configuration key (e.g. {@code "server.address.hostname"}).
   * @return The value, or {@code null} if no value was set in the configuration.
   * @throws IllegalArgumentException If the key cannot be parsed.
   */
  @Nullable
  Object get(String key);

  /**
   * Get the position where a key is defined in the TOML document.
   *
   * @param key A configuration key (e.g. {@code "server.address.port"}).
   * @return The input position, or {@code null} if the key was not set in this configuration.
   * @throws IllegalArgumentException If the key cannot be parsed.
   */
  @Nullable
  DocumentPosition inputPositionOf(String key);

  /**
   * Get a string from this configuration.
   *
   * @param key A configuration key (e.g. {@code "server.address.hostname"}).
   * @return The value.
   * @throws IllegalArgumentException If the key cannot be parsed.
   * @throws InvalidConfigurationPropertyTypeException If the value is not a string.
   * @throws NoConfigurationPropertyException If the key was not set in the configuration.
   */
  String getString(String key);

  /**
   * Get an integer from this configuration.
   *
   * @param key A configuration key (e.g. {@code "server.address.port"}).
   * @return The value.
   * @throws IllegalArgumentException If the key cannot be parsed.
   * @throws InvalidConfigurationPropertyTypeException If the value is not an integer.
   * @throws NoConfigurationPropertyException If the key was not set in the configuration.
   */
  int getInteger(String key);

  /**
   * Get a long from this configuration.
   *
   * @param key A configuration key (e.g. {@code "server.address.port"}).
   * @return The value.
   * @throws IllegalArgumentException If the key cannot be parsed.
   * @throws InvalidConfigurationPropertyTypeException If the value is not a long.
   * @throws NoConfigurationPropertyException If the key was not set in the configuration.
   */
  long getLong(String key);

  /**
   * Get a double from this configuration.
   *
   * @param key A configuration key (e.g. {@code "server.priority"}).
   * @return The value.
   * @throws IllegalArgumentException If the key cannot be parsed.
   * @throws InvalidConfigurationPropertyTypeException If the value is not a double.
   * @throws NoConfigurationPropertyException If the key was not set in the configuration.
   */
  double getDouble(String key);

  /**
   * Get a boolean from this configuration.
   *
   * @param key A configuration key (e.g. {@code "server.active"}).
   * @return The value.
   * @throws IllegalArgumentException If the key cannot be parsed.
   * @throws InvalidConfigurationPropertyTypeException If the value is not a boolean.
   * @throws NoConfigurationPropertyException If the key was not set in the configuration.
   */
  boolean getBoolean(String key);

  /**
   * Get a map from this configuration.
   *
   * @param key A configuration key (e.g. {@code "server.active"}).
   * @return The value.
   * @throws IllegalArgumentException If the key cannot be parsed.
   * @throws InvalidConfigurationPropertyTypeException If the value is not a map.
   * @throws NoConfigurationPropertyException If the key was not set in the configuration.
   */
  Map<String, Object> getMap(String key);

  /**
   * Get a list from this configuration.
   *
   * @param key A configuration key (e.g. {@code "server.common_names"}).
   * @return The value.
   * @throws IllegalArgumentException If the key cannot be parsed.
   * @throws InvalidConfigurationPropertyTypeException If the value is not a list.
   * @throws NoConfigurationPropertyException If the key was not set in the configuration.
   */
  List<Object> getList(String key);

  /**
   * Get a list of strings from this configuration.
   *
   * @param key A configuration key (e.g. {@code "server.common_names"}).
   * @return The value.
   * @throws IllegalArgumentException If the key cannot be parsed.
   * @throws InvalidConfigurationPropertyTypeException If the value is not a list of strings.
   * @throws NoConfigurationPropertyException If the key was not set in the configuration.
   */
  List<String> getListOfString(String key);

  /**
   * Get a list of integers from this configuration.
   *
   * @param key A configuration key (e.g. {@code "server.address.ports"}).
   * @return The value.
   * @throws IllegalArgumentException If the key cannot be parsed.
   * @throws InvalidConfigurationPropertyTypeException If the value is not a list of integers.
   * @throws NoConfigurationPropertyException If the key was not set in the configuration.
   */
  List<Integer> getListOfInteger(String key);

  /**
   * Get a list of longs from this configuration.
   *
   * @param key A configuration key (e.g. {@code "server.address.ports"}).
   * @return The value.
   * @throws IllegalArgumentException If the key cannot be parsed.
   * @throws InvalidConfigurationPropertyTypeException If the value is not a list of longs.
   * @throws NoConfigurationPropertyException If the key was not set in the configuration.
   */
  List<Long> getListOfLong(String key);

  /**
   * Get a list of doubles from this configuration.
   *
   * @param key A configuration key (e.g. {@code "server.priorities"}).
   * @return The value.
   * @throws IllegalArgumentException If the key cannot be parsed.
   * @throws InvalidConfigurationPropertyTypeException If the value is not a list of doubles.
   * @throws NoConfigurationPropertyException If the key was not set in the configuration.
   */
  List<Double> getListOfDouble(String key);

  /**
   * Get a list of booleans from this configuration.
   *
   * @param key A configuration key (e.g. {@code "server.flags"}).
   * @return The value.
   * @throws IllegalArgumentException If the key cannot be parsed.
   * @throws InvalidConfigurationPropertyTypeException If the value is not a list of booleans.
   * @throws NoConfigurationPropertyException If the key was not set in the configuration.
   */
  List<Boolean> getListOfBoolean(String key);

  /**
   * Get a list of maps from this configuration.
   *
   * @param key A configuration key (e.g. {@code "mainnet.servers"}).
   * @return The value.
   * @throws IllegalArgumentException If the key cannot be parsed.
   * @throws InvalidConfigurationPropertyTypeException If the value is not a list of maps.
   * @throws NoConfigurationPropertyException If the key was not set in the configuration.
   */
  List<Map<String, Object>> getListOfMap(String key);

  /**
   * Get the canonical form of a configuration key.
   *
   * @param key A configuration key (e.g. {@code "server.flags"}).
   * @return The canonical form of the key.
   * @throws IllegalArgumentException If the key cannot be parsed.
   */
  static String canonicalKey(String key) {
    return canonicalDottedKey(key);
  }
}