001/*
002 * Copyright 2002-2019 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.context;
018
019import java.util.Locale;
020
021/**
022 * Strategy interface for resolving messages, with support for the parameterization
023 * and internationalization of such messages.
024 *
025 * <p>Spring provides two out-of-the-box implementations for production:
026 * <ul>
027 * <li>{@link org.springframework.context.support.ResourceBundleMessageSource}: built
028 * on top of the standard {@link java.util.ResourceBundle}, sharing its limitations.
029 * <li>{@link org.springframework.context.support.ReloadableResourceBundleMessageSource}:
030 * highly configurable, in particular with respect to reloading message definitions.
031 * </ul>
032 *
033 * @author Rod Johnson
034 * @author Juergen Hoeller
035 * @see org.springframework.context.support.ResourceBundleMessageSource
036 * @see org.springframework.context.support.ReloadableResourceBundleMessageSource
037 */
038public interface MessageSource {
039
040        /**
041         * Try to resolve the message. Return default message if no message was found.
042         * @param code the message code to look up, e.g. 'calculator.noRateSet'.
043         * MessageSource users are encouraged to base message names on qualified class
044         * or package names, avoiding potential conflicts and ensuring maximum clarity.
045         * @param args an array of arguments that will be filled in for params within
046         * the message (params look like "{0}", "{1,date}", "{2,time}" within a message),
047         * or {@code null} if none
048         * @param defaultMessage a default message to return if the lookup fails
049         * @param locale the locale in which to do the lookup
050         * @return the resolved message if the lookup was successful, otherwise
051         * the default message passed as a parameter (which may be {@code null})
052         * @see #getMessage(MessageSourceResolvable, Locale)
053         * @see java.text.MessageFormat
054         */
055        String getMessage(String code, Object[] args, String defaultMessage, Locale locale);
056
057        /**
058         * Try to resolve the message. Treat as an error if the message can't be found.
059         * @param code the message code to look up, e.g. 'calculator.noRateSet'.
060         * MessageSource users are encouraged to base message names on qualified class
061         * or package names, avoiding potential conflicts and ensuring maximum clarity.
062         * @param args an array of arguments that will be filled in for params within
063         * the message (params look like "{0}", "{1,date}", "{2,time}" within a message),
064         * or {@code null} if none
065         * @param locale the locale in which to do the lookup
066         * @return the resolved message (never {@code null})
067         * @throws NoSuchMessageException if no corresponding message was found
068         * @see #getMessage(MessageSourceResolvable, Locale)
069         * @see java.text.MessageFormat
070         */
071        String getMessage(String code, Object[] args, Locale locale) throws NoSuchMessageException;
072
073        /**
074         * Try to resolve the message using all the attributes contained within the
075         * {@code MessageSourceResolvable} argument that was passed in.
076         * <p>NOTE: We must throw a {@code NoSuchMessageException} on this method
077         * since at the time of calling this method we aren't able to determine if the
078         * {@code defaultMessage} property of the resolvable is {@code null} or not.
079         * @param resolvable the value object storing attributes required to resolve a message
080         * (may include a default message)
081         * @param locale the locale in which to do the lookup
082         * @return the resolved message (never {@code null} since even a
083         * {@code MessageSourceResolvable}-provided default message needs to be non-null)
084         * @throws NoSuchMessageException if no corresponding message was found
085         * (and no default message was provided by the {@code MessageSourceResolvable})
086         * @see MessageSourceResolvable#getCodes()
087         * @see MessageSourceResolvable#getArguments()
088         * @see MessageSourceResolvable#getDefaultMessage()
089         * @see java.text.MessageFormat
090         */
091        String getMessage(MessageSourceResolvable resolvable, Locale locale) throws NoSuchMessageException;
092
093}