001// Copyright 2008-2014 The Apache Software Foundation 002// 003// Licensed under the Apache License, Version 2.0 (the "License"); 004// you may not use this file except in compliance with the License. 005// You may obtain a copy of the License at 006// 007// http://www.apache.org/licenses/LICENSE-2.0 008// 009// Unless required by applicable law or agreed to in writing, software 010// distributed under the License is distributed on an "AS IS" BASIS, 011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 012// See the License for the specific language governing permissions and 013// limitations under the License. 014 015package org.apache.tapestry5.annotations; 016 017import java.lang.annotation.*; 018 019import static org.apache.tapestry5.ioc.annotations.AnnotationUseContext.*; 020import org.apache.tapestry5.ioc.annotations.UseWith; 021 022/** 023 * Indicates that a method should only be evaluated once per request and the result cached. 024 * Further calls to the method during the same request will return the cached result. 025 * However, if the method's component occurs more than once within an enclosing component, 026 * the cached results will be distinct for each occurrence. 027 * <p/> 028 * This annotation is commonly used on getters for component properties: 029 * <pre> 030 * @Cached 031 * Date getNow() { 032 * new Date(); 033 * } 034 * </pre> 035 * You may not apply @Cached to void methods or methods with parameters. 036 * <p/> 037 * Note that this annotation is inheritance-safe; if a subclass calls a superclass method that 038 * has @Cached then the value the subclass method gets is the cached value. 039 * <p/> 040 * The watch parameter can be passed a binding expression which will be evaluated each time the method is called. The 041 * method will then only be executed the first time it is called and after that only when the value of the binding 042 * changes. This can be used, for instance, to have the method only evaluated once per iteration of a loop by setting 043 * watch to the value or index of the loop. 044 */ 045@Target(ElementType.METHOD) 046@Retention(RetentionPolicy.RUNTIME) 047@Documented 048@UseWith({COMPONENT,MIXIN,PAGE}) 049public @interface Cached 050{ 051 /** 052 * The optional binding to watch (default binding prefix is "prop"). 053 */ 054 String watch() default ""; 055}