/**
 * The contents of this file are subject to the license and copyright
 * detailed in the LICENSE and NOTICE files at the root of the source
 * tree and available online at
 *
 * http://www.dspace.org/license/
 */
package org.dspace.services;

import java.util.List;
import java.util.Properties;
import org.apache.commons.configuration.Configuration;


/**
 * This service handles retrieval of the configuration data for a DSpace 
 * instance.
 * <p>
 * The configuration files are properties files which look like this for
 * simple values:
 * {@code
 * thing.name = aaronz
 * thing.number = 1234
 * thing.on = true
 * thing.value = abc,def,ghi
 * }
 * For these simple cases the service will automatically translate the 
 * settings into strings, booleans, numbers and arrays as requested
 * in the various {@link #getPropertyAsType(String, Class)} methods.
 * <p>
 * There are special case configuration parameters allowed as well.
 * <p>
 * The first allows setting of a parameter on any DSpace service by the 
 * given name:
 * {@code
 * emailEnabled@org.dspace.Service = true
 * adminUser@org.dspace.impl.MyService = aaronz
 * }
 * This should be used sparingly and really only by system admins (not 
 * developers).  Developers should be using simple config values to 
 * expose service configurations.
 * <p>
 * The second allows controlling the implementation used for a service 
 * interface or provider:
 * {@code
 * $org.dspace.Service = org.dspace.impl.MyService
 * }
 * 
 * @author Aaron Zeckoski (azeckoski @ gmail.com)
 */
public interface ConfigurationService {

    /**
     * Get a configuration property (setting) from the system as a 
     * specified type.
     * 
     * @param <T> class type
     * @param name the property name
     * @param type the type to return the property as
     * @return the property value OR null if none is found
     * @throws UnsupportedOperationException if the type cannot be converted to the requested type
     */
    public <T> T getPropertyAsType(String name, Class<T> type);

    /**
     * Get a configuration property (setting) from the system, or return
     * a default value if none is found.
     * 
     * @param <T> class type
     * @param name the property name
     * @param defaultValue the value to return if this name is not found
     * @return the property value OR null if none is found
     * @throws IllegalArgumentException if the defaultValue type does not match the type of the property by name
     */
    public <T> T getPropertyAsType(String name, T defaultValue);

    /**
     * Get a configuration property (setting) from the system, or return 
     * (and possibly store) a default value if none is found.
     * 
     * @param <T> class type
     * @param name the property name
     * @param defaultValue the value to return if this name is not found
     * @param setDefaultIfNotFound if this is true and the config value 
     * is not found then the default value will be set in the 
     * configuration store assuming it is not null.  Otherwise the
     * default value is just returned but not set.
     * @return the property value OR null if none is found
     * @throws IllegalArgumentException if the defaultValue type does not match the type of the property by name
     */
    public <T> T getPropertyAsType(String name, T defaultValue, boolean setDefaultIfNotFound);

    /**
     * Get keys all currently known configuration settings
     * 
     * @return all the configuration keys as a List
     */
    public List<String> getPropertyKeys();

    /**
     * Get keys all currently known configuration settings, which
     * begin with a given prefix.
     * <P>
     * For example, passing in "db" would return the keys "db.url", "db.username", etc.
     *
     * @param prefix prefix of key
     * @return all the configuration keys as a List
     */
    public List<String> getPropertyKeys(String prefix);

    /**
     * Convenience method - get a configuration property (setting) from 
     * the system as a String.
     * 
     * @param name the property name
     * @return the property value OR null if none is found
     */
    public String getProperty(String name);

    /**
     * Convenience method - get a configuration property (setting) from
     * the system as a String.
     *
     * @param name the property name
     * @param defaultValue default value if property not found
     * @return the property value OR default value if not found
     */
    public String getProperty(String name, String defaultValue);

    /**
     * Convenience method - get a configuration property (setting) from
     * the system as a String Array.
     *
     * @param name the property name
     * @return the String Array value
     */
    public String[] getArrayProperty(String name);

    /**
     * Convenience method - get a configuration property (setting) from
     * the system as a String Array.
     *
     * @param name the property name
     * @param defaultValue the default value if property not found
     * @return the String Array value or default value if not found
     */
    public String[] getArrayProperty(String name, String[] defaultValue);

    /**
     * Convenience method - get a configuration property (setting) from
     * the system as a boolean value.
     *
     * @param name the property name
     * @return the boolean property value (true/false)
     */
    public boolean getBooleanProperty(String name);

    /**
     * Convenience method - get a configuration property (setting) from
     * the system as a boolean value.
     *
     * @param name the property name
     * @param defaultValue the default value if property not found
     * @return the boolean property value (true/false) or default value if not found
     */
    public boolean getBooleanProperty(String name, boolean defaultValue);

    /**
     * Convenience method - get a configuration property (setting) from
     * the system as an int value.
     *
     * @param name the property name
     * @return the integer property value
     */
    public int getIntProperty(String name);

    /**
     * Convenience method - get a configuration property (setting) from
     * the system as an int value.
     *
     * @param name the property name
     * @param defaultValue the default value if property not found
     * @return the integer property value or default value if not found
     */
    public int getIntProperty(String name, int defaultValue);

    /**
     * Convenience method - get a configuration property (setting) from
     * the system as a long value.
     *
     * @param name the property name
     * @return the long property value
     */
    public long getLongProperty(String name);

    /**
     * Convenience method - get a configuration property (setting) from
     * the system as a long value.
     *
     * @param name the property name
     * @param defaultValue the default value if property not found
     * @return the long property value or default value if not found
     */
    public long getLongProperty(String name, long defaultValue);

    /**
     * Convenience method - get a configuration property (setting) from
     * the system as its stored object
     * 
     * @param name the property name
     * @return the property value OR null if none is found
     */
    public Object getPropertyValue(String name);

    /**
     * Convenience method - get all configuration properties (settings)
     * from the system.
     *
     * @return all the configuration properties in a properties object (name to value)
     */
    public Properties getProperties();

    /**
     * Convenience method - get entire configuration (settings)
     * from the system.
     * 
     * @return Configuration object representing the system configuration
     */
    public Configuration getConfiguration();

    /**
     * Return whether a property exists within the configuration
     *
     * @param name the property name
     * @return true if property exists, false if not
     */
    public boolean hasProperty(String name);

    /**
     * Set a configuration property (setting) in the system.
     * Type is not important here since conversion happens automatically
     * when properties are requested.
     * 
     * @param name the property name 
     * @param value the property value (set this to null to clear out the property)
     * @return true if the property is new or changed from the existing value, false if it is the same
     * @throws IllegalArgumentException if the name is null
     * @throws UnsupportedOperationException if the type cannot be converted to something that is understandable by the system as a configuration property value
     */
    public boolean setProperty(String name, Object value);

    /**
     * Reload the configuration from the DSpace configuration files.
     * <P>
     * Uses the initialized ConfigurationService to reload all configurations.
     */
    public void reloadConfig();

}