package org.apache.struts.services;

import java.util.Date;
import java.util.Locale;
import java.text.DateFormat;

public interface LocalizationService extends Service {
    
    /**
     * The default format format for dates in this service.
     * Consult javadocs on the java.text.DateFormat class for
     * more information
     */
    public static int DEFAULT_DATE_FORMAT = DateFormat.DEFAULT;
    
    /**
     * The default format format for times in this service.
     * Consult javadocs on the java.text.DateFormat class for
     * more information
     */
    public static int DEFAULT_TIME_FORMAT = DateFormat.DEFAULT;
    
    
    /**
     * Set the Locale used by the methods in this class
     * @param locale The locale for this class
     */
    public void setLocale(Locale locale);
    
    /**
     * Retrieve the Locale used by the methods in this class
     * @return the Locale used by this class
     */
    public Locale getLocale();
    
    
    /**
     * Sets the default date format used for this class.  The default date
     * format before using this method is specified by DEFAULT_DATE_FORMAT
     * @param format An int representing the format of the date, possible
     *               values are from the java.text.DateFormat class:
     *               DateFormat.SHORT, DateFormat.MEDIUM, DateFormat.LONG,
     *               DateFormat.FULL
     */
    public void setDateFormat(int format);
    
    /**
     * Sets the default time format used for this class. The default date
     * format before using this method is specified by DEFAULT_TIME_FORMAT
     * @param format An int representing the format of the time, possible
     *               values are from the java.text.DateFormat class:
     *               DateFormat.SHORT, DateFormat.MEDIUM, DateFormat.LONG,
     *               DateFormat.FULL
     */
    public void setTimeFormat(int format);
    
    
    /**
     * Attempt to load the content of the resource specified
     * @param key The key of the resource
     * @return A byte array representing the content of the resource
     */
    public byte[] getResource(String key);
    
    /**
     * Attempt to load the content of the resource specified into a String
     * @param key The key of the resource
     * @param encoding The encoding of the content
     * @return A String representing the content of the resource
     * @throws UnsupportedEncodingException if the encoding specified is not
     *                                      supported
     */
    public String getResource(String key, String encoding);
    
    /**
     * Retrieve a Locale-specific date in the default format specified by
     * {@link #setDateFormat(int) setDateFormat} or, if not specified, 
     * DEFAULT_DATE_FORMAT
     * @return A Locale-specific date in the default format
     */
    public String getDate();
    
    /**
     * Retrieve a Locale-specific date in the specified format
     * @param format An int representing the format of the date, possible
     *               values are from the java.text.DateFormat class:
     *               DateFormat.SHORT, DateFormat.MEDIUM, DateFormat.LONG,
     *               DateFormat.FULL
     * @return A Locale-specific date in the format specified
     */
    public String getDate(int format);
    
    /**
     * Retrieve a Locale-specific time in the default format specified by
     * {@link #setTimeFormat(int) setTimeFormat} or, if not specified, 
     * DEFAULT_TIME_FORMAT
     * @return A Locale-specific time in the default format
     */
    public String getTime();
    
    /**
     * Retrieve a Locale-specific time in the format specified
     * @param format An int representing the format of the date, possible
     *               values are from the java.text.DateFormat class:
     *               DateFormat.SHORT, DateFormat.MEDIUM, DateFormat.LONG,
     *               DateFormat.FULL
     * @return A Locale-specific time in the format specified
     */
    public String getTime(int format);
    
    /**
     * Retrieves the Locale-specific formatted date
     * @param date The date to format
     * @return A String representing a Locale-specific representation of
     *         <code>date</code>
     */
    public String getFormattedDate(Date date);
    
    /**
     * Retrieves the Locale-specific formatted time
     * @param date The date to retrieve the time from
     * @return A String representing a Locale-specific representation of
     *         the time specified by <code>date</code>
     */
    public String getFormattedTime(Date date);
    
    /**
     * Retrieve a Locale-formatted number from the number given
     * @param number A java.lang.Number object to convert.  Basically
     *               any primitive type number wrapped in it's class
     *               representation (Float,Double,Integer)
     * @param isCurrency Whether or not to return the value as currency
     * @return A Locale-formatted number as a String
     */
    public String getFormattedNumber(Number number, boolean isCurrency);
}