Package: groovy.transform.options

## [Java] Class PropertyHandler

- groovy.transform.options.PropertyHandler

-     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 using reflection at compile time.

  During each transform, methods are invoked in a fixed order: validateAttributes first; if it returns `true`, then validateProperties; if that also returns `true`, then createPropInit, createPropGetter, and createPropSetter 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
    Modifiers | Name | Description
    --- | --- | ---
    `static ClassNode` | `PROPERTY_OPTIONS_TYPE` | Class node for PropertyOptions.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public Statement` | `createPropGetter(PropertyNode pNode)` Create the getter block used when reading the property including any defensive copying.
    `` | `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.
    `` | `public Statement` | `createPropSetter(PropertyNode pNode)` Create the setter block used when setting the property.
    `` | `public static PropertyHandler` | `createPropertyHandler(AbstractASTTransformation xform, GroovyClassLoader loader, ClassNode cNode)` Creates the property handler configured for the supplied class.
    `` | `protected boolean` | `isValidAttribute(AbstractASTTransformation xform, AnnotationNode anno, String memberName)` Helper for use from validateAttributes: confirms that the named attribute is absent from the host annotation.
    `` | `public abstract boolean` | `validateAttributes(AbstractASTTransformation xform, AnnotationNode anno)` Validates annotation attributes supported by this handler.
    `` | `public boolean` | `validateProperties(AbstractASTTransformation xform, BlockStatement body, ClassNode cNode, List<PropertyNode> props)` Validates the properties selected for processing.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### public static final ClassNode PROPERTY_OPTIONS_TYPE

      Class node for PropertyOptions.

  - ### Method Detail

    - #### public Statement createPropGetter(PropertyNode pNode)

      Create the getter block used when reading the property including any defensive copying.

      Parameters:
        `pNode` - the property node

    - #### 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

    - #### 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

    - #### 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

    - #### protected boolean isValidAttribute(AbstractASTTransformation xform, AnnotationNode anno, String memberName)

      Helper for use from validateAttributes: 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)

    - #### 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

    - #### 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