Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.faces.convert
Class NumberConverter

    java.lang.Object
      javax.faces.convert.NumberConverter

All Implemented Interfaces:
  PartialStateHolder, StateHolder, Converter

    public class NumberConverter

extends java.lang.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
`static java.lang.String` | `CONVERTER_ID` The standard converter id for this converter.
`static java.lang.String` | `CURRENCY_ID` The message identifier of the `FacesMessage` to be created if the conversion to `Number` fails.
`static java.lang.String` | `NUMBER_ID` The message identifier of the `FacesMessage` to be created if the conversion to `Number` fails.
`static java.lang.String` | `PATTERN_ID` The message identifier of the `FacesMessage` to be created if the conversion to `Number` fails.
`static java.lang.String` | `PERCENT_ID` The message identifier of the `FacesMessage` to be created if the conversion to `Number` fails.
`static java.lang.String` | `STRING_ID` The message identifier of the `FacesMessage` to be created if the conversion of the `Number` value to `String` fails.

Constructor Summary
`NumberConverter()`

Method Summary
`void` | `clearInitialState()` Reset the PartialStateHolder to a non-delta tracking state.
`java.lang.Object` | `getAsObject(FacesContext context, UIComponent component, java.lang.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 Apply Request Values phase of the request processing lifecycle.
`java.lang.String` | `getAsString(FacesContext context, UIComponent component, java.lang.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.
`java.lang.String` | `getCurrencyCode()` Return the ISO 4217 currency code used by `getAsString()` with a `type` of `currency`.
`java.lang.String` | `getCurrencySymbol()` Return the currency symbol used by `getAsString()` with a `type` of `currency`.
`java.util.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.
`java.lang.String` | `getPattern()` Return the format pattern to be used when formatting and parsing numbers.
`java.lang.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, java.lang.Object state)` Perform any processing required to restore the state from the entries in the state Object.
`java.lang.Object` | `saveState(FacesContext context)` Gets the state of the instance as a `Serializable` Object.
`void` | `setCurrencyCode(java.lang.String currencyCode)` Set the ISO 4217 currency code used by `getAsString()` with a `type` of `currency`.
`void` | `setCurrencySymbol(java.lang.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(java.util.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(java.lang.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(java.lang.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 Detail

### CONVERTER_ID

    public static final java.lang.String CONVERTER_ID

  The standard converter id for this converter.

  See Also:
    Constant Field Values

### CURRENCY_ID

    public static final java.lang.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:
    Constant Field Values

### NUMBER_ID

    public static final java.lang.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.
  HA
  - `{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:
    Constant Field Values

### PATTERN_ID

    public static final java.lang.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:
    Constant Field Values

### PERCENT_ID

    public static final java.lang.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:
    Constant Field Values

### STRING_ID

    public static final java.lang.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:
    Constant Field Values

Constructor Detail

### NumberConverter

    public NumberConverter()

Method Detail

### getCurrencyCode

    public java.lang.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`.

### setCurrencyCode

    public void setCurrencyCode(java.lang.String currencyCode)

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

  Parameters:
    `currencyCode` - The new currency code

### getCurrencySymbol

    public java.lang.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`.

### setCurrencySymbol

    public void setCurrencySymbol(java.lang.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`.

### 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`.

### 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.

### 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.

### 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.

### 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.

### 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 java.util.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.

### setLocale

    public void setLocale(java.util.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 java.lang.String getPattern()

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

### setPattern

    public void setPattern(java.lang.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 java.lang.String getType()

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

### setType

    public void setType(java.lang.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 java.lang.Object getAsObject(FacesContext context,
                                        UIComponent component,
                                        java.lang.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 Apply Request Values 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
    `java.lang.NullPointerException` - if `context` or `component` is `null`

### getAsString

    public java.lang.String getAsString(FacesContext context,
                                        UIComponent component,
                                        java.lang.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
    `java.lang.NullPointerException` - if `context` or `component` is `null`

### saveState

    public java.lang.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(javax.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`

### restoreState

    public void restoreState(FacesContext context,
                             java.lang.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(javax.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`

### 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`

### 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(javax.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`

### clearInitialState

    public void clearInitialState()

  Description copied from interface: `PartialStateHolder`

  Reset the PartialStateHolder to a non-delta tracking state.

  Specified by:
    `clearInitialState` in interface `PartialStateHolder`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright 2002-2010 Oracle America Inc, Inc. All Rights Reserved.