Package org.codehaus.groovy.transform

# Class AbstractASTTransformation

java.lang.Object
org.codehaus.groovy.transform.AbstractASTTransformation

All Implemented Interfaces:
  `ASTTransformation`, `ErrorCollecting`

Direct Known Subclasses:
  `ActiveObjectASTTransformation`, `AutoCloneASTStubber`, `AutoCloneASTTransformation`, `AutoFinalASTTransformation`, `AutoImplementASTStubber`, `AutoImplementASTTransformation`, `BaseScriptASTTransformation`, `BindableASTStubber`, `BuilderASTStubber`, `BuilderASTTransformation`, `DelegateASTStubber`, `DelegateASTTransformation`, `EqualsAndHashCodeASTStubber`, `EqualsAndHashCodeASTTransformation`, `ExternalizeMethodsASTStubber`, `ExternalizeMethodsASTTransformation`, `ExternalizeVerifierASTTransformation`, `FinalASTStubber`, `FinalASTTransformation`, `GinqASTTransformation`, `ImmutableASTTransformation`, `IndexedPropertyASTStubber`, `IndexedPropertyASTTransformation`, `InheritConstructorsASTStubber`, `InheritConstructorsASTTransformation`, `LazyASTStubber`, `LazyASTTransformation`, `LogASTTransformation`, `MapConstructorASTStubber`, `MapConstructorASTTransformation`, `MemoizedASTTransformation`, `MixinASTTransformation`, `NamedVariantASTStubber`, `NamedVariantASTTransformation`, `NonSealedASTTransformation`, `NotYetImplementedASTTransformation`, `NullCheckASTTransformation`, `PackageScopeASTTransformation`, `ReadWriteLockASTTransformation`, `RecordBaseASTStubber`, `RecordCompletionASTTransformation`, `RecordTypeASTTransformation`, `SealedASTTransformation`, `SealedCompletionASTTransformation`, `SingletonASTStubber`, `SingletonASTTransformation`, `SortableASTStubber`, `SortableASTTransformation`, `SourceURIASTTransformation`, `SynchronizedASTTransformation`, `TailRecursiveASTTransformation`, `ToStringASTStubber`, `ToStringASTTransformation`, `TraitASTTransformation`, `TupleConstructorASTStubber`, `TupleConstructorASTTransformation`, `VetoableASTStubber`

public abstract class AbstractASTTransformation extends Object implements ASTTransformation, ErrorCollecting
Abstract base class for AST transformations.

Provides utility methods for extracting annotation members, validating properties/fields, and filtering members based on include/exclude specifications.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final ClassNode`
  `RETENTION_CLASSNODE`
  A shared ClassNode representing the `Retention` annotation.
  `protected SourceUnit`
  `sourceUnit`
  The source unit associated with the compilation context.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AbstractASTTransformation()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addError(String msg, ASTNode node)`
  Records a transformation error message associated with an AST node.
  `protected boolean`
  `checkIncludeExcludeUndefinedAware(AnnotationNode node, List<String> excludes, List<String> includes, String typeName)`
  Validates that only one of 'includes' or 'excludes' is specified, not both.
  `protected void`
  `checkIncludeExcludeUndefinedAware(AnnotationNode node, List<String> excludes, List<String> includes, List<ClassNode> excludeTypes, List<ClassNode> includeTypes, String typeName)`
  Validates that only one filtering list is specified among 'includes', 'excludes', 'includeTypes', and 'excludeTypes'.
  `protected boolean`
  `checkNotInterface(ClassNode cNode, String annotationName)`
  Validates that the target class node is not an interface.
  `boolean`
  `checkPropertyList(ClassNode cNode, List<String> propertyNameList, String listName, AnnotationNode anno, String typeName, boolean includeFields)`
  Validates that all property names in the given list exist in the target class.
  `boolean`
  `checkPropertyList(ClassNode cNode, List<String> propertyNameList, String listName, AnnotationNode anno, String typeName, boolean includeFields, boolean includeSuperProperties, boolean allProperties)`
  Validates that all property names in the given list exist in the target class.
  `boolean`
  `checkPropertyList(ClassNode cNode, List<String> propertyNameList, String listName, AnnotationNode anno, String typeName, boolean includeFields, boolean includeSuperProperties, boolean allProperties, boolean includeSuperFields, boolean includeStatic)`
  Validates that all property names in the given list exist in the target class.
  `protected List<AnnotationNode>`
  `copyAnnotatedNodeAnnotations(AnnotatedNode annotatedNode, String myTypeName)`
  Copies all `candidateAnnotations` with retention policy `RetentionPolicy.RUNTIME` and `RetentionPolicy.CLASS`.
  `protected List<AnnotationNode>`
  `copyAnnotatedNodeAnnotations(AnnotatedNode annotatedNode, String myTypeName, boolean includeGenerated)`
  Copies all `candidateAnnotations` with retention policy `RetentionPolicy.RUNTIME` and `RetentionPolicy.CLASS`.
  `static boolean`
  `deemedInternal(AnnotatedNode node)`
  `static boolean`
  `deemedInternalName(String name)`
  Determines whether a name is considered internal and should typically be excluded.
  `String`
  `getAnnotationName()`
  If the transform is associated with a single annotation, returns a name suitable for displaying in error messages.
  `List<ClassNode>`
  `getMemberClassList(AnnotationNode anno, String name)`
  Retrieves a list of ClassNode values from a list-type annotation member.
  `ClassNode`
  `getMemberClassValue(AnnotationNode node, String name)`
  Retrieves the ClassNode value of an annotation member.
  `ClassNode`
  `getMemberClassValue(AnnotationNode node, String name, ClassNode defaultValue)`
  Retrieves the ClassNode value of an annotation member with a default fallback.
  `int`
  `getMemberIntValue(AnnotationNode node, String name)`
  Retrieves the integer value of an annotation member.
  `static List<String>`
  `getMemberStringList(AnnotationNode anno, String name)`
  Retrieves a list of string values from a list-type annotation member.
  `static String`
  `getMemberStringValue(AnnotationNode node, String name)`
  Retrieves the string value of an annotation member.
  `static String`
  `getMemberStringValue(AnnotationNode node, String name, String defaultValue)`
  Retrieves the string value of an annotation member with a default fallback.
  `Object`
  `getMemberValue(AnnotationNode node, String name)`
  Retrieves the value of an annotation member that is a constant expression.
  `boolean`
  `hasAnnotation(ClassNode node, ClassNode annotation)`
  Checks whether a class node has a specific annotation.
  `protected void`
  `init(ASTNode[] nodes, SourceUnit sourceUnit)`
  Initializes the transformation with the annotation and source unit context.
  `static void`
  `markAsInternal(AnnotatedNode node)`
  `boolean`
  `memberHasValue(AnnotationNode node, String name, Object value)`
  Checks whether an annotation member has a specific value.
  `static boolean`
  `shouldSkip(String name, List<String> excludes, List<String> includes)`
  Determines whether a name should be skipped based on include/exclude filters.
  `static boolean`
  `shouldSkip(String name, List<String> excludes, List<String> includes, boolean allNames)`
  Determines whether a name should be skipped based on include/exclude filters.
  `static boolean`
  `shouldSkip(AnnotatedNode node, List<String> excludes, List<String> includes, boolean allNames)`
  Variant that checks both the name and `@Internal` annotation.
  `static boolean`
  `shouldSkipOnDescriptorUndefinedAware(boolean checkReturn, Map genericsSpec, MethodNode mNode, List<ClassNode> excludeTypes, List<ClassNode> includeTypes)`
  Determines whether a method should be skipped based on method descriptor matching against include/exclude type lists.
  `static boolean`
  `shouldSkipUndefinedAware(String name, List<String> excludes, List<String> includes)`
  Determines whether a name should be skipped based on include/exclude filters and the undefined marker semantics.
  `static boolean`
  `shouldSkipUndefinedAware(String name, List<String> excludes, List<String> includes, boolean allNames)`
  Determines whether a name should be skipped based on include/exclude filters with support for the undefined marker semantics.
  `static boolean`
  `shouldSkipUndefinedAware(AnnotatedNode node, List<String> excludes, List<String> includes, boolean allNames)`
  Variant that checks both the name and `@Internal` annotation.
  `static List<String>`
  `tokenize(String rawExcludes)`
  Tokenizes a string into a list of individual tokens using comma and space as delimiters.

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface org.codehaus.groovy.transform.ASTTransformation

  `visit`

- ## Field Details

  - ### RETENTION_CLASSNODE

    public static final ClassNode RETENTION_CLASSNODE
    A shared ClassNode representing the `Retention` annotation. Used for checking retention policy of annotations during AST transformation.

  - ### sourceUnit

    protected SourceUnit sourceUnit
    The source unit associated with the compilation context. Provides access to error collection and source file information during AST transformation.

- ## Constructor Details

  - ### AbstractASTTransformation

    public AbstractASTTransformation()

- ## Method Details

  - ### copyAnnotatedNodeAnnotations

    protected List<AnnotationNode> copyAnnotatedNodeAnnotations(AnnotatedNode annotatedNode, String myTypeName)
    Copies all `candidateAnnotations` with retention policy `RetentionPolicy.RUNTIME` and `RetentionPolicy.CLASS`.

    Annotations with `GeneratedClosure` members are not supported for now.

  - ### copyAnnotatedNodeAnnotations

    protected List<AnnotationNode> copyAnnotatedNodeAnnotations(AnnotatedNode annotatedNode, String myTypeName, boolean includeGenerated)
    Copies all `candidateAnnotations` with retention policy `RetentionPolicy.RUNTIME` and `RetentionPolicy.CLASS`.

    Annotations with `GeneratedClosure` members are not supported for now.

  - ### getAnnotationName

    public String getAnnotationName()
    If the transform is associated with a single annotation, returns a name suitable for displaying in error messages.
    Returns:
      The simple name of the annotation including the "@" or null if no such name is defined

  - ### init

    protected void init(ASTNode[] nodes, SourceUnit sourceUnit)
    Initializes the transformation with the annotation and source unit context. This method must be called before the transformation processes any AST nodes.
    Parameters:
      `nodes` - An array containing exactly 2 elements: the first must be an AnnotationNode specifying the annotation driving the transformation, and the second must be an AnnotatedNode to which the annotation is applied.
      `sourceUnit` - The source compilation unit providing error collection and source info
    Throws:
      `GroovyBugError` - if nodes is null, has wrong size, or wrong element types

  - ### memberHasValue

    public boolean memberHasValue(AnnotationNode node, String name, Object value)
    Checks whether an annotation member has a specific value.
    Parameters:
      `node` - the annotation node to check
      `name` - the name of the annotation member
      `value` - the expected value to match against
    Returns:
      true if the member exists and is a ConstantExpression with the given value

  - ### getMemberValue

    public Object getMemberValue(AnnotationNode node, String name)
    Retrieves the value of an annotation member that is a constant expression.
    Parameters:
      `node` - the annotation node to query
      `name` - the name of the annotation member
    Returns:
      the constant value of the member, or null if the member doesn't exist or is not a ConstantExpression

  - ### getMemberStringValue

    public static String getMemberStringValue(AnnotationNode node, String name, String defaultValue)
    Retrieves the string value of an annotation member with a default fallback. Returns the default value if the member is undefined (see `Undefined`).
    Parameters:
      `node` - the annotation node to query
      `name` - the name of the annotation member
      `defaultValue` - the value to return if the member is missing or undefined
    Returns:
      the string value of the member, or the default value if the member is undefined or not a ConstantExpression

  - ### getMemberStringValue

    public static String getMemberStringValue(AnnotationNode node, String name)
    Retrieves the string value of an annotation member. This is a convenience overload that calls `getMemberStringValue(AnnotationNode, String, String)` with null as the default value.
    Parameters:
      `node` - the annotation node to query
      `name` - the name of the annotation member
    Returns:
      the string value of the member, or null if the member is missing or undefined

  - ### getMemberIntValue

    public int getMemberIntValue(AnnotationNode node, String name)
    Retrieves the integer value of an annotation member.
    Parameters:
      `node` - the annotation node to query
      `name` - the name of the annotation member
    Returns:
      the integer value if the member is a ConstantExpression holding an Integer, otherwise 0

  - ### getMemberClassValue

    public ClassNode getMemberClassValue(AnnotationNode node, String name)
    Retrieves the ClassNode value of an annotation member. This is a convenience overload that calls `getMemberClassValue(AnnotationNode, String, ClassNode)` with null as the default value.
    Parameters:
      `node` - the annotation node to query
      `name` - the name of the annotation member
    Returns:
      the ClassNode value if the member is a ClassExpression with a defined type, otherwise null

  - ### getMemberClassValue

    public ClassNode getMemberClassValue(AnnotationNode node, String name, ClassNode defaultValue)
    Retrieves the ClassNode value of an annotation member with a default fallback. Validates that the member is a ClassExpression and generates errors for invalid expression types (VariableExpression or ConstantExpression).
    Parameters:
      `node` - the annotation node to query
      `name` - the name of the annotation member
      `defaultValue` - the value to return if the member is missing or not a valid ClassExpression
    Returns:
      the ClassNode value if the member is a ClassExpression with a defined type, otherwise the default value

  - ### getMemberStringList

    public static List<String> getMemberStringList(AnnotationNode anno, String name)
    Retrieves a list of string values from a list-type annotation member. Handles both ListExpression members and comma/space-separated string values. Returns null if the member is the undefined marker.
    Parameters:
      `anno` - the annotation node to query
      `name` - the name of the annotation member
    Returns:
      a list of strings if the member contains string values, or null if the member is missing or undefined

  - ### getMemberClassList

    public List<ClassNode> getMemberClassList(AnnotationNode anno, String name)
    Retrieves a list of ClassNode values from a list-type annotation member. Handles both single ClassExpression members and ListExpression members. Generates errors for invalid expression types and returns null if the member is undefined.
    Parameters:
      `anno` - the annotation node to query
      `name` - the name of the annotation member
    Returns:
      a list of ClassNode values if the member contains class values, or null if missing or undefined

  - ### addError

    public void addError(String msg, ASTNode node)
    Records a transformation error message associated with an AST node. The error is collected and reported at the end of compilation. This method implements `ErrorCollecting.addError(String, ASTNode)`.
    Specified by:
      `addError` in interface `ErrorCollecting`
    Parameters:
      `msg` - the error message to report
      `node` - the AST node associated with the error for source location tracking

  - ### checkNotInterface

    protected boolean checkNotInterface(ClassNode cNode, String annotationName)
    Validates that the target class node is not an interface. Generates an error if the target is an interface since transformation cannot be applied.
    Parameters:
      `cNode` - the class node to validate
      `annotationName` - the name of the annotation for error reporting
    Returns:
      true if the class is not an interface, false otherwise

  - ### hasAnnotation

    public boolean hasAnnotation(ClassNode node, ClassNode annotation)
    Checks whether a class node has a specific annotation.
    Parameters:
      `node` - the class node to check
      `annotation` - the annotation ClassNode to look for
    Returns:
      true if the node is annotated with the given annotation

  - ### tokenize

    public static List<String> tokenize(String rawExcludes)
    Tokenizes a string into a list of individual tokens using comma and space as delimiters.
    Parameters:
      `rawExcludes` - a comma or space-separated string, or null
    Returns:
      a list of tokens, or an empty list if the input is null

  - ### markAsInternal

    public static void markAsInternal(AnnotatedNode node)
    Since:
      6.0.0
    See Also:
      - `AnnotatedNodeUtils.markAsInternal(AnnotatedNode)`

  - ### deemedInternalName

    public static boolean deemedInternalName(String name)
    Determines whether a name is considered internal and should typically be excluded. A name is considered internal if it contains a dollar sign ('$'), which is commonly used for generated member names.
    Parameters:
      `name` - the name to check
    Returns:
      true if the name contains a dollar sign, false otherwise

  - ### deemedInternal

    public static boolean deemedInternal(AnnotatedNode node)
    Since:
      6.0.0
    See Also:
      - `AnnotatedNodeUtils.deemedInternal(AnnotatedNode)`

  - ### shouldSkipUndefinedAware

    public static boolean shouldSkipUndefinedAware(String name, List<String> excludes, List<String> includes)
    Determines whether a name should be skipped based on include/exclude filters and the undefined marker semantics. This method provides a convenient overload that calls `shouldSkipUndefinedAware(String, List, List, boolean)` with allNames set to false.
    Parameters:
      `name` - the name to check
      `excludes` - a list of names to exclude, or null
      `includes` - a list of names to include, or null
    Returns:
      true if the name should be skipped (in excludes, internal, or not in includes when includes is specified)

  - ### shouldSkipUndefinedAware

    public static boolean shouldSkipUndefinedAware(String name, List<String> excludes, List<String> includes, boolean allNames)
    Determines whether a name should be skipped based on include/exclude filters with support for the undefined marker semantics.
    Parameters:
      `name` - the name to check
      `excludes` - a list of names to exclude, or null
      `includes` - a list of names to include, or null
      `allNames` - if false, also skips names that are deemed internal (containing '$'); if true, only respects explicit include/exclude lists
    Returns:
      true if the name should be skipped

  - ### shouldSkipUndefinedAware

    public static boolean shouldSkipUndefinedAware(AnnotatedNode node, List<String> excludes, List<String> includes, boolean allNames)
    Variant that checks both the name and `@Internal` annotation.
    Since:
      6.0.0

  - ### shouldSkip

    public static boolean shouldSkip(String name, List<String> excludes, List<String> includes)
    Determines whether a name should be skipped based on include/exclude filters. This method provides a convenient overload that calls `shouldSkip(String, List, List, boolean)` with allNames set to false.
    Parameters:
      `name` - the name to check
      `excludes` - a list of names to exclude, or null
      `includes` - a list of names to include, or null (if non-empty and name not in it, name is skipped)
    Returns:
      true if the name should be skipped (in excludes, internal, or not in includes when includes is non-empty)

  - ### shouldSkip

    public static boolean shouldSkip(String name, List<String> excludes, List<String> includes, boolean allNames)
    Determines whether a name should be skipped based on include/exclude filters.
    Parameters:
      `name` - the name to check
      `excludes` - a list of names to exclude, or null
      `includes` - a list of names to include, or null (if non-empty and name not in it, name is skipped)
      `allNames` - if false, also skips names that are deemed internal (containing '$'); if true, only respects explicit include/exclude lists
    Returns:
      true if the name should be skipped

  - ### shouldSkip

    public static boolean shouldSkip(AnnotatedNode node, List<String> excludes, List<String> includes, boolean allNames)
    Variant that checks both the name and `@Internal` annotation.
    Since:
      6.0.0

  - ### shouldSkipOnDescriptorUndefinedAware

    public static boolean shouldSkipOnDescriptorUndefinedAware(boolean checkReturn, Map genericsSpec, MethodNode mNode, List<ClassNode> excludeTypes, List<ClassNode> includeTypes)
    Determines whether a method should be skipped based on method descriptor matching against include/exclude type lists. Allows filtering methods by their signature and return type for selective processing during transformations that handle multiple methods.
    Parameters:
      `checkReturn` - if true, compares full method descriptors including return type; if false, compares only parameter descriptors excluding return type
      `genericsSpec` - a map of generic type specifications for resolving generic method signatures
      `mNode` - the method node to evaluate
      `excludeTypes` - a list of ClassNodes specifying methods to exclude, or null
      `includeTypes` - a list of ClassNodes specifying methods to include, or null
    Returns:
      true if the method should be skipped (in excludeTypes or not in includeTypes when includeTypes is specified)

  - ### checkIncludeExcludeUndefinedAware

    protected boolean checkIncludeExcludeUndefinedAware(AnnotationNode node, List<String> excludes, List<String> includes, String typeName)
    Validates that only one of 'includes' or 'excludes' is specified, not both. Generates an error if both are provided.
    Parameters:
      `node` - the annotation node associated with this check for error reporting
      `excludes` - the excludes list, or null
      `includes` - the includes list, or null
      `typeName` - the transformation type name for error reporting
    Returns:
      false if both includes and excludes are non-null/non-empty, true otherwise

  - ### checkIncludeExcludeUndefinedAware

    protected void checkIncludeExcludeUndefinedAware(AnnotationNode node, List<String> excludes, List<String> includes, List<ClassNode> excludeTypes, List<ClassNode> includeTypes, String typeName)
    Validates that only one filtering list is specified among 'includes', 'excludes', 'includeTypes', and 'excludeTypes'. Generates an error if more than one filtering specification is provided.
    Parameters:
      `node` - the annotation node associated with this check for error reporting
      `excludes` - the string excludes list, or null
      `includes` - the string includes list, or null
      `excludeTypes` - the type excludes list, or null
      `includeTypes` - the type includes list, or null
      `typeName` - the transformation type name for error reporting

  - ### checkPropertyList

    public boolean checkPropertyList(ClassNode cNode, List<String> propertyNameList, String listName, AnnotationNode anno, String typeName, boolean includeFields)
    Validates that all property names in the given list exist in the target class. This is a convenience overload that calls `checkPropertyList(ClassNode, List, String, AnnotationNode, String, boolean, boolean, boolean, boolean, boolean)` with defaults: includeSuperProperties=false, allProperties=false, includeSuperFields=false, includeStatic=false.
    Parameters:
      `cNode` - the class node to validate properties against
      `propertyNameList` - the list of property names to verify, or null
      `listName` - the name of the list (for error reporting, e.g., "includes" or "excludes")
      `anno` - the annotation node for error reporting
      `typeName` - the transformation type name for error reporting
      `includeFields` - whether to also check for matching field names
    Returns:
      true if all properties exist or the list is null/empty, false if any property is not found

  - ### checkPropertyList

    public boolean checkPropertyList(ClassNode cNode, List<String> propertyNameList, String listName, AnnotationNode anno, String typeName, boolean includeFields, boolean includeSuperProperties, boolean allProperties)
    Validates that all property names in the given list exist in the target class. This is a convenience overload that calls `checkPropertyList(ClassNode, List, String, AnnotationNode, String, boolean, boolean, boolean, boolean, boolean)` with defaults: includeSuperFields=false, includeStatic=false.
    Parameters:
      `cNode` - the class node to validate properties against
      `propertyNameList` - the list of property names to verify, or null
      `listName` - the name of the list (for error reporting, e.g., "includes" or "excludes")
      `anno` - the annotation node for error reporting
      `typeName` - the transformation type name for error reporting
      `includeFields` - whether to also check for matching field names
      `includeSuperProperties` - whether to include inherited properties
      `allProperties` - whether to include all accessible properties
    Returns:
      true if all properties exist or the list is null/empty, false if any property is not found

  - ### checkPropertyList

    public boolean checkPropertyList(ClassNode cNode, List<String> propertyNameList, String listName, AnnotationNode anno, String typeName, boolean includeFields, boolean includeSuperProperties, boolean allProperties, boolean includeSuperFields, boolean includeStatic)
    Validates that all property names in the given list exist in the target class. Checks both properties and optionally fields in the class and its superclasses. Generates errors for any properties or fields that cannot be found.
    Parameters:
      `cNode` - the class node to validate properties against
      `propertyNameList` - the list of property names to verify, or null
      `listName` - the name of the list (for error reporting, e.g., "includes" or "excludes")
      `anno` - the annotation node for error reporting
      `typeName` - the transformation type name for error reporting
      `includeFields` - whether to also check for matching field names in the current class
      `includeSuperProperties` - whether to include inherited properties from superclasses
      `allProperties` - whether to include all accessible properties or only declared ones
      `includeSuperFields` - whether to also check superclass fields
      `includeStatic` - whether to include static properties
    Returns:
      true if all properties exist or the list is null/empty, false if any property is not found