Class VirtualField<T,F>

java.lang.Object
io.opentelemetry.instrumentation.api.util.VirtualField<T,F>
Type Parameters:
T - The type that will contain the new virtual field.
F - The field type that'll be added to T.

public abstract class VirtualField<T,F> extends Object
Represents a "virtual" field of type F that is added to type T in the runtime.

A virtual field has similar semantics to a weak-keys strong-values map: the value will be garbage collected when their owner instance is collected. It is discouraged to use a virtual field for keeping values that might reference their key, as it may cause memory leaks.

  • Constructor Details

    • VirtualField

      public VirtualField()
  • Method Details

    • find

      public static <U extends T, V extends F, T, F> VirtualField<U,V> find(Class<T> type, Class<F> fieldType)
      Finds a VirtualField instance for given type and fieldType.

      In runtime, when using the javaagent, the calls to this method are rewritten to something more performant while injecting inline advice into a method. This rewriting is not performed for non-inline advice. Users are advised not to rely on agent automatically rewriting the virtual field usages and instead look up VirtualField once and stored in a field to avoid repeatedly calling this method. Rewriting calls to this method may be removed in a future agent release.

      Parameters:
      type - The type that will contain the new virtual field.
      fieldType - The field type that will be added to type.
      See Also:
    • find

      public static <U extends T, V extends F, T, F> VirtualField<U,V> find(Class<T> type, Class<F> fieldType, String fieldName)
      Finds a VirtualField instance for given type, fieldType and fieldName.

      Conceptually this can be thought of as adding a field with name fieldName to class type with type fieldType. Alternatively this can be viewed as a map where an object of type type is associated with another map where they key is composed of fieldName and fieldType and the value is the value of the virtual field.

      Calls to this method may be expensive, caller should keep the returned VirtualField and reuse it instead of repeatedly calling this method.

      Unlike calls to find(Class, Class) calls to this method are never rewritten.

      Parameters:
      type - The type that will contain the new virtual field.
      fieldType - The field type that will be added to type.
      fieldName - The name of the virtual field.
    • get

      @Nullable public abstract F get(T object)
      Gets the value of this virtual field.
    • set

      public abstract void set(T object, @Nullable F fieldValue)
      Sets the new value of this virtual field.