/*
 * 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.uima.util;

import java.io.IOException;
import java.io.InputStream;
import java.util.Set;

import org.apache.uima.resource.ResourceConfigurationException;

/**
 * A <code>Settings</code> object holds the properties used for external parameter overrides.
 * 
 * Similar to java.util.Properties but: 
 *  - supports UTF-8 (so \\uXXXX escapes are not needed or supported)
 *  - keys must be valid Java identifiers (actually must not contain '=' ':' '}' or white-space)
 *  - reverses priority in that duplicate entries are ignored, i.e. once set values cannot be changed
 *  - multiple files can be loaded
 *  - values can contain references to other values, e.g. name = .... ${key} ....
 *  - arrays are represented as strings, e.g. '[elem1,elem2]', and can span multiple lines
 *  - '\' can be used in values to escape '$' '{' '[' ',' ']' 
 *   
 * @author burn
 * 
 */

public interface Settings {
  
  /**
   * Load properties from an input stream.  
   * Existing properties are not changed and a warning is logged if the new value is different.
   * May be called multiple times, so effective search is in load order.
   * Arrays are enclosed in [] and the elements may be separated by <code>,</code> or new-line, so 
   *   can span multiple lines without using a final \ 
   * 
   * @param in - Stream holding properties
   * @throws IOException if name characters illegal
   */
  public void load(InputStream in) throws IOException;

  /**
   * Load properties from the comma-separated list of files specified in the system property 
   *   UimaExternalOverrides
   * Files are loaded in order --- so in descending priority.
   * 
   * @throws ResourceConfigurationException wraps IOException
   */
  public void loadSystemDefaults() throws ResourceConfigurationException;

  /**
   * Look up the value for a property.
   * Perform one substitution pass on ${key} substrings replacing them with the value for key.
   * Recursively evaluate the value to be substituted.  NOTE: infinite loops not detected!
   * If the key variable has not been defined, an exception is thrown.
   * To avoid evaluation and get ${key} in the output escape the $ or {
   * Arrays are returned as a comma-separated string, e.g. "[elem1,elem2]" 
   * Note: escape characters are not removed as they may affect array separators. 
   * 
   * @param name - name to look up
   * @return     - value of property
   * @throws ResourceConfigurationException if the value references an undefined property
   */
  public String lookUp(String name) throws ResourceConfigurationException;

  /**
   * Return a set of keys of all properties loaded
   * 
   * @return - set of strings
   */
  public Set<String> getKeys();

  /**
   * Get the value of an external override setting.
   * 
   * @param name - the name of the parameter
   * @return     - the value found in the settings file(s), or null if missing.
   * @throws ResourceConfigurationException 
   *                 if the value references an undefined property, or the value is an array
   */
  String getSetting(String name) throws ResourceConfigurationException;
  
  /**
  * Get the array of values for an external override setting.
  * 
  * @param name  - the name of the parameter
  * @return      - an array of values found in the settings file(s), or null if missing.
  * @throws ResourceConfigurationException 
  *                  if the value references an undefined property, or the value is not an array
  */
  public String[] getSettingArray(String name) throws ResourceConfigurationException;
  
}