Class Interner<E>

java.lang.Object
cloud.opencode.base.collections.specialized.Interner<E>
Type Parameters:
E - the type of objects to intern | 要驻留的对象类型
public abstract class Interner<E> extends Object
Interner - Object Interning (Pooling) Utility Interner - 对象驻留（池化）工具

Provides canonical instances of equivalent objects, similar to String.intern() but for any object type. This reduces memory usage by ensuring that only one instance of each distinct value exists.

为等价对象提供规范实例，类似于 String.intern() 但适用于任何对象类型。 通过确保每个不同值只存在一个实例来减少内存使用。

Usage Examples | 使用示例:

// Strong interner - keeps all entries
Interner<String> strongInterner = Interner.strong();
String canonical = strongInterner.intern("hello");

// Weak interner - allows garbage collection
Interner<MyClass> weakInterner = Interner.weak();
MyClass canonical = weakInterner.intern(new MyClass("data"));

// Custom equivalence
Interner<String> caseInsensitive = Interner.<String>newBuilder()
    .equivalence(Equivalence.from(
        String::equalsIgnoreCase,
        s -> s.toLowerCase().hashCode()))
    .weak()
    .build();

// With concurrency level
Interner<String> concurrent = Interner.<String>newBuilder()
    .concurrencyLevel(16)
    .strong()
    .build();

Performance | 性能特性:

  • intern: O(1) average - intern: O(1) 平均
  • Thread-safe: Yes - 线程安全: 是
  • Memory: Strong keeps all, Weak allows GC - 内存: Strong 保留所有，Weak 允许 GC

Features | 主要功能:

  • Strong and weak reference interning - 强引用和弱引用驻留
  • Custom equivalence support - 自定义等价关系支持
  • Configurable concurrency level - 可配置的并发级别
  • Automatic garbage collection for weak references - 弱引用自动垃圾回收
Since:
JDK 25, opencode-base-collections V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    Interner.Builder<E>
    Builder for creating Interner instances.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Interner()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    Function<E,E>
    asFunction()
    Creates a function that interns its input using this interner.
    abstract E
    intern(E sample)
    Returns a canonical instance for the given object.
    static <E> Interner.Builder<E>
    newBuilder()
    Creates a new interner builder.
    static <E> Interner<E>
    strong()
    Creates a strong interner that uses equals() for equivalence.
    static <E> Interner<E>
    weak()
    Creates a weak interner that uses equals() for equivalence.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Interner

      public Interner()

  • Method Details

    • intern

      public abstract E intern(E sample)
      Returns a canonical instance for the given object. 返回给定对象的规范实例。

      If an equivalent object has been interned before, returns the previously interned instance. Otherwise, interns and returns the given object.

      如果之前已驻留等价对象，则返回之前驻留的实例。否则，驻留并返回给定对象。

      Parameters:
      sample - the object to intern | 要驻留的对象
      Returns:
      the canonical instance | 规范实例
      Throws:
      NullPointerException - if sample is null | 如果 sample 为 null

    • strong

      public static <E> Interner<E> strong()
      Creates a strong interner that uses equals() for equivalence. 创建使用 equals() 进行等价判断的强驻留器。

      Strong interners keep all interned objects indefinitely.

      强驻留器无限期保留所有驻留对象。

      Type Parameters:
      E - the type | 类型
      Returns:
      a new strong interner | 新的强驻留器

    • weak

      public static <E> Interner<E> weak()
      Creates a weak interner that uses equals() for equivalence. 创建使用 equals() 进行等价判断的弱驻留器。

      Weak interners allow garbage collection of interned objects when they are no longer referenced elsewhere.

      弱驻留器允许在驻留对象不再被其他地方引用时进行垃圾回收。

      Type Parameters:
      E - the type | 类型
      Returns:
      a new weak interner | 新的弱驻留器

    • newBuilder

      public static <E> Interner.Builder<E> newBuilder()
      Creates a new interner builder. 创建新的驻留器构建器。
      Type Parameters:
      E - the type | 类型
      Returns:
      a new builder | 新的构建器

    • asFunction

      public Function<E,E> asFunction()
      Creates a function that interns its input using this interner. 创建使用此驻留器驻留其输入的函数。
      Returns:
      the interning function | 驻留函数