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 021import org.springframework.lang.Nullable; 022 023/** 024 * Strategy interface for resolving messages, with support for the parameterization 025 * and internationalization of such messages. 026 * 027 * <p>Spring provides two out-of-the-box implementations for production: 028 * <ul> 029 * <li>{@link org.springframework.context.support.ResourceBundleMessageSource}: built 030 * on top of the standard {@link java.util.ResourceBundle}, sharing its limitations. 031 * <li>{@link org.springframework.context.support.ReloadableResourceBundleMessageSource}: 032 * highly configurable, in particular with respect to reloading message definitions. 033 * </ul> 034 * 035 * @author Rod Johnson 036 * @author Juergen Hoeller 037 * @see org.springframework.context.support.ResourceBundleMessageSource 038 * @see org.springframework.context.support.ReloadableResourceBundleMessageSource 039 */ 040public interface MessageSource { 041 042 /** 043 * Try to resolve the message. Return default message if no message was found. 044 * @param code the message code to look up, e.g. 'calculator.noRateSet'. 045 * MessageSource users are encouraged to base message names on qualified class 046 * or package names, avoiding potential conflicts and ensuring maximum clarity. 047 * @param args an array of arguments that will be filled in for params within 048 * the message (params look like "{0}", "{1,date}", "{2,time}" within a message), 049 * or {@code null} if none 050 * @param defaultMessage a default message to return if the lookup fails 051 * @param locale the locale in which to do the lookup 052 * @return the resolved message if the lookup was successful, otherwise 053 * the default message passed as a parameter (which may be {@code null}) 054 * @see #getMessage(MessageSourceResolvable, Locale) 055 * @see java.text.MessageFormat 056 */ 057 @Nullable 058 String getMessage(String code, @Nullable Object[] args, @Nullable String defaultMessage, Locale locale); 059 060 /** 061 * Try to resolve the message. Treat as an error if the message can't be found. 062 * @param code the message code to look up, e.g. 'calculator.noRateSet'. 063 * MessageSource users are encouraged to base message names on qualified class 064 * or package names, avoiding potential conflicts and ensuring maximum clarity. 065 * @param args an array of arguments that will be filled in for params within 066 * the message (params look like "{0}", "{1,date}", "{2,time}" within a message), 067 * or {@code null} if none 068 * @param locale the locale in which to do the lookup 069 * @return the resolved message (never {@code null}) 070 * @throws NoSuchMessageException if no corresponding message was found 071 * @see #getMessage(MessageSourceResolvable, Locale) 072 * @see java.text.MessageFormat 073 */ 074 String getMessage(String code, @Nullable Object[] args, Locale locale) throws NoSuchMessageException; 075 076 /** 077 * Try to resolve the message using all the attributes contained within the 078 * {@code MessageSourceResolvable} argument that was passed in. 079 * <p>NOTE: We must throw a {@code NoSuchMessageException} on this method 080 * since at the time of calling this method we aren't able to determine if the 081 * {@code defaultMessage} property of the resolvable is {@code null} or not. 082 * @param resolvable the value object storing attributes required to resolve a message 083 * (may include a default message) 084 * @param locale the locale in which to do the lookup 085 * @return the resolved message (never {@code null} since even a 086 * {@code MessageSourceResolvable}-provided default message needs to be non-null) 087 * @throws NoSuchMessageException if no corresponding message was found 088 * (and no default message was provided by the {@code MessageSourceResolvable}) 089 * @see MessageSourceResolvable#getCodes() 090 * @see MessageSourceResolvable#getArguments() 091 * @see MessageSourceResolvable#getDefaultMessage() 092 * @see java.text.MessageFormat 093 */ 094 String getMessage(MessageSourceResolvable resolvable, Locale locale) throws NoSuchMessageException; 095 096}