/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package javax.faces.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import javax.inject.Qualifier;

/**
 * This annotation injects a CDI proxy that points through a JSF 2.3 search expression to a valid JSF component 
 * instance. 
 * 
 * The implementation must provide an implementation of javax.enterprise.inject.spi.Extension that implements the
 * semantics such that proxy classes with this annotation are created when the bean instance is injected, and 
 * de-allocated when the bean is discarded. The proxy instances must be bound to a normal scope that is active as 
 * long as the current view is available in the current faces request. The instances can be stored in the UIViewRoot 
 * view transient map.
 * 
 * When a method of the proxy is invoked in the CDI bean, the proxy instance must use the search expression to locate
 * the real UIComponent instance in the component tree using a call to SearchExpressionHandler.resolveComponent(...),
 * passing as hint SearchExpressionHint.SKIP_VIRTUAL_COMPONENTS. The component that will be used as a source
 * reference to locate the component will be the component returned by UIComponent.getCurrentComponent(...) at the
 * moment the method is called, so the user is responsible to provide an expression that can be valid at any time 
 * the proxy component is used.
 * 
 * @since 2.3
 */
@Qualifier
@Retention(value=RetentionPolicy.RUNTIME)
@Target(value={ElementType.PARAMETER, ElementType.FIELD})
public @interface ResolveComponent
{
    /**
     * Contains the search expression used to locate the required component in the component tree.
     * 
     * @return 
     */
    public String value() default "";
}