ToString (Groovy 4.0.23)

groovy.transform.ToString

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE})
@GroovyASTTransformationClass("org.codehaus.groovy.transform.ToStringASTTransformation")
public @interface ToString

Class annotation used to assist in the creation of toString() methods in classes. The @ToString annotation instructs the compiler to execute an AST transformation which adds the necessary toString() method.

It allows you to write classes in this shortened form:

 @ToString
 class Customer {
     String first, last
     int age
     Date since = new Date()
     Collection favItems
     private answer = 42
 }
 println new Customer(first:'Tom', last:'Jones', age:21, favItems:['Books', 'Games'])

Which will have this output:

 Customer(Tom, Jones, 21, Wed Jul 14 23:57:14 EST 2010, [Books, Games])

There are numerous options to customize the format of the generated output. E.g. if you change the first annotation to:

 @ToString(includeNames=true)

Then the output will be:

 Customer(first:Tom, last:Jones, age:21, since:Wed Jul 14 23:57:50 EST 2010, favItems:[Books, Games])

Or if you change the first annotation to:

 @ToString(includeNames=true,includeFields=true,excludes="since,favItems")

Then the output will be:

 Customer(first:Tom, last:Jones, age:21, answer:42)

If you have this example:

 import groovy.transform.ToString
 @ToString class NamedThing {
     String name
 }
 @ToString(includeNames=true,includeSuper=true)
 class AgedThing extends NamedThing {
     int age
 }
 String agedThingAsString = new AgedThing(name:'Lassie', age:5).toString()
 assert agedThingAsString == 'AgedThing(age:5, super:NamedThing(Lassie))'

@ToString can also be used in conjunction with @Canonical and @Immutable.

If you want to omit fields or properties referring to null, you can use the ignoreNulls flag:

 import groovy.transform.ToString
 @ToString(ignoreNulls = true) class NamedThing {
     String name
 }
 assert new NamedThing(name: null).toString() == 'NamedThing()'

By default the fully-qualified class name is used as part of the generated toString. If you want to exclude the package, you can set the includePackage flag to false, e.g.:

 package my.company
 import groovy.transform.ToString
 @ToString(includePackage = false) class NamedThing {
     String name
 }
 println new NamedThing(name: "Lassie")

Which results in:

 NamedThing(name: Lassie)

If the includePackage flag is true (the default), then the output will be:

 my.company.NamedThing(name: Lassie)

More examples:

 //--------------------------------------------------------------------------
 // Most simple implementation of toString.
 import groovy.transform.ToString

 @ToString
 class Person {
     String name
     List likes
     private boolean active = false
 }

 def person = new Person(name: 'mrhaki', likes: ['Groovy', 'Java'])

 assert person.toString() == 'Person(mrhaki, [Groovy, Java])'

 //--------------------------------------------------------------------------
 // includeNames to output the names of the properties.
 import groovy.transform.ToString

 @ToString(includeNames=true)
 class Person {
     String name
     List likes
     private boolean active = false
 }

 def person = new Person(name: 'mrhaki', likes: ['Groovy', 'Java'])

 assert person.toString() == 'Person(name:mrhaki, likes:[Groovy, Java])'

 //--------------------------------------------------------------------------
 // includeFields to not only output properties, but also field values.
 import groovy.transform.ToString

 @ToString(includeNames=true, includeFields=true)
 class Person {
     String name
     List likes
     private boolean active = false
 }

 def person = new Person(name: 'mrhaki', likes: ['Groovy', 'Java'])

 assert person.toString() == 'Person(name:mrhaki, likes:[Groovy, Java], active:false)'

 //--------------------------------------------------------------------------
 // Use includeSuper to include properties from super class in output.
 import groovy.transform.ToString

 @ToString(includeNames=true)
 class Person {
     String name
     List likes
     private boolean active = false
 }

 @ToString(includeSuper=true, includeNames=true)
 class Student extends Person {
     List courses
 }

 def student = new Student(name: 'mrhaki', likes: ['Groovy', 'Java'], courses: ['IT', 'Business'])

 assert student.toString() == 'Student(courses:[IT, Business], super:Person(name:mrhaki, likes:[Groovy, Java]))'

 //--------------------------------------------------------------------------
 // excludes active field and likes property from output
 import groovy.transform.ToString

 @ToString(includeNames=true, includeFields=true, excludes='active,likes')
 class Person {
     String name
     List likes
     private boolean active = false
 }

 def person = new Person(name: 'mrhaki', likes: ['Groovy', 'Java'])

 assert person.toString() == 'Person(name:mrhaki)'

 //--------------------------------------------------------------------------
 // Don't include the package name in the output
 package com.mrhaki.blog.groovy

 import groovy.transform.*

 @ToString(includePackage=false)
 class Course {
     String title
     Integer maxAttendees
 }

 final Course course = new Course(title: 'Groovy 101', maxAttendees: 200)

 assert course.toString() == 'Course(Groovy 101, 200)'

 //--------------------------------------------------------------------------
 // Don't use properties with null value.
 package com.mrhaki.blog.groovy

 import groovy.transform.*

 @ToString(ignoreNulls=true)
 class Course {
     String title
     Integer maxAttendees
 }

 final Course course = new Course(title: 'Groovy 101')

 assert course.toString() == 'com.mrhaki.blog.groovy.Course(Groovy 101)'

 //--------------------------------------------------------------------------
 // Cache toString() result.
 package com.mrhaki.blog.groovy

 import groovy.transform.*

 @ToString(cache=true)
 class Course {
     String title
     Integer maxAttendees
 }

 Course course = new Course(title: 'Groovy 101', maxAttendees: 200)

 assert course.toString() == 'com.mrhaki.blog.groovy.Course(Groovy 101, 200)'

 // Value change will not be reflected in toString().
 course.title = 'Grails with REST'

 assert course.toString() == 'com.mrhaki.blog.groovy.Course(Groovy 101, 200)'
 assert course.title == 'Grails with REST'

See Also:: Immutable; Canonical

Since:: 1.8.0

Element Summary

Optional Element Summary
Type	Name and Description
`boolean`	`allNames` Whether to include all fields and/or properties in the generated toString, including those with names that are considered internal.
`boolean`	`allProperties` Whether to include all properties (as per the JavaBean spec) in the generated toString.
`boolean`	`cache` Whether to cache toString() calculations.
`String[]`	`excludes` List of field and/or property names to exclude from generated toString.
`String`	`fieldSeparator` The string to use between each property/field.
`boolean`	`ignoreNulls` Don't display any fields or properties with value `null`.
`boolean`	`includeFields` Include fields as well as properties in the generated toString.
`boolean`	`includeNames` Whether to include names of properties/fields in the generated toString.
`boolean`	`includePackage` Whether to include the fully-qualified class name (i.e. including the package) or just the simple class name in the generated toString.
`boolean`	`includeSuper` Whether to include the toString() of super in the generated toString.
`boolean`	`includeSuperFields` Include super fields in the generated toString.
`boolean`	`includeSuperProperties` Whether to include super properties in the generated toString.
`String[]`	`includes` List of field and/or property names to include within the generated toString.
`String`	`leftDelimiter` The String to use after the classname and before the list of properties/fields.
`String`	`nameValueSeparator` The string to use between the name of the property/field and its value when `includeNames` is true.
`boolean`	`pojo` Whether to avoid using Groovy runtime methods when printing the toString for class members.
`String`	`rightDelimiter` The String to use after the list of properties/fields.
`boolean`	`useGetters` Whether to access properties directly by their fields (faster) or via their getters.

Inherited Methods Summary

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

- Element Detail
  - public boolean allNames
    
    Whether to include all fields and/or properties in the generated toString, including those with names that are considered internal.
    Since:
    2.5.0
    Default:
    false
  - public boolean allProperties
    
    Whether to include all properties (as per the JavaBean spec) in the generated toString. Groovy recognizes any field-like definitions with no explicit visibility as property definitions and always includes them in the @ToString generated toString (as well as auto-generating the appropriate getters and setters). Groovy also treats any explicitly created getXxx() or isYyy() methods as property getters as per the JavaBean specification. Old versions of Groovy did not. So set this flag to false for the old behavior or if you want to explicitly exclude such properties. JavaBean properties come after any Groovy properties but before any fields for a given class (unless 'includes' is used to determine the order).
    Since:
    2.5.0
    Default:
    true
  - public boolean cache
    
    Whether to cache toString() calculations. You should only set this to true if you know the object is immutable (or technically mutable but never changed).
    Since:
    2.1.0
    Default:
    false
  - public String[] excludes
    
    List of field and/or property names to exclude from generated toString. Must not be used if 'includes' is used. For convenience, a String with comma separated names can be used in addition to an array (using Groovy's literal list notation) of String values.
    Default:
    {}
  - public String fieldSeparator
    
    The string to use between each property/field.
    Since:
    4.0.0
    Default:
    ", "
  - public boolean ignoreNulls
    
    Don't display any fields or properties with value null.
    Default:
    false
  - public boolean includeFields
    
    Include fields as well as properties in the generated toString. Fields come after any properties.
    Default:
    false
  - public boolean includeNames
    
    Whether to include names of properties/fields in the generated toString.
    Default:
    false
  - public boolean includePackage
    
    Whether to include the fully-qualified class name (i.e. including the package) or just the simple class name in the generated toString.
    Since:
    2.0.6
    Default:
    true
  - public boolean includeSuper
    
    Whether to include the toString() of super in the generated toString.
    Default:
    false
  - public boolean includeSuperFields
    
    Include super fields in the generated toString. Groovy properties, JavaBean properties and fields (in that order) from superclasses come after the members from a subclass (unless 'includes' is used to determine the order).
    Since:
    2.5.0
    Default:
    false
  - public boolean includeSuperProperties
    
    Whether to include super properties in the generated toString. Groovy properties, JavaBean properties and fields (in that order) from superclasses come after the members from a subclass (unless 'includes' is used to determine the order).
    Since:
    2.4.0
    Default:
    false
  - public String[] includes
    
    List of field and/or property names to include within the generated toString. The order of inclusion is determined by the order in which the names are specified. Must not be used if 'excludes' is used. For convenience, a String with comma separated names can be used in addition to an array (using Groovy's literal list notation) of String values. The default value is a special marker value indicating that no includes are defined; all fields and/or properties are included if 'includes' remains undefined and 'excludes' is explicitly or implicitly an empty list. The special name 'super' can be used instead of using the 'includeSuper' flag.
    Default:
    { Undefined.STRING }
  - public String leftDelimiter
    
    The String to use after the classname and before the list of properties/fields.
    Since:
    4.0.0
    Default:
    "("
  - public String nameValueSeparator
    
    The string to use between the name of the property/field and its value when includeNames is true.
    Since:
    4.0.0
    Default:
    ":"
  - public boolean pojo
    
    Whether to avoid using Groovy runtime methods when printing the toString for class members. The generated code is more similar to what is typically used in POJO classes. The presence of the @POJO annotation on a class is looked for by default but this annotation attribute allows the feature to be explicitly configured if desired. NOTE: this is an incubating feature and may change in future versions.
    Since:
    4.0.0
    Default:
    false
  - public String rightDelimiter
    
    The String to use after the list of properties/fields.
    Since:
    4.0.0
    Default:
    ")"
  - public boolean useGetters
    
    Whether to access properties directly by their fields (faster) or via their getters.
    Since:
    4.0.12
    Default:
    true

Summary:
Optional

| Detail:
Element

[Java] Annotation Type ToString

Element Summary

Inherited Methods Summary

Element Detail

public boolean allNames

public boolean allProperties

public boolean cache

public String[] excludes

public String fieldSeparator

public boolean ignoreNulls

public boolean includeFields

public boolean includeNames

public boolean includePackage

public boolean includeSuper

public boolean includeSuperFields

public boolean includeSuperProperties

public String[] includes

public String leftDelimiter

public String nameValueSeparator

public boolean pojo

public String rightDelimiter

public boolean useGetters