commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mben...@apache.org
Subject svn commit: r631256 - in /commons/proper/lang/trunk/src/java/org/apache/commons/lang/text: ExtendedMessageFormat.java FormatFactory.java
Date Tue, 26 Feb 2008 15:36:56 GMT
Author: mbenson
Date: Tue Feb 26 07:36:55 2008
New Revision: 631256

URL: http://svn.apache.org/viewvc?rev=631256&view=rev
Log:
improve documentation

Modified:
    commons/proper/lang/trunk/src/java/org/apache/commons/lang/text/ExtendedMessageFormat.java
    commons/proper/lang/trunk/src/java/org/apache/commons/lang/text/FormatFactory.java

Modified: commons/proper/lang/trunk/src/java/org/apache/commons/lang/text/ExtendedMessageFormat.java
URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/java/org/apache/commons/lang/text/ExtendedMessageFormat.java?rev=631256&r1=631255&r2=631256&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/java/org/apache/commons/lang/text/ExtendedMessageFormat.java
(original)
+++ commons/proper/lang/trunk/src/java/org/apache/commons/lang/text/ExtendedMessageFormat.java
Tue Feb 26 07:36:55 2008
@@ -28,11 +28,35 @@
 import org.apache.commons.lang.Validate;
 
 /**
- * Extends <code>MessageFormat</code> to allow pluggable/additional formatting
- * options for embedded format elements; requires elaboration.
+ * Extends <code>java.text.MessageFormat</code> to allow pluggable/additional
formatting
+ * options for embedded format elements.  Client code should specify a registry
+ * of <code>FormatFactory</code> instances associated with <code>String</code>
+ * format names.  This registry will be consulted when the format elements are 
+ * parsed from the message pattern.  In this way custom patterns can be specified,
+ * and the formats supported by <code>java.text.MessageFormat</code> can be overridden
+ * at the format and/or format style level (@see MessageFormat).  A "format element"
+ * embedded in the message pattern is specified (<b>()?</b> signifies optionality):<br
/>
+ * <pre>
+ * <code>{</code
+ * <i>argument-number</i>
+ * <b>(</b>
+ *     <code>,</code><i>format-name</i>
+ *     <b>(</b><code>,</code><i>format-style</i><b>)?</b>
+ * <b>)?</b>
+ * <code>}</code>
+ * </pre>
  *
- * Note that the mutator methods for the replacement Formats are to be considered
- * unnecessary and thus have been disabled (UnsupportedOperationException).
+ * <i>format-name</i> and <i>format-style</i> values are trimmed
of surrounding whitespace
+ * in the manner of <code>java.text.MessageFormat</code>.  If <i>format-name</i>
denotes
+ * <code>FormatFactory formatFactoryInstance</code> in <code>registry</code>,
a <code>Format</code>
+ * matching <i>format-name</i> and <i>format-style</i> is requested
from
+ * <code>formatFactoryInstance</code>.  If this is successful, the <code>Format</code>
+ * found is used for this format element.
+ *
+ * <p>NOTICE: The various subformat mutator methods are considered unnecessary; they
exist on the parent
+ * class to allow the type of customization which it is the job of this class to provide
in
+ * a configurable fashion.  These methods have thus been disabled and will throw
+ * <code>UnsupportedOperationException</code>s if called.</p>
  * 
  * @author Matt Benson
  * @author Niall Pemberton
@@ -175,7 +199,7 @@
 
     /**
      * {@inheritDoc}
-     * UNSUPPORTED
+     * @throws UnsupportedOperationException
      */
     public void setFormat(int formatElementIndex, Format newFormat) {
         throw new UnsupportedOperationException();
@@ -183,7 +207,7 @@
 
     /**
      * {@inheritDoc}
-     * UNSUPPORTED
+     * @throws UnsupportedOperationException
      */
     public void setFormatByArgumentIndex(int argumentIndex, Format newFormat) {
         throw new UnsupportedOperationException();
@@ -191,7 +215,7 @@
 
     /**
      * {@inheritDoc}
-     * UNSUPPORTED
+     * @throws UnsupportedOperationException
      */
     public void setFormats(Format[] newFormats) {
         throw new UnsupportedOperationException();
@@ -199,7 +223,7 @@
 
     /**
      * {@inheritDoc}
-     * UNSUPPORTED
+     * @throws UnsupportedOperationException
      */
     public void setFormatsByArgumentIndex(Format[] newFormats) {
         throw new UnsupportedOperationException();

Modified: commons/proper/lang/trunk/src/java/org/apache/commons/lang/text/FormatFactory.java
URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/java/org/apache/commons/lang/text/FormatFactory.java?rev=631256&r1=631255&r2=631256&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/java/org/apache/commons/lang/text/FormatFactory.java (original)
+++ commons/proper/lang/trunk/src/java/org/apache/commons/lang/text/FormatFactory.java Tue
Feb 26 07:36:55 2008
@@ -15,7 +15,9 @@
      * Create or retrieve a format instance.
      *
      * @param name The format type name
-     * @param arguments Arguments used to create the format instance
+     * @param arguments Arguments used to create the format instance. This allows the
+     *                  <code>FormatFactory</code> to implement the "format style"
+     *                  concept from <code>java.text.MessageFormat</code>.
      * @param locale The locale, may be null
      * @return The format instance
      */



Mime
View raw message