jakarta.faces.application.ResourceDependency 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.application;

import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

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

/**
 * 
 * Instances of {@link jakarta.faces.component.UIComponent} or {@link jakarta.faces.render.Renderer} that have this
 * annotation (or {@link ResourceDependencies} attached at the class level will automatically have a resource dependency
 * added so that the named resource will be present in user agent's view of the UIViewRoot in which this
 * component or renderer is used.
 * 
 *
 * 
 *
 * 
 * The default implementation must support attaching this annotation to {@link jakarta.faces.component.UIComponent} or
 * {@link jakarta.faces.render.Renderer} classes. In both cases, the event that precipitates the processing of this
 * annotation is the insertion of a UIComponent instance into the view hierarchy on an initial request for
 * a view. When that event happens, the following action must be taken.
 * 
 *
 * 
 * 
 * 
 * If this annotation is not present on the class in question, no action must be taken.
 * 
 * 
 *
 * 
 * 
 * Create a {@link jakarta.faces.component.UIOutput} instance by passing jakarta.faces.Output. to
 * {@link Application#createComponent(java.lang.String)}.
 * 
 * 
 *
 * 
 * 
 * Get the annotation instance from the class and obtain the values of the name, library, and
 * target attributes.
 * 
 * 
 *
 * 
 * 
 * If library is the empty string, let library be null.
 * 
 * 
 *
 * 
 * 
 * If target is the empty string, let target be null.
 * 
 * 
 *
 * 
 * 
 * Obtain the renderer-type for the resource name by passing name to
 * {@link ResourceHandler#getRendererTypeForResourceName}.
 * 
 * 
 *
 * 
 * 
 * Call setRendererType on the UIOutput instance, passing the renderer-type.
 * 
 * 
 *
 * 
 * 
 * Obtain the Map of attributes from the UIOutput component by calling
 * {@link jakarta.faces.component.UIComponent#getAttributes}.
 * 
 * 
 *
 * 
 * 
 * Store the name into the attributes Map under the key "name".
 * 
 * 
 *
 * 
 * 
 * If library is non-null, store it under the key "library".
 * 
 * 
 *
 * 
 * 
 * If target is non-null, store it under the key "target".
 * 
 * 
 *
 * 
 * 
 * Otherwise, if target is null, call
 * {@link jakarta.faces.component.UIViewRoot#addComponentResource(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent)},
 * passing the UIOutput instance as the second argument.
 * 
 * 
 * 
 *
 * 
 * Example:
 * 
 *
 *  * 
  @ResourceDependency(library="corporate", name="colorAndMedia.css"),

 * 
 *
 *
 * 
 *
 * @since 2.0
 */
@Retention(RUNTIME)
@Target(TYPE)
@Inherited
@Repeatable(ResourceDependencies.class)
public @interface ResourceDependency {

    /**
     * 
     * The resourceName of the resource pointed to by this ResourceDependency. It is valid to have
     * Jakarta Expression Language Expressions in the value of this attribute, as long as the expression resolves to an
     * instance of the expected type.
     * 
     *
     * @return the name.
     */
    public String name();

    /**
     * 
     * The libraryName in which the resource pointed to by this ResourceDependency resides. If not
     * specified, defaults to the empty string. It is valid to have Jakarta Expression Language Expressions in the value of
     * this attribute, as long as the expression resolves to an instance of the expected type.
     * 
     *
     * @return the library.
     */
    public String library() default "";

    /**
     * 
     * The value given for this attribute will be passed as the "target" argument to
     * {@link jakarta.faces.component.UIViewRoot#addComponentResource(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent, java.lang.String)}.
     * If this attribute is specified,
     * {@link jakarta.faces.component.UIViewRoot#addComponentResource(jakarta.faces.context.FacesContext,jakarta.faces.component.UIComponent)}
     * must be called instead, as described above. It is valid to have Jakarta Expression Language Expressions in the value
     * of this attribute, as long as the expression resolves to an instance of the expected type.
     * 
     *
     * @return the target.
     */
    public String target() default "";

}