Package org.mapstruct.ap.internal.util

Class NullabilityResolver

java.lang.Object
org.mapstruct.ap.internal.util.NullabilityResolver
public class NullabilityResolver extends Object
Resolver for JSpecify nullness annotations on elements, used to decide whether a null check is required for a source-to-target property mapping.

A single instance is created per annotation-processor run and carries the enabled flag derived from the mapstruct.disableJSpecify option. When disabled, all public entry points short-circuit to NullabilityResolver.Nullability.UNKNOWN / null, which causes downstream callers to fall back to the pre-JSpecify NullValueCheckStrategy-based behavior.

Author:
Filip Hrisafov

  • Constructor Details

    • NullabilityResolver

      public NullabilityResolver(boolean enabled)

  • Method Details

    • getNullability

      public NullabilityResolver.Nullability getNullability(Element element, BooleanSupplier enclosingTypeNullMarked)
      Determines the nullability of an accessor element based on JSpecify annotations.

      For getter methods (ExecutableElement), this checks the return type's annotations since JSpecify annotations are TYPE_USE annotations placed on the return type. For setter parameters (VariableElement), this checks the parameter type's annotations. For fields (VariableElement), this checks the field type's annotations.

      If no direct annotation is found, the method walks the enclosing element chain looking for a method-level @NullMarked / @NullUnmarked. If nothing is found there either, enclosingTypeNullMarked is consulted — when it returns true, unannotated types are effectively @NonNull. The supplier is invoked at most once.

      When this resolver is disabled, NullabilityResolver.Nullability.UNKNOWN is returned without any inspection — the supplier is not invoked.

      Parameters:
      element - the accessor element to inspect (getter method, setter parameter, or field); may be null in which case NullabilityResolver.Nullability.UNKNOWN is returned
      enclosingTypeNullMarked - supplier for whether the enclosing bean type is in a @NullMarked scope; must be non-null
      Returns:
      the nullability state

    • getSetterNullability

      public NullabilityResolver.Nullability getSetterNullability(Element element, BooleanSupplier enclosingTypeNullMarked)
      Determines the nullability of a write-accessor element — either a setter method or a field.

      For setter methods (ExecutableElement) the nullability annotation lives on the parameter type, not on the method itself, so the first parameter's nullability is returned. For fields (or any other element type) the element's own type nullability is returned.

      Parameters:
      element - the write-accessor element (setter or field); may be null in which case NullabilityResolver.Nullability.UNKNOWN is returned
      enclosingTypeNullMarked - supplier for whether the enclosing bean type is in a @NullMarked scope; must be non-null
      Returns:
      the nullability state of the setter's parameter or of the field

    • requiresNullCheck

      public Boolean requiresNullCheck(NullabilityResolver.Nullability sourceNullability, NullabilityResolver.Nullability targetNullability)
      Determines whether a null check is required for a property mapping based on JSpecify annotations on the source and target elements.

      Only returns a non-null decision for the clear-cut cases: source @NonNull (skip check) or target @NonNull (always check). All other cases return null to defer to the existing NullValueCheckStrategy.

      Parameters:
      sourceNullability - the nullability of the source (getter return type / parameter)
      targetNullability - the nullability of the target (setter parameter / field)
      Returns:
      Boolean.TRUE if a null check is needed, Boolean.FALSE if it should be skipped, or null if JSpecify annotations are not present and the existing strategy should be used