<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<!--NewPage-->
<html>
<head>
<!-- Generated by javadoc on Wed Jul 28 01:21:15 GMT 1999 -->
<title>
  Class java.text.MessageFormat
</title>
</head>
<body>
<a name="_top_"></a>
<pre>
<a href="packages.html">All Packages</a>  <a href="tree.html">Class Hierarchy</a>  <a href="Package-java.text.html">This Package</a>  <a href="java.text.Format.html#_top_">Previous</a>  <a href="java.text.NumberFormat.html#_top_">Next</a>  <a href="AllNames.html">Index</a></pre>
<hr>
<h1>
  Class java.text.MessageFormat
</h1>
<pre>
<a href="java.lang.Object.html#_top_">java.lang.Object</a>
   |
   +----<a href="java.text.Format.html#_top_">java.text.Format</a>
           |
           +----java.text.MessageFormat
</pre>
<hr>
<dl>
  <dt> public class <b>MessageFormat</b>
  <dt> extends <a href="java.text.Format.html#_top_">Format</a>
</dl>
<code>MessageFormat</code> provides a means to produce concatenated
 messages in language-neutral way. Use this to construct messages
 displayed for end users.
 <p>
 <code>MessageFormat</code> takes a set of objects, formats them, then
 inserts the formatted strings into the pattern at the appropriate places.
 <p>
 <strong>Note:</strong>
 <code>MessageFormat</code> differs from the other <code>Format</code>
 classes in that you create a <code>MessageFormat</code> object with one
 of its constructors (not with a <code>getInstance</code> style factory
 method). The factory methods aren't necessary because <code>MessageFormat</code>
 doesn't require any complex setup for a given locale. In fact,
 <code>MessageFormat</code> doesn't implement any locale specific behavior
 at all. It just needs to be set up on a sentence by sentence basis.
 <p>
 Here are some examples of usage:
 <blockquote>
 <pre>
 Object[] arguments = {
     new Integer(7),
     new Date(System.currentTimeMillis()),
     "a disturbance in the Force"
 };
 String result = MessageFormat.format(
     "At {1,time} on {1,date}, there was {2} on planet {0,number,integer}.",
     arguments);
 <output>: At 12:30 PM on Jul 3, 2053, there was a disturbance
           in the Force on planet 7.
 </pre>
 </blockquote>
 Typically, the message format will come from resources, and the
 arguments will be dynamically set at runtime.
 <p>
 Example 2:
 <blockquote>
 <pre>
 Object[] testArgs = {new Long(3), "MyDisk"};
 MessageFormat form = new MessageFormat(
     "The disk \"{1}\" contains {0} file(s).");
 System.out.println(form.format(testArgs));
 // output, with different testArgs
 <output>: The disk "MyDisk" contains 0 file(s).
 <output>: The disk "MyDisk" contains 1 file(s).
 <output>: The disk "MyDisk" contains 1,273 file(s).
 </pre>
 </blockquote>
 <p>
 The pattern is of the form:
 <blockquote>
 <pre>
 messageFormatPattern := string ( "{" messageFormatElement "}" string )*
 messageFormatElement := argument { "," elementFormat }
 elementFormat := "time" { "," datetimeStyle }
                | "date" { "," datetimeStyle }
                | "number" { "," numberStyle }
                | "choice" { "," choiceStyle }
 datetimeStyle := "short"
                  | "medium"
                  | "long"
                  | "full"
                  | dateFormatPattern
 numberStyle := "currency"
               | "percent"
               | "integer"
               | numberFormatPattern
 choiceStyle := choiceFormatPattern
 </pre>
 </blockquote>
 If there is no <code>elementFormat</code>,
 then the argument must be a string, which is substituted. If there is
 no <code>dateTimeStyle</code> or <code>numberStyle</code>, then the
 default format is used (for example, <code>NumberFormat.getInstance</code>,
 <code>DateFormat.getTimeInstance</code>, or <code>DateFormat.getInstance</code>).
 <p>
 In strings, single quotes can be used to quote the "{"
 (curly brace) if necessary. A real single quote is represented by ''.
 Inside a <code>messageFormatElement</code>, quotes are <strong>not</strong>
 removed. For example, {1,number,$'#',##} will produce a number format
 with the pound-sign quoted, with a result such as: "$#31,45".
 <p>
 If a pattern is used, then unquoted braces in the pattern, if any, must match:
 that is, "ab {0} de" and "ab '}' de" are ok, but "ab {0'}' de" and "ab } de" are
 not.
 <p>
 The argument is a number from 0 to 9, which corresponds to the
 arguments presented in an array to be formatted.
 <p>
 It is ok to have unused arguments in the array.
 With missing arguments or arguments that are not of the right class for
 the specified format, a <code>ParseException</code> is thrown.
 First, <code>format</code> checks to see if a <code>Format</code> object has been
 specified for the argument with the <code>setFormats</code> method.
 If so, then <code>format</code> uses that <code>Format</code> object to format the
 argument. Otherwise, the argument is formatted based on the object's
 type. If the argument is a <code>Number</code>, then <code>format</code>
 uses <code>NumberFormat.getInstance</code> to format the argument; if the
 argument is a <code>Date</code>, then <code>format</code> uses
 <code>DateFormat.getDateTimeInstance</code> to format the argument.
 Otherwise, it uses the <code>toString</code> method.
 <p>
 For more sophisticated patterns, you can use a <code>ChoiceFormat</code> to get
 output such as:
 <blockquote>
 <pre>
 MessageFormat form = new MessageFormat("The disk \"{1}\" contains {0}.");
 double[] filelimits = {0,1,2};
 String[] filepart = {"no files","one file","{0,number} files"};
 ChoiceFormat fileform = new ChoiceFormat(filelimits, filepart);
 form.setFormat(1,fileform); // NOT zero, see below
 Object[] testArgs = {new Long(12373), "MyDisk"};
 System.out.println(form.format(testArgs));
 // output, with different testArgs
 output: The disk "MyDisk" contains no files.
 output: The disk "MyDisk" contains one file.
 output: The disk "MyDisk" contains 1,273 files.
 </pre>
 </blockquote>
 You can either do this programmatically, as in the above example,
 or by using a pattern (see
 <a href="java.text.ChoiceFormat.html"><code>ChoiceFormat</code></a>
 for more information) as in:
 <blockquote>
 <pre>
 form.applyPattern(
    "There {0,choice,0#are no files|1#is one file|1#are {0,number,integer} files}.");
 </pre>
 </blockquote>
 <p>
 <strong>Note:</strong> As we see above, the string produced
 by a <code>ChoiceFormat</code> in <code>MessageFormat</code> is treated specially;
 occurances of '{' are used to indicated subformats, and cause recursion.
 If you create both a <code>MessageFormat</code> and <code>ChoiceFormat</code>
 programmatically (instead of using the string patterns), then be careful not to
 produce a format that recurses on itself, which will cause an infinite loop.
 <p>
 <strong>Note:</strong> formats are numbered by order of
 variable in the string.
 This is <strong>not</strong> the same as the argument numbering!
 For example: with "abc{2}def{3}ghi{0}...",
 <ul>
 <li>format0 affects the first variable {2}
 <li>format1 affects the second variable {3}
 <li>format2 affects the second variable {0}
 <li>and so on.
 </ul>
 <p>
 You can use <code>setLocale</code> followed by <code>applyPattern</code>
 (and then possibly <code>setFormat</code>) to re-initialize a
 <code>MessageFormat</code> with a different locale.
<p>
<dl>
    <dt> <b>See Also:</b>
    <dd> <a href="java.util.Locale.html#_top_">Locale</a>, <a href="java.text.Format.html#_top_">Format</a>, <a href="java.text.NumberFormat.html#_top_">NumberFormat</a>, <a href="java.text.DecimalFormat.html#_top_">DecimalFormat</a>, <a href="java.text.ChoiceFormat.html#_top_">ChoiceFormat</a>
</dl>
<hr>
<a name="index"></a>
<h2>
  <img src="images/constructor-index.gif" width=275 height=38 alt="Constructor Index">
</h2>
<dl>
  <dt> <img src="images/yellow-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#MessageFormat(java.lang.String)"><b>MessageFormat</b></a>(String)
  <dd>  Constructs with the specified pattern.
</dl>
<h2>
  <img src="images/method-index.gif" width=207 height=38 alt="Method Index">
</h2>
<dl>
  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#applyPattern(java.lang.String)"><b>applyPattern</b></a>(String)
  <dd>  Sets the pattern.
  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#clone()"><b>clone</b></a>()
  <dd>  Overrides Cloneable

  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#equals(java.lang.Object)"><b>equals</b></a>(Object)
  <dd>  Equality comparision between two message format objects

  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#format(java.lang.Object, java.lang.StringBuffer, java.text.FieldPosition)"><b>format</b></a>(Object, StringBuffer, FieldPosition)
  <dd>  Formats an object to produce a string.
  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#format(java.lang.Object[], java.lang.StringBuffer, java.text.FieldPosition)"><b>format</b></a>(Object[], StringBuffer, FieldPosition)
  <dd>  Returns pattern with formatted objects.
  <dt> <img src="images/green-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#format(java.lang.String, java.lang.Object[])"><b>format</b></a>(String, Object[])
  <dd>  Convenience routine.
  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#getFormats()"><b>getFormats</b></a>()
  <dd>  Gets formats that were set with setFormats.
  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#getLocale()"><b>getLocale</b></a>()
  <dd>  Gets the locale.
  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#hashCode()"><b>hashCode</b></a>()
  <dd>  Generates a hash code for the message format object.
  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#parse(java.lang.String)"><b>parse</b></a>(String)
  <dd>  Parses the string.
  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#parse(java.lang.String, java.text.ParsePosition)"><b>parse</b></a>(String, ParsePosition)
  <dd>  Parses the string.
  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#parseObject(java.lang.String, java.text.ParsePosition)"><b>parseObject</b></a>(String, ParsePosition)
  <dd>  Parses the string.
  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#setFormat(int, java.text.Format)"><b>setFormat</b></a>(int, Format)
  <dd>  Sets formats individually to use on parameters.
  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#setFormats(java.text.Format[])"><b>setFormats</b></a>(Format[])
  <dd>  Sets formats to use on parameters.
  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#setLocale(java.util.Locale)"><b>setLocale</b></a>(Locale)
  <dd>  Constructs with the specified pattern and formats for the
 arguments in that pattern.
  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
	<a href="#toPattern()"><b>toPattern</b></a>()
  <dd>  Gets the pattern.
</dl>
<a name="constructors"></a>
<h2>
  <img src="images/constructors.gif" width=231 height=38 alt="Constructors">
</h2>
<a name="MessageFormat"></a>
<a name="MessageFormat(java.lang.String)"><img src="images/yellow-ball.gif" width=12 height=12 alt=" o "></a>
<b>MessageFormat</b>
<pre>
 public MessageFormat(<a href="java.lang.String.html#_top_">String</a> pattern)
</pre>
<dl>
  <dd> Constructs with the specified pattern.
<p>
  <dd><dl>
    <dt> <b>See Also:</b>
    <dd> <a href="#applyPattern">applyPattern</a>
  </dl></dd>
</dl>
<a name="methods"></a>
<h2>
  <img src="images/methods.gif" width=151 height=38 alt="Methods">
</h2>
<a name="setLocale(java.util.Locale)"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="setLocale"><b>setLocale</b></a>
<pre>
 public void setLocale(<a href="java.util.Locale.html#_top_">Locale</a> theLocale)
</pre>
<dl>
  <dd> Constructs with the specified pattern and formats for the
 arguments in that pattern.
<p>
  <dd><dl>
    <dt> <b>See Also:</b>
    <dd> <a href="#setPattern">setPattern</a>
  </dl></dd>
</dl>
<a name="getLocale()"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="getLocale"><b>getLocale</b></a>
<pre>
 public <a href="java.util.Locale.html#_top_">Locale</a> getLocale()
</pre>
<dl>
  <dd> Gets the locale. This locale is used for fetching default number or date
 format information.
<p>
</dl>
<a name="applyPattern(java.lang.String)"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="applyPattern"><b>applyPattern</b></a>
<pre>
 public void applyPattern(<a href="java.lang.String.html#_top_">String</a> newPattern)
</pre>
<dl>
  <dd> Sets the pattern. See the class description.
<p>
</dl>
<a name="toPattern()"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="toPattern"><b>toPattern</b></a>
<pre>
 public <a href="java.lang.String.html#_top_">String</a> toPattern()
</pre>
<dl>
  <dd> Gets the pattern. See the class description.
<p>
</dl>
<a name="setFormats(java.text.Format[])"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="setFormats"><b>setFormats</b></a>
<pre>
 public void setFormats(<a href="java.text.Format.html#_top_">Format</a> newFormats[])
</pre>
<dl>
  <dd> Sets formats to use on parameters.
 See the class description about format numbering.
<p>
</dl>
<a name="setFormat(int, java.text.Format)"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="setFormat"><b>setFormat</b></a>
<pre>
 public void setFormat(int variable,
                       <a href="java.text.Format.html#_top_">Format</a> newFormat)
</pre>
<dl>
  <dd> Sets formats individually to use on parameters.
 See the class description about format numbering.
<p>
</dl>
<a name="getFormats()"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="getFormats"><b>getFormats</b></a>
<pre>
 public <a href="java.text.Format.html#_top_">Format</a>[] getFormats()
</pre>
<dl>
  <dd> Gets formats that were set with setFormats.
 See the class description about format numbering.
<p>
</dl>
<a name="format(java.lang.Object[], java.lang.StringBuffer, java.text.FieldPosition)"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="format"><b>format</b></a>
<pre>
 public final <a href="java.lang.StringBuffer.html#_top_">StringBuffer</a> format(<a href="java.lang.Object.html#_top_">Object</a> source[],
                                  <a href="java.lang.StringBuffer.html#_top_">StringBuffer</a> result,
                                  <a href="java.text.FieldPosition.html#_top_">FieldPosition</a> ignore)
</pre>
<dl>
  <dd> Returns pattern with formatted objects.
<p>
  <dd><dl>
    <dt> <b>Parameters:</b>
    <dd> source - an array of objects to be formatted & substituted.
    <dd> result - where text is appended.
    <dd> ignore - no useful status is returned.
  </dl></dd>
</dl>
<a name="format(java.lang.String, java.lang.Object[])"><img src="images/green-ball.gif" width=12 height=12 alt=" o "></a>
<a name="format"><b>format</b></a>
<pre>
 public static <a href="java.lang.String.html#_top_">String</a> format(<a href="java.lang.String.html#_top_">String</a> pattern,
                             <a href="java.lang.Object.html#_top_">Object</a> arguments[])
</pre>
<dl>
  <dd> Convenience routine.
 Avoids explicit creation of MessageFormat,
 but doesn't allow future optimizations.
<p>
</dl>
<a name="format(java.lang.Object, java.lang.StringBuffer, java.text.FieldPosition)"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="format"><b>format</b></a>
<pre>
 public final <a href="java.lang.StringBuffer.html#_top_">StringBuffer</a> format(<a href="java.lang.Object.html#_top_">Object</a> source,
                                  <a href="java.lang.StringBuffer.html#_top_">StringBuffer</a> result,
                                  <a href="java.text.FieldPosition.html#_top_">FieldPosition</a> ignore)
</pre>
<dl>
  <dd> Formats an object to produce a string.
<p>
  <dd><dl>
    <dt> <b>Overrides:</b>
    <dd> <a href="java.text.Format.html#format(java.lang.Object, java.lang.StringBuffer, java.text.FieldPosition)">format</a> in class <a href="java.text.Format.html#_top_">Format</a>
  </dl></dd>
</dl>
<a name="parse(java.lang.String, java.text.ParsePosition)"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="parse"><b>parse</b></a>
<pre>
 public <a href="java.lang.Object.html#_top_">Object</a>[] parse(<a href="java.lang.String.html#_top_">String</a> source,
                       <a href="java.text.ParsePosition.html#_top_">ParsePosition</a> status)
</pre>
<dl>
  <dd> Parses the string.
 <p>Caveats: The parse may fail in a number of circumstances.
 For example:
 <ul>
 <li>If one of the arguments does not occur in the pattern.
 <li>If the format of an argument is loses information, such as
     with a choice format where a large number formats to "many".
 <li>Does not yet handle recursion (where
     the substituted strings contain {n} references.)
 <li>Will not always find a match (or the correct match)
     if some part of the parse is ambiguous.
     For example, if the pattern "{1},{2}" is used with the
     string arguments {"a,b", "c"}, it will format as "a,b,c".
     When the result is parsed, it will return {"a", "b,c"}.
 <li>If a single argument is formatted twice in the string,
     then the later parse wins.
 </ul>
<p>
</dl>
<a name="parse(java.lang.String)"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="parse"><b>parse</b></a>
<pre>
 public <a href="java.lang.Object.html#_top_">Object</a>[] parse(<a href="java.lang.String.html#_top_">String</a> source) throws <a href="java.text.ParseException.html#_top_">ParseException</a>
</pre>
<dl>
  <dd> Parses the string. Does not yet handle recursion (where
 the substituted strings contain {n} references.)
<p>
  <dd><dl>
    <dt> <b>Throws:</b> <a href="java.text.ParseException.html#_top_">ParseException</a>
    <dd> if the string can't be parsed.
  </dl></dd>
</dl>
<a name="parseObject(java.lang.String, java.text.ParsePosition)"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="parseObject"><b>parseObject</b></a>
<pre>
 public <a href="java.lang.Object.html#_top_">Object</a> parseObject(<a href="java.lang.String.html#_top_">String</a> text,
                           <a href="java.text.ParsePosition.html#_top_">ParsePosition</a> status)
</pre>
<dl>
  <dd> Parses the string. Does not yet handle recursion (where
 the substituted strings contain %n references.)
<p>
  <dd><dl>
    <dt> <b>Overrides:</b>
    <dd> <a href="java.text.Format.html#parseObject(java.lang.String, java.text.ParsePosition)">parseObject</a> in class <a href="java.text.Format.html#_top_">Format</a>
  </dl></dd>
</dl>
<a name="clone()"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="clone"><b>clone</b></a>
<pre>
 public <a href="java.lang.Object.html#_top_">Object</a> clone()
</pre>
<dl>
  <dd> Overrides Cloneable
<p>
  <dd><dl>
    <dt> <b>Overrides:</b>
    <dd> <a href="java.text.Format.html#clone()">clone</a> in class <a href="java.text.Format.html#_top_">Format</a>
  </dl></dd>
</dl>
<a name="equals(java.lang.Object)"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="equals"><b>equals</b></a>
<pre>
 public boolean equals(<a href="java.lang.Object.html#_top_">Object</a> obj)
</pre>
<dl>
  <dd> Equality comparision between two message format objects
<p>
  <dd><dl>
    <dt> <b>Overrides:</b>
    <dd> <a href="java.lang.Object.html#equals(java.lang.Object)">equals</a> in class <a href="java.lang.Object.html#_top_">Object</a>
  </dl></dd>
</dl>
<a name="hashCode()"><img src="images/red-ball.gif" width=12 height=12 alt=" o "></a>
<a name="hashCode"><b>hashCode</b></a>
<pre>
 public int hashCode()
</pre>
<dl>
  <dd> Generates a hash code for the message format object.
<p>
  <dd><dl>
    <dt> <b>Overrides:</b>
    <dd> <a href="java.lang.Object.html#hashCode()">hashCode</a> in class <a href="java.lang.Object.html#_top_">Object</a>
  </dl></dd>
</dl>
<hr>
<pre>
<a href="packages.html">All Packages</a>  <a href="tree.html">Class Hierarchy</a>  <a href="Package-java.text.html">This Package</a>  <a href="java.text.Format.html#_top_">Previous</a>  <a href="java.text.NumberFormat.html#_top_">Next</a>  <a href="AllNames.html">Index</a></pre>
</body>
</html>
