// Copyright 2017 The Bazel Authors. All rights reserved.
//
// 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.devtools.build.lib.skyframe.serialization.autocodec;

import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

/**
 * Specifies that AutoCodec should generate a codec implementation for the annotated class. This is
 * generally only needed in the following cases:
 *
 * <ol>
 * <li>Interning work. {@link com.google.devtools.build.lib.skyframe.AspectKeyCreator.AspectKey}
 * </li>
 * <li>Non-trivial calculations and field initialization. {@link
 * com.google.devtools.build.lib.pkgcache.TestFilter} </li>
 * <li>Some paths are forbidden for DynamicCodec. {@link
 * com.google.devtools.build.lib.skyframe.serialization.AutoRegistry} </li>
 * </ol>
 *
 * <p>Example:
 *
 * <pre>{@code
 * @AutoCodec
 * class Target {
 * }</pre>
 *
 * The {@code _AutoCodec} suffix is added to the {@code Target} to obtain the generated class name.
 * In the example, that results in a class named {@code Target_AutoCodec} but applications should
 * not need to directly access the generated class.
 */
@Target(ElementType.TYPE)
public @interface AutoCodec {
  // AutoCodec works by determining a unique *instantiator*, either a constructor or factory method,
  // to serve as a specification for serialization. The @AutoCodec.Instantiator tag can be helpful
  // for marking a specific instantiator.
  //
  // AutoCodec inspects the parameters of the instantiator and finds fields of the class
  // corresponding in both name and type. For serialization, it generates code that reads those
  // fields using reflection. For deserialization it generates code to invoke the instantiator.

  /**
   * Marks a specific method to use as the instantiator.
   *
   * <p>This marking is required when the class has more than one constructor.
   *
   * <p>Indicates an instantiator, either a constructor or factory method, for codec generation. A
   * compile-time error will result if multiple methods are thus tagged.
   */
  @Target({ElementType.CONSTRUCTOR, ElementType.METHOD})
  @interface Instantiator {}

  /**
   * Marks a static method to use for interning.
   *
   * <p>The method must accept an instance of the enclosing {@code AutoCodec} tagged class and
   * return an instance of the tagged class.
   */
  @Target({ElementType.METHOD})
  @interface Interner {}

  /**
   * Checks whether or not this class is allowed to be serialized. See {@link
   * com.google.devtools.build.lib.skyframe.serialization.SerializationContext#checkClassExplicitlyAllowed}.
   */
  boolean checkClassExplicitlyAllowed() default false;

  /**
   * Adds an explicitly allowed class for this serialization session. See {@link
   * com.google.devtools.build.lib.skyframe.serialization.SerializationContext#addExplicitlyAllowedClass}.
   */
  Class<?>[] explicitlyAllowClass() default {};
}