Converters

Conversion is part of the request processing lifecycle (see the six phases) and it runs at both ends of a round trip:

Two consequences follow. A converter always sees the request’s locale: Faces requires converters that need a locale to take it from the UIViewRoot of the current FacesContext, so changing the locale of the view changes how numbers and dates are parsed and printed. And because validation happens on the converted value, the order of the errors on a field is always "conversion first, validation second": a field that fails conversion never reaches its validators.

The specification also asks converters to be symmetric: getAsObject(getAsString(x)) should give back a value equal to x. When that is impossible (a java.text.Format that prints two adjacent numbers with no separator, for example) the converter should at least document it.

Source: Jakarta Faces 4.1 specification, 3.3 Conversion Model and UIInput.validate() and getConvertedValue()

For each UIInput and UIOutput component Faces uses the first converter it finds in this order:

The last box of the flowchart is the one that surprises people, and it behaves differently in the two implementations; see Implicit Conversion. Select components follow the same rules, with one extra source of information for the converter: the type of the values of their f:selectItem and f:selectItems children (see Entity Converters for Select Menus).

A plain expression in the page text is not a Faces component and never uses a converter. In the scratch run <li>isbn=[#{reviewBean.isbn}]</li> printed the toString() of the record (Isbn[digits=9780306406157]), while <h:outputText value="#{reviewBean.isbn}"/> printed 978-0-306-40615-7 because h:outputText is a UIOutput and found the converter registered for Isbn.

Source: UIInput.getConvertedValue() and Jakarta EE Tutorial: Converting a Component’s Value

Faces registers a converter for every Java type that a form commonly needs. They live in the jakarta.faces.convert package, and each has a constant converter id (CONVERTER_ID):

The tutorial’s list of converter ids stops at jakarta.faces.Short; the 4.1 specification adds jakarta.faces.UUID, and the 4.1 API documents UUIDConverter with "Since: 4.1". The specification text also says "java.lang.UUID" where it means java.util.UUID, which is the class the converter handles. A compliant implementation additionally has to accept the registration of a converter for String.

Notice what is not in the table: LocalDate, LocalDateTime, Date, List, any entity or value object. They have no converter by type, so you attach one (f:convertDateTime, your own converter) or the property cannot be bound to an input field (see Implicit Conversion).

There are four ways to attach a converter to a component:

Source: Jakarta EE Tutorial: Using the Standard Converters and VDL documentation: f:converter

The tutorial says the converter attribute accepts "the identifier or the fully-qualified class name" of the converter. In the scratch run, converter="org.example.bookshelf.web.IsbnConverter" failed on both implementations (Mojarra: Named Object: ... not found, MyFaces: Could not find any registered converter-class by converterId), but that converter was registered only for its class with forClass. Use the converter id, or a binding/EL expression, and do not rely on the class name.

Implicit conversion is the by-type registration at work, and it is why a Integer bean property needs no tag at all. These are the observed results of posting the Bookshelf test page (a request-scoped bean, Mojarra 4.1.17), with the bean properties of the type shown:

The last row is a classic source of bugs. Faces by default stores an empty text field in a String property as "", so a check such as title == null never fires. Set the context parameter jakarta.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL to true in web.xml and an empty field becomes null (verified: with the parameter true the same post left title null, without it ""; see the context parameters). Bean Validation’s @NotNull and @NotBlank are the other way to express the rule; see the validators and Bean Validation pages.

f:convertNumber registers a NumberConverter (id jakarta.faces.Number) on the nearest parent component. It formats and parses numbers, currencies and percentages with java.text.NumberFormat or a DecimalFormat pattern. The attributes, from the 4.1 VDL documentation:

These outputs were produced by h:outputText with fixed numbers (default locale en_US):

Source: VDL documentation: f:convertNumber and Jakarta EE Tutorial: Using NumberConverter

Parsing is where the details matter. These were verified with bean properties Double ratio, BigDecimal amount and Long votes:

f:convertDateTime registers a DateTimeConverter (id jakarta.faces.DateTime). Since Faces 2.3 it handles the java.time types as well as java.util.Date; the type attribute chooses the formatter:

The other attributes are dateStyle and timeStyle (default, short, medium, long, full; with a java.time formatter default means medium), pattern, locale, timeZone, binding and for. When pattern is set, dateStyle, timeStyle and (for java.util.Date) type are ignored; for the java.time types the pattern is passed to DateTimeFormatter.ofPattern(pattern, locale), and for java.util.Date to SimpleDateFormat. Parsing is non-lenient: the string must match the format exactly.

Verified outputs (a Date of the epoch, rendered with timeZone="UTC", and LocalDate 2026-10-07):

Source: VDL documentation: f:convertDateTime and Jakarta EE Tutorial: Using DateTimeConverter

Four traps appear with dates, all verified:

UUIDConverter is new in Faces 4.1 (java.util.UUID properties, id jakarta.faces.UUID). A UUID bean property bound to an input field needs no tag: the value 123e4567-e89b-12d3-a456-426614174000 was converted, and zzz was rejected with "'zzz' must be a UUID. Example: 29573f55-4254-4afa-9ca6-6b5ae6c7ab6e". In Faces 4.0 and earlier the same field needs a custom converter.

EnumConverter has been available since 1.2 and converts any enum to its name() and back. It is the converter behind a menu of constants:

With getGenres() returning Genre.values() the menu rendered options whose values are the constant names (FICTION, SCIENCE, HISTORY). Posting POETRY (a value the menu never offered) produced the message "'POETRY' must be convertible to an enum from the enum that contains the constant 'POETRY'", which is also what a tampered request looks like. Labels come from itemLabel (or toString() of the constant): write the display text in a resource bundle, not in the enum’s name(), because name() is the value that travels in the form.

The upcoming Faces 5.0 lists, among its planned issues, generics for the standard converters and an EnumConverter that finds the enum type from the value expression. Both are planned changes in a milestone, not current behaviour.

Source: UUIDConverter (since 4.1) and EnumConverter

When the standard converters do not know your type, write your own. A converter is a class that implements jakarta.faces.convert.Converter<T> and its two methods:

The interface in 4.1 is generic. The class must have a public no-argument constructor (or, for a per-class converter, one that takes a Class, which is how EnumConverter receives its enum type), and a new instance is created wherever the converter is used. The specification says converters need not be thread-safe because they are only used inside one request thread, and it follows that a converter exposed as an @ApplicationScoped bean (see below) must be written to be stateless.

The Bookshelf identifies a book by its ISBN-13, which the application models as a small value type:

With forClass the converter is registered by type, so every Isbn property in the application uses it with no tag at all, in input fields and in h:outputText. Run on the form, + 978-0-306-40615-7 ` converted to `+Isbn[digits=9780306406157], the stored value was shown again as 978-0-306-40615-7, and 12345 produced the message "Not an ISBN-13" with the detail text above.

Source: Jakarta EE Tutorial: Creating and Using a Custom Converter and Converter API

Because the converter has no dependency on the container, a unit test needs no Faces runtime. The FacesContext and UIComponent arguments can be null when the converter does not use them (a converter that reads component attributes needs a real or mocked component):

The same four calls were run in a main method against the compiled converter, and printed Isbn[digits=9780306406157], null, 978-0-306-40615-7 and Not an ISBN-13 | ERROR 2; the JUnit 5 form shown here is the same code with assertions; the testing page compiles and runs the same four tests (all passed) and shows how to test a converter that reads component attributes.

Source: ConverterException API and Converter API

A converter instantiated by Faces is not a CDI bean, so @Inject does not work inside it. Run on Mojarra 4.1.17, a converter declared with the plain @FacesConverter("plainInjected") and an @Inject AuthorService field was created and called, but the field was null: the converter returned its marker for "not injected". The 4.1 API provides the fix, the managed element of the annotation: "an indicator that flags whether or not the given converter is a CDI managed converter". A managed converter is created and injected by CDI. The Bookshelf uses one to turn an author id from the form into an Author:

Source: FacesConverter.managed and Jakarta EE Tutorial: Creating a Custom Converter

The @Dependent line is not decoration. With bean-discovery-mode="annotated" in beans.xml (the mode the section’s project uses), @FacesConverter is a CDI qualifier and not a bean-defining annotation, so the class is not a bean until you give it a scope. Without it:

Add @Dependent (a new instance per use, as for ordinary converters), or use bean-discovery-mode="all". Both implementations then behaved the same. Forgetting the scope is the most common reason a managed converter "does not work"; managed validators are covered on the validators page.

A managed converter can be registered by id (as here, converter="bookshelf.author") or by type (@FacesConverter(forClass = Author.class, managed = true)); the by-type form worked for a selectOneMenu and for a selectManyCheckbox bound to a List<Author> with no converter attribute at all, on Mojarra.

Select components render a list of strings and need to map the chosen string back to the object. The selectOneMenu for the author is the standard case of an entity converter: the value of each f:selectItem is the object, the rendered option value is getAsString() (the id), and getAsObject() finds the object again from the id. How the lookup reaches a database (and why it needs a service, not a static DAO) is on the persistence page.

The menu rendered <option value="1">Ursula K. Le Guin</option> and so on, and posting 2 set the property to the Author with id 2.

Source: Jakarta EE Tutorial: Creating and Using a Custom Converter

For a List<Author>, a selectManyCheckbox or selectManyListbox has a problem: the generic type of the property is erased at run time, so Faces cannot ask the property for its element type. The API documentation for h:selectManyListbox calls it out as a subtlety of converters and collections. Name the converter on the component (converter="bookshelf.author") or register one by type. Without any converter, the selectManyCheckbox test failed with two messages: "Conversion Error setting value '2' for 'null Converter'." for a single select, and "Validation Error: Value is not valid" for the many-select, because the posted strings no longer matched the item values.

Four rules make entity converters safe:

For a generic converter that serves every entity of an application (the usual answer to "I have forty entity classes"), the OmniFaces library offers ready-made select-item converters; they are covered with that library, on the OmniFaces page.

The tutorial’s Duke’s Tutoring case study registers @FacesConverter(forClass = Guardian.class, value = "guardian") and says the forClass attribute makes it the default converter for Guardian. The API documentation says the opposite: when value is not empty, only the id registration is made. That is what happened in the scratch run: with @FacesConverter(value = "bookshelf.author", forClass = Author.class, managed = true) and no converter attribute, the selectOneMenu failed with "Conversion Error setting value '2' for 'null Converter'", so the by-type registration had not been made. Use the id and the attribute, or forClass alone.

Source: Jakarta EE Tutorial: Using a Custom Converter and VDL documentation: h:selectManyListbox

A converter reports failure by throwing jakarta.faces.convert.ConverterException. The constructors take a String or a FacesMessage (and optionally a cause). Prefer the FacesMessage form: it carries a severity, a summary and a detail. Faces catches the exception in UIInput.validate(), queues the message on the FacesContext for the client id of the component, marks the component invalid and moves on to Render Response, as the diagram at the start of this page shows. Four things are worth knowing:

This is the form the rest of the section builds on: the converters from this page combined with the template of the templating page. The bean is request-scoped to keep the example short; the scopes page explains why a real Ajax form uses a view-scoped bean.

Source: Jakarta EE Tutorial: Using the Standard Converters and Jakarta EE Tutorial: Using Ajax with Jakarta Faces

The form was loaded in a real browser (the Ajax script ran) and submitted twice. The first, invalid submission (12345 in ISBN, no author, x as rating, 07/10/2026 as date, abc as price) re-rendered the form with:

and the second, valid one (978-0-306-40615-7, author 2, rating 5, 2026-10-07, 1,234.50, tags sci-fi; classics) ended with "Saved review of 978-0-306-40615-7 by Italo Calvino, rating 5, read on 2026-10-07, paid 1234.50, tags [sci-fi, classics], genre null". The messages for the numeric-pattern failure show the pattern as the "example", which can confuse readers; set converterMessage on fields whose pattern is not obvious.

Everything that touches security in this form is on the server (see the security page for output escaping): the author id and the ISBN are untrusted input that the converters parse and check, the page never prints a user-supplied value with escape="false", and the action only runs when conversion and validation succeed.

The two implementations pass the same specification tests, and for converters they agree on the contract. The differences below were all observed by running the same files on Mojarra 4.1.17 and MyFaces 4.1.4, and they are the reason an application should be tested on the implementation it deploys:

Behaviour the two shared in the runs: the formatted output of every f:convertNumber and f:convertDateTime row above, converterMessage, a managed converter with @Dependent used by id on a menu, the custom ISBN, tag list and author converters, and a converter that is a CDI bean attached with an EL expression. The GMT default, the label text and the by-type menu lookup were run on Mojarra only.

Source: Apache MyFaces Core 4.1 and Jakarta Faces 4.1 specification, 3.3 Conversion Model

The 2.3 row follows the section’s version page; the 2.0 row and the point at which Converter became generic were not independently checked.

Conversion is covered in nearly every Faces book: the converter chapters of JavaServer Faces 2.0: The Complete Reference (Burns and Schalk), the converter recipes of the JSF 2.0 Cookbook (Leonard, including converters with parameters and converters bound to beans), the conversion and validation chapters of Mann’s JavaServer Faces in Action and of Dudney et al. The central idea (a converter maps between the string in the page and the object in the model, in both directions, in two lifecycle phases) has not changed since the first edition. These points have: