Commits

Anonymous committed ea2f45e

Comments (0)

Files changed (3)

src/java/com/opensymphony/xwork/LocaleProvider.java

 
 
 /**
- * LocaleProvider
+ * Indicates that the implementing class can provide its own {@link Locale}. This
+ * is useful for when an action may wish override the default locale. All that is
+ * needed is to implement this interface and return your own custom locale.
+ * The {@link TextProvider} interface uses this interface heavily for retrieving
+ * internationalized messages from resource bundles.
+ *
  * @author Jason Carreira
  * Date: Oct 29, 2003 9:11:22 PM
  */

src/java/com/opensymphony/xwork/TextProvider.java

 
 
 /**
- * TextProvider
+ * Provides access to {@link ResourceBundle}s and their underlying text messages.
+ * Implementing classes can delegate {@link TextProviderSupport}. Messages will be
+ * searched in multiple resource bundles, starting with the one associated with
+ * this particular class (action in most cases), continuing to try the message
+ * bundle associated with each superclass as well. It will stop once a bundle is
+ * found that contains the given text. This gives a cascading style that allow
+ * global texts to be defined for an application base class.
+ *
+ * You can override {@link LocaleProvider#getLocale()} to change the behaviour of how
+ * to choose locale for the bundles that are returned. Typically you would
+ * use the {@link LocaleProvider} interface to get the users configured locale.
+ *
+ * @see LocaleProvider
+ * @see TextProviderSupport
  * @author Jason Carreira
  * Created Feb 10, 2003 9:55:48 AM
  */
     //~ Methods ////////////////////////////////////////////////////////////////
 
     /**
-     * Get a text from the resource bundles associated with this action.
-     * The resource bundles are searched, starting with the one associated
-     * with this particular action, and testing all its superclasses' bundles.
-     * It will stop once a bundle is found that contains the given text. This gives
-     * a cascading style that allow global texts to be defined for an application base
-     * class.
+     * Gets a message based on a message key, or null if no message is found.
      *
-     * @param   aTextName  name of text to be found
-     * @return     value of named text
+     * @param key the resource bundle key that is to be searched for
+     * @return the message as found in the resource bundle, or null if none is found.
      */
-    String getText(String aTextName);
+    String getText(String key);
 
     /**
-     * Get a text from the resource bundles associated with this action.
-     * The resource bundles are searched, starting with the one associated
-     * with this particular action, and testing all its superclasses' bundles.
-     * It will stop once a bundle is found that contains the given text. This gives
-     * a cascading style that allow global texts to be defined for an application base
-     * class. If no text is found for this text name, the default value is returned.
+     * Gets a message based on a key, or, if the message is not found, a supplied
+     * default value is returned.
      *
-     * @param   aTextName  name of text to be found
-     * @param   defaultValue the default value which will be returned if no text is found
-     * @return     value of named text
+     * @param key the resource bundle key that is to be searched for
+     * @param defaultValue the default value which will be returned if no message is found
+     * @return the message as found in the resource bundle, or defaultValue if none is found
      */
-    String getText(String aTextName, String defaultValue);
+    String getText(String key, String defaultValue);
 
     /**
-     * Get a text from the resource bundles associated with this action.
-     * The resource bundles are searched, starting with the one associated
-     * with this particular action, and testing all its superclasses' bundles.
-     * It will stop once a bundle is found that contains the given text. This gives
-     * a cascading style that allow global texts to be defined for an application base
-     * class. If no text is found for this text name, the default value is returned.
+     * Gets a message based on a key using the supplied args, as defined in
+     * {@link java.text.MessageFormat}, or null if no message is found.
      *
-     * @param   aTextName  name of text to be found
-     * @param   args a List of args to be used in a MessageFormat message
-     * @return     value of named text
+     * @param key the resource bundle key that is to be searched for
+     * @param args a list args to be used in a {@link java.text.MessageFormat} message
+     * @return the message as found in the resource bundle, or null if none is found.
      */
-    String getText(String aTextName, List args);
+    String getText(String key, List args);
 
     /**
-     * Get a text from the resource bundles associated with this action.
-     * The resource bundles are searched, starting with the one associated
-     * with this particular action, and testing all its superclasses' bundles.
-     * It will stop once a bundle is found that contains the given text. This gives
-     * a cascading style that allow global texts to be defined for an application base
-     * class. If no text is found for this text name, the default value is returned.
+     * Gets a message based on a key using the supplied args, as defined in
+     * {@link java.text.MessageFormat}, or, if the message is not found, a supplied
+     * default value is returned.
      *
-     * @param   aTextName  name of text to be found
-     * @param   defaultValue the default value which will be returned if no text is found
-     * @param   args a List of args to be used in a MessageFormat message
-     * @return     value of named text
+     * @param key the resource bundle key that is to be searched for
+     * @param defaultValue the default value which will be returned if no message is found
+     * @param args a list args to be used in a {@link java.text.MessageFormat} message
+     * @return the message as found in the resource bundle, or defaultValue if none is found
      */
-    String getText(String aTextName, String defaultValue, List args);
+    String getText(String key, String defaultValue, List args);
 
     /**
-    * Get the named bundle.
+    * Get the named bundle, such as "com/acme/Foo".
     *
-    * You can override the getLocale() methodName to change the behaviour of how
-    * to choose locale for the bundles that are returned. Typically you would
-    * use the TextProvider interface to get the users configured locale, or use
-    * your own methodName to allow the user to select the locale and store it in
-    * the session (by using the SessionAware interface).
-    *
-    * @param   aBundleName  bundle name
-    * @return     a resource bundle
+    * @param bundleName the name of the resource bundle, such as "com/acme/Foo"
     */
-    ResourceBundle getTexts(String aBundleName);
+    ResourceBundle getTexts(String bundleName);
 
     /**
-    * Get the resource bundle associated with this action.
-    * This will be based on the actual subclass that is used.
-    *
-    * @return     resouce bundle
+    * Get the resource bundle associated with the implementing class (usually an action).
     */
     ResourceBundle getTexts();
 }

src/java/com/opensymphony/xwork/ValidationAware.java

  * ValidationAware classes can accept Action (class level) or field level error messages. Action level messages are kept
  * in a Collection. Field level error messages are kept in a Map from String field name to a List of field error msgs.
  *
- * @author $author$
+ * @author $Author$
  * @version $Revision$
  */
 public interface ValidationAware extends Serializable {