Overview of Maven Projects module

MavenProjectAPI
The Maven Project API provides some miscellaneous friend APIs and SPIs relating to Maven projects.

What is New (see all changes)?

Nov 5 '24 RunConfig provides access to Maven options
RunConfig now provides access to Maven options / flags. Client can decide which options / flags will be passed to command line.
Aug 10 '24 Enable using PluginConfigPathParams with null valued pathItemName Maven documentation for plugin configuration declares, that for list and array typed configuration plugins, the name of the single entry element does not matter, only the name of the wrapping element is relevant. This change modifies
```
PluginPropertyUtils.PluginConfigPathParams
```
to always report
```
null
```
for
```
pathItemName
```
and adds a constructor without that parameter, deprecating the original constructor.
Dec 6 '23 Allow extensions to declare run-like goals
The GUI recognizes user modifications to actions and refuses to configure a modified "run" action with vm and app arguments. It is now possible for a plugin to register an alternative goal, which is recognized as "exec"-like one and does not disable the GUI.

For an example, see MavenActionProvider.
Oct 3 '23 Support for partially loaded projects Added a getPartialProject that returns potentially incompletely loaded project instead of a mocked-up fallback (see isErrorPlaceholder(). Also added a isIncomplete() check that checks project's status.
Jan 23 '23 Added a RunUtils.createRunConfig() variant that allows to create a RunConfig for a project-defined action. Clients can use this function to use all user customizations that may have been configured for the project action before executing it using RunUtils.run.

Use Cases

API/SPI to be used by modules wanting to enhance the maven project's integration in the IDE.

Exported Interfaces

This table lists all of the module exported APIs with defined stability classifications. It is generated based on answers to questions about the architecture of the module. Read them all...

Group of java interfaces

Group of java interfaces
Interface Name	In/Out	Stability	Specified in What Document?
MavenProjectAPI	Exported	Friend	The Maven Project API provides some miscellaneous friend APIs and SPIs relating to Maven projects.

Group of layer interfaces

Interface Name In/Out Stability Specified in What Document?

MavenProjectCustomizer

Exported

Official

"Projects/org-netbeans-modules-maven/Customizer" folder's content is used to construct the project's customizer. It's content is expected to be ProjectCustomizer.CompositeCategoryProvider instances. The lookup passed to the panels contains an instance of Project and org.netbeans.modules.maven.api.customizer.ModelHandle Please note that the latter is not part of any public APIs and you need friend dependency to make use of it.

MavenLogicalViewProvider

Exported

Official

"Projects/org-netbeans-modules-maven/Nodes" folder's content is used to construct the project's child nodes. It's content is expected to be NodeFactory instances.

MavenLookup

Exported

Official

"Projects/org-netbeans-modules-maven/Lookup" folder's content is used to construct the project's additional lookup. It's content is expected to be LookupProvider instances. Maven project provides LookupMergers for Sources, PrivilegedTemplates, RecommendedTemplates and other classes. Implementations added by 3rd parties will be merged into a single instance in the project's lookup.

MavenPackagingLookup

Exported

Under Development

Projects/org-netbeans-modules-maven/<packaging-type>/Lookup is added to the project's additional Lookup. The content is expected to contain packaing-specific services and processors, for example, PrerequisitesCheckers. In addition, Projects/org-netbeans-modules-maven/_any/Lookup defines services that act after the packaging-specific ones.

For the details and examples, see description in PrerequisitesChecker javadoc.

PluginLookup

Exported

Official

Technology-related services can be registered so they activate in a project that has configured a specific Maven plugin. Such services should be placed in Projects/org-netbeans-modules-maven/<plugin-id>/Lookup folder. Maven core module will plug these providers in as soon as the plugin-id appears in the POM model, and will remove them from project's Lookup when the plugin is no longer part of the project's model. See NbMavenProject javadoc for details/examples.

MavenActions

Exported

Official

"Projects/org-netbeans-modules-maven/ProjectActions", "Projects/org-netbeans-modules-maven/DependenciesActions" and "Projects/org-netbeans-modules-maven/DependencyActions" folders' content is used to add item's to node popup. To main project node, Dependencies node and node for single dependency. It's content is expected to be Action instances.

LifecycleParticipants

Exported

Official

A module can disable warning for a custom lifecycle participant by creating a folder in Projects/org-netbeans-modules-maven/LifecycleParticipant. Currently single boolean attribute, ignoreOnModelLoad is supported, which suppresses project problem and warning about the custom participant. The participant's code does not run after project load.

MavenArchetypes

Exported

Official

"Projects/org-netbeans-modules-maven/Archetypes" folder contains fileobjects that represent archetypes. The archetypes are defined by the following file attributes:

Archetype attributes
groupId	mandatory
artifactId	mandatory
version	mandatory
repository	optional	url of the archetype's repository
nameBundleKey	optional	key in bundle file that holds localized name
descriptionBundleKey	optional	key in bundle file that holds localized description

Project.org-netbeans-modules-maven.RunGoals Exported Under Development A executable-like plugin goals, that may serve in place of exec:exec may be registered here. The core implementation will recognize such goals as exec's and will not disable app amd VM parameter configuration UI. For an example, see MavenActionProvider.

Group of lookup interfaces

Group of lookup interfaces
Interface Name	In/Out	Stability	Specified in What Document?
ExplicitProcessParameters	Exported	Under Development	Project actions that execute user application (run, debug) accept additional VM and application arguments as a series of ExplicitProcessParameters instance(s) in the action's Lookup. See ExplicitProcessParameters javadoc for more details.

Group of property interfaces

Group of property interfaces
Interface Name	In/Out	Stability	Specified in What Document?
netbeans.ignore.jdk.bootclasspath	Exported	Under Development	The maven support recognizes special tag in maven-compiler-plugin configuration that instructs the IDE to not put JDK libraries on a classpath. One can use: <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <compilerArguments> <bootclasspath>netbeans.ignore.jdk.bootclasspath</bootclasspath> </compilerArguments> </configuration> </plugin> section in `pom.xml` to suppress the JDK libraries.
exec.vmArgs	Exported	Stable	The plugin exports Java VM parameters to be used for application execution in `${exec.vmArgs}` property that can be used in action mappings or Maven pom.xml.
exec.appArgs	Exported	Stable	The plugin exports application parameters to be used for application execution in `${exec.appArgs}` property that can be used in action mappings or Maven pom.xml.
NbIde.	Exported	Private	Properties designed to be read only by NB IDE code, and not passed to Maven can be prefixed by this prefix. Maven module uses such properties to communicate between services that participate on maven launch internally.
jpda.attach	Exported	Stable	One can define following code in nbactions.xml file to start a process during goal execution and attach a debugger to it once the execution is over. Here is an example using enhancement in the Maven Android plugin: <action> <actionName>debug</actionName> <goals> <goal>clean</goal> <goal>package</goal> <goal>android:deploy</goal> <goal>android:run</goal> </goals> <properties> <skipTests>true</skipTests> <android.run.debug>${jpda.attach.port}</android.run.debug> <jpda.attach>true</jpda.attach> </properties> </action> Value of `jpda.attach` property can either be `true` and in such case the IDE finds an empty port and sets values of `jpda.attach.port` and `jpda.attach.address` properties accordingly, or it can be directly specified `address:port` or just port number to connect to.
jpda.attach.trigger	Exported	Stable	One can define following code in nbactions.xml file to start a process during goal execution and attach a debugger to it when the external process prints a text indicating it's ready for attaching debugger. One example is debugging applications using Multi-OS Engine: <action> <actionName>debug</actionName> <goals> <goal>package</goal> <goal>moe:launch</goal> </goals> <properties> <skipTests>true</skipTests> <moe.options>debug:${jpda.attach.port}</moe.options> <jpda.attach>true</jpda.attach> <jpda.attach.trigger>JDWP will wait for debugger on port</jpda.attach.trigger> </properties> <activatedProfiles> <activatedProfile>moe</activatedProfile> </activatedProfiles> </action> Value of `jpda.attach.trigger` property is the expected text.

Group of systemproperty interfaces

Group of systemproperty interfaces
Interface Name	In/Out	Stability	Specified in What Document?
org.netbeans.modules.maven.execute.AbstractOutputHandler.SLEEP_DELAY	Exported	Under Development	A system property can be used to change the default indexing sleep delay during builds, in case reparsing starts too soon (wasting CPU) or too late (impeding editing).

Group of branding interfaces

Group of branding interfaces
Interface Name	In/Out	Stability	Specified in What Document?
org.netbeans.modules.maven.options.DEFAULT_REUSE_OUTPUT	Exported	Under Development	Brand the `DEFAULT_REUSE_OUTPUT` key in a `org.netbeans.modules.maven.options.Bundle` file with one of the values `true` or `false` to specify the default behavior of reusing output by your application. Use `never` value, if the reuse shall never be done, regardless of the settings value.
org.netbeans.modules.maven.api.execute.DEFAULT_COMPILE_ON_SAVE	Exported	Under Development	Brand the `DEFAULT_COMPILE_ON_SAVE` key in a `org.netbeans.modules.maven.api.execute.Bundle` file with one of the values `all` or `none` to specify the default behavior of compile on save in Maven projects.
org.netbeans.modules.maven.indexer.api.DEFAULT_CREATE_INDEX	Exported	Under Development	Brand the `DEFAULT_CREATE_INDEX` key in `org.netbeans.modules.maven.indexer.api.Bundle` file with one of the values `true` or `false` to control (usually to disable with `DEFAULT_CREATE_INDEX=false`) the default behavior automatic maven index downloading.
org.netbeans.modules.maven.indexer.api.DEFAULT_UPDATE_FREQ	Exported	Under Development	Brand the `DEFAULT_UPDATE_FREQ` key in `org.netbeans.modules.maven.indexer.api.Bundle` file with one of the values: `0` - once a week `1` - once a day `2` - on each startup `3` - never to control (usually to disable with `DEFAULT_UPDATE_FREQ=3`) the default behavior automatic maven index downloading.

Group of java.io.File interfaces

Interface Name In/Out Stability Specified in What Document?

nbactions.xml

Exported

Group of java.io.File interfaces
Interface Name	In/Out	Stability	Specified in What Document?
nbactions.xml	Exported	Stable	NetBeans Maven support recognizes special file(s) that can be placed next to a `pom.xml`. These files contain description of bindings between NetBeans UI actions (compile, run, debug, etc.) and the actual Maven goals to execute. Primary name of the file is `nbactions.xml`. In addition to this, there can be other `nbactions-profile.xml` where profile is the name of a Maven profile. These files are active when such profile is choosen as a selected project configuration. The sample format of the file follows: <?xml version="1.0" encoding="UTF-8"?> <actions> <action> <actionName>run</actionName> <goals> <goal>process-classes</goal> <goal>exec:java</goal> </goals> </action> <action> <actionName>debug</actionName> <goals> <goal>process-classes</goal> <goal>exec:java</goal> </goals> <properties> <jpda.listen>maven</jpda.listen> </properties> </action> <action> <!-- this action is shown in 'Custom' submenu of project popup menu --> <actionName>CUSTOM-bck2brwsr-show</actionName> <displayName>Run in a Browser</displayName> <goals> <goal>clean</goal> <goal>package</goal> <goal>bck2brwsr:show</goal> </goals> <activatedProfiles> <activatedProfile>bck2brwsr</activatedProfile> </activatedProfiles> <properties> <skipTests>true</skipTests> </properties> </action> <!-- the profiles section is only useful in nbactions.xml and gets activated when profile of given id is choosen in the UI --> <profiles> <profile> <id>bck2brwsr</id> <!-- changes meaning of run action when bck2brwsr profile is selected --> <actions> <action> <actionName>run</actionName> <displayName>Run in a Browser</displayName> <goals> <goal>clean</goal> <goal>package</goal> <goal>bck2brwsr:show</goal> </goals> <activatedProfiles> <activatedProfile>bck2brwsr</activatedProfile> </activatedProfiles> <properties> <skipTests>true</skipTests> </properties> </action> </actions> </profile> </profiles> </actions> If an action is not found in currently selected <profile> section, the system fallbacks to the main list of actions. In the previous example, the debug action would be taken from main list for all the profiles.

Stable

NetBeans Maven support recognizes special file(s) that can be placed next to a pom.xml. These files contain description of bindings between NetBeans UI actions (compile, run, debug, etc.) and the actual Maven goals to execute.

Primary name of the file is nbactions.xml. In addition to this, there can be other nbactions-profile.xml where profile is the name of a Maven profile. These files are active when such profile is choosen as a selected project configuration. The sample format of the file follows:

<?xml version="1.0" encoding="UTF-8"?>
<actions>
    <action>
        <actionName>run</actionName>
        <goals>
            <goal>process-classes</goal>
            <goal>exec:java</goal>
        </goals>
    </action>
    <action>
        <actionName>debug</actionName>
        <goals>
            <goal>process-classes</goal>
            <goal>exec:java</goal>
        </goals>
        <properties>
            <jpda.listen>maven</jpda.listen>
        </properties>
    </action>
    <action>
        <!-- this action is shown in 'Custom' submenu of project popup menu -->
        <actionName>CUSTOM-bck2brwsr-show</actionName>
        <displayName>Run in a Browser</displayName>
        <goals>
            <goal>clean</goal>
            <goal>package</goal>
            <goal>bck2brwsr:show</goal>
        </goals>
        <activatedProfiles>
            <activatedProfile>bck2brwsr</activatedProfile>
        </activatedProfiles>
        <properties>
            <skipTests>true</skipTests>
        </properties>
    </action>
    <!-- the profiles section is only useful in nbactions.xml 
        and gets activated when profile of given id is choosen in the UI
        -->
    <profiles>
        <profile>
            <id>bck2brwsr</id>
            <!-- changes meaning of run action when bck2brwsr profile
                 is selected
            -->
            <actions>
                <action>
                    <actionName>run</actionName>
                    <displayName>Run in a Browser</displayName>
                    <goals>
                        <goal>clean</goal>
                        <goal>package</goal>
                        <goal>bck2brwsr:show</goal>
                    </goals>
                    <activatedProfiles>
                        <activatedProfile>bck2brwsr</activatedProfile>
                    </activatedProfiles>
                    <properties>
                        <skipTests>true</skipTests>
                    </properties>
                </action>
            </actions>
        </profile>
    </profiles>
</actions>

If an action is not found in currently selected <profile> section, the system fallbacks to the main list of actions. In the previous example, the debug action would be taken from main list for all the profiles.