0
# Recipe Transformations
1

2
30+ built-in recipes for common Maven operations including dependency management, plugin configuration, and project structure changes.
3

4
## Capabilities
5

6
### Base Recipe System
7

8
All Maven recipes extend the OpenRewrite Recipe base class and can be applied to Maven projects.
9

10
```java { .api }
11
/**
12
 * Base class for all OpenRewrite recipes
13
 */
14
public abstract class Recipe {
15
    /**
16
     * Get the display name of this recipe
17
     */
18
    public abstract String getDisplayName();
19
    
20
    /**
21
     * Get a description of what this recipe does
22
     */
23
    public abstract String getDescription();
24
    
25
    /**
26
     * Apply this recipe to source files
27
     */
28
    public abstract TreeVisitor<?, ExecutionContext> getVisitor();
29
}
30
```
31

32
### Dependency Management Recipes
33

34
#### AddDependency
35

36
Add a new dependency to the project's dependencies section.
37

38
```java { .api }
39
/**
40
 * Recipe to add a new dependency to Maven POM
41
 */
42
public class AddDependency extends Recipe {
43
    /**
44
     * Create recipe to add dependency
45
     * @param groupId Group ID of dependency to add
46
     * @param artifactId Artifact ID of dependency to add  
47
     * @param version Version of dependency to add
48
     * @param versionPattern Optional version pattern for dynamic versions
49
     * @param scope Dependency scope (default: Compile)
50
     * @param releasesOnly Whether to only consider release versions
51
     * @param onlyIfUsing Only add if these classes/packages are used
52
     * @param classifier Optional classifier
53
     * @param optional Whether dependency is optional
54
     * @param type Dependency type (default: jar)
55
     * @param familyPattern Pattern to match against recipe family
56
     * @param acceptTransitive Accept transitive dependencies
57
     */
58
    public AddDependency(String groupId, String artifactId, String version, 
59
                        @Nullable String versionPattern, @Nullable String scope,
60
                        @Nullable Boolean releasesOnly, @Nullable String onlyIfUsing,
61
                        @Nullable String classifier, @Nullable Boolean optional,
62
                        @Nullable String type, @Nullable String familyPattern,
63
                        @Nullable Boolean acceptTransitive);
64
}
65
```
66

67
**Usage Examples:**
68

69
```java
70
// Add JUnit dependency
71
AddDependency addJUnit = new AddDependency(
72
    "org.junit.jupiter", "junit-jupiter", "5.8.2", 
73
    null, "test", null, null, null, null, null, null, null
74
);
75

76
// Add Spring Boot starter with version pattern
77
AddDependency addSpringBoot = new AddDependency(
78
    "org.springframework.boot", "spring-boot-starter", null,
79
    "2.7.x", "compile", true, null, null, null, null, null, null
80
);
81

82
// Apply recipe
83
Recipe recipe = addJUnit;
84
RecipeRun run = recipe.run(List.of(pomDocument), ctx);
85
List<Result> results = run.getResults();
86
```
87

88
#### RemoveDependency
89

90
Remove a dependency from the project.
91

92
```java { .api }
93
/**
94
 * Recipe to remove a dependency from Maven POM
95
 */
96
public class RemoveDependency extends Recipe {
97
    /**
98
     * Create recipe to remove dependency
99
     * @param groupId Group ID of dependency to remove
100
     * @param artifactId Artifact ID of dependency to remove
101
     */
102
    public RemoveDependency(String groupId, String artifactId);
103
}
104
```
105

106
#### UpgradeDependencyVersion
107

108
Upgrade a dependency to a newer version.
109

110
```java { .api }
111
/**
112
 * Recipe to upgrade dependency version
113
 */
114
public class UpgradeDependencyVersion extends Recipe {
115
    /**
116
     * Create recipe to upgrade dependency version
117
     * @param groupId Group ID of dependency to upgrade
118
     * @param artifactId Artifact ID of dependency to upgrade
119
     * @param newVersion New version to upgrade to
120
     * @param versionPattern Optional version pattern constraint
121
     * @param overrideManagedVersion Whether to override managed version
122
     */
123
    public UpgradeDependencyVersion(String groupId, String artifactId, String newVersion,
124
                                   @Nullable String versionPattern, 
125
                                   @Nullable Boolean overrideManagedVersion);
126
}
127
```
128

129
#### ChangeDependencyScope
130

131
Change the scope of an existing dependency.
132

133
```java { .api }
134
/**
135
 * Recipe to change dependency scope
136
 */
137
public class ChangeDependencyScope extends Recipe {
138
    /**
139
     * Create recipe to change dependency scope
140
     * @param groupId Group ID of dependency
141
     * @param artifactId Artifact ID of dependency
142
     * @param newScope New scope to apply
143
     */
144
    public ChangeDependencyScope(String groupId, String artifactId, String newScope);
145
}
146
```
147

148
#### ChangeDependencyGroupIdAndArtifactId
149

150
Change the coordinates of a dependency (useful for artifact relocations).
151

152
```java { .api }
153
/**
154
 * Recipe to change dependency coordinates
155
 */
156
public class ChangeDependencyGroupIdAndArtifactId extends Recipe {
157
    /**
158
     * Create recipe to change dependency coordinates
159
     * @param oldGroupId Current group ID
160
     * @param oldArtifactId Current artifact ID
161
     * @param newGroupId New group ID
162
     * @param newArtifactId New artifact ID
163
     * @param newVersion Optional new version
164
     */
165
    public ChangeDependencyGroupIdAndArtifactId(String oldGroupId, String oldArtifactId,
166
                                               String newGroupId, String newArtifactId,
167
                                               @Nullable String newVersion);
168
}
169
```
170

171
### Managed Dependency Recipes  
172

173
#### AddManagedDependency
174

175
Add a managed dependency to the dependencyManagement section.
176

177
```java { .api }
178
/**
179
 * Recipe to add managed dependency
180
 */
181
public class AddManagedDependency extends Recipe {
182
    /**
183
     * Create recipe to add managed dependency
184
     * @param groupId Group ID of managed dependency
185
     * @param artifactId Artifact ID of managed dependency
186
     * @param version Version of managed dependency
187
     * @param scope Optional scope for managed dependency
188
     * @param type Optional type for managed dependency
189
     * @param classifier Optional classifier for managed dependency
190
     */
191
    public AddManagedDependency(String groupId, String artifactId, String version,
192
                               @Nullable String scope, @Nullable String type,  
193
                               @Nullable String classifier);
194
}
195
```
196

197
#### RemoveManagedDependency
198

199
Remove a managed dependency from dependencyManagement.
200

201
```java { .api }
202
/**
203
 * Recipe to remove managed dependency
204
 */
205
public class RemoveManagedDependency extends Recipe {
206
    /**
207
     * Create recipe to remove managed dependency
208
     * @param groupId Group ID of managed dependency to remove
209
     * @param artifactId Artifact ID of managed dependency to remove
210
     */
211
    public RemoveManagedDependency(String groupId, String artifactId);
212
}
213
```
214

215
### Plugin Management Recipes
216

217
#### AddPlugin
218

219
Add a Maven plugin to the build plugins section.
220

221
```java { .api }
222
/**
223
 * Recipe to add Maven plugin
224
 */
225
public class AddPlugin extends Recipe {
226
    /**
227
     * Create recipe to add Maven plugin
228
     * @param groupId Plugin group ID (default: org.apache.maven.plugins)
229
     * @param artifactId Plugin artifact ID
230
     * @param version Plugin version
231
     * @param configuration Optional plugin configuration
232
     * @param dependencies Optional plugin dependencies
233
     * @param executions Optional plugin executions
234
     */
235
    public AddPlugin(String groupId, String artifactId, @Nullable String version,
236
                    @Nullable String configuration, @Nullable List<Dependency> dependencies,
237
                    @Nullable List<PluginExecution> executions);
238
}
239
```
240

241
#### UpgradePluginVersion
242

243
Upgrade a Maven plugin to a newer version.
244

245
```java { .api }
246
/**
247
 * Recipe to upgrade plugin version
248
 */
249
public class UpgradePluginVersion extends Recipe {
250
    /**
251
     * Create recipe to upgrade plugin version
252
     * @param groupId Plugin group ID
253
     * @param artifactId Plugin artifact ID
254
     * @param newVersion New version to upgrade to
255
     */
256
    public UpgradePluginVersion(String groupId, String artifactId, String newVersion);
257
}
258
```
259

260
#### ChangePluginConfiguration
261

262
Modify plugin configuration.
263

264
```java { .api }
265
/**
266
 * Recipe to change plugin configuration
267
 */
268
public class ChangePluginConfiguration extends Recipe {
269
    /**
270
     * Create recipe to change plugin configuration
271
     * @param groupId Plugin group ID
272
     * @param artifactId Plugin artifact ID
273
     * @param configuration New configuration XML
274
     */
275
    public ChangePluginConfiguration(String groupId, String artifactId, String configuration);
276
}
277
```
278

279
#### ChangePluginExecutions
280

281
Modify plugin executions.
282

283
```java { .api }
284
/**
285
 * Recipe to change plugin executions
286
 */
287
public class ChangePluginExecutions extends Recipe {
288
    /**
289
     * Create recipe to change plugin executions  
290
     * @param groupId Plugin group ID
291
     * @param artifactId Plugin artifact ID
292
     * @param executions New executions configuration
293
     */
294
    public ChangePluginExecutions(String groupId, String artifactId, 
295
                                 List<PluginExecution> executions);
296
}
297
```
298

299
### Property Management Recipes
300

301
#### AddProperty
302

303
Add a property to the project properties section.
304

305
```java { .api }
306
/**
307
 * Recipe to add Maven property
308
 */
309
public class AddProperty extends Recipe {
310
    /**
311
     * Create recipe to add property
312
     * @param key Property name
313
     * @param value Property value  
314
     * @param preserveExisting Whether to preserve existing value if present
315
     */
316
    public AddProperty(String key, String value, Boolean preserveExisting);
317
}
318
```
319

320
#### ChangePropertyValue
321

322
Change the value of an existing property.
323

324
```java { .api }
325
/**
326
 * Recipe to change property value
327
 */
328
public class ChangePropertyValue extends Recipe {
329
    /**
330
     * Create recipe to change property value
331
     * @param key Property name to change
332
     * @param newValue New property value
333
     * @param addIfMissing Whether to add property if it doesn't exist
334
     */
335
    public ChangePropertyValue(String key, String newValue, Boolean addIfMissing);
336
}
337
```
338

339
#### RemoveProperty
340

341
Remove a property from the project.
342

343
```java { .api }
344
/**
345
 * Recipe to remove Maven property
346
 */
347
public class RemoveProperty extends Recipe {
348
    /**
349
     * Create recipe to remove property
350
     * @param key Property name to remove
351
     */
352
    public RemoveProperty(String key);
353
}
354
```
355

356
#### RemoveRedundantProperties
357

358
Remove properties that are redundant or have default values.
359

360
```java { .api }
361
/**
362
 * Recipe to remove redundant properties
363
 */
364
public class RemoveRedundantProperties extends Recipe {
365
    // No constructor parameters - removes known redundant properties
366
}
367
```
368

369
### Project Structure Recipes
370

371
#### AddParentPom
372

373
Add or change the parent POM reference.
374

375
```java { .api }
376
/**
377
 * Recipe to add parent POM
378
 */
379
public class AddParentPom extends Recipe {
380
    /**
381
     * Create recipe to add parent POM
382
     * @param groupId Parent group ID
383
     * @param artifactId Parent artifact ID
384
     * @param version Parent version
385
     * @param relativePath Optional relative path to parent
386
     * @param versionPattern Optional version pattern
387
     */
388
    public AddParentPom(String groupId, String artifactId, String version,
389
                       @Nullable String relativePath, @Nullable String versionPattern);
390
}
391
```
392

393
#### ChangeParentPom
394

395
Change the parent POM coordinates.
396

397
```java { .api }
398
/**
399
 * Recipe to change parent POM
400
 */
401
public class ChangeParentPom extends Recipe {
402
    /**
403
     * Create recipe to change parent POM
404
     * @param oldGroupId Current parent group ID
405
     * @param oldArtifactId Current parent artifact ID
406
     * @param newGroupId New parent group ID
407
     * @param newArtifactId New parent artifact ID
408
     * @param newVersion New parent version
409
     * @param versionPattern Optional version pattern
410
     */
411
    public ChangeParentPom(String oldGroupId, String oldArtifactId,
412
                          String newGroupId, String newArtifactId, String newVersion,
413
                          @Nullable String versionPattern);
414
}
415
```
416

417
#### IncrementProjectVersion
418

419
Increment the project version following semantic versioning.
420

421
```java { .api }
422
/**
423
 * Recipe to increment project version
424
 */
425
public class IncrementProjectVersion extends Recipe {
426
    /**
427
     * Create recipe to increment version
428
     * @param incrementType Type of increment (major, minor, patch)
429
     */
430
    public IncrementProjectVersion(String incrementType);
431
}
432
```
433

434
### Advanced Dependency Recipes
435

436
#### AddCommentToMavenDependency
437

438
Add XML comments to dependencies for documentation.
439

440
```java { .api }
441
/**
442
 * Recipe to add comment to Maven dependency
443
 */
444
public class AddCommentToMavenDependency extends Recipe {
445
    /**
446
     * Create recipe to add dependency comment
447
     * @param groupId Dependency group ID
448
     * @param artifactId Dependency artifact ID
449
     * @param comment Comment text to add
450
     */
451
    public AddCommentToMavenDependency(String groupId, String artifactId, String comment);
452
}
453
```
454

455
#### RemoveDuplicateDependencies
456

457
Remove duplicate dependency declarations.
458

459
```java { .api }
460
/**
461
 * Recipe to remove duplicate dependencies
462
 */
463
public class RemoveDuplicateDependencies extends Recipe {
464
    // No constructor parameters - removes all duplicates automatically
465
}
466
```
467

468
#### AddExclusion
469

470
Add exclusions to dependencies.
471

472
```java { .api }
473
/**
474
 * Recipe to add dependency exclusion
475
 */
476
public class AddExclusion extends Recipe {
477
    /**
478
     * Create recipe to add exclusion
479
     * @param groupId Dependency group ID to add exclusion to
480
     * @param artifactId Dependency artifact ID to add exclusion to
481
     * @param exclusionGroupId Group ID to exclude
482
     * @param exclusionArtifactId Artifact ID to exclude
483
     */
484
    public AddExclusion(String groupId, String artifactId,  
485
                       String exclusionGroupId, String exclusionArtifactId);
486
}
487
```
488

489
#### RemoveExclusion
490

491
Remove exclusions from dependencies.
492

493
```java { .api }
494
/**
495
 * Recipe to remove dependency exclusion
496
 */
497
public class RemoveExclusion extends Recipe {
498
    /**
499
     * Create recipe to remove exclusion
500
     * @param groupId Dependency group ID to remove exclusion from
501
     * @param artifactId Dependency artifact ID to remove exclusion from
502
     * @param exclusionGroupId Group ID exclusion to remove
503
     * @param exclusionArtifactId Artifact ID exclusion to remove
504
     */
505
    public RemoveExclusion(String groupId, String artifactId,
506
                          String exclusionGroupId, String exclusionArtifactId);
507
}
508
```
509

510
### Specialized Recipes
511

512
#### UpdateMavenProjectPropertyJavaVersion
513

514
Update Java version properties in Maven projects.
515

516
```java { .api }
517
/**
518
 * Recipe to update Java version properties
519
 */
520
public class UpdateMavenProjectPropertyJavaVersion extends Recipe {
521
    /**
522
     * Create recipe to update Java version
523
     * @param version New Java version (e.g., "17", "11", "8")
524
     */
525
    public UpdateMavenProjectPropertyJavaVersion(String version);
526
}
527
```
528

529
#### UseMavenCompilerPluginReleaseConfiguration
530

531
Use Maven Compiler Plugin release configuration instead of source/target properties.
532

533
```java { .api }
534
/**
535
 * Recipe to use Maven Compiler Plugin release configuration
536
 */
537
public class UseMavenCompilerPluginReleaseConfiguration extends Recipe {
538
    /**
539
     * Create recipe to use release configuration
540
     * @param releaseVersion Java release version (e.g., "17", "11")
541
     */
542
    public UseMavenCompilerPluginReleaseConfiguration(String releaseVersion);
543
}
544
```
545

546
#### ModernizeObsoletePoms
547

548
Modernize obsolete POM configurations and deprecated elements.
549

550
```java { .api }
551
/**
552
 * Recipe to modernize obsolete POM configurations
553
 */
554
public class ModernizeObsoletePoms extends Recipe {
555
    // No constructor parameters - automatically modernizes obsolete configurations
556
}
557
```
558

559
#### AddDevelocityMavenExtension
560

561
Add Develocity (Gradle Enterprise) Maven extension.
562

563
```java { .api }
564
/**
565
 * Recipe to add Develocity Maven extension
566
 */
567
public class AddDevelocityMavenExtension extends Recipe {
568
    /**
569
     * Create recipe to add Develocity extension
570
     * @param version Develocity extension version
571
     * @param server Optional Develocity server URL
572
     */
573
    public AddDevelocityMavenExtension(String version, @Nullable String server);
574
}
575
```
576

577
#### EnableDevelocityBuildCache
578

579
Enable Develocity build cache in Maven projects.
580

581
```java { .api }
582
/**
583
 * Recipe to enable Develocity build cache
584
 */
585
public class EnableDevelocityBuildCache extends Recipe {
586
    // No constructor parameters - enables build cache automatically
587
}
588
```
589

590
### Plugin Dependency Recipes
591

592
#### AddPluginDependency
593

594
Add dependencies to Maven plugins.
595

596
```java { .api }
597
/**
598
 * Recipe to add plugin dependency
599
 */
600
public class AddPluginDependency extends Recipe {
601
    /**
602
     * Create recipe to add plugin dependency
603
     * @param pluginGroupId Plugin group ID
604
     * @param pluginArtifactId Plugin artifact ID
605
     * @param dependencyGroupId Dependency group ID to add
606
     * @param dependencyArtifactId Dependency artifact ID to add
607
     * @param dependencyVersion Dependency version
608
     */
609
    public AddPluginDependency(String pluginGroupId, String pluginArtifactId,
610
                              String dependencyGroupId, String dependencyArtifactId,
611
                              String dependencyVersion);
612
}
613
```
614

615
#### RemovePluginDependency
616

617
Remove dependencies from Maven plugins.
618

619
```java { .api }
620
/**
621
 * Recipe to remove plugin dependency
622
 */
623
public class RemovePluginDependency extends Recipe {
624
    /**
625
     * Create recipe to remove plugin dependency
626
     * @param pluginGroupId Plugin group ID
627
     * @param pluginArtifactId Plugin artifact ID
628
     * @param dependencyGroupId Dependency group ID to remove
629
     * @param dependencyArtifactId Dependency artifact ID to remove
630
     */
631
    public RemovePluginDependency(String pluginGroupId, String pluginArtifactId,
632
                                 String dependencyGroupId, String dependencyArtifactId);
633
}
634
```
635

636
### Recipe Composition and Usage
637

638
**Usage Examples:**
639

640
```java
641
// Apply single recipe
642
AddDependency recipe = new AddDependency(
643
    "org.junit.jupiter", "junit-jupiter", "5.8.2", 
644
    null, "test", null, null, null, null, null, null, null
645
);
646

647
ExecutionContext ctx = new InMemoryExecutionContext();
648
RecipeRun run = recipe.run(List.of(pomDocument), ctx);
649
List<Result> results = run.getResults();
650

651
for (Result result : results) {
652
    if (result.getDiff() != null) {
653
        System.out.println("Applied change:");
654
        System.out.println(result.getDiff());
655
    }
656
}
657

658
// Compose multiple recipes
659
List<Recipe> recipes = Arrays.asList(
660
    new AddDependency("org.junit.jupiter", "junit-jupiter", "5.8.2", 
661
                     null, "test", null, null, null, null, null, null, null),
662
    new ChangePropertyValue("maven.compiler.source", "17", true),
663
    new ChangePropertyValue("maven.compiler.target", "17", true),
664
    new UpgradePluginVersion("org.apache.maven.plugins", "maven-compiler-plugin", "3.8.1")
665
);
666

667
// Apply all recipes
668
for (Recipe recipe : recipes) {
669
    RecipeRun run = recipe.run(sourceFiles, ctx);
670
    sourceFiles = run.getResults().stream()
671
        .map(result -> result.getAfter())
672
        .filter(Objects::nonNull)
673
        .collect(toList());
674
}
675

676
// Use RecipeSpec for declarative configuration
677
RecipeSpec spec = new RecipeSpec();
678
spec.setName("com.example.UpdateProject");
679
spec.setDisplayName("Update Project Dependencies");
680
spec.setRecipeList(Arrays.asList(
681
    "org.openrewrite.maven.AddDependency",
682
    "org.openrewrite.maven.UpgradeDependencyVersion"
683
));
684

685
Recipe compositeRecipe = Recipe.fromSpec(spec);
686
```