+ * Usage example: *
* new MessageBuilder().
* severity(Severity.ERROR).
- * code("invalidFormat").
- * arg("mathForm.decimalField").
- * arg("#,###.##").
- * defaultText("The decimal field must be in format #,###.##").
+ * code("invalidFormat").
+ * resolvableArg("label", "mathForm.decimalField").
+ * arg("format", "#,###.##").
+ * defaultText("The decimal field must be in format #,###.##").
* build();
*
- *
+ * Example messages.properties loaded by the MessageSource:
+ *
+ * invalidFormat=The #{label} must be in format #{format}.
+ * mathForm.decimalField=Decimal Field
+ *
* @author Keith Donald
+ * @see MessageContext#add(MessageResolver, String)
*/
public class MessageBuilder {
@@ -70,9 +72,9 @@ public class MessageBuilder {
}
/**
- * Add a message code to use to resolve the message text.
+ * Add a code to use to resolve the template for generating the localized message text.
* Successive calls to this method add additional codes.
- * Codes are applied in the order they are added.
+ * Codes are tried in the order they are added.
* @param code the message code
* @return this, for fluent API usage
*/
@@ -82,8 +84,10 @@ public class MessageBuilder {
}
/**
- * Add a message argument.
- * Successive calls to this method add additional args.
+ * Add a message argument to insert into the message text.
+ * Named message arguments are inserted by eval expressions denoted within the resolved message template.
+ * For example, the value of the 'format' argument would be inserted where a corresponding #{format} expression is defined in the message template.
+ * Successive calls to this method add additional arguments.
* @param name the argument name
* @param value the argument value
* @return this, for fluent API usage
@@ -94,14 +98,14 @@ public class MessageBuilder {
}
/**
- * Add a message argument whose value is a resolvable message code.
- * Successive calls to this method add additional resolvable arguements.
+ * Add a message argument to insert into the message text, where the actual value to be inserted should be resolved by the {@link MessageSource}.
+ * Successive calls to this method add additional resolvable arguments.
* @param name the argument name
- * @param value the argument value
+ * @param code the code to use to resolve the argument value
* @return this, for fluent API usage
*/
- public MessageBuilder resolvableArg(String name, Object value) {
- args.put(name, new ResolvableArgumentValue(value));
+ public MessageBuilder resolvableArg(String name, Object code) {
+ args.put(name, new ResolvableArgumentValue(code));
return this;
}
@@ -135,12 +139,12 @@ public class MessageBuilder {
return new DefaultMessageResolver(severity, codesArray, args, defaultText, expressionParser);
}
- static class ResolvableArgumentValue implements MessageSourceResolvable {
+ private static class ResolvableArgumentValue implements MessageSourceResolvable {
- private Object value;
+ private Object code;
- public ResolvableArgumentValue(Object value) {
- this.value = value;
+ public ResolvableArgumentValue(Object code) {
+ this.code = code;
}
public Object[] getArguments() {
@@ -148,15 +152,15 @@ public class MessageBuilder {
}
public String[] getCodes() {
- return new String[] { value.toString() };
+ return new String[] { code.toString() };
}
public String getDefaultMessage() {
- return String.valueOf(value);
+ return String.valueOf(code);
}
public String toString() {
- return new ToStringCreator(this).append("value", value).toString();
+ return new ToStringCreator(this).append("code", code).toString();
}
}
diff --git a/org.springframework.context/src/main/java/org/springframework/ui/message/MessageResolutionException.java b/org.springframework.context/src/main/java/org/springframework/ui/message/MessageResolutionException.java
index a8a8d9c0973..39a418575e9 100644
--- a/org.springframework.context/src/main/java/org/springframework/ui/message/MessageResolutionException.java
+++ b/org.springframework.context/src/main/java/org/springframework/ui/message/MessageResolutionException.java
@@ -1,7 +1,32 @@
+/*
+ * Copyright 2004-2009 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
package org.springframework.ui.message;
+/**
+ * Runtime exception thrown by a {@link MessageResolver} if a message resolution fails.
+ * @author Keith Donald
+ */
+@SuppressWarnings("serial")
public class MessageResolutionException extends RuntimeException {
+ /**
+ * Creates a new message resolution exception.
+ * @param message a messaging describing the failure
+ * @param cause the cause of the failure
+ */
public MessageResolutionException(String message, Throwable cause) {
super(message, cause);
}
diff --git a/org.springframework.context/src/main/java/org/springframework/ui/message/MessageResolver.java b/org.springframework.context/src/main/java/org/springframework/ui/message/MessageResolver.java
index b8113562b9e..38bebae2125 100644
--- a/org.springframework.context/src/main/java/org/springframework/ui/message/MessageResolver.java
+++ b/org.springframework.context/src/main/java/org/springframework/ui/message/MessageResolver.java
@@ -20,9 +20,7 @@ import java.util.Locale;
import org.springframework.context.MessageSource;
/**
- * A factory for a Message. Allows a Message to be internationalized and to be resolved from a
- * {@link MessageSource message resource bundle}.
- *
+ * A factory for a localized Message.
* @author Keith Donald
* @see Message
* @see MessageSource
@@ -30,10 +28,11 @@ import org.springframework.context.MessageSource;
public interface MessageResolver {
/**
- * Resolve the message from the message source using the current locale.
+ * Resolve the message from the message source for the locale.
* @param messageSource the message source, an abstraction for a resource bundle
- * @param locale the current locale of this request
+ * @param locale the locale of this request
* @return the resolved message
+ * @throws MessageResolutionException if a resolution failure occurs
*/
public Message resolveMessage(MessageSource messageSource, Locale locale);
}