package org.apache.struts.i18n;

import java.util.Locale;
import java.util.TimeZone;
import java.io.InputStream;

/**
 * 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 getData method that returns an InputStream and write
 * directly to the Stream they're using for resources that contain large size
 * content.
 */
public interface Resource {

    /**
     * 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.
     * @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
     */
    public byte[] getData(String key, Locale locale, TimeZone timeZone);
    
    /**
     * 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
     */
    public InputStream getDataStream(String key, Locale locale, TimeZone timeZone);   
}