jakarta.faces.convert.FacesConverter Maven / Gradle / Ivy

/*
 * Copyright (c) 1997, 2020 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 jakarta.faces.convert;

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.PARAMETER;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import jakarta.enterprise.util.AnnotationLiteral;
import jakarta.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 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,
 * {@link jakarta.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 jakarta.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(RUNTIME)
@Target({ TYPE, FIELD, METHOD, 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 jakarta.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 jakarta.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;

    /**
     * 
     * Supports inline instantiation of the {@link FacesConverter} qualifier.
     * 
     *
     * @since 4.0
     */
    public static final class Literal extends AnnotationLiteral implements FacesConverter {

        private static final long serialVersionUID = 1L;

        /**
         * Instance of the {@link FacesConverter} qualifier.
         */
        public static final Literal INSTANCE = of("", Object.class, false);

        private final String value;
        private final Class forClass;
        private final boolean managed;

        public static Literal of(String value, Class forClass, boolean managed) {
            return new Literal(value, forClass, managed);
        }

        private Literal(String value, Class forClass, boolean managed) {
            this.value = value;
            this.forClass = forClass;
            this.managed = managed;
        }

        @Override
        public String value() {
            return value;
        }

        @Override
        public Class forClass() {
            return forClass;
        }

        @Override
        public boolean managed() {
            return managed;
        }
    }
}