net.time4j.format.RelativeTimeProvider 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 (RelativeTimeProvider.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 RelativeTimeProvider} then Time4J will use
 * an internal implementation which just offers unit patterns either in
 * english or in scientific notation. 
 *
 * Note: This interface enhances the standard {@code UnitPatternProvider} by
 * new methods for short/abbreviated relative times and extra words for
 * "yesterday-today-tomorrow". 
 *
 * @author  Meno Hochschild
 * @since   3.6/4.4
 * @see     java.util.ServiceLoader
 * @doctags.spec    Implementations must have a public no-arg constructor.
 */
/*[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. 
 *
 * Note: Dieses Interface erweitert den Standard {@code UnitPatternProvider} um
 * neue Methoden für abgekürzte relative Zeiten und extra Wörter für
 * "gestern-heute-morgen". 
 *
 * @author  Meno Hochschild
 * @since   3.6/4.4
 * @see     java.util.ServiceLoader
 * @doctags.spec    Implementations must have a public no-arg constructor.
 */
public interface RelativeTimeProvider
    extends UnitPatternProvider {

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

    /**
     * Yields the localized unit pattern with short 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 short years in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   3.6/4.4
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit kurzem 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 short years in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   3.6/4.4
     */
    String getShortYearPattern(
        Locale lang,
        boolean future,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with short 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 short months in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   3.6/4.4
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit kurzem 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 short months in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   3.6/4.4
     */
    String getShortMonthPattern(
        Locale lang,
        boolean future,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with short 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 short weeks in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   3.6/4.4
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit kurzem 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 short weeks in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   3.6/4.4
     */
    String getShortWeekPattern(
        Locale lang,
        boolean future,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with short 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 short days in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   3.6/4.4
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit kurzem 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 short days in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   3.6/4.4
     */
    String getShortDayPattern(
        Locale lang,
        boolean future,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with short 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 short hours in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   3.6/4.4
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit kurzem 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 short hours in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   3.6/4.4
     */
    String getShortHourPattern(
        Locale lang,
        boolean future,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with short 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 short minutes in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   3.6/4.4
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit kurzem 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 short minutes in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   3.6/4.4
     */
    String getShortMinutePattern(
        Locale lang,
        boolean future,
        PluralCategory category
    );

    /**
     * Yields the localized unit pattern with short 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 short seconds in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   3.6/4.4
     */
    /*[deutsch]
     * Liefert das lokalisierte Zeiteinheitsmuster mit kurzem 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 short seconds in the past or future
     * @throws  java.util.MissingResourceException if no pattern was found
     * @since   3.6/4.4
     */
    String getShortSecondPattern(
        Locale lang,
        boolean future,
        PluralCategory category
    );

    /**
     * Yields the localized word for "yesterday". 
     *
     * @param   lang    language setting
     * @return  String
     * @throws  java.util.MissingResourceException if not found
     * @since   3.6/4.4
     */
    /*[deutsch]
     * Liefert das lokalisierte Wort für den gestrigen Tag. 
     *
     * @param   lang    language setting
     * @return  String
     * @throws  java.util.MissingResourceException if not found
     * @since   3.6/4.4
     */
    String getYesterdayWord(Locale lang);

    /**
     * Yields the localized word for "today". 
     *
     * @param   lang    language setting
     * @return  String
     * @throws  java.util.MissingResourceException if not found
     * @since   3.6/4.4
     */
    /*[deutsch]
     * Liefert das lokalisierte Wort für den heutigen Tag. 
     *
     * @param   lang    language setting
     * @return  String
     * @throws  java.util.MissingResourceException if not found
     * @since   3.6/4.4
     */
    String getTodayWord(Locale lang);

    /**
     * Yields the localized word for "tomorrow". 
     *
     * @param   lang    language setting
     * @return  String
     * @throws  java.util.MissingResourceException if not found
     * @since   3.6/4.4
     */
    /*[deutsch]
     * Liefert das lokalisierte Wort für den morgigen Tag. 
     *
     * @param   lang    language setting
     * @return  String
     * @throws  java.util.MissingResourceException if not found
     * @since   3.6/4.4
     */
    String getTomorrowWord(Locale lang);

}