IMessageConveyor xref

View Javadoc

    1   /*
    2    * Copyright (c) 2009 QOS.ch All rights reserved.
    3    *
    4    * Permission is hereby granted, free of charge, to any person obtaining a copy
    5    * of this software and associated documentation files (the "Software"), to deal
    6    * in the Software without restriction, including without limitation the rights
    7    * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    8    * copies of the Software, and to permit persons to whom the Software is
    9    * furnished to do so, subject to the following conditions:
    10   *
    11   * The above copyright notice and this permission notice shall be included in
    12   * all copies or substantial portions of the Software.
    13   *
    14   * THE SOFTWARE IS PROVIDED "AS  IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    15   * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    16   * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    17   * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    18   * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    19   * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    20   * SOFTWARE.
    21   */
    22
    23  package ch.qos.cal10n;
    24
    25  import java.text.MessageFormat;
    26
    27  // note that the getMessage method does not take a Locale.
    28  // It is supposed that the MessageConveyor instance knows
    29  // which locale to use.
    30
    31  /**
    32   * Retrieve a localized message by its key as specified by an enum.
    33   *
    34   * <p>
    35   * The strategy in retrieving messages may vary from implementation to
    36   * implementation.
    37   *
    38   * @author Ceki G&uuml;lc&uuml;
    39   */
    40  public interface IMessageConveyor {
    41
    42    /**
    43     * Retrieve a localized message by its key as specified by an enum.
    44     *
    45     * <p>
    46     * Note that any further arguments passed in 'args' will be interpolated using
    47     * the translated message. The interpolation will be done by and according to
    48     * conventions of {@link MessageFormat}.
    49     *
    50     * @param <E>
    51     *          an enum type
    52     * @param key
    53     *          an enum instance
    54     * @param args
    55     *          optional arguments
    56     * @return The translated/localized message
    57     */
    58    <E extends Enum<?>> String getMessage(E key, Object... args) throws MessageConveyorException;
    59
    60    /**
    61     * Syntactic sugar for the case where the massage is contained in a
    62     * {@link MessageParameterObj}.
    63     *
    64     * <p>
    65     * Equivalent to calling
    66     *
    67     * <pre>
    68     * getMessage(mpo.getKey(), mpo.getArgs());
    69     * </pre>
    70     *
    71     * @see #getMessage(Enum, Object...)
    72     * @param mpo
    73     *          The MessageParameterObj to translate
    74     * @return translated message
    75     */
    76    String getMessage(MessageParameterObj mpo) throws MessageConveyorException;
    77  }