0
# Apache Groovy
1

2
Apache Groovy is a powerful multi-faceted programming language for the JVM platform that supports a spectrum of programming styles incorporating features from dynamic languages such as optional and duck typing, but also static compilation and static type checking at levels similar to or greater than Java. It aims to greatly increase developer productivity with many powerful features but also a concise, familiar and easy to learn syntax.
3

4
## Package Information
5

6
- **Package Name**: org.codehaus.groovy:groovy
7
- **Package Type**: maven
8
- **Language**: Groovy/Java
9
- **Installation**: Add to Maven `pom.xml`:
10
  ```xml
11
  <dependency>
12
    <groupId>org.codehaus.groovy</groupId>
13
    <artifactId>groovy</artifactId>
14
    <version>3.0.25</version>
15
  </dependency>
16
  ```
17
- **Installation**: Add to Gradle `build.gradle`:
18
  ```groovy
19
  implementation 'org.codehaus.groovy:groovy:3.0.25'
20
  ```
21

22
## Core Imports
23

24
Common Java imports for using Groovy:
25

26
```java
27
import groovy.lang.*;
28
import groovy.util.*;
29
```
30

31
For Groovy scripts:
32
```groovy
33
import groovy.transform.*
34
import groovy.util.*
35
```
36

37
## Basic Usage
38

39
```java
40
import groovy.lang.GroovyShell;
41
import groovy.lang.Script;
42
import groovy.lang.Binding;
43

44
// Execute Groovy code dynamically
45
GroovyShell shell = new GroovyShell();
46
Script script = shell.parse("println 'Hello from Groovy!'");
47
script.run();
48

49
// Execute with variable bindings
50
Binding binding = new Binding();
51
binding.setVariable("name", "World");
52
shell.setProperty("binding", binding);
53
Object result = shell.evaluate("return \"Hello ${name}!\"");
54
System.out.println(result); // Prints: Hello World!
55
```
56

57
## Architecture
58

59
Groovy's architecture consists of several key components:
60

61
- **Language Core** (`groovy.lang`): Fundamental language constructs (GroovyObject, Closure, Script, MetaClass)
62
- **Runtime System** (`org.codehaus.groovy.runtime`): Method dispatch, type coercion, and runtime support
63
- **AST Framework** (`org.codehaus.groovy.ast`): Abstract syntax tree for compilation and meta-programming
64
- **Transform System** (`groovy.transform`): Compile-time code generation and AST transformations
65
- **Utility Libraries** (`groovy.util`): Configuration, XML processing, CLI tools, and data structures
66

67
## Capabilities
68

69
### Core Language Runtime
70

71
Essential runtime classes and interfaces that enable Groovy's dynamic behavior, meta-programming capabilities, and integration with the JVM. Includes the fundamental GroovyObject interface, closures, scripts, and meta-class system.
72

73
```java { .api }
74
interface GroovyObject {
75
    Object invokeMethod(String name, Object args);
76
    Object getProperty(String propertyName);
77
    void setProperty(String propertyName, Object newValue);
78
    MetaClass getMetaClass();
79
    void setMetaClass(MetaClass metaClass);
80
}
81

82
class GroovyShell {
83
    Script parse(String scriptText);
84
    Object evaluate(String scriptText);
85
    Object run(String scriptText, String[] args);
86
}
87

88
class Closure<V> {
89
    V call();
90
    V call(Object... args);
91
    Closure<V> curry(Object... args);
92
    Closure<V> memoize();
93
}
94
```
95

96
[Core Language Runtime](./core-language.md)
97

98
### AST and Compilation
99

100
Abstract Syntax Tree classes and compilation support for programmatic code generation, AST transformations, and compile-time meta-programming. Essential for building Groovy-based tools and IDEs.
101

102
```java { .api }
103
class ASTNode {
104
    int getLineNumber();
105
    int getColumnNumber();
106
    String getText();
107
}
108

109
class ClassNode extends ASTNode {
110
    String getName();
111
    List<MethodNode> getMethods();
112
    List<FieldNode> getFields();
113
    List<PropertyNode> getProperties();
114
}
115

116
class AstBuilder {
117
    List<ASTNode> buildFromString(String source);
118
    List<ASTNode> buildFromCode(Closure closure);
119
}
120
```
121

122
[AST and Compilation](./ast-compilation.md)
123

124
### Configuration and Data Processing
125

126
Configuration file parsing, XML processing, command-line interface building, and data structure utilities. Includes ConfigSlurper for application configuration and XML processing tools.
127

128
```java { .api }
129
class ConfigSlurper {
130
    ConfigObject parse(String text);
131
    ConfigObject parse(URL location);
132
    void setEnvironment(String environment);
133
}
134

135
class XmlSlurper {
136
    GPathResult parse(String xml);
137
    GPathResult parse(File file);
138
    GPathResult parseText(String xml);
139
}
140

141
class CliBuilder {
142
    OptionAccessor parse(String[] args);
143
    void usage();
144
}
145
```
146

147
[Configuration and Data Processing](./config-data.md)
148

149
### Collections and Utilities
150

151
Enhanced collection classes, observable data structures, and utility functions that extend Java's collection framework with Groovy-specific features and dynamic behavior.
152

153
```java { .api }
154
class ObservableList<E> extends ArrayList<E> {
155
    void addPropertyChangeListener(PropertyChangeListener listener);
156
    void removePropertyChangeListener(PropertyChangeListener listener);
157
}
158

159
class Node {
160
    String name();
161
    Object value();
162
    Map<String, String> attributes();
163
    List<Node> children();
164
    Node parent();
165
}
166

167
class ListWithDefault<T> {
168
    static <T> ListWithDefault<T> withDefault(List<T> list, Closure defaultValue);
169
    T getDefaultValue(int index);
170
}
171
```
172

173
[Collections and Utilities](./collections-utilities.md)
174

175
### Transform Annotations
176

177
Compile-time code generation annotations that automatically add common functionality like toString(), equals(), builders, immutability, and static compilation support.
178

179
```java { .api }
180
@Target({ElementType.TYPE})
181
@Retention(RetentionPolicy.SOURCE)
182
@interface CompileStatic { }
183

184
@Target({ElementType.TYPE})
185
@Retention(RetentionPolicy.SOURCE)
186
@interface Immutable {
187
    String[] excludes() default {};
188
    boolean copyWith() default false;
189
}
190

191
@Target({ElementType.TYPE})
192
@Retention(RetentionPolicy.SOURCE)
193
@interface ToString {
194
    String[] excludes() default {};
195
    boolean includeNames() default false;
196
    boolean includeFields() default false;
197
}
198
```
199

200
[Transform Annotations](./transform-annotations.md)
201

202
### XML Processing
203

204
Comprehensive XML parsing, navigation, and generation capabilities including both tree-based (XmlParser) and streaming (XmlSlurper) approaches with GPath expression support.
205

206
```java { .api }
207
class XmlParser {
208
    Node parse(String xml);
209
    Node parse(File file);
210
    Node parseText(String xml);
211
}
212

213
class MarkupBuilder {
214
    MarkupBuilder(Writer writer);
215
    Object invokeMethod(String name, Object args);
216
}
217

218
abstract class GPathResult {
219
    String text();
220
    int size();
221
    GPathResult children();
222
    GPathResult parent();
223
    GPathResult find(Closure closure);
224
    GPathResult findAll(Closure closure);
225
}
226
```
227

228
[XML Processing](./xml-processing.md)
229

230
### Time and Date Operations
231

232
Time arithmetic, date manipulation, and duration calculations through category-based extensions to Java's Date and temporal classes.
233

234
```java { .api }
235
class TimeCategory {
236
    static Date plus(Date date, BaseDuration duration);
237
    static Date minus(Date date, BaseDuration duration);
238
    static BaseDuration minus(Date lhs, Date rhs);
239
}
240

241
class TimeDuration extends BaseDuration {
242
    int getDays();
243
    int getHours();
244
    int getMinutes();
245
    int getSeconds();
246
}
247
```
248

249
[Time and Date Operations](./time-date.md)
250

251
### JSON Processing
252

253
Comprehensive JSON parsing, generation, and manipulation capabilities through JsonSlurper for parsing JSON data and JsonBuilder for creating JSON output with full type safety and streaming support.
254

255
```java { .api }
256
class JsonSlurper {
257
    Object parseText(String text);
258
    Object parse(Reader reader);
259
    Object parse(File file);
260
    void setType(JsonParserType type);
261
}
262

263
class JsonBuilder {
264
    JsonBuilder();
265
    JsonBuilder(Object content);
266
    void call(Closure closure);
267
    String toString();
268
}
269

270
enum JsonParserType {
271
    CHARACTER_SOURCE, LAX, INDEX_OVERLAY
272
}
273
```
274

275
[JSON Processing](./json-processing.md)
276

277
### SQL Database Operations
278

279
Comprehensive database connectivity, query execution, and data manipulation through the Groovy SQL API. Provides simplified database access with automatic resource management, transaction support, and result set navigation.
280

281
```java { .api }
282
class Sql {
283
    static Sql newInstance(String url, String user, String password, String driver);
284
    List<GroovyRowResult> rows(String sql);
285
    void eachRow(String sql, Closure closure);
286
    int executeUpdate(String sql);
287
    void withTransaction(Closure closure);
288
}
289

290
interface GroovyRowResult extends Map<String, Object> {
291
    Object getProperty(String columnName);
292
    Object getAt(int columnIndex);
293
}
294
```
295

296
[SQL Database Operations](./sql-database.md)
297

298
### Testing APIs
299

300
Comprehensive testing framework with enhanced JUnit integration, mocking capabilities, and Groovy-specific assertion utilities. Provides GroovyTestCase for improved test organization and mock objects for isolation testing.
301

302
```java { .api }
303
abstract class GroovyTestCase extends TestCase {
304
    void shouldFail(Closure code);
305
    void shouldFail(Class<? extends Throwable> expectedType, Closure code);
306
    void assertScript(String script);
307
    Object evaluate(String script);
308
}
309

310
class MockFor {
311
    MockFor(Class clazz);
312
    void demand(String methodName);
313
    Object use(Closure closure);
314
}
315
```
316

317
[Testing APIs](./testing-apis.md)
318

319
### Template Engines
320

321
Comprehensive templating system with multiple engines for generating dynamic text output. Includes SimpleTemplateEngine for basic templating, GStringTemplateEngine for GString-based templates, and specialized engines for XML/HTML generation with streaming support.
322

323
```java { .api }
324
class SimpleTemplateEngine extends TemplateEngine {
325
    Template createTemplate(String templateText);
326
    Template createTemplate(Reader reader);
327
}
328

329
interface Template {
330
    Writable make(Map binding);
331
    Writable make();
332
}
333

334
class MarkupTemplateEngine extends TemplateEngine {
335
    MarkupTemplateEngine(TemplateConfiguration configuration);
336
    Template createTypeCheckedTemplate(String templateText);
337
}
338
```
339

340
[Template Engines](./template-engines.md)
341

342
### I/O and File Processing
343

344
Enhanced file system operations, stream processing, and I/O utilities through Groovy extensions to Java's I/O classes. Provides simplified file manipulation, automatic resource management, and powerful text processing capabilities.
345

346
```java { .api }
347
class File {
348
    String getText();
349
    void setText(String text);
350
    File eachLine(Closure closure);
351
    Object withReader(Closure closure);
352
    Object withWriter(Closure closure);
353
    void eachFileRecurse(Closure closure);
354
}
355

356
class InputStream {
357
    String getText();
358
    byte[] getBytes();
359
    void copyTo(OutputStream target);
360
}
361
```
362

363
[I/O and File Processing](./io-file-processing.md)
364

365
### Dependency Management
366

367
Grape dependency management system for dynamic dependency resolution and loading, including @Grab annotation support for declaring dependencies in scripts.
368

369
```java { .api }
370
class Grape {
371
    static void grab(String endorsedModule);
372
    static void grab(Map<String, Object> dependency);
373
    static void addResolver(Map<String, Object> args);
374
    static URI[] resolve(Map<String, Object> args);
375
}
376

377
@Target({ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.LOCAL_VARIABLE, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE})
378
@Retention(RetentionPolicy.SOURCE)
379
@interface Grab {
380
    String group() default "";
381
    String module();
382
    String version();
383
    String classifier() default "";
384
}
385
```
386

387
[Dependency Management](./dependency-management.md)
388

389
## Types
390

391
### Core Language Types
392

393
```java { .api }
394
interface MetaClass {
395
    Object invokeMethod(Object object, String methodName, Object[] arguments);
396
    Object getProperty(Object object, String propertyName);
397
    void setProperty(Object object, String propertyName, Object newValue);
398
    boolean respondsTo(Object obj, String name);
399
    MetaProperty hasProperty(Object obj, String name);
400
}
401

402
class Binding {
403
    Object getVariable(String name);
404
    void setVariable(String name, Object value);
405
    Map<String, Object> getVariables();
406
    boolean hasVariable(String name);
407
}
408

409
class GString implements CharSequence {
410
    String toString();
411
    Object[] getValues();
412
    String[] getStrings();
413
}
414

415
interface Range<T> extends List<T> {
416
    T getFrom();
417
    T getTo();
418
    boolean contains(Object obj);
419
    int size();
420
}
421

422
class Tuple implements List<Object> {
423
    Object get(int index);
424
    int size();
425
    Tuple subTuple(int startIndex, int endIndex);
426
}
427
```
428

429
### Configuration Types
430

431
```java { .api }
432
class ConfigObject extends LinkedHashMap<String, Object> {
433
    ConfigObject flatten();
434
    ConfigObject merge(ConfigObject other);
435
    void writeTo(Writer writer);
436
}
437

438
interface OptionAccessor {
439
    boolean hasOption(String opt);
440
    String getOptionValue(String opt);
441
    String[] getOptionValues(String opt);
442
    List<?> getArgList();
443
}
444
```
445

446
### AST Types
447

448
```java { .api }
449
class MethodNode extends ASTNode {
450
    String getName();
451
    Parameter[] getParameters();
452
    ClassNode getReturnType();
453
    Statement getCode();
454
    int getModifiers();
455
}
456

457
class FieldNode extends ASTNode {
458
    String getName();
459
    ClassNode getType();
460
    Expression getInitialExpression();
461
    int getModifiers();
462
}
463

464
class PropertyNode extends ASTNode {
465
    String getName();
466
    ClassNode getType();
467
    Statement getGetterBlock();
468
    Statement getSetterBlock();
469
    FieldNode getField();
470
}
471
```