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

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jboss-jsf-api_2.3_spec Show documentation
JSR-000372: JavaServer(TM) Faces 2.3 API
There is a newer version: 3.1.0.SP02
Show newest version
/*
 * 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.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 javax.faces.component.UIComponent} or {@link javax.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 javax.faces.component.UIComponent} or {@link javax.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 javax.faces.component.UIOutput} instance by passing
 * javax.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 javax.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 javax.faces.component.UIViewRoot#addComponentResource(javax.faces.context.FacesContext, javax.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 javax.faces.component.UIViewRoot#addComponentResource(javax.faces.context.FacesContext, javax.faces.component.UIComponent, java.lang.String)}.
     * If this attribute is specified,
     * {@link javax.faces.component.UIViewRoot#addComponentResource(javax.faces.context.FacesContext,javax.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 "";

}