javax.faces.convert.FacesConverter Maven / Gradle / Ivy
Show all versions of jakarta.faces Show documentation
/*
* Copyright (c) 1997, 2018 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package javax.faces.convert;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.annotation.Inherited;
import javax.inject.Qualifier;
/**
* The presence of this annotation
* on a class automatically registers the class with the runtime as a
* {@link Converter}. The value of the {@link #value} attribute is
* taken to be converter-id, the value of the {@link #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
* JSF.11.5, the proper variant of
* Application.addConverter() is called. If
* converter-id is not the empty string, {@link
* javax.faces.application.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, {@link
* javax.faces.application.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 {@code @FacesConverter} annotation to
* register a single {@code Converter} implementation both in the {@code
* by-class} and the {@code 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 {@code @FacesConverter} annotation,
* and derive two sub-classes, each with a {@code @FacesConverter}
* annotation. One sub-class has a {@code value} attribute but no
* {@code forClass} attribute, and the other sub-class has the converse.
* Please see the ViewDeclarationLanguage documentation for {@code
* } for another important subtlety regarding
* converters and collections.
*
*
*/
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
@Inherited
@Qualifier
public @interface FacesConverter {
/**
* 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 {@link
* javax.faces.application.Application#createConverter(java.lang.String)}.
*
* @return the converter-id
*/
String value() default "";
/**
* 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 {@link
* javax.faces.application.Application#createConverter(java.lang.Class)}.
*
* @return the class
*/
Class forClass() default Object.class;
/**
* 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.
*
* @return whether or not this converter is managed by CDI
*/
boolean managed() default false;
}