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 Details

  • 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