Annotation Type Placeholder


@Target(METHOD) @Retention(SOURCE) public @interface Placeholder
Annotation to indicate a placeholder method.

A placeholder method is an abstract method in a Refaster template class which can represent an arbitrary expression (if the return type is nonvoid), or zero or more statements (if the return type is void), in terms of its arguments. For example,


 abstract class ComputeIfAbsent<K, V> {
  @Placeholder abstract V computeValue(K key);

  @BeforeTemplate void getOrCompute(Map<K, V> map, K key) {
     V value = map.get(key);
     if (value == null) {
       map.put(key, value = computeValue(key));
     }
   }

  @AfterTemplate void computeIfAbsent(Map<K, V> map, K key) {
     V value = map.computeIfAbsent(key, (K k) -> computeValue(k));
   }
 }
 

Here, computeValue represents an arbitrary expression in terms of key, and the @AfterTemplate rewrites that same expression in terms of the parameter of a lambda expression.

For a multi-line example, consider


 abstract class TryWithResources<T extends AutoCloseable> {
  @Placeholder abstract T open();
  @Placeholder void process(T resource);

  @BeforeTemplate void tryFinallyClose() {
     T resource = open();
     try {
       process(resource);
     } finally {
       resource.close();
     }
   }

  @AfterTemplate void tryWithResource() {
     try (T resource = open()) {
       process(resource);
     }
   }
 }
 

Here, process is any block, though it must refer to resource in some way; it is not permitted to reassign the contents of resource.

Placeholder methods are not permitted to refer to any local variables or parameters of the @BeforeTemplate that are not passed to them as arguments. Additionally, they must contain references to all arguments that are passed to them -- except those corresponding to parameters annotated with MayOptionallyUse.

Author:
lowasser@google.com (Louis Wasserman)
  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    Identifies whether the placeholder is allowed to match an expression which simply returns one of the placeholder arguments unchanged.
  • Element Details

    • allowsIdentity

      boolean allowsIdentity
      Identifies whether the placeholder is allowed to match an expression which simply returns one of the placeholder arguments unchanged.
      Default:
      false