jakarta.faces.application.ResourceDependency Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jakarta.faces Show documentation
EE4J Compatible Implementation for Jakarta Faces API
The newest version!
/*
 * 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 "";

}