Important APIs

Dependency Facet

A lot of Forge plugins make it easy to install extra libraries or frameworks to your project. In a Maven project this almost always result in adding new dependencies to your POM by copy pasting from some website. Make installing a framework easier by letting Forge do the POM work for the user. 

Creating dependencies

Dependencies can easily be created using the DependencyBuilder.

Dependency dep = DependencyBuilder.create()

The Dependency class is also input for many other Forge APIs.

Prompting for versions

Of course it’s a bad idea to couple your plugin directly to a specific version of the Maven dependency. To let the user choose a version Forge can list all available versions in the repository and prompt the user.

DependencyFacet dependencyFacet = project.getFacet(DependencyFacet.class);
Dependency myDep = DependencyBuilder.create()
List<Dependency> versions = dependencyFacet.resolveAvailableVersions(myDep);
Dependency dependency = shell.promptChoiceTyped("What version do you want to install?", versions);

You can also limit the versions using a range:



Adding a dependency to the POM

Now that we have our dependency we can add it to the POM file. Maven supports different ways to work with plugin; you can either have managed dependencies or direct dependencies. Managed dependencies are an indirection where you specify the version of a dependency in the parent POM. For multi-module projects this is often preferred. Forge can do both however.

dependencyFacet.addDirectDependency(Dependency dep);
dependencyFacet.addManagedDependency(Dependency dep);

Maven Plugin Facet

A little more advanced is creating Maven Plugin configuration from your plugin.
First of all your plugin needs the forge-maven-api.


Creating a plugin

Now let’s start building the plugin. You use the MavenPluginBuilder for this. First of all a plugin needs a dependency (group id and artifact id).

DependencyBuilder findbugsDependencyBuilder = DependencyBuilder.create()

MavenPluginBuilder findbugsPlugin = MavenPluginBuilder.create()

Add a plugin to the POM

After building a plugin you can add it to the POM.

MavenPluginFacet pluginFacet = project.getFacet(MavenPluginFacet.class);

Plugin Configuration

Most Maven plugins need some kind of configuration. Each configuration element is also a XML element in the POM and can potentialy be deeply nested. This makes the API a little tricky to work with, so try to make small steps.

So for example, let’s add a xmlOutput configuration element to the plugin.

MavenPluginBuilder findbugsPlugin = MavenPluginBuilder.create()

Resource Facet

The Resource Facet gives access to resources (files) in a project. It understands the Maven directory structure (e.g. src/test/resources).

FileResource<?> resource = (FileResource<?>) resources.getTestResourceFolder().getChild("example.xml");

resource.setContents("new string");

XML parsing and generation

Many plugins will have to read/write XML files (e.g. to generate configuration files). Forge has a convenient XML API.

Node xml = XMLParser.parse(resource.getResourceInputStream());
Node config = xml.getOrCreate("someelement");


This will result in the following XML:

     <property name="test">hello</property>