content: /*
   * DazzleConf
   * Copyright © 2025 Anand Beh
   *
   * DazzleConf is free software: you can redistribute it and/or modify
   * it under the terms of the GNU Lesser General Public License as published by
   * the Free Software Foundation, either version 3 of the License, or
   * (at your option) any later version.
   *
   * DazzleConf is distributed in the hope that it will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
   * GNU Lesser General Public License for more details.
   *
   * You should have received a copy of the GNU Lesser General Public License
   * along with DazzleConf. If not, see <https://www.gnu.org/licenses/>
   * and navigate to version 3 of the GNU Lesser General Public License.
   */
  
  package space.arim.dazzleconf.reflect;
  
  import org.apiguardian.api.API;
  import org.checkerframework.checker.nullness.qual.NonNull;
  
  import java.lang.invoke.MethodHandles;
  
  /**
   * A low-level service responsible for generating, instantiating, and invoking methods on arbitrary interface
   * implementations.
   * <p>
   * This service provides two APIs, the {@link Instantiator} and the {@link MethodMirror}. The purpose of separating
   * these interfaces is to make it easy for different reflection service implementations to re-share one or the other
   * object.
   * <p>
   * <b>API status</b>
   * <p>
   * Because of this API's status as a service provider, it may require updating to keep in sync with the library's
   * minor versions. Some minor versions might offer new features, which would need to be implemented by this interface
   * and its {@code Instantiator}/{@code MethodMirror} implementations.
   * <p>
   * If implementations of {@code ReflectionService} are not updated, they will still be compatible with the library in a
   * strict sense. Existing code will never break. However, newer features may be disabled or refuse to work.
   * <p>
   * <b>Lookup</b>
   * <p>
   * Both the methods on this interface take a {@code lookup} parameter. By default, ths library will pass a lookup
   * representing its own {@code space.arim.dazzleconf} module. If the library user specifies another lookup, it will be
   * passed instead.
   * <p>
   * Implementors can rely on this lookup having full privileged access, however. Thus, the implementor may rely on it
   * for reflective access to an interface that is to be implemented, <i>invokespecial</i> on one of its methods, or for
   * loading or defining classes implementing that interface.
   *
   */
  @API(status = API.Status.MAINTAINED)
  public interface ReflectionService {
  
      /**
       * Gets the instantiator this service provides.
       * <p>
       * The instantiator is responsible for generating and instantiating implementations of the configuration
       * interface.
       *
       * @param lookup the lookup to use for privileged access
       * @return an instantiator
       */
      @NonNull Instantiator makeInstantiator(MethodHandles.@NonNull Lookup lookup);
  
      /**
       * Gets the {@link MethodMirror} this service provides.
       * <p>
       * The method mirror is responsible for
       * <p>
       * The method mirror is supplied by this function, and it may share resources and techniques with the instantiator.
       * In particular, {@link MethodMirror#makeInvoker(Object, Class)} can be more efficient when used with objects
       * generated by the same instantiator in {@link #makeInstantiator(MethodHandles.Lookup)}.
       *
       * @param lookup the lookup to use for privileged access
       * @return a method mirror
       */
      @NonNull MethodMirror makeMethodMirror(MethodHandles.@NonNull Lookup lookup);
  
  }
  