myfaces-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sless...@apache.org
Subject svn commit: r763448 - /myfaces/core/branches/2_0_0/api/src/main/java/javax/faces/application/FacesMessage.java
Date Wed, 08 Apr 2009 23:05:24 GMT
Author: slessard
Date: Wed Apr  8 23:05:24 2009
New Revision: 763448

URL: http://svn.apache.org/viewvc?rev=763448&view=rev
Log:
MYFACES-2036 - Comment on javax.faces.application.FacesMessage Class

Modified:
    myfaces/core/branches/2_0_0/api/src/main/java/javax/faces/application/FacesMessage.java

Modified: myfaces/core/branches/2_0_0/api/src/main/java/javax/faces/application/FacesMessage.java
URL: http://svn.apache.org/viewvc/myfaces/core/branches/2_0_0/api/src/main/java/javax/faces/application/FacesMessage.java?rev=763448&r1=763447&r2=763448&view=diff
==============================================================================
--- myfaces/core/branches/2_0_0/api/src/main/java/javax/faces/application/FacesMessage.java
(original)
+++ myfaces/core/branches/2_0_0/api/src/main/java/javax/faces/application/FacesMessage.java
Wed Apr  8 23:05:24 2009
@@ -22,22 +22,68 @@
 import java.util.*;
 
 /**
- * see Javadoc of <a href="http://java.sun.com/javaee/javaserverfaces/1.2/docs/api/index.html">JSF
Specification</a>
+ *see Javadoc of <a href="http://java.sun.com/javaee/javaserverfaces/1.2/docs/api/index.html">JSF
Specification</a>
+ *<p><code>FacesMessage</code> represents a single validation (or other)
message, which is typically associated with a 
+ *particular component in the view. A {@link FacesMessage} instance may be created based
on a specific messageId. 
+ *The specification defines the set of messageIds for which there must be {@link FacesMessage}
instances.</p>
  *
+ *<ui>The implementation must take the following steps when creating FacesMessage instances
given a messageId:
+ *    <li>Call {@link Application.getMessageBundle()}. If <code>non-null</code>,
locate the named <code>ResourceBundle</code>, using the 
+ *    <code>Locale</code> from the current {@linkUIViewRoot} and see if it has
a value for the argument <code>messageId</code>. 
+ *    If it does, treat the value as the <code>summary</code> of the {@link FacesMessage}.
If it does not, or if 
+ *    {@link Application.getMessageBundle()} returned null, look in the ResourceBundle named
by the value of the constant 
+ *    {@link FACES_MESSAGES} and see if it has a value for the argument messageId. If it
does, treat the value as the 
+ *    summary of the <code>FacesMessage</code>. If it does not, there is no initialization
information for the <code>FacesMessage</code> 
+ *    instance.
+ *    </li>
+ *    <li>In all cases, if a <code>ResourceBundle</code> hit is found for
the <code>{messageId}</code>, look for further hits under 
+ *    the key <code>{messageId}_detail</code>. Use this value, if present, as
the <code>detail</code> for the returned <code>FacesMessage</code>.
+ *    </li>
+ *    <li>Make sure to perform any parameter substitution required for the <code>summary</code>
and <code>detail</code> of the 
+ *    <code>FacesMessage</code>.
+ *    </li>
+ *</ui>
  * @author Manfred Geiler (latest modification by $Author$)
  * @version $Revision$ $Date$
+ * 
  */
 public class FacesMessage implements Serializable
 {
     private static final long serialVersionUID = 4851488727794169661L;
 
+    /**
+     * <code>ResourceBundle</code> identifier for messages whose message identifiers
are defined in the JavaServer Faces specification.
+     */
     public static final String FACES_MESSAGES = "javax.faces.Messages";
 
+    /**
+     * Message severity level indicating an informational message rather than an error.
+     */
     public static final FacesMessage.Severity SEVERITY_INFO = new Severity("Info", 1);
+    
+    /**
+     * Message severity level indicating that an error might have occurred.
+     */
     public static final FacesMessage.Severity SEVERITY_WARN = new Severity("Warn", 2);
+    
+    /**
+     * Message severity level indicating that an error has occurred.
+     */
     public static final FacesMessage.Severity SEVERITY_ERROR = new Severity("Error", 3);
+    
+    /**
+     * Message severity level indicating that a serious error has occurred.
+     */
     public static final FacesMessage.Severity SEVERITY_FATAL = new Severity("Fatal", 4);
+    
+    /**
+     * Immutable <code>Lis</code> of valid {@link FacesMessage.Severity}instances,
in ascending order of their ordinal value.
+     */
     public static final List<FacesMessage.Severity> VALUES;
+    
+    /**
+     * Immutable <code>Map</code> of valid {@link FacesMessage.Severity}instances,
keyed by name.
+     */
     public static final Map<String, FacesMessage.Severity> VALUES_MAP;
     
     static
@@ -55,17 +101,29 @@
     private String _summary;
     private String _detail;
 
+    /**
+     *Construct a new {@link FacesMessage} with no initial values. The severity is set to
Severity.INFO.
+     */
     public FacesMessage()
     {
         _severity = SEVERITY_INFO;
     }
 
+    /**
+     * Construct a new {@link FacesMessage} with just a summary. The detail is null, the
severity is set to 
+     * <code>Severity.INFO</code>.
+     */
     public FacesMessage(String summary)
     {
         _summary = summary;
         _severity = SEVERITY_INFO;
     }
 
+    /**
+     * Construct a new {@link FacesMessage} with the specified initial values. The severity
is set to Severity.INFO.
+     * @param summary - Localized summary message text
+     * @param detail - Localized detail message text 
+     */
     public FacesMessage(String summary, String detail)
     {
         _summary = summary;
@@ -73,6 +131,12 @@
         _severity = SEVERITY_INFO;
     }
 
+    /**
+     * Construct a new {@link FacesMessage}with the specified initial values.
+     * @param severity- the severity
+     * @param summary- Localized summary message text
+     * @param detail- Localized detail message text 
+     */
     public FacesMessage(FacesMessage.Severity severity,
                         String summary,
                         String detail)
@@ -83,27 +147,45 @@
         _detail = detail;
     }
 
+    /**
+     * 
+     * @return
+     */
     public FacesMessage.Severity getSeverity()
     {
         return _severity;
     }
 
+    /**
+     * Return the severity level.
+     */
     public void setSeverity(FacesMessage.Severity severity)
     {
         if(severity == null) throw new NullPointerException("severity");
         _severity = severity;
     }
 
+    /**
+     * Return the localized summary text.
+     */
     public String getSummary()
     {
         return _summary;
     }
 
+    /**
+     * Set the localized summary text.
+     * @param summary- The new localized summary text
+     */
     public void setSummary(String summary)
     {
         _summary = summary;
     }
 
+    /**
+     * 
+     * @return
+     */
     public String getDetail()
     {
         if (_detail == null)
@@ -115,6 +197,10 @@
         return _detail;
     }
 
+    /**
+     * Set the localized detail text.
+     * @param detail - The new localized detail text
+     */
     public void setDetail(String detail)
     {
         _detail = detail;



Mime
View raw message