package io.eguan.configuration;

/*
 * #%L
 * Project eguan
 * %%
 * Copyright (C) 2012 - 2017 Oodrive
 * %%
 * Licensed 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.
 * #L%
 */

import java.io.File;
import java.io.IOException;
import java.io.OutputStream;
import java.util.Collection;
import java.util.Map;
import java.util.Properties;

import javax.annotation.concurrent.Immutable;

/**
 * Interface for all configuration implementations based on text configuration files.
 * 
 * Implementing classes provide a front for text-based configurations in {@link Properties} format and guarantee their
 * validity with respect to constraints implemented by a set of {@link ConfigKey}s.
 * 
 * @param <T>
 *            the {@link ConfigKey}s implementation this configuration manages
 * 
 * @author oodrive
 * @author pwehrle
 * @author llambert
 */
@Immutable
public interface Configuration<T extends ConfigKey<?>> {

    /**
     * Gets all configuration keys.
     * 
     * Keys returned by this method are provided by {@link ConfigurationContext}s associated to this
     * {@link Configuration}.
     * 
     * @return the complete list of {@link ConfigKey configuration keys} managed by this {@link Configuration}
     */
    Collection<T> getConfigKeys();

    /**
     * Gets the part of the configuration that is not managed by any {@link ConfigurationContext} associated to this
     * {@link Configuration}.
     * 
     * Implementing classes provide defensive copies of the result, as modifications to the returned value would violate
     * the immutable constraint on {@link Configuration}.
     * 
     * @return a {@link Properties} object (not backed by the actual instance) containing all key-value pairs not
     *         covered by one of the associated {@link ConfigurationContext}s
     */
    Properties getUnmanagedKeys();

    /**
     * Copies this {@link Configuration} while altering the values for keys given in the given key-value map.
     * 
     * Keys for which a new value is provided must be managed by the original instance.
     * 
     * @param newKeyValueMap
     *            a {@link Map} of keys with matching values to add or overwrite in the copy
     * @return an independent copy of the original {@link Configuration}, with the new values explicitly set
     * @throws ConfigValidationException
     *             if the copy is not valid
     * @throws IOException
     *             if reading the old or writing the new {@link Configuration} instance fails
     * @throws NullPointerException
     *             if the key-value map is <code>null</code>
     * @throws IllegalArgumentException
     *             if any of the keys is not managed by this {@link Configuration} or the associated value cannot be
     *             used
     */
    Configuration<T> copyAndAlterConfiguration(final Map<T, Object> newKeyValueMap) throws ConfigValidationException,
            IOException, NullPointerException, IllegalArgumentException;

    /**
     * Stores the configuration in the given destination.
     * 
     * This method stores all key-value pairs explicitly defined in the configuration loaded on creation, i.e. keys not
     * present, even if returned by {@link #getConfigKeys()}, remain undefined.
     * 
     * @param outputStream
     *            destination output stream.
     * @throws IOException
     *             if writing to the output stream fails
     */
    public void storeConfiguration(final OutputStream outputStream) throws IOException;

    /**
     * Stores the complete configuration including default values in given destination.
     * 
     * This method stores a key-value pair for each key returned by {@link #getConfigKeys()}, inserting default values
     * if no value is explicitly defined.
     * 
     * @param outputStream
     *            destination output stream.
     * @throws IOException
     *             if writing to the output stream fails
     */
    public void storeCompleteConfiguration(final OutputStream outputStream) throws IOException;

    /**
     * Gets the complete configuration as a {@link Properties} instance.
     * 
     * @return a non-<code>null</code> {@link Properties} instance
     * @see #storeCompleteConfiguration(OutputStream)
     */
    public Properties getCompleteConfigurationAsProperties();

    /**
     * Stores the configuration in the given file. If it exists, the current file is renamed to
     * <code>prevConfiguration</code>. On failure, the previous configuration is renamed back <code>configuration</code>
     * .<br>
     * Note: <b><i><code>prevConfiguration</code> is deleted before renaming the destination file</i></b>.
     * 
     * @param configuration
     *            the destination file
     * @param prevConfiguration
     *            new file name of the current configuration file
     * @param complete
     *            <code>true</code> to save the complete configuration (see
     *            {@link #storeCompleteConfiguration(OutputStream)}).
     * @throws IOException
     *             if writing the configuration to the file fails
     */
    public void storeConfiguration(final File configuration, final File prevConfiguration, final boolean complete)
            throws IOException;
}