com.google.auto.value.extension.memoized.Memoized Maven / Gradle / Ivy

/*
 * Copyright (C) 2016 Google, Inc.
 *
 * Licensed 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 com.google.auto.value.extension.memoized;

import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.SOURCE;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

/**
 * Annotates methods in {@link com.google.auto.value.AutoValue @AutoValue} classes for which the
 * generated subclass will memoize the
 * returned value.
 *
 * Methods annotated with {@code @Memoized} cannot:
 * 

 * be {@code abstract} (except for {@link #hashCode()} and {@link #toString()}), {@code
 *     private}, {@code final}, or {@code static}
 * 
return {@code void}
 * 
have any parameters
 * 
 * 
 * If you want to memoize {@link #hashCode()} or {@link #toString()}, you can redeclare them,
 * keeping them {@code abstract}, and annotate them with {@code @Memoize}.
 *
 * 
If a {@code @Memoized} method is annotated with an annotation whose simple name is
 * {@code Nullable}, then {@code null} values will also be memoized. Otherwise, if the method
 * returns {@code null}, the overriding method will throw a {@link NullPointerException}.
 *
 * 
The overriding method uses
 * double-checked locking to
 * ensure that the annotated method is called at most once.
 *
 * 
Example
 *
 *  *   {@code @AutoValue}
 *   abstract class Value {
 *     abstract String stringProperty();
 *
 *     {@code @Memoized}
 *     String derivedProperty() {
 *       return someCalculationOn(stringProperty());
 *     }
 *   }
 *
 *   {@code @Generated}
 *   class AutoValue_Value {
 *     // …
 *
 *     private volatile String derivedProperty;
 *
 *     {@code Override}
 *     String derivedProperty() {
 *       if (derivedProperty == null) {
 *         synchronized (this) {
 *           if (derivedProperty == null) {
 *             derivedProperty = super.derivedProperty();
 *           }
 *         }
 *       }
 *       return derivedProperty;
 *     }
 *   }
 */
@Documented
@Retention(SOURCE)
@Target(METHOD)
public @interface Memoized {}