org.apache.myfaces.trinidad.convert

## Class ColorConverter

- java.lang.Object
- - org.apache.myfaces.trinidad.convert.ColorConverter

- All Implemented Interfaces:
    javax.faces.component.StateHolder, javax.faces.convert.Converter

      public class ColorConverter
      extends Object
      implements javax.faces.convert.Converter, javax.faces.component.StateHolder

  Converters string to Color object and vice versa based on the patterns and the transparency set.

  Pattern format for colors:

  Color Format Syntax:

  To specify the color format use a color pattern string. In this pattern, all ASCII letters are reserved as pattern letters, which are defined as the following:

  >      Symbol   Meaning                 Presentation        Example
  >      ------   -------                 ------------        -------
  >      r        red component           (Number)            242
  >      g        green component         (Number)            242
  >      b        blue component          (Number)            242
  >      a        alpha component         (Number)            255
  >      R        red component           (Hex)               F2
  >      G        green component         (Hex)               F2
  >      B        blue component          (Hex)               F2
  >      A        alpha component         (Hex)               FF
  >      '        escape for text         (Delimiter)
  >      ''       single quote            (Literal)           '

  Examples:

  >      Format Pattern                         Result
  >      --------------                         -------
  >      "#RRGGBB"                         ->>  #6609CC
  >      "rrr,ggg,bbb"                     ->>  102,009,204
  >      "t"                               ->>  Transparent (when alpha is zero)

  If patterns is not set then it defaults to patterns "#RRGGBB", "r,g,b" The first pattern is special - it is always used for formatting color values. For default case, getAsString() will use "#RRGGBB" format to represent the color. Object as String.

  The `getAsObject()` method parses a String into a `Color`, 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`.
  - Parses the trimmed string as mentioned in the documentation, If the string does not match the patterns specified throw `ConverterException` containing a `CONVERT_MESSAGE_ID` message. The detail message of `CONVERT_MESSAGE_ID` can be overridden by setting a custom error message, by calling method `setMessageDetailConvert()`. The custom message can contain placeholders as specified in `CONVERT_MESSAGE_ID`. The placeholders will be replaced by appropriate values as mentioned in `CONVERT_MESSAGE_ID`

  The `getAsString()` method expects a value of type `Color` (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.
  - return the string representation of color based on the first pattern.
  Version:
    $Name: $ ($Revision: adfrt/faces/adf-faces-api/src/main/java/oracle/adf/view/faces/convert/ColorConverter.java#0 $) $Date: 10-nov-2005.19:09:09 $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CONVERT_MESSAGE_ID` The message identifier of the `FacesMessage` to be created when input value cannot be converterd to color based on the patterns set.
    `static String` | `CONVERTER_ID` Standard converter id for this converter.
    `static String[]` | `DEFAULT_COLOR_FORMAT_PATTERNS` Deprecated. use getDefaultColorFormatPatterns()

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ColorConverter()` Construct a ColorConverter with the default values.
    `ColorConverter(String[] patterns, boolean allowsTransparent)` Construct a ColorConverter with preconfigured values.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(Object obj)` Compares this ColorConverter with the specified Object for equality.
    `Object` | `getAsObject(javax.faces.context.FacesContext context, javax.faces.component.UIComponent component, String value)` Convert the specified string value, which is associated with the specified `UIComponent`, into a Color object based on the patterns set.
    `String` | `getAsString(javax.faces.context.FacesContext context, javax.faces.component.UIComponent component, Object value)` Return a String representation for the Color object based on the first pattern in the given patterns.
    `static String[]` | `getDefaultColorFormatPatterns()` Returns the default patterns to be used if the pattern if not supplied.
    `String` | `getHint()` Return custom hint message.
    `String` | `getMessageDetailConvert()` Return custom detail error message that was set for creating faces message, for values that cannot be converted to `Color`
    `String[]` | `getPatterns()` Retrun the patterns set for this converter.
    `protected String` | `getTransparentString(javax.faces.context.FacesContext context)`
    `javax.faces.el.ValueBinding` | `getValueBinding(String name)` Deprecated.
    `javax.el.ValueExpression` | `getValueExpression(String name)` Return the `ValueExpression` used to calculate the value for the specified attribute name, if any.
    `int` | `hashCode()` Returns the hash code for this converter.
    `boolean` | `isTransient()`
    `boolean` | `isTransparentAllowed()` Return if localized transparent text should be supported by this converter.
    `void` | `restoreState(javax.faces.context.FacesContext context, Object state)`
    `Object` | `saveState(javax.faces.context.FacesContext context)`
    `void` | `setHint(String hintFormat)` Custom hint message.
    `void` | `setMessageDetailConvert(String convertMessageDetail)` Custom error message to be used, for creating detail part of the faces message, when `value` cannot be converted to `Color`.
    `void` | `setPatterns(String[] patterns)` Set the R,G, B patterns, based on the patterns set, Color object is created during call to getAsObject(FacesContext,UIComponent, String), while based on the first pattern which is at index 0, the String representation for the object is determined with call to getAsString(FacesContext, UIComponent, Object).
    `void` | `setTransient(boolean isTransient)`
    `void` | `setTransparentAllowed(boolean isTransparentAllowed)` Set if localized transparent text should be supported by this converter.
    `void` | `setValueBinding(String name, javax.faces.el.ValueBinding binding)` Deprecated.
    `void` | `setValueExpression(String name, javax.el.ValueExpression expression)` Set the `ValueExpression` used to calculate the value for the specified attribute if any.

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

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

- - ### Field Detail

    - #### CONVERTER_ID

          public static final String CONVERTER_ID

      Standard converter id for this converter.

      See Also:
        Constant Field Values

    - #### CONVERT_MESSAGE_ID

          public static final String CONVERT_MESSAGE_ID

      The message identifier of the `FacesMessage` to be created when input value cannot be converterd to color based on the patterns set. The message format string for this message may optionally include a `{0}`, `{1}`, `{4}` placeholdes, which will be replaced by input value, component label and the pattern set in the converter.

      See Also:
        Constant Field Values

    - #### DEFAULT_COLOR_FORMAT_PATTERNS

          @Deprecated
          public static final String[] DEFAULT_COLOR_FORMAT_PATTERNS

      Deprecated. use getDefaultColorFormatPatterns()

  - ### Constructor Detail

    - #### ColorConverter

          public ColorConverter(String[] patterns,
                        boolean allowsTransparent)

      Construct a ColorConverter with preconfigured values.

      Parameters:
        `patterns` - The set of R,G,B format patterns that are accepted by this Converter. The first pattern is special - it is always used for formatting color values.
        `allowsTransparent` - Indicates whether or not transparent colors are considered valid.

    - #### ColorConverter

          public ColorConverter()

      Construct a ColorConverter with the default values. The defualt patterns being "#RRGGBB", "r,g,b" and allowsTransparent is set to false.

  - ### Method Detail

    - #### getDefaultColorFormatPatterns

          public static final String[] getDefaultColorFormatPatterns()

      Returns the default patterns to be used if the pattern if not supplied. The default patterns is `"#RRGGBB", "r,g,b"` The first pattern is special, it is always used for formatting color values

    - #### getAsObject

          public Object getAsObject(javax.faces.context.FacesContext context,
                           javax.faces.component.UIComponent component,
                           String value)

      Convert the specified string value, which is associated with the specified `UIComponent`, into a Color object based on the patterns set.

      Specified by:
        `getAsObject` in interface `javax.faces.convert.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 return a Color object.
      Throws:
        `javax.faces.convert.ConverterException` - if conversion cannot be successfully performed
        `NullPointerException` - if `context` or `component` is `null`

    - #### getAsString

          public String getAsString(javax.faces.context.FacesContext context,
                           javax.faces.component.UIComponent component,
                           Object value)

      Return a String representation for the Color object based on the first pattern in the given patterns.

      Specified by:
        `getAsString` in interface `javax.faces.convert.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 String representation for the Color object based on the first pattern in the specified patterns.
      Throws:
        `javax.faces.convert.ConverterException` - if conversion cannot be successfully performed
        `NullPointerException` - if `context` or `component` is `null`
        `IllegalArgumentException` - if the `value` is not of type other than `Color`, `String` or `value` can be null.

    - #### setTransparentAllowed

          public void setTransparentAllowed(boolean isTransparentAllowed)

      Set if localized transparent text should be supported by this converter.

      Parameters:
        `isTransparentAllowed` -

    - #### setPatterns

          public void setPatterns(String[] patterns)
                           throws IllegalArgumentException

      Set the R,G, B patterns, based on the patterns set, Color object is created during call to getAsObject(FacesContext,UIComponent, String), while based on the first pattern which is at index 0, the String representation for the object is determined with call to getAsString(FacesContext, UIComponent, Object). `null` value for patterns result in IllegalArgumentException.

      Parameters:
        `patterns` -
      Throws:
        `IllegalArgumentException` - if a value of pattern is null or if an invalid pattern is passed.

    - #### getPatterns

          public String[] getPatterns()

      Retrun the patterns set for this converter.

      Returns:
        patterns

    - #### isTransparentAllowed

          public boolean isTransparentAllowed()

      Return if localized transparent text should be supported by this converter.

    - #### equals

          public boolean equals(Object obj)

      Compares this ColorConverter with the specified Object for equality.

      Overrides:
        `equals` in class `Object`
      Parameters:
        `obj` - Object to which this ColorConverter is to be compared.
      Returns:
        true if and only if the specified Object is a ColorConverter and if the values patterns, transparentAllowed and transient are equal.

    - #### hashCode

          public int hashCode()

      Returns the hash code for this converter.

      Overrides:
        `hashCode` in class `Object`
      Returns:
        a hash code value for this object.

    - #### isTransient

          public boolean isTransient()

      Specified by:
        `isTransient` in interface `javax.faces.component.StateHolder`

    - #### setTransient

          public void setTransient(boolean isTransient)

      Specified by:
        `setTransient` in interface `javax.faces.component.StateHolder`

    - #### saveState

          public Object saveState(javax.faces.context.FacesContext context)

      Specified by:
        `saveState` in interface `javax.faces.component.StateHolder`

    - #### restoreState

          public void restoreState(javax.faces.context.FacesContext context,
                          Object state)

      Specified by:
        `restoreState` in interface `javax.faces.component.StateHolder`

    - #### setValueExpression

          public void setValueExpression(String name,
                                javax.el.ValueExpression expression)

      Set the `ValueExpression` used to calculate the value for the specified attribute if any.

      Parameters:
        `name` - Name of the attribute for which to set a `ValueExpression`
        `expression` - The `ValueExpression` to set, or `null` to remove any currently set `ValueExpression`
      Throws:
        `NullPointerException` - if `name` is `null`
        `IllegalArgumentException` - if `name` is not a valid attribute of this converter

    - #### getValueExpression

          public javax.el.ValueExpression getValueExpression(String name)

      Return the `ValueExpression` used to calculate the value for the specified attribute name, if any.

      Parameters:
        `name` - Name of the attribute or property for which to retrieve a `ValueExpression`
      Throws:
        `NullPointerException` - if `name` is `null`
        `IllegalArgumentException` - if `name` is not a valid attribute of this converter

    - #### setValueBinding

          public void setValueBinding(String name,
                             javax.faces.el.ValueBinding binding)

      Deprecated.

      Set the `ValueBinding` used to calculate the value for the specified attribute if any.

      Parameters:
        `name` - Name of the attribute for which to set a `ValueBinding`
        `binding` - The `ValueBinding` to set, or `null` to remove any currently set `ValueBinding`
      Throws:
        `NullPointerException` - if `name` is `null`
        `IllegalArgumentException` - if `name` is not a valid attribute of this converter

    - #### getValueBinding

          public javax.faces.el.ValueBinding getValueBinding(String name)

      Deprecated.

      Return the `ValueBinding` used to calculate the value for the specified attribute name, if any.

      Parameters:
        `name` - Name of the attribute or property for which to retrieve a `ValueBinding`
      Throws:
        `NullPointerException` - if `name` is `null`
        `IllegalArgumentException` - if `name` is not a valid attribute of this converter

    - #### setMessageDetailConvert

          public void setMessageDetailConvert(String convertMessageDetail)

      Custom error message to be used, for creating detail part of the faces message, when `value` cannot be converted to `Color`. Overrides the detail message identified by `CONVERT_MESSAGE_ID`
      Parameters:
        `convertMessageDetail` - Custom error message.
      See Also:
        `CONVERT_MESSAGE_ID`

    - #### getMessageDetailConvert

          public String getMessageDetailConvert()

      Return custom detail error message that was set for creating faces message, for values that cannot be converted to `Color`
      Returns:
        Custom error message.
      See Also:
        `setMessageDetailConvert(String)`

    - #### setHint

          public void setHint(String hintFormat)

      Custom hint message.

      Overrides default hint message
      Parameters:
        `hintFormat` - Custom hint message.

    - #### getHint

          public String getHint()

      Return custom hint message.

      Returns:
        Custom hint message.
      See Also:
        `setHint(String)`

    - #### getTransparentString

          protected String getTransparentString(javax.faces.context.FacesContext context)

Copyright © 2001-2016 The Apache Software Foundation. All Rights Reserved.