Module jdk.dynalink
Package jdk.dynalink.linker

# Interface GuardingTypeConverterFactory

public interface GuardingTypeConverterFactory
Optional interface that can be implemented by `GuardingDynamicLinker` implementations to provide language-specific type conversion capabilities. Note that if you implement this interface, you will very likely want to implement `ConversionComparator` interface too, as your additional language-specific conversions, in absence of a strategy for prioritizing these conversions, will cause more ambiguity for `BeansLinker` in selecting the correct overload when trying to link to an overloaded Java method.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `GuardedInvocation`
  `convertToType(Class<?> sourceType, Class<?> targetType, Supplier<MethodHandles.Lookup> lookupSupplier)`
  Returns a guarded type conversion that receives a value of the specified source type and returns a value converted to the specified target type.

- ## Method Details

  - ### convertToType

    GuardedInvocation convertToType(Class<?> sourceType, Class<?> targetType, Supplier<MethodHandles.Lookup> lookupSupplier) throws Exception
    Returns a guarded type conversion that receives a value of the specified source type and returns a value converted to the specified target type. Value types can be either primitives or reference types, including interfaces, so you can even provide converters for converting your language's objects to Java interfaces and classes by generating adapters for them.

    The type of the invocation is `(sourceType)→targetType`, while the type of the guard is `(sourceType)→boolean`. You are allowed to return unconditional invocations (with no guard) if the source type is specific to your runtime and your runtime only.

    Note that this method will never be invoked for `method invocation conversions` as those can be automatically applied by `MethodHandle.asType(MethodType)`. An implementation can assume it is never requested to produce a converter for those conversions. If a language runtime needs to customize method invocation conversions, it should `set an autoconversion strategy in the dynamic linker factory` instead.

    Dynalink is at liberty to either cache some of the returned converters or to repeatedly request the converter factory to create the same conversion.

    Parameters:
      `sourceType` - source type
      `targetType` - the target type.
      `lookupSupplier` - a supplier for retrieving the lookup of the class on whose behalf a type converter is requested. When a converter is requested as part of linking an `invokedynamic` instruction the supplier will return the lookup passed to the bootstrap method, otherwise if the method is invoked from within a `LinkerServices.getWithLookup(Supplier, jdk.dynalink.SecureLookupSupplier)` it will delegate to the secure lookup supplier. In any other case, it will return the public lookup. A typical case where the lookup might be needed is when the converter creates a Java adapter class on the fly (e.g. to convert some object from the dynamic language into a Java interface for interoperability). Invoking the `Supplier.get()` method on the passed supplier will be subject to the same security checks as `SecureLookupSupplier.getLookup()`. An implementation should avoid retrieving the lookup if it is not needed so as to avoid the expense of `AccessController.doPrivileged` call.
    Returns:
      a guarded invocation that can take an object (if it passes guard) and return another object that is its representation coerced into the target type. In case the factory is certain it is unable to handle a conversion, it can return null. In case the factory is certain that it can always handle the conversion, it can return an unconditional invocation (one whose guard is null).
    Throws:
      `Exception` - if there was an error during creation of the converter
    See Also:
      - `LinkerServices.getWithLookup(Supplier, SecureLookupSupplier)`