Package jakarta.faces.convert

Class NumberConverter

java.lang.Object
jakarta.faces.convert.NumberConverter
All Implemented Interfaces:
PartialStateHolder, StateHolder, Converter
public class NumberConverter extends Object implements Converter, PartialStateHolder

Converter implementation for java.lang.Number values.

The getAsObject() method parses a String into an java.lang.Double or java.lang.Long, according to the following algorithm:

  • If the specified String is null, return a null. Otherwise, trim leading and trailing whitespace before proceeding.
  • If the specified String - after trimming - has a zero length, return null.
  • If the locale property is not null, use that Locale for managing parsing. Otherwise, use the Locale from the UIViewRoot.
  • If a pattern has been specified, its syntax must conform the rules specified by java.text.DecimalFormat. Such a pattern will be used to parse, and the type property will be ignored.
  • If a pattern has not been specified, parsing will be based on the type property, which expects a currency, a number, or a percent. The parse pattern for currencies, numbers, and percentages is determined by calling the getCurrencyInstance(), getNumberInstance(), or getPercentInstance() method of the java.text.NumberFormat class, passing in the selected Locale.
  • If the integerOnly property has been set to true, only the integer portion of the String will be parsed. See the JavaDocs for the setParseIntegerOnly() method of the java.text.NumberFormat class for more information.

The getAsString() method expects a value of type java.lang.Number (or a subclass), and creates a formatted String according to the following algorithm:

  • If the specified value is null, return a zero-length String.
  • If the specified value is a String, return it unmodified.
  • If the locale property is not null, use that Locale for managing formatting. Otherwise, use the Locale from the FacesContext.
  • If a pattern has been specified, its syntax must conform the rules specified by java.text.DecimalFormat. Such a pattern will be used to format, and the type property (along with related formatting options described in the next paragraph) will be ignored.
  • If a pattern has not been specified, formatting will be based on the type property, which formats the value as a currency, a number, or a percent. The format pattern for currencies, numbers, and percentages is determined by calling the percentages is determined by calling the getCurrencyInstance(), getNumberInstance(), or getPercentInstance() method of the java.text.NumberFormat class, passing in the selected Locale. In addition, the following properties will be applied to the format pattern, if specified:
    • If the groupingUsed property is true, the setGroupingUsed(true) method on the corresponding NumberFormat instance will be called.
    • The minimum and maximum number of digits in the integer and fractional portions of the result will be configured based on any values set for the maxFractionDigits, maxIntegerDigits, minFractionDigits, and minIntegerDigits properties.
    • If the type is set to currency, it is also possible to configure the currency symbol to be used, using either the currencyCode or currencySymbol properties. If both are set, the value for currencyCode takes precedence on a JDK 1.4 (or later) JVM; otherwise, the value for currencySymbol takes precedence.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    CONVERTER_ID
    The standard converter id for this converter.
    static final String
    CURRENCY_ID
    The message identifier of the FacesMessage to be created if the conversion to Number fails.
    static final String
    NUMBER_ID
    The message identifier of the FacesMessage to be created if the conversion to Number fails.
    static final String
    PATTERN_ID
    The message identifier of the FacesMessage to be created if the conversion to Number fails.
    static final String
    PERCENT_ID
    The message identifier of the FacesMessage to be created if the conversion to Number fails.
    static final String
    STRING_ID
    The message identifier of the FacesMessage to be created if the conversion of the Number value to String fails.

    Fields inherited from interface jakarta.faces.convert.Converter

    DATETIMECONVERTER_DEFAULT_TIMEZONE_IS_SYSTEM_TIMEZONE_PARAM_NAME

  • Constructor Summary

    Constructors
    Constructor
    Description
    NumberConverter()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clearInitialState()
    Reset the PartialStateHolder to a non-delta tracking state.
    Object
    getAsObject(FacesContext context, UIComponent component, String value)
    Convert the specified string value, which is associated with the specified UIComponent, into a model data object that is appropriate for being stored during the Process Validations phase of the request processing lifecycle.
    String
    getAsString(FacesContext context, UIComponent component, Object value)
    Convert the specified model object value, which is associated with the specified UIComponent, into a String that is suitable for being included in the response generated during the Render Response phase of the request processing lifeycle.
    String
    getCurrencyCode()
    Return the ISO 4217 currency code used by getAsString() with a type of currency.
    String
    getCurrencySymbol()
    Return the currency symbol used by getAsString() with a type of currency.
    Locale
    getLocale()
    Return the Locale to be used when parsing numbers.
    int
    getMaxFractionDigits()
    Return the maximum number of digits getAsString() should render in the fraction portion of the result.
    int
    getMaxIntegerDigits()
    Return the maximum number of digits getAsString() should render in the integer portion of the result.
    int
    getMinFractionDigits()
    Return the minimum number of digits getAsString() should render in the fraction portion of the result.
    int
    getMinIntegerDigits()
    Return the minimum number of digits getAsString() should render in the integer portion of the result.
    String
    getPattern()
    Return the format pattern to be used when formatting and parsing numbers.
    String
    getType()
    Return the number type to be used when formatting and parsing numbers.
    boolean
    initialStateMarked()
    Return true if delta state changes are being tracked, otherwise false
    boolean
    isGroupingUsed()
    Return true if getAsString should include grouping separators if necessary.
    boolean
    isIntegerOnly()
    Return true if only the integer portion of the given value should be returned from getAsObject().
    boolean
    isTransient()
    If true, the Object implementing this interface must not participate in state saving or restoring.
    void
    markInitialState()
    The runtime must ensure that the PartialStateHolder.markInitialState() method is called on each instance of this interface in the view at the appropriate time to indicate the component is in its initial state.
    void
    restoreState(FacesContext context, Object state)
    Perform any processing required to restore the state from the entries in the state Object.
    Object
    saveState(FacesContext context)
    Gets the state of the instance as a Serializable Object.
    void
    setCurrencyCode(String currencyCode)
    Set the ISO 4217 currency code used by getAsString() with a type of currency.
    void
    setCurrencySymbol(String currencySymbol)
    Set the currency symbol used by getAsString() with a type of currency.
    void
    setGroupingUsed(boolean groupingUsed)
    Set the flag indicating whether getAsString() should include grouping separators if necessary.
    void
    setIntegerOnly(boolean integerOnly)
    Set to true if only the integer portion of the given value should be returned from getAsObject().
    void
    setLocale(Locale locale)
    Set the Locale to be used when parsing numbers.
    void
    setMaxFractionDigits(int maxFractionDigits)
    Set the maximum number of digits getAsString() should render in the fraction portion of the result.
    void
    setMaxIntegerDigits(int maxIntegerDigits)
    Set the maximum number of digits getAsString() should render in the integer portion of the result.
    void
    setMinFractionDigits(int minFractionDigits)
    Set the minimum number of digits getAsString() should render in the fraction portion of the result.
    void
    setMinIntegerDigits(int minIntegerDigits)
    Set the minimum number of digits getAsString() should render in the integer portion of the result.
    void
    setPattern(String pattern)
    Set the format pattern to be used when formatting and parsing numbers.
    void
    setTransient(boolean transientFlag)
    Denotes whether or not the Object implementing this interface must or must not participate in state saving or restoring.
    void
    setType(String type)
    Set the number type to be used when formatting and parsing numbers.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • CONVERTER_ID

      public static final String CONVERTER_ID

      The standard converter id for this converter.

      See Also:

    • CURRENCY_ID

      public static final String CURRENCY_ID

      The message identifier of the FacesMessage to be created if the conversion to Number fails. The message format string for this message may optionally include the following placeholders:

      • {0} replaced by the unconverted value.
      • {1} replaced by an example value.
      • {2} replaced by a String whose value is the label of the input component that produced this message.
      See Also:

    • NUMBER_ID

      public static final String NUMBER_ID

      The message identifier of the FacesMessage to be created if the conversion to Number fails. The message format string for this message may optionally include the following placeholders:

      • {0} replaced by the unconverted value.
      • {1} replaced by an example value.
      • {2} replaced by a String whose value is the label of the input component that produced this message.
      See Also:

    • PATTERN_ID

      public static final String PATTERN_ID

      The message identifier of the FacesMessage to be created if the conversion to Number fails. The message format string for this message may optionally include the following placeholders:

      • {0} replaced by the unconverted value.
      • {1} replaced by an example value.
      • {2} replaced by a String whose value is the label of the input component that produced this message.
      See Also:

    • PERCENT_ID

      public static final String PERCENT_ID

      The message identifier of the FacesMessage to be created if the conversion to Number fails. The message format string for this message may optionally include the following placeholders:

      • {0} replaced by the unconverted value.
      • {1} replaced by an example value.
      • {2} replaced by a String whose value is the label of the input component that produced this message.
      See Also:

    • STRING_ID

      public static final String STRING_ID

      The message identifier of the FacesMessage to be created if the conversion of the Number value to String fails. The message format string for this message may optionally include the following placeholders:

      • {0} relaced by the unconverted value.
      • {1} replaced by a String whose value is the label of the input component that produced this message.
      See Also:

  • Constructor Details

    • NumberConverter

      public NumberConverter()

  • Method Details

    • getCurrencyCode

      public String getCurrencyCode()

      Return the ISO 4217 currency code used by getAsString() with a type of currency. If not set, the value used will be based on the formatting Locale.

      Returns:
      the currency code

    • setCurrencyCode

      public void setCurrencyCode(String currencyCode)

      Set the ISO 4217 currency code used by getAsString() with a type of currency.

      Parameters:
      currencyCode - The new currency code

    • getCurrencySymbol

      public String getCurrencySymbol()

      Return the currency symbol used by getAsString() with a type of currency. If not set, the value used will be based on the formatting Locale.

      Returns:
      the currency symbol

    • setCurrencySymbol

      public void setCurrencySymbol(String currencySymbol)

      Set the currency symbol used by getAsString() with a type of currency.

      Parameters:
      currencySymbol - The new currency symbol

    • isGroupingUsed

      public boolean isGroupingUsed()

      Return true if getAsString should include grouping separators if necessary. If not modified, the default value is true.

      Returns:
      whether or not grouping is used

    • setGroupingUsed

      public void setGroupingUsed(boolean groupingUsed)

      Set the flag indicating whether getAsString() should include grouping separators if necessary.

      Parameters:
      groupingUsed - The new grouping used flag

    • isIntegerOnly

      public boolean isIntegerOnly()

      Return true if only the integer portion of the given value should be returned from getAsObject(). If not modified, the default value is false.

      Returns:
      whether or not this is integer only

    • setIntegerOnly

      public void setIntegerOnly(boolean integerOnly)

      Set to true if only the integer portion of the given value should be returned from getAsObject().

      Parameters:
      integerOnly - The new integer-only flag

    • getMaxFractionDigits

      public int getMaxFractionDigits()

      Return the maximum number of digits getAsString() should render in the fraction portion of the result.

      Returns:
      the maximum fraction digits

    • setMaxFractionDigits

      public void setMaxFractionDigits(int maxFractionDigits)

      Set the maximum number of digits getAsString() should render in the fraction portion of the result. If not set, the number of digits depends on the value being converted.

      Parameters:
      maxFractionDigits - The new limit

    • getMaxIntegerDigits

      public int getMaxIntegerDigits()

      Return the maximum number of digits getAsString() should render in the integer portion of the result.

      Returns:
      the max integer digits

    • setMaxIntegerDigits

      public void setMaxIntegerDigits(int maxIntegerDigits)

      Set the maximum number of digits getAsString() should render in the integer portion of the result. If not set, the number of digits depends on the value being converted.

      Parameters:
      maxIntegerDigits - The new limit

    • getMinFractionDigits

      public int getMinFractionDigits()

      Return the minimum number of digits getAsString() should render in the fraction portion of the result.

      Returns:
      the min fraction digits

    • setMinFractionDigits

      public void setMinFractionDigits(int minFractionDigits)

      Set the minimum number of digits getAsString() should render in the fraction portion of the result. If not set, the number of digits depends on the value being converted.

      Parameters:
      minFractionDigits - The new limit

    • getMinIntegerDigits

      public int getMinIntegerDigits()

      Return the minimum number of digits getAsString() should render in the integer portion of the result.

      Returns:
      the minimum integer digits

    • setMinIntegerDigits

      public void setMinIntegerDigits(int minIntegerDigits)

      Set the minimum number of digits getAsString() should render in the integer portion of the result. If not set, the number of digits depends on the value being converted.

      Parameters:
      minIntegerDigits - The new limit

    • getLocale

      public Locale getLocale()

      Return the Locale to be used when parsing numbers. If this value is null, the Locale stored in the UIViewRoot for the current request will be utilized.

      Returns:
      the Locale for this converter

    • setLocale

      public void setLocale(Locale locale)

      Set the Locale to be used when parsing numbers. If set to null, the Locale stored in the UIViewRoot for the current request will be utilized.

      Parameters:
      locale - The new Locale (or null)

    • getPattern

      public String getPattern()

      Return the format pattern to be used when formatting and parsing numbers.

      Returns:
      the pattern

    • setPattern

      public void setPattern(String pattern)

      Set the format pattern to be used when formatting and parsing numbers. Valid values are those supported by java.text.DecimalFormat. An invalid value will cause a ConverterException when getAsObject() or getAsString() is called.

      Parameters:
      pattern - The new format pattern

    • getType

      public String getType()

      Return the number type to be used when formatting and parsing numbers. If not modified, the default type is number.

      Returns:
      the type

    • setType

      public void setType(String type)

      Set the number type to be used when formatting and parsing numbers. Valid values are currency, number, or percent. An invalid value will cause a ConverterException when getAsObject() or getAsString() is called.

      Parameters:
      type - The new number style

    • getAsObject

      public Object getAsObject(FacesContext context, UIComponent component, String value)
      Description copied from interface: Converter

      Convert the specified string value, which is associated with the specified UIComponent, into a model data object that is appropriate for being stored during the Process Validations phase of the request processing lifecycle.

      Specified by:
      getAsObject in interface Converter
      Parameters:
      context - FacesContext for the request being processed
      component - UIComponent with which this model object value is associated
      value - String value to be converted (may be null)
      Returns:
      null if the value to convert is null, otherwise the result of the conversion
      Throws:
      ConverterException - if conversion cannot be successfully performed
      NullPointerException - if context or component is null

    • getAsString

      public String getAsString(FacesContext context, UIComponent component, Object value)
      Description copied from interface: Converter

      Convert the specified model object value, which is associated with the specified UIComponent, into a String that is suitable for being included in the response generated during the Render Response phase of the request processing lifeycle.

      Specified by:
      getAsString in interface Converter
      Parameters:
      context - FacesContext for the request being processed
      component - UIComponent with which this model object value is associated
      value - Model object value to be converted (may be null)
      Returns:
      a zero-length String if value is null, otherwise the result of the conversion
      Throws:
      ConverterException - if conversion cannot be successfully performed
      NullPointerException - if context or component is null

    • saveState

      public Object saveState(FacesContext context)
      Description copied from interface: StateHolder

      Gets the state of the instance as a Serializable Object.

      If the class that implements this interface has references to instances that implement StateHolder (such as a UIComponent with event handlers, validators, etc.) this method must call the StateHolder.saveState(jakarta.faces.context.FacesContext) method on all those instances as well. This method must not save the state of children and facets. That is done via the StateManager

      This method must not alter the state of the implementing object. In other words, after executing this code: 

       
 Object state = component.saveState(facesContext);

      component should be the same as before executing it.

      The return from this method must be Serializable

      Specified by:
      saveState in interface StateHolder
      Parameters:
      context - the Faces context.
      Returns:
      the saved state.

    • restoreState

      public void restoreState(FacesContext context, Object state)
      Description copied from interface: StateHolder

      Perform any processing required to restore the state from the entries in the state Object.

      If the class that implements this interface has references to instances that also implement StateHolder (such as a UIComponent with event handlers, validators, etc.) this method must call the StateHolder.restoreState(jakarta.faces.context.FacesContext, java.lang.Object) method on all those instances as well.

      If the state argument is null, take no action and return.

      Specified by:
      restoreState in interface StateHolder
      Parameters:
      context - the Faces context.
      state - the state.

    • isTransient

      public boolean isTransient()
      Description copied from interface: StateHolder

      If true, the Object implementing this interface must not participate in state saving or restoring.

      Specified by:
      isTransient in interface StateHolder
      Returns:
      true if transient, false otherwise.

    • setTransient

      public void setTransient(boolean transientFlag)
      Description copied from interface: StateHolder

      Denotes whether or not the Object implementing this interface must or must not participate in state saving or restoring.

      Specified by:
      setTransient in interface StateHolder
      Parameters:
      transientFlag - boolean pass true if this Object will not participate in state saving or restoring, otherwise pass false.

    • markInitialState

      public void markInitialState()
      Description copied from interface: PartialStateHolder

      The runtime must ensure that the PartialStateHolder.markInitialState() method is called on each instance of this interface in the view at the appropriate time to indicate the component is in its initial state. The implementor of the interface must ensure that PartialStateHolder.initialStateMarked() returns true from the time markInitialState() is called until PartialStateHolder.clearInitialState() is called, after which time initialStateMarked() must return false. Also, during the time that the instance returns true from initialStateMarked(), the implementation must return only the state that has changed in its implementation of StateHolder.saveState(jakarta.faces.context.FacesContext).

      Specified by:
      markInitialState in interface PartialStateHolder

    • initialStateMarked

      public boolean initialStateMarked()
      Description copied from interface: PartialStateHolder

      Return true if delta state changes are being tracked, otherwise false

      Specified by:
      initialStateMarked in interface PartialStateHolder
      Returns:
      true if the initial state is marked, false otherwise.

    • clearInitialState

      public void clearInitialState()
      Description copied from interface: PartialStateHolder

      Reset the PartialStateHolder to a non-delta tracking state.

      Specified by:
      clearInitialState in interface PartialStateHolder