net.time4j.format.UnitPatternProvider Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of time4j-core Show documentation
There is a newer version: 4.38
/*
 * -----------------------------------------------------------------------
 * Copyright © 2013-2015 Meno Hochschild, 
 * -----------------------------------------------------------------------
 * This file (UnitPatternProvider.java) is part of project Time4J.
 *
 * Time4J is free software: You can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published
 * by the Free Software Foundation, either version 2.1 of the License, or
 * (at your option) any later version.
 *
 * Time4J is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with Time4J. If not, see .
 * -----------------------------------------------------------------------
 */

package net.time4j.format;

import java.util.Locale;


/**
 * This SPI-interface enables the access to localized
 * unit patterns and is instantiated via a {@code ServiceLoader}-mechanism. 
 *
 * If there is no external {@code UnitPatternProvider} then Time4J will use
 * an internal implementation which just offers unit patterns either in
 * english or in scientific notation. 
 *
 * Specification:
 * Implementations must have a public no-arg constructor. 
 *
 * @author  Meno Hochschild
 * @since   1.2
 * @see     java.util.ServiceLoader
 */
/*[deutsch]
 * Dieses SPI-Interface ermöglicht den Zugriff
 * auf {@code Locale}-abhängige Zeiteinheitsmuster und wird über
 * einen {@code ServiceLoader}-Mechanismus instanziert. 
 *
 * Wird kein externer {@code UnitPatternProvider} gefunden, wird intern
 * eine Instanz erzeugt, die lediglich Zeiteinheitsmuster auf Englisch
 * oder in wissenschaftlicher Notation anbietet. 
 *
 * Specification:
 * Implementations must have a public no-arg constructor. 
 *
 * @author  Meno Hochschild
 * @since   1.2
 * @see     java.util.ServiceLoader
 */
public interface UnitPatternProvider {

    //~ Methoden ----------------------------------------------------------

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of years. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for years
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext und
     * einem Platzhalter "{0}" für die Anzahl der Jahre. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for years
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getYearPattern(
        Locale lang,
        TextWidth width,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of months. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for months
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext und
     * einem Platzhalter "{0}" für die Anzahl der Monate. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for months
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getMonthPattern(
        Locale lang,
        TextWidth width,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of weeks. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for weeks
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext und
     * einem Platzhalter "{0}" für die Anzahl der Wochen. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for weeks
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getWeekPattern(
        Locale lang,
        TextWidth width,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of days. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for days
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext und
     * einem Platzhalter "{0}" für die Anzahl der Tage. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for days
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getDayPattern(
        Locale lang,
        TextWidth width,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of hours. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for hours
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext und
     * einem Platzhalter "{0}" für die Anzahl der Stunden. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for hours
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getHourPattern(
        Locale lang,
        TextWidth width,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of minutes. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for minutes
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext und
     * einem Platzhalter "{0}" für die Anzahl der Minuten. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for minutes
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getMinutePattern(
        Locale lang,
        TextWidth width,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of seconds. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for seconds
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext und
     * einem Platzhalter "{0}" für die Anzahl der Sekunden. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for seconds
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getSecondPattern(
        Locale lang,
        TextWidth width,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of milliseconds. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for milliseconds
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext
     * und einem Platzhalter "{0}" für die Anzahl der
     * Millisekunden. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for milliseconds
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getMilliPattern(
        Locale lang,
        TextWidth width,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of microseconds. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for microseconds
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext
     * und einem Platzhalter "{0}" für die Anzahl der
     * Mikrosekunden. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for microseconds
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getMicroPattern(
        Locale lang,
        TextWidth width,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of nanoseconds. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for nanoseconds
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext
     * und einem Platzhalter "{0}" für die Anzahl der
     * Nanosekunden. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   category    plural category
     * @return  unit pattern for nanoseconds
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getNanoPattern(
        Locale lang,
        TextWidth width,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of years in the past or future. 
     *
     * @param   lang        language setting
     * @param   future      use future or past form
     * @param   category    plural category
     * @return  unit pattern for years in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext und
     * einem Platzhalter "{0}" für die Anzahl der Jahre in der
     * Vergangenheit oder Zukunft. 
     *
     * @param   lang        language setting
     * @param   future      use future or past form
     * @param   category    plural category
     * @return  unit pattern for years in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getYearPattern(
        Locale lang,
        boolean future,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of months in the past or future. 
     *
     * @param   lang        language setting
     * @param   future      use future or past form
     * @param   category    plural category
     * @return  unit pattern for months in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext und
     * einem Platzhalter "{0}" für die Anzahl der Monate in
     * der Vergangenheit oder Zukunft. 
     *
     * @param   lang        language setting
     * @param   future      use future or past form
     * @param   category    plural category
     * @return  unit pattern for months in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getMonthPattern(
        Locale lang,
        boolean future,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of weeks in the past or future. 
     *
     * @param   lang        language setting
     * @param   future      use future or past form
     * @param   category    plural category
     * @return  unit pattern for weeks in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext und
     * einem Platzhalter "{0}" für die Anzahl der Wochen in
     * der Vergangenheit oder Zukunft. 
     *
     * @param   lang        language setting
     * @param   future      use future or past form
     * @param   category    plural category
     * @return  unit pattern for weeks in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getWeekPattern(
        Locale lang,
        boolean future,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of days in the past or future. 
     *
     * @param   lang        language setting
     * @param   future      use future or past form
     * @param   category    plural category
     * @return  unit pattern for days in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext und
     * einem Platzhalter "{0}" für die Anzahl der Tage in der
     * Vergangenheit oder Zukunft. 
     *
     * @param   lang        language setting
     * @param   future      use future or past form
     * @param   category    plural category
     * @return  unit pattern for days in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getDayPattern(
        Locale lang,
        boolean future,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of hours in the past or future. 
     *
     * @param   lang        language setting
     * @param   future      use future or past form
     * @param   category    plural category
     * @return  unit pattern for hours in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext und
     * einem Platzhalter "{0}" für die Anzahl der Stunden in
     * der Vergangenheit oder Zukunft. 
     *
     * @param   lang        language setting
     * @param   future      use future or past form
     * @param   category    plural category
     * @return  unit pattern for hours in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getHourPattern(
        Locale lang,
        boolean future,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of minutes in the past or future. 
     *
     * @param   lang        language setting
     * @param   future      use future or past form
     * @param   category    plural category
     * @return  unit pattern for minutes in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext und
     * einem Platzhalter "{0}" für die Anzahl der Minuten in
     * der Vergangenheit oder Zukunft. 
     *
     * @param   lang        language setting
     * @param   future      use future or past form
     * @param   category    plural category
     * @return  unit pattern for minutes in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getMinutePattern(
        Locale lang,
        boolean future,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with unit name and a placeholder
     * "{0}" for the count of seconds in the past or future. 
     *
     * @param   lang        language setting
     * @param   future      use future or past form
     * @param   category    plural category
     * @return  unit pattern for seconds in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit Zeiteinheitstext und
     * einem Platzhalter "{0}" für die Anzahl der Sekunden in
     * der Vergangenheit oder Zukunft. 
     *
     * @param   lang        language setting
     * @param   future      use future or past form
     * @param   category    plural category
     * @return  unit pattern for seconds in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getSecondPattern(
        Locale lang,
        boolean future,
        PluralCategory category
    );

    /**
     * Yields the localized word for the current time (now). 
     *
     * @param   lang    language setting
     * @return  String
     * @throws  java.util.MissingResourceException if not found
     * @since   1.2
     */
    /*[deutsch]
     * Liefert das lokalisierte Wort für die aktuelle Zeit
     * (jetzt). 
     *
     * @param   lang    language setting
     * @return  String
     * @throws  java.util.MissingResourceException if not found
     * @since   1.2
     */
    String getNowWord(Locale lang);

    /**
     * Constructs a localized list pattern suitable for the use in
     * {@link java.text.MessageFormat#format(String, Object[])}. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   size        count of list items
     * @return  message format pattern with placeholders {0}, {1}, ..., {x}, ...
     * @throws  IllegalArgumentException if size is smaller than 2
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    /*[deutsch]
     * Konstruiert ein lokalisiertes Listenformat geeignet für
     * {@link java.text.MessageFormat#format(String, Object[])}. 
     *
     * @param   lang        language setting
     * @param   width       text width (ABBREVIATED as synonym for SHORT)
     * @param   size        count of list items
     * @return  message format pattern with placeholders {0}, {1}, ..., {x}, ...
     * @throws  IllegalArgumentException if size is smaller than 2
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   1.2
     */
    String getListPattern(
        Locale lang,
        TextWidth width,
        int size
    );

}