Package: groovy.transform

## [Java] Annotation Type InheritConstructors

- groovy.transform.InheritConstructors

-     @Documented
      @Retention(RetentionPolicy.SOURCE)
      @Target(ElementType.TYPE)
      public @interface InheritConstructors

  Class annotation to make constructors from a super class available in a subclass. Should be used with care with other annotations which create constructors - see "Known Limitations" for more details.

  `@InheritConstructors` saves you typing some boilerplate code.

  Example usage:

       class Person {
           String first, last
           Person(String first, String last) {
               this.first = first
               this.last = last.toUpperCase()
           }
       }

       @groovy.transform.InheritConstructors
       class PersonAge extends Person {
           int age
       }

       def js = new PersonAge('John', 'Smith')
       js.age = 25

       assert "$js.last, $js.first is $js.age years old" == 'SMITH, John is 25 years old'

  for this case, the `PersonAge` class will be equivalent to the following code:

       class PersonAge extends Person {
           PersonAge(String first, String last) {
               super(first, last)
           }
           int age
       }

  You may add additional constructors in addition to inherited ones. If the argument types of a supplied constructor exactly match those of a parent constructor, then that constructor won't be inherited.

  Style note: Don't go overboard using this annotation. Typical Groovy style is to use named-arg constructors when possible. This is easy to do for Groovy objects or any objects following JavaBean conventions. In other cases, inheriting the constructors may be useful. However, subclasses often introduce new properties and these are often best set in a constructor; especially if that matches the style adopted in parent classes. So, even for the example above, it may have been better style to define an explicit constructor for `PersonAge` that also set the `age` property. Sometimes, consistent style is much more important than saving a few keystrokes.

  As another example, this:

       @InheritConstructors class CustomException extends RuntimeException { }

  is equivalent to this:

       class CustomException extends RuntimeException {
           CustomException() {
               super()
           }
           CustomException(String message) {
               super(message)
           }
           CustomException(String message, Throwable cause) {
               super(message, cause)
           }
           CustomException(Throwable cause) {
               super(cause)
           }
       }

  Known Limitations:
  - This AST transform creates (potentially) numerous constructors. You should take care to avoid constructors with duplicate signatures if you are defining your own constructors or combining with other AST transforms which create constructors (e.g. `@TupleConstructor`); the order in which the particular transforms are processed becomes important in that case.
  - If you create Groovy constructors with optional arguments this leads to multiple constructors created in the byte code. The expansion to multiple constructors occurs in a later phase to this AST transformation. This means that you can't override (i.e. not inherit) the constructors with signatures that Groovy adds later. If you get it wrong you will get a compile-time error about the duplication.
  - Under joint compilation, when the super class is in the same compilation unit and its constructors come from another constructor-generating transform (e.g. `@TupleConstructor`), the inherited signatures appear in the stub only when the super class is declared before the subclass in source. The runtime always produces the full surface; the stub remains a strict subset when source order is reversed, and Java callers reaching for the missing signatures won't compile against the stub even though the runtime supports them.

  More examples:

       //--------------------------------------------------------------------------
       import groovy.transform.InheritConstructors

       @InheritConstructors
       class MyException extends Exception {
       }

       def e = new MyException()
       def e1 = new MyException('message')   // Other constructors are available.
       assert 'message' == e1.message

       //--------------------------------------------------------------------------
       import groovy.transform.InheritConstructors
       class Person {
           String name

           Person(String name) {
               this.name = name
           }
       }

       @InheritConstructors
       class Child extends Person {}

       def child = new Child('Liam')
       assert 'Liam' == child.name

  Since:
    1.7.3

- - ### Element Summary

    Optional Element Summary
    Type | Name and Description
    --- | ---
    `boolean` | `constructorAnnotations` Whether to carry over annotations on the copied constructors.
    `boolean` | `parameterAnnotations` Whether to carry over parameter annotations on the copied constructors.

  - ### Inherited Methods Summary

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

- - ### Element Detail

    - #### public boolean constructorAnnotations

      Whether to carry over annotations on the copied constructors. Currently Closure annotation members are not supported.

      Returns:
        true if copied constructor should keep constructor annotations
      Default:
        false

    - #### public boolean parameterAnnotations

      Whether to carry over parameter annotations on the copied constructors. Currently Closure annotation members are not supported.

      Returns:
        true if copied constructor should keep parameter annotations
      Default:
        false