/*
    * $Id: Resources.java 354330 2005-12-06 06:05:19Z niallp $
    * $Revision: 354330 $
    * $Date: 2005-12-06 01:05:19 -0500 (Tue, 06 Dec 2005) $
    *
    * ====================================================================
    *
    *  Copyright 2003-2005 The Apache Software Foundation
    *
   *  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.
   *
   */
  
  package org.apache.commons.resources;
  
  import java.io.InputStream;
  import java.io.Reader;
  import java.io.Serializable;
  import java.util.Iterator;
  import java.util.Locale;
  
  /***
   * <p>An abstract representation of a set of internationalized resources,
   * which are arbitrary objects identified by a unique String <code>key</code>.
   * Localized versions of the resources (based on Locale parameter)
   * can be retrieved in a variety of formats.</p>
   *
   * <p>When presented with an invalid <code>key</code> value, resource
   * getter methods will behave differently based on the current value of
   * the <code>returnNull</code> property for this {@link Resources} instance.
   * If the property value is <code>true</code>, the getter method will return
   * <code>null</code> (which may be ambiguous if <code>null</code> is a valid
   * resource value).  If the property value is <code>false</code>, a
   * <code>ResourcesKeyException</code> will be thrown instead.</p>
   *
   * <p>Different implementations of the {@link Resources} interface support
   * a variety of mechanisms for acquiring the data content represented by
   * the keys.  Examples could include property files, XML files, databases, web
   * application resources, and other specialized approaches as desired.</p>
   *
   * <p>Different implementations of the {@link Resources} interface may apply
   * different semantics to the use of the <code>locale</code> 
   * attribute used to perform localization.  Consult
   * the documentation for the specific {@link Resources} implementation you
   * are using for the specific details of your implementation.</p>
   *
   * <p>Developers implementing {@link Resources} should extend the
   * {@link org.apache.commons.resources.impl.ResourcesBase} class,
   * and override the necessary methods,
   * to shield themselves from future changes that may occur in this interface.
   *
   * @see org.apache.commons.resources.impl.ResourcesBase
   * @see org.apache.commons.resources.impl.CollectionResourcesBase
   * @see org.apache.commons.resources.impl.JDBCResources
   * @see org.apache.commons.resources.impl.PropertyResources
   * @see org.apache.commons.resources.impl.ResourceBundleResources
   * @see org.apache.commons.resources.impl.WebappPropertyResources
   * @see org.apache.commons.resources.impl.WebappXMLResources
   * @see org.apache.commons.resources.impl.XMLResources
   */
  public interface Resources extends Serializable {
  
  
      // ------------------------------------------------------ Lifecycle Methods
  
  
      /***
       * <p>This must be called to initialize the data content of this
       * {@link Resources} instance, before any of the <code>getXxx()</code>
       * methods are called.</p>
       *
       * @exception ResourcesException if an error occurs during initialization
       */
      public void init();
  
  
      /***
       * <p>This method must be called when the manager of this resource
       * decides that it's no longer needed.  After this method is called,
       * no further calls to any of the <code>getXxx()</code> methods are
       * allowed.</p>
       *
       * @exception ResourcesException if an error occurs during finalization
       */
      public void destroy();
  
  
      // ------------------------------------------------------------- Properties
  
 
     /***
      * <p>Return an <code>Iterator</code> over the defined keys in this
      * {@link Resources} instance.</p>
      *
      * @return The keys contained in this resources instance.
      */
     public Iterator getKeys();
 
 
     /***
      * <p>Return the logical name of this {@link Resources} instance.</p>
      *
      * @return The name of this resources instance.
      */
     public String getName();
 
 
     /***
      * <p>Return <code>true</code> if resource getter methods will return
      * <code>null</code> instead of throwing an exception on invalid
      * key values.</p>
      * @return <code>true</code> if null is returned for invalid key values.
      */
     public boolean isReturnNull();
 
 
     /***
      * <p>Set a flag determining whether resource getter methods should
      * return <code>null</code> instead of throwing an exception on
      * invalid key values.</p>
      *
      * @param returnNull The new flag value
      */
     public void setReturnNull(boolean returnNull);
 
 
     // ---------------------------------------------- Content Retrieval Methods
 
 
     /***
      * <p>Return the content for the specified <code>key</code> as a
      * byte array, localized based on the specified <code>locale</code>.
      * </p>
      *
      * @param key Identifier for the requested content
      * @param locale Locale with which to localize retrieval,
      *  or <code>null</code> for the default Locale
      * @return content for a specified key.
      *
      * @exception ResourcesException if an error occurs retrieving or
      *  returning the requested content
      * @exception ResourcesKeyException if no value for the specified
      *  key was found, and <code>isReturnNull()</code> returns
      *  <code>false</code>
      */
     public byte[] getBytes(String key, Locale locale);
 
 
     /***
      * <p>Return the content for the specified <code>key</code> as an
      * InputStream, localized based on the specified <code>locale</code>.
      * </p>
      *
      * @param key Identifier for the requested content
      * @param locale Locale with which to localize retrieval,
      *  or <code>null</code> for the default Locale
      * @return content for a specified key.
      *
      * @exception ResourcesException if an error occurs retrieving or
      *  returning the requested content
      * @exception ResourcesKeyException if no value for the specified
      *  key was found, and <code>isReturnNull()</code> returns
      *  <code>false</code>
      */
     public InputStream getInputStream(String key, Locale locale);
 
 
     /***
      * <p>Return the content for the specified <code>key</code> as an
      * Object, localized based on the specified <code>locale</code>.
      * </p>
      *
      * @param key Identifier for the requested content
      * @param locale Locale with which to localize retrieval,
      *  or <code>null</code> for the default Locale
      * @return content for a specified key.
      *
      * @exception ResourcesException if an error occurs retrieving or
      *  returning the requested content
      * @exception ResourcesKeyException if no value for the specified
      *  key was found, and <code>isReturnNull()</code> returns
      *  <code>false</code>
      */
     public Object getObject(String key, Locale locale);
 
 
     /***
      * <p>Return the content for the specified <code>key</code> as a
      * Reader, localized based on the specified <code>locale</code>.
      * </p>
      *
      * @param key Identifier for the requested content
      * @param locale Locale with which to localize retrieval,
      *  or <code>null</code> for the default Locale
      * @return content for a specified key.
      *
      * @exception ResourcesException if an error occurs retrieving or
      *  returning the requested content
      * @exception ResourcesKeyException if no value for the specified
      *  key was found, and <code>isReturnNull()</code> returns
      *  <code>false</code>
      */
     public Reader getReader(String key, Locale locale);
 
 
     /***
      * <p>Return the content for the specified <code>key</code> as a
      * String, localized based on the specified <code>locale</code>.
      * </p>
      *
      * @param key Identifier for the requested content
      * @param locale Locale with which to localize retrieval,
      *  or <code>null</code> for the default Locale
      * @return content for a specified key.
      *
      * @exception ResourcesException if an error occurs retrieving or
      *  returning the requested content
      * @exception ResourcesKeyException if no value for the specified
      *  key was found, and <code>isReturnNull()</code> returns
      *  <code>false</code>
      */
     public String getString(String key, Locale locale);
 
 
 }