ExtendedMessageFormat (Apache Commons Text 1.13.0 API)
Description: declaration: package: org.apache.commons.text, class: ExtendedMessageFormat

Package org.apache.commons.text

# Class ExtendedMessageFormat

java.lang.Object
java.text.Format
java.text.MessageFormat
org.apache.commons.text.ExtendedMessageFormat

All Implemented Interfaces:
  `Serializable`, `Cloneable`

public class ExtendedMessageFormat extends MessageFormat
Extends `MessageFormat` to allow pluggable/additional formatting options for embedded format elements. Client code should specify a registry of `FormatFactory` instances associated with `String` 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 `MessageFormat` can be overridden at the format and/or format style level (see MessageFormat). A "format element" embedded in the message pattern is specified (()? signifies optionality):
`{}<em>argument-number</em><strong>(</strong>{@code ,}<em>format-name</em><b> (</b>{@code ,}<em>format-style</em><strong>)?)?</strong>{@code }`

format-name and format-style values are trimmed of surrounding whitespace in the manner of `MessageFormat`. If format-name denotes `FormatFactory formatFactoryInstance` in `registry`, a `Format` matching format-name and format-style is requested from `formatFactoryInstance`. If this is successful, the `Format` found is used for this format element.

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 `UnsupportedOperationException` if called.

Limitations inherited from `MessageFormat`:

- When using "choice" subformats, support for nested formatting instructions is limited to that provided by the base class.
- Thread-safety of `Format`s, including `MessageFormat` and thus `ExtendedMessageFormat`, is not guaranteed.

Since:
  1.0
See Also:
  - Serialized Form

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class java.text.MessageFormat

  `MessageFormat.Field`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ExtendedMessageFormat(String pattern)`
  Constructs a new ExtendedMessageFormat for the default locale.
  `ExtendedMessageFormat(String pattern, Locale locale)`
  Constructs a new ExtendedMessageFormat.
  `ExtendedMessageFormat(String pattern, Locale locale, Map<String,? extends FormatFactory> registry)`
  Constructs a new ExtendedMessageFormat.
  `ExtendedMessageFormat(String pattern, Map<String,? extends FormatFactory> registry)`
  Constructs a new ExtendedMessageFormat for the default locale.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final void`
  `applyPattern(String pattern)`
  Applies the specified pattern.
  `boolean`
  `equals(Object obj)`
  Tests if this extended message format is equal to another object.
  `int`
  `hashCode()`
  `void`
  `setFormat(int formatElementIndex, Format newFormat)`
  Throws UnsupportedOperationException - see class Javadoc for details.
  `void`
  `setFormatByArgumentIndex(int argumentIndex, Format newFormat)`
  Throws UnsupportedOperationException - see class Javadoc for details.
  `void`
  `setFormats(Format[] newFormats)`
  Throws UnsupportedOperationException - see class Javadoc for details.
  `void`
  `setFormatsByArgumentIndex(Format[] newFormats)`
  Throws UnsupportedOperationException - see class Javadoc for details.
  `String`
  `toPattern()`

  ### Methods inherited from class java.text.MessageFormat

  `clone, format, format, format, formatToCharacterIterator, getFormats, getFormatsByArgumentIndex, getLocale, parse, parse, parseObject, setLocale`

  ### Methods inherited from class java.text.Format

  `format, parseObject`

  ### Methods inherited from class java.lang.Object

  `finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### ExtendedMessageFormat

    public ExtendedMessageFormat(String pattern)
    Constructs a new ExtendedMessageFormat for the default locale.
    Parameters:
      `pattern` - the pattern to use, not null
    Throws:
      `IllegalArgumentException` - in case of a bad pattern.

  - ### ExtendedMessageFormat

    public ExtendedMessageFormat(String pattern, Locale locale)
    Constructs a new ExtendedMessageFormat.
    Parameters:
      `pattern` - the pattern to use, not null
      `locale` - the locale to use, not null
    Throws:
      `IllegalArgumentException` - in case of a bad pattern.

  - ### ExtendedMessageFormat

    public ExtendedMessageFormat(String pattern, Locale locale, Map<String,? extends FormatFactory> registry)
    Constructs a new ExtendedMessageFormat.
    Parameters:
      `pattern` - the pattern to use, not null
      `locale` - the locale to use, not null
      `registry` - the registry of format factories, may be null
    Throws:
      `IllegalArgumentException` - in case of a bad pattern.

  - ### ExtendedMessageFormat

    public ExtendedMessageFormat(String pattern, Map<String,? extends FormatFactory> registry)
    Constructs a new ExtendedMessageFormat for the default locale.
    Parameters:
      `pattern` - the pattern to use, not null
      `registry` - the registry of format factories, may be null
    Throws:
      `IllegalArgumentException` - in case of a bad pattern.

- ## Method Details

  - ### applyPattern

    public final void applyPattern(String pattern)
    Applies the specified pattern.
    Overrides:
      `applyPattern` in class `MessageFormat`
    Parameters:
      `pattern` - String

  - ### equals

    public boolean equals(Object obj)
    Tests if this extended message format is equal to another object.
    Overrides:
      `equals` in class `MessageFormat`
    Parameters:
      `obj` - the object to compare to
    Returns:
      true if this object equals the other, otherwise false

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `MessageFormat`

  - ### setFormat

    public void setFormat(int formatElementIndex, Format newFormat)
    Throws UnsupportedOperationException - see class Javadoc for details.
    Overrides:
      `setFormat` in class `MessageFormat`
    Parameters:
      `formatElementIndex` - format element index
      `newFormat` - the new format
    Throws:
      `UnsupportedOperationException` - always thrown since this isn't supported by ExtendMessageFormat

  - ### setFormatByArgumentIndex

    public void setFormatByArgumentIndex(int argumentIndex, Format newFormat)
    Throws UnsupportedOperationException - see class Javadoc for details.
    Overrides:
      `setFormatByArgumentIndex` in class `MessageFormat`
    Parameters:
      `argumentIndex` - argument index
      `newFormat` - the new format
    Throws:
      `UnsupportedOperationException` - always thrown since this isn't supported by ExtendMessageFormat

  - ### setFormats

    public void setFormats(Format[] newFormats)
    Throws UnsupportedOperationException - see class Javadoc for details.
    Overrides:
      `setFormats` in class `MessageFormat`
    Parameters:
      `newFormats` - new formats
    Throws:
      `UnsupportedOperationException` - always thrown since this isn't supported by ExtendMessageFormat

  - ### setFormatsByArgumentIndex

    public void setFormatsByArgumentIndex(Format[] newFormats)
    Throws UnsupportedOperationException - see class Javadoc for details.
    Overrides:
      `setFormatsByArgumentIndex` in class `MessageFormat`
    Parameters:
      `newFormats` - new formats
    Throws:
      `UnsupportedOperationException` - always thrown since this isn't supported by ExtendMessageFormat

  - ### toPattern

    public String toPattern()
    Overrides:
      `toPattern` in class `MessageFormat`