package org.apache.i18n

import java.util.Locale;
import java.util.TimeZone;
import java.util.MissingResourceException;

import java.io.InputStream;
import java.io.Serializable;

import java.net.URL;

/**
 * This class represents an internationalized resource, that is, anything
 * that can pull specific content out in the context of a certain locale and
 * optionally time zone.  The basic idea is that each peice of content is
 * associated with a String key, and that key is used to retrieve the content.
 * Developers using implementations of this class should keep in mind that
 * they should use the getDataStream method that returns an InputStream and write
 * directly to the Stream they're using for resources that contain large size
 * content.
 */
public interface Resource implements Serializable {

    
    /**
     * This is called on to initialize the Resource, before any of the
     * getData* methods are called, and after the setConfigurationURL() method
     * is called.
     */
    public void init();
    
    /**
     * This method is called when the manager of this resource decides that
     * it's no longer needed.
     */
    public void destroy();
    
    /**
     * Get the name of this resource
     * @return A logical String representation of the name of this resource
     */
    public String getName();
    
    /**
     * Retrieves content based on the locale and time zone specified.  Note
     * that this method has the potential to cause memory problems for content
     * that is relatively large.
     * @param key The key for the content
     * @param locale The locale to retreive the content in, if <code>null</code>,
     *               the default locale
     * @param timeZone The time zone to retrieve the content for, if <code>null</code>,
     *                 the default time zone.  Resource implementations may ignore
     *                 the time zone argument all together.
     */
    public byte[] getData(String key, Locale locale, TimeZone timeZone)
        throws MissingResourceException;
    
    /**
     * Retrieves content based on the locale and time zone specified.  Note
     * that this method has the potential to cause memory problems for content
     * that is relatively large.
     * @param key The key for the content
     * @param locale The locale to retreive the content in, if <code>null</code>,
     *               the default locale
     * @param timeZone The time zone to retrieve the content for, if <code>null</code>,
     *                 the default time zone.  Resource implementations may ignore
     *                 the time zone argument all together.
     * @param args An array of Strings representing numbered arguments to plug
     *             into the data.  This is Resource implementation dependent.
     */
    public byte[] getData(String key, Locale locale, TimeZone timeZone,
                          String[] args)
        throws MissingResourceException;
    
    /**
     * Retrieves content based on the locale and time zone specified.  Note
     * that this method has the potential to cause memory problems for content
     * that is relatively large.
     * @param key The key for the content
     * @param locale The locale to retreive the content in, if <code>null</code>,
     *               the default locale
     * @param timeZone The time zone to retrieve the content for, if <code>null</code>,
     *                 the default time zone.  Resource implementations may ignore
     *                 the time zone argument all together.
     */
    public String getData(String key, Locale locale, TimeZone timeZone)
        throws MissingResourceException;
    
    
    /**
     * Retrieves content based on the locale and time zone specified.  Note
     * that this method has the potential to cause memory problems for content
     * that is relatively large.
     * @param key The key for the content
     * @param locale The locale to retreive the content in, if <code>null</code>,
     *               the default locale
     * @param timeZone The time zone to retrieve the content for, if <code>null</code>,
     *                 the default time zone.  Resource implementations may ignore
     *                 the time zone argument all together.
     * @param args An array of Strings representing numbered arguments to plug
     *             into the data.  This is Resource implementation dependent.
     */
    public String getData(String key, Locale locale, TimeZone timeZone,
                          String[] args)
        throws MissingResourceException;
    
    /**
     * Retrieves an InputStream representing the content based on the key, locale,
     * and time zone specified
     * @param key The key for the content
     * @param locale The locale to retreive the content in, if <code>null</code>,
     *               the default locale
     * @param timeZone The time zone to retrieve the content for, if <code>null</code>,
     *                 the default time zone.  Resource implementations may ignore
     *                 the time zone argument all together.
     */
    public InputStream getDataStream(String key, Locale locale, TimeZone timeZone)
        throws MissingResourceException;
    
    /**
     * Retrieves an InputStream representing the content based on the key, locale,
     * and time zone specified
     * @param key The key for the content
     * @param locale The locale to retreive the content in, if <code>null</code>,
     *               the default locale
     * @param timeZone The time zone to retrieve the content for, if <code>null</code>,
     *                 the default time zone.  Resource implementations may ignore
     *                 the time zone argument all together.
     * @param args An array of Strings representing numbered arguments to plug
     *             into the data.  This is Resource implementation dependent.
     */
    public InputStream getDataStream(String key, Locale locale, TimeZone timeZone,
                                     String[] args)
        throws MissingResourceException;
    
    /**
     * This method is guaranteed to be called before the init() method for this 
     * class.
     * @param config The URL of the configuration file for this resource
     */    
    public void setConfigurationURL(URL config);
}