Package jakarta.faces.convert

Annotation Type FacesConverter

@Retention(RUNTIME) @Target({TYPE,FIELD,METHOD,PARAMETER}) @Inherited @Qualifier public @interface FacesConverter

The presence of this annotation on a class automatically registers the class with the runtime as a Converter. The value of the value() attribute is taken to be converter-id, the value of the forClass() attribute is taken to be converter-for-class and the fully qualified class name of the class to which this annotation is attached is taken to be the converter-class. The implementation must guarantee that for each class annotated with FacesConverter, found with the algorithm in section 11.4 "Annotations that correspond to and may take the place of entries in the Application Configuration Resources" of the Jakarta Faces Specification Document, the proper variant of Application.addConverter() is called. If converter-id is not the empty string, Application.addConverter(java.lang.String,java.lang.String) is called, passing the derived converter-id as the first argument and the derived converter-class as the second argument. If converter-id is the empty string, Application.addConverter(java.lang.Class,java.lang.String) is called, passing the converter-for-class as the first argument and the derived converter-class as the second argument. The implementation must guarantee that all such calls to addConverter() happen during application startup time and before any requests are serviced.

The preceding text contains an important subtlety which application users should understand. It is not possible to use a single @FacesConverter annotation to register a single Converter implementation both in the by-class and the by-converter-id data structures. One way to achieve this result is to put the actual converter logic in an abstract base class, without a @FacesConverter annotation, and derive two sub-classes, each with a @FacesConverter annotation. One sub-class has a value attribute but no forClass attribute, and the other sub-class has the converse.

Please see the ViewDeclarationLanguage documentation for <h:selectManyListBox> for another important subtlety regarding converters and collections.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    FacesConverter.Literal
    Supports inline instantiation of the FacesConverter qualifier.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Class
    forClass
    The value of this annotation attribute is taken to be the converter-for-class with which instances of this class of converter can be instantiated by calling Application.createConverter(java.lang.Class).
    boolean
    managed
    The value of this annotation attribute is taken to be an indicator that flags whether or not the given converter is a CDI managed converter.
    String
    value
    The value of this annotation attribute is taken to be the converter-id with which instances of this class of converter can be instantiated by calling Application.createConverter(java.lang.String).

  • Element Details

    • value

      String value

      The value of this annotation attribute is taken to be the converter-id with which instances of this class of converter can be instantiated by calling Application.createConverter(java.lang.String).

      Returns:
      the converter-id
      Default:
      ""

    • forClass

      Class forClass

      The value of this annotation attribute is taken to be the converter-for-class with which instances of this class of converter can be instantiated by calling Application.createConverter(java.lang.Class).

      Returns:
      the class
      Default:
      java.lang.Object.class

    • managed

      boolean managed

      The value of this annotation attribute is taken to be an indicator that flags whether or not the given converter is a CDI managed converter.

      Returns:
      whether or not this converter is managed by CDI
      Default:
      false