Module jdk.dynalink
Package jdk.dynalink

Class DynamicLinkerFactory

java.lang.Object
jdk.dynalink.DynamicLinkerFactory
public final class DynamicLinkerFactory extends Object
一个用于创建 DynamicLinker 对象的工厂类。动态链接器是 Dynalink 中的核心对象；它们由几个 GuardingDynamicLinker 对象组成，并协调调用站点与它们的链接。通常的动态链接器是一个链接器，由工厂的用户明确预先创建的所有 GuardingDynamicLinker 对象组成，并配置了 setPrioritizedLinkers(List)，以及任何 自动发现的 链接器，最后是配置了 setFallbackLinkers(List) 的链接器；这最后一类通常包括 BeansLinker。

  • Constructor Details

    • DynamicLinkerFactory

      public DynamicLinkerFactory()
      创建一个具有默认配置的新动态链接器工厂。创建后，可以使用各种 setXxx() 方法对工厂进行配置，并根据其当前配置使用 createLinker() 创建一个或多个动态链接器。

  • Method Details

    • setClassLoader

      public void setClassLoader(ClassLoader classLoader)
      设置用于自动发现可用的守卫动态链接器的类加载器。通过此类加载器可用的 GuardingDynamicLinkerExporter 实现将通过 ServiceLoader 机制自动实例化，并且它们提供的链接器将被合并到此工厂创建的 DynamicLinker 中。这允许跨语言互操作性，如果将其本机对象传递给此运行时，则属于此语言运行时的调用站点可以由这些自动发现的运行时的链接器进行链接。如果未显式通过调用此方法设置类加载器，则将使用调用 createLinker() 的线程的线程上下文类加载器。如果显式调用此方法并传递 null，则将使用 ServiceLoader.loadInstalled(Class) 来加载链接器。
      参数:
      classLoader - 用于自动发现可用链接器的类加载器。

    • setPrioritizedLinkers

      public void setPrioritizedLinkers(List<? extends GuardingDynamicLinker> prioritizedLinkers)
      设置优先守卫动态链接器。使用 Dynalink 的语言运行时通常至少会有一个适用于其自身语言的链接器。当动态链接器在链接调用站点时，首先将由结果动态链接器咨询这些链接器，然后再咨询任何自动发现的和回退链接器。如果工厂还自动发现与优先链接器之一匹配的链接器类，则将忽略自动发现的类，并使用显式优先实例。
      参数:
      prioritizedLinkers - 优先链接器的列表。可以为 null。
      抛出:
      NullPointerException - 如果列表中的任何元素为 null。

    • setPrioritizedLinkers

      public void setPrioritizedLinkers(GuardingDynamicLinker... prioritizedLinkers)
      设置优先守卫动态链接器。等同于使用 Arrays.asList(prioritizedLinkers) 调用 setPrioritizedLinkers(List)。
      参数:
      prioritizedLinkers - 优先链接器的数组。可以为 null。
      抛出:
      NullPointerException - 如果数组中的任何元素为 null。

    • setPrioritizedLinker

      public void setPrioritizedLinker(GuardingDynamicLinker prioritizedLinker)
      设置单个优先链接器。等同于使用单元素列表调用 setPrioritizedLinkers(List)。
      参数:
      prioritizedLinker - 单个优先链接器。不得为 null。
      抛出:
      NullPointerException - 如果传递了 null。

    • setFallbackLinkers

      public void setFallbackLinkers(List<? extends GuardingDynamicLinker> fallbackLinkers)
      设置回退守卫动态链接器。当动态链接器在链接调用站点时，将在自动发现和优先链接器之后最后咨询这些链接器。如果工厂还自动发现与回退链接器之一匹配的链接器类，则将忽略自动发现的类，并使用显式回退实例。
      参数:
      fallbackLinkers - 回退链接器的列表。可以为空以指示调用方希望不设置回退链接器。请注意，如果未显式调用此方法或传递 null，则工厂将创建一个 BeansLinker 实例作为默认回退链接器。
      抛出:
      NullPointerException - 如果列表中的任何元素为 null。

    • setFallbackLinkers

      public void setFallbackLinkers(GuardingDynamicLinker... fallbackLinkers)
      设置回退守卫动态链接器。等同于使用 Arrays.asList(fallbackLinkers) 调用 setFallbackLinkers(List)。
      参数:
      fallbackLinkers - 回退链接器的数组。可以为空以指示调用方希望不设置回退链接器。请注意，如果未显式调用此方法或传递 null，则工厂将创建一个 BeansLinker 实例作为默认回退链接器。
      抛出:
      NullPointerException - 如果数组中的任何元素为 null。

    • setSyncOnRelink

      public void setSyncOnRelink(boolean syncOnRelink)
      设置此工厂创建的动态链接器是否在重新链接调用站点后调用 MutableCallSite.syncAll(MutableCallSite[])。默认为 false。如果您的运行时支持动态链接代码的多线程执行，则可能希望将其设置为 true。
      参数:
      syncOnRelink - true 表示在重新链接时调用同步，否则为 false。

    • setUnstableRelinkThreshold

      public void setUnstableRelinkThreshold(int unstableRelinkThreshold)
      设置不稳定的重新链接阈值；调用站点重新链接的次数超过该阈值后，将被视为不稳定，并随后对其进行的链接请求将指示此情况。当未明确设置时，默认为 8。
      参数:
      unstableRelinkThreshold - 新的阈值。不得小于零。零的值表示调用站点永远不会被视为不稳定。
      参见:

    • setPrelinkTransformer

      public void setPrelinkTransformer(GuardedInvocationTransformer prelinkTransformer)
      设置预链接转换器。这是一个在组件链接器创建受保护调用之后、在动态链接器将其链接到调用站点之前最后有机会修改受保护调用的 GuardedInvocationTransformer。通常用于将调用的返回值类型适应为调用站点的类型。当未明确设置时，将使用一个默认的预链接转换器，该转换器简单地调用 GuardedInvocation.asType(LinkerServices, MethodType)。定制的预链接转换器很少需要；它们主要用作实现高级技术的构建块，例如代码去优化策略。
      参数:
      prelinkTransformer - 动态链接器的预链接转换器。可以为 null，以便工厂使用默认转换器。

    • setAutoConversionStrategy

      public void setAutoConversionStrategy(MethodTypeConversionStrategy autoConversionStrategy)
      设置表示自动类型转换转换策略的对象。在LinkerServices.asType(MethodHandle, MethodType)应用了所有自定义转换到方法句柄后，仍然需要对方法调用转换进行处理，通常可以根据MethodHandle.asType(MethodType)自动应用。然而，有时语言运行时会希望为自己的调用站点定制甚至这些转换。一个典型的例子是允许对空返回值进行拆箱，这在普通的MethodHandles.asType()中默认是被禁止的。在这种情况下，语言运行时可以安装自己的自定义自动转换策略，可以处理空值。请注意，当策略的MethodTypeConversionStrategy.asType(MethodHandle, MethodType)被调用时，自定义语言转换将已经应用于方法句柄，因此按设计，句柄当前的方法类型与期望的最终类型之间的差异将始终只有可以接受方法调用转换的部分。该策略还不需要调用最终的MethodHandle.asType()，因为这将在内部作为最后一步完成。
      参数:
      autoConversionStrategy - 为此工厂创建的链接器应用方法调用转换的策略。如果不需要自定义策略，则可以为null。

    • setInternalObjectsFilter

      public void setInternalObjectsFilter(MethodHandleTransformer internalObjectsFilter)
      设置一个方法句柄转换器，该转换器应该充当LinkerServices.filterInternalObjects(MethodHandle)的实现，用于由此工厂创建的动态链接器的链接器服务。一些语言运行时可能有不应逃逸其范围的内部对象。它们可以在这里添加一个转换器，该转换器将修改方法句柄，以便任何可能接收内部语言运行时对象的参数都将在其上添加一个过滤器，以防止它们逃逸，可能通过包装它们。该转换器还可以在返回值上潜在地添加一个解包过滤器。DefaultInternalObjectFilter作为一个方便的类，用于轻松创建这种过滤转换器。
      参数:
      internalObjectsFilter - 过滤掉内部对象的方法句柄转换器，或为null。

    • createLinker

      public DynamicLinker createLinker()
      根据当前配置创建一个新的动态链接器。可以多次调用此方法以创建多个动态链接器。在每次调用此方法时，自动发现的链接器都会被新实例化。允许在调用之间更改工厂的配置。该方法不是线程安全的。调用后，调用者可以调用getAutoLoadingErrors()来检索在尝试加载自动发现的链接器时发生的ServiceConfigurationError列表。这些错误从此方法的调用中永远不会抛出，因为它会尽一切努力从中恢复并忽略失败的链接器。
      返回:
      新的动态链接器

    • getAutoLoadingErrors

      public List<ServiceConfigurationError> getAutoLoadingErrors()
      返回在上次调用createLinker()时加载自动发现的链接器时遇到的ServiceConfigurationError列表。它们可以是任何非Dynalink特定的服务配置问题，以及一些Dynalink特定的错误，当工厂尝试自动加载的导出器：
      返回:
      遇到的ServiceConfigurationError的不可变列表。可能为空。