Package groovy.transform.options

# Class PropertyHandler

java.lang.Object
groovy.transform.options.PropertyHandler

Direct Known Subclasses:
  `DefaultPropertyHandler`, `ImmutablePropertyHandler`

public abstract class PropertyHandler extends Object
Used to provide custom property handling when getting, setting or initializing properties.

Subclasses are plugged in via the `propertyHandler` attribute on the `PropertyOptions` annotation. Implementations must declare a public no-argument constructor; the handler is instantiated via `createPropertyHandler(org.codehaus.groovy.transform.AbstractASTTransformation, groovy.lang.GroovyClassLoader, org.codehaus.groovy.ast.ClassNode)` using reflection at compile time.

During each transform, methods are invoked in a fixed order: `validateAttributes(org.codehaus.groovy.transform.AbstractASTTransformation, org.codehaus.groovy.ast.AnnotationNode)` first; if it returns `true`, then `validateProperties(org.codehaus.groovy.transform.AbstractASTTransformation, org.codehaus.groovy.ast.stmt.BlockStatement, org.codehaus.groovy.ast.ClassNode, java.util.List<org.codehaus.groovy.ast.PropertyNode>)`; if that also returns `true`, then `createPropInit(org.codehaus.groovy.transform.AbstractASTTransformation, org.codehaus.groovy.ast.AnnotationNode, org.codehaus.groovy.ast.ClassNode, org.codehaus.groovy.ast.PropertyNode, org.codehaus.groovy.ast.Parameter)`, `createPropGetter(org.codehaus.groovy.ast.PropertyNode)`, and `createPropSetter(org.codehaus.groovy.ast.PropertyNode)` are called per property as required by the host transform. Returning `false` from a validation method short-circuits processing.

Since:
  2.5.0

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final ClassNode`
  `PROPERTY_OPTIONS_TYPE`
  Class node for `PropertyOptions`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PropertyHandler()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static PropertyHandler`
  `createPropertyHandler(AbstractASTTransformation xform, GroovyClassLoader loader, ClassNode cNode)`
  Creates the property handler configured for the supplied class.
  `Statement`
  `createPropGetter(PropertyNode pNode)`
  Create the getter block used when reading the property including any defensive copying.
  `abstract Statement`
  `createPropInit(AbstractASTTransformation xform, AnnotationNode anno, ClassNode cNode, PropertyNode pNode, Parameter namedArgsMap)`
  Create a statement that will initialize the property including any defensive copying.
  `Statement`
  `createPropSetter(PropertyNode pNode)`
  Create the setter block used when setting the property.
  `protected boolean`
  `isValidAttribute(AbstractASTTransformation xform, AnnotationNode anno, String memberName)`
  Helper for use from `validateAttributes(org.codehaus.groovy.transform.AbstractASTTransformation, org.codehaus.groovy.ast.AnnotationNode)`: confirms that the named attribute is absent from the host annotation.
  `abstract boolean`
  `validateAttributes(AbstractASTTransformation xform, AnnotationNode anno)`
  Validates annotation attributes supported by this handler.
  `boolean`
  `validateProperties(AbstractASTTransformation xform, BlockStatement body, ClassNode cNode, List<PropertyNode> props)`
  Validates the properties selected for processing.

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

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

- ## Field Details

  - ### PROPERTY_OPTIONS_TYPE

    public static final ClassNode PROPERTY_OPTIONS_TYPE
    Class node for `PropertyOptions`.

- ## Constructor Details

  - ### PropertyHandler

    public PropertyHandler()

- ## Method Details

  - ### validateAttributes

    public abstract boolean validateAttributes(AbstractASTTransformation xform, AnnotationNode anno)
    Validates annotation attributes supported by this handler.
    Parameters:
      `xform` - the active transform
      `anno` - the property options annotation
    Returns:
      `true` if validation succeeds

  - ### validateProperties

    public boolean validateProperties(AbstractASTTransformation xform, BlockStatement body, ClassNode cNode, List<PropertyNode> props)
    Validates the properties selected for processing.
    Parameters:
      `xform` - the active transform
      `body` - the statement block being generated
      `cNode` - the owning class
      `props` - the candidate properties
    Returns:
      `true` if validation succeeds

  - ### createPropInit

    public abstract Statement createPropInit(AbstractASTTransformation xform, AnnotationNode anno, ClassNode cNode, PropertyNode pNode, Parameter namedArgsMap)
    Create a statement that will initialize the property including any defensive copying. Return `null` to indicate that no initialization statement should be emitted for this property; this is distinct from returning an empty block and skips the corresponding entry in the generated constructor body altogether.
    Parameters:
      `xform` - the transform being processed
      `anno` - the annotation node
      `cNode` - the classnode containing the property
      `pNode` - the property node to initialize
      `namedArgsMap` - an "args" Map if the property value should come from a named arg map or null if not

  - ### createPropGetter

    public Statement createPropGetter(PropertyNode pNode)
    Create the getter block used when reading the property including any defensive copying.
    Parameters:
      `pNode` - the property node

  - ### createPropSetter

    public Statement createPropSetter(PropertyNode pNode)
    Create the setter block used when setting the property. Can be null for read-only properties.
    Parameters:
      `pNode` - the property node

  - ### isValidAttribute

    protected boolean isValidAttribute(AbstractASTTransformation xform, AnnotationNode anno, String memberName)
    Helper for use from `validateAttributes(org.codehaus.groovy.transform.AbstractASTTransformation, org.codehaus.groovy.ast.AnnotationNode)`: confirms that the named attribute is absent from the host annotation. Despite the positive name, this returns `false` and records a compile error when the attribute is set, so subclasses can chain calls in the style `return isValidAttribute(xform, anno, "useSuper");` to reject attributes that the host transform supports but this handler does not.
    Parameters:
      `xform` - the active transform
      `anno` - the annotation being processed
      `memberName` - the attribute name expected to be absent
    Returns:
      `true` if the attribute is absent (i.e. valid for this handler); `false` if present (a compile error is added as a side effect)

  - ### createPropertyHandler

    public static PropertyHandler createPropertyHandler(AbstractASTTransformation xform, GroovyClassLoader loader, ClassNode cNode)
    Creates the property handler configured for the supplied class. If the class carries a `PropertyOptions` annotation, the `propertyHandler` attribute is read and the named handler class is instantiated via its public no-argument constructor; otherwise a `DefaultPropertyHandler` is returned. A compile error is recorded (and `null` returned) if the handler cannot be loaded, lacks a no-arg constructor, or is not a `PropertyHandler` subtype.
    Parameters:
      `xform` - the active transform
      `loader` - the class loader used to instantiate custom handlers
      `cNode` - the class being transformed
    Returns:
      the configured property handler, or `null` if one could not be created