Table of Contents
The Eclipse plugins generate files that are used by the Eclipse IDE, thus making it possible to import the project into Eclipse (File
- Import…
- Existing Projects into Workspace
).
The eclipse-wtp
is automatically applied whenever the eclipse
plugin is applied to a War or Ear project. For utility projects (i.e. Java projects used by other web projects), you need to apply the eclipse-wtp
plugin explicitly.
What exactly the eclipse
plugin generates depends on which other plugins are used:
Eclipse plugin behavior
Plugin | Description |
None |
Generates minimal |
Adds Java configuration to |
|
Adds Groovy configuration to |
|
Adds Scala support to |
|
Adds web application support to |
|
Adds ear application support to |
The eclipse-wtp
plugin generates all WTP settings files and enhances the .project
file. If a Java or War is applied, .classpath
will be extended to get a proper packaging structure for this utility library or web application project.
Both Eclipse plugins are open to customization and provide a standardized set of hooks for adding and removing content from the generated files.
To use either the Eclipse or the Eclipse WTP plugin, include one of the lines in your build script:
Note: Internally, the eclipse-wtp
plugin also applies the eclipse
plugin so you don’t need to apply both.
Both Eclipse plugins add a number of tasks to your projects. The main tasks that you will use are the eclipse
and cleanEclipse
tasks.
The Eclipse plugins add the tasks shown below to a project.
Eclipse plugin - tasks
Task name | Depends on | Type | Description |
|
all Eclipse configuration file generation tasks |
Generates all Eclipse configuration files |
|
|
all Eclipse configuration file clean tasks |
Removes all Eclipse configuration files |
|
|
|
Removes the |
|
|
|
Removes the |
|
|
|
Removes the |
|
|
|
Generates the |
|
|
|
Generates the |
|
|
|
Generates the |
Eclipse WTP plugin - additional tasks
Task name | Depends on | Type | Description |
|
|
Removes the |
|
|
|
Removes the |
|
|
|
Generates the |
|
|
|
Generates the |
Configuration of the Eclipse plugins
Model | Reference name | Description |
|
Top level element that enables configuration of the Eclipse plugin in a DSL-friendly fashion. |
|
|
Allows configuring project information |
|
|
Allows configuring classpath information. |
|
|
Allows configuring jdt information (source/target Java compatibility). |
|
|
Allows configuring wtp component information only if |
|
|
Allows configuring wtp facet information only if |
The Eclipse plugins allow you to customize the generated metadata files. The plugins provide a DSL for configuring model objects that model the Eclipse view of the project. These model objects are then merged with the existing Eclipse XML metadata to ultimately generate new metadata. The model objects provide lower level hooks for working with domain objects representing the file content before and after merging with the model configuration. They also provide a very low level hook for working directly with the raw XML for adjustment before it is persisted, for fine tuning and configuration that the Eclipse and Eclipse WTP plugins do not model.
Sections of existing Eclipse files that are also the target of generated content will be amended or overwritten, depending on the particular section. The remaining sections will be left as-is.
To completely rewrite existing Eclipse files, execute a clean task together with its corresponding generation task, like “gradle cleanEclipse eclipse
” (in that order). If you want to make this the default behavior, add “tasks.eclipse.dependsOn(cleanEclipse)
” to your build script. This makes it unnecessary to execute the clean task explicitly.
This strategy can also be used for individual files that the plugins would generate. For instance, this can be done for the “.classpath
” file with “gradle cleanEclipseClasspath eclipseClasspath
”.
The Eclipse plugins provide objects modeling the sections of the Eclipse files that are generated by Gradle. The generation lifecycle is as follows:
The file is read; or a default version provided by Gradle is used if it does not exist
The
beforeMerged
hook is executed with a domain object representing the existing fileThe existing content is merged with the configuration inferred from the Gradle build or defined explicitly in the eclipse DSL
The
whenMerged
hook is executed with a domain object representing contents of the file to be persistedThe
withXml
hook is executed with a raw representation of the XML that will be persistedThe final XML is persisted
The following table lists the domain object used for each of the Eclipse model types:
Advanced configuration hooks
Model | beforeMerged { arg -> } argument type |
whenMerged { arg -> } argument type |
withXml { arg -> } argument type |
withProperties { arg -> } argument type |
- |
||||
- |
||||
- |
||||
- |
||||
- |
A complete overwrite causes all existing content to be discarded, thereby losing any changes made directly in the IDE. Alternatively, the beforeMerged
hook makes it possible to overwrite just certain parts of the existing content. The following example removes all existing dependencies from the Classpath
domain object:
Example: Partial Overwrite for Classpath
build.gradle
eclipse.classpath.file { beforeMerged { classpath -> classpath.entries.removeAll { entry -> entry.kind == 'lib' || entry.kind == 'var' } } }
The resulting .classpath
file will only contain Gradle-generated dependency entries, but not any other dependency entries that may have been present in the original file. (In the case of dependency entries, this is also the default behavior.) Other sections of the .classpath
file will be either left as-is or merged. The same could be done for the natures in the .project
file:
Example: Partial Overwrite for Project
build.gradle
eclipse.project.file.beforeMerged { project -> project.natures.clear() }
The whenMerged
hook allows to manipulate the fully populated domain objects. Often this is the preferred way to customize Eclipse files. Here is how you would export all the dependencies of an Eclipse project:
Example: Export Classpath Entries
build.gradle
eclipse.classpath.file {
whenMerged { classpath ->
classpath.entries.findAll { entry -> entry.kind == 'lib' }*.exported = false
}
}
The withXml
hook allows to manipulate the in-memory XML representation just before the file gets written to disk. Although Groovy’s XML support makes up for a lot, this approach is less convenient than manipulating the domain objects. In return, you get total control over the generated file, including sections not modeled by the domain objects.
Example: Customizing the XML
build.gradle
apply plugin: 'eclipse-wtp' eclipse.wtp.facet.file.withXml { provider -> provider.asNode().fixed.find { it.@facet == 'jst.java' }.@facet = 'jst2.java' }