1 /* 2 * Copyright 2016 Google LLC 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package com.google.auto.value.extension.memoized; 17 18 import static java.lang.annotation.ElementType.METHOD; 19 import static java.lang.annotation.RetentionPolicy.CLASS; 20 21 import java.lang.annotation.Documented; 22 import java.lang.annotation.Retention; 23 import java.lang.annotation.Target; 24 25 /** 26 * Annotates methods in {@link com.google.auto.value.AutoValue @AutoValue} classes for which the 27 * generated subclass will <a href="https://en.wikipedia.org/wiki/Memoization">memoize</a> the 28 * returned value. 29 * 30 * <p>Methods annotated with {@code @Memoized} cannot: 31 * 32 * <ul> 33 * <li>be {@code abstract} (except for {@link #hashCode()} and {@link #toString()}), {@code 34 * private}, {@code final}, or {@code static} 35 * <li>return {@code void} 36 * <li>have any parameters 37 * </ul> 38 * 39 * <p>If you want to memoize {@link #hashCode()} or {@link #toString()}, you can redeclare them, 40 * keeping them {@code abstract}, and annotate them with {@code @Memoize}. 41 * 42 * <p>If a {@code @Memoized} method is annotated with an annotation whose simple name is {@code 43 * Nullable}, then {@code null} values will also be memoized. Otherwise, if the method returns 44 * {@code null}, the overriding method will throw a {@link NullPointerException}. 45 * 46 * <p>The overriding method uses <a 47 * href="https://errorprone.info/bugpattern/DoubleCheckedLocking">double-checked locking</a> to 48 * ensure that the annotated method is called at most once. 49 * 50 * <h3>Example</h3> 51 * 52 * <pre> 53 * {@code @AutoValue} 54 * abstract class Value { 55 * abstract String stringProperty(); 56 * 57 * {@code @Memoized} 58 * String derivedProperty() { 59 * return someCalculationOn(stringProperty()); 60 * } 61 * } 62 * 63 * {@code @Generated} 64 * class AutoValue_Value { 65 * // … 66 * 67 * private volatile String derivedProperty; 68 * 69 * {@code Override} 70 * String derivedProperty() { 71 * if (derivedProperty == null) { 72 * synchronized (this) { 73 * if (derivedProperty == null) { 74 * derivedProperty = super.derivedProperty(); 75 * } 76 * } 77 * } 78 * return derivedProperty; 79 * } 80 * }</pre> 81 */ 82 @Documented 83 @Retention(CLASS) 84 @Target(METHOD) 85 public @interface Memoized {} 86