NetBeans Architecture Answers for Maven Projects module

General Information

Question (arch-what): What is this project good for?
WARNING: Question with id="arch-what" has not been answered!
Question (arch-overall): Describe the overall architecture.
Answer:
• MavenProjectAPI -

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

Question (arch-usecases): Describe the main use cases of the new API. Who will use it under what circumstances? What kind of code would typically need to be written to use the module?
Answer:

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

Question (arch-time): What are the time estimates of the work?
WARNING: Question with id="arch-time" has not been answered!
Question (arch-quality): How will the quality of your code be tested and how are future regressions going to be prevented?
WARNING: Question with id="arch-quality" has not been answered!
Question (arch-where): Where one can find sources for your module?
WARNING: Question with id="arch-where" has not been answered!

Project and platform dependencies

Question (dep-nb): What other NetBeans projects and modules does this one depend on?
WARNING: Question with id="dep-nb" has not been answered!
Question (dep-non-nb): What other projects outside NetBeans does this one depend on?
WARNING: Question with id="dep-non-nb" has not been answered!
Question (dep-platform): On which platforms does your module run? Does it run in the same way on each?
WARNING: Question with id="dep-platform" has not been answered!
Question (dep-jre): Which version of JRE do you need (1.2, 1.3, 1.4, etc.)?
WARNING: Question with id="dep-jre" has not been answered!
Question (dep-jrejdk): Do you require the JDK or is the JRE enough?
WARNING: Question with id="dep-jrejdk" has not been answered!

Deployment

Question (deploy-jar): Do you deploy just module JAR file(s) or other files as well?
WARNING: Question with id="deploy-jar" has not been answered!
Question (deploy-nbm): Can you deploy an NBM via the Update Center?
WARNING: Question with id="deploy-nbm" has not been answered!
Question (deploy-shared): Do you need to be installed in the shared location only, or in the user directory only, or can your module be installed anywhere?
WARNING: Question with id="deploy-shared" has not been answered!
Question (deploy-packages): Are packages of your module made inaccessible by not declaring them public?
WARNING: Question with id="deploy-packages" has not been answered!
Question (deploy-dependencies): What do other modules need to do to declare a dependency on this one, in addition to or instead of the normal module dependency declaration (e.g. tokens to require)?
WARNING: Question with id="deploy-dependencies" has not been answered!

Compatibility with environment

Question (compat-i18n): Is your module correctly internationalized?
WARNING: Question with id="compat-i18n" has not been answered!
Question (compat-standards): Does the module implement or define any standards? Is the implementation exact or does it deviate somehow?
WARNING: Question with id="compat-standards" has not been answered!
Question (compat-version): Can your module coexist with earlier and future versions of itself? Can you correctly read all old settings? Will future versions be able to read your current settings? Can you read or politely ignore settings stored by a future version?
WARNING: Question with id="compat-version" has not been answered!
Question (compat-deprecation): How the introduction of your project influences functionality provided by previous version of the product?
WARNING: Question with id="compat-deprecation" has not been answered!

Access to resources

Question (resources-file): Does your module use java.io.File directly?
Answer:

nbactions.xml -

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.

jpda.attach -

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 -

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.

Question (resources-layer): Does your module provide own layer? Does it create any files or folders in it? What it is trying to communicate by that and with which components?
WARNING: Question with id="resources-layer" has not been answered!
Question (resources-read): Does your module read any resources from layers? For what purpose?
Answer: MavenProjectCustomizer -

"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 -

"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 -

"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 -

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 -

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 -

"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 -

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 -

"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

ActionConfiguration -

Project API clients may place ProjectConfiguration instance in the context Lookup passed to ActionProvider.isActionEnabled() or ActionProvider.invokeAction(). If such instance is present, the action is configured according to settings in the selected configuration. If not present, the active configuration is used. See example in NbMavenProject documentation.

Question (resources-mask): Does your module mask/hide/override any resources provided by other modules in their layers?
WARNING: Question with id="resources-mask" has not been answered!
Question (resources-preferences): Does your module uses preferences via Preferences API? Does your module use NbPreferences or or regular JDK Preferences ? Does it read, write or both ? Does it share preferences with other modules ? If so, then why ?
WARNING: Question with id="resources-preferences" has not been answered!

Lookup of components

Question (lookup-lookup): Does your module use org.openide.util.Lookup or any similar technology to find any components to communicate with? Which ones?
WARNING: Question with id="lookup-lookup" has not been answered!
Question (lookup-register): Do you register anything into lookup for other code to find?
WARNING: Question with id="lookup-register" has not been answered!
Question (lookup-remove): Do you remove entries of other modules from lookup?
WARNING: Question with id="lookup-remove" has not been answered!

Execution Environment

Question (exec-property): Is execution of your code influenced by any environment or Java system (System.getProperty) property? On a similar note, is there something interesting that you pass to java.util.logging.Logger? Or do you observe what others log?
Answer:

netbeans.ignore.jdk.bootclasspath - 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.

org.netbeans.modules.maven.execute.AbstractOutputHandler.SLEEP_DELAY - 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).

org.netbeans.modules.maven.options.DEFAULT_REUSE_OUTPUT - 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 - 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. exec.vmArgs - 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 - 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. - 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. ExplicitProcessParameters - 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. org.netbeans.modules.maven.indexer.api.DEFAULT_CREATE_INDEX - 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 - 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. Project.org-netbeans-modules-maven.RunGoals - 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.
Question (exec-component): Is execution of your code influenced by any (string) property of any of your components?
WARNING: Question with id="exec-component" has not been answered!
Question (exec-ant-tasks): Do you define or register any ant tasks that other can use?
WARNING: Question with id="exec-ant-tasks" has not been answered!
Question (exec-classloader): Does your code create its own class loader(s)?
WARNING: Question with id="exec-classloader" has not been answered!
Question (exec-reflection): Does your code use Java Reflection to execute other code?
WARNING: Question with id="exec-reflection" has not been answered!
Question (exec-privateaccess): Are you aware of any other parts of the system calling some of your methods by reflection?
WARNING: Question with id="exec-privateaccess" has not been answered!
Question (exec-process): Do you execute an external process from your module? How do you ensure that the result is the same on different platforms? Do you parse output? Do you depend on result code?
WARNING: Question with id="exec-process" has not been answered!
Question (exec-introspection): Does your module use any kind of runtime type information (instanceof, work with java.lang.Class, etc.)?
WARNING: Question with id="exec-introspection" has not been answered!
Question (exec-threading): What threading models, if any, does your module adhere to? How the project behaves with respect to threading?
WARNING: Question with id="exec-threading" has not been answered!
Question (security-policy): Does your functionality require modifications to the standard policy file?
WARNING: Question with id="security-policy" has not been answered!
Question (security-grant): Does your code grant additional rights to some other code?
WARNING: Question with id="security-grant" has not been answered!

Format of files and protocols

Question (format-types): Which protocols and file formats (if any) does your module read or write on disk, or transmit or receive over the network? Do you generate an ant build script? Can it be edited and modified?
WARNING: Question with id="format-types" has not been answered!
Question (format-dnd): Which protocols (if any) does your code understand during Drag & Drop?
WARNING: Question with id="format-dnd" has not been answered!
Question (format-clipboard): Which data flavors (if any) does your code read from or insert to the clipboard (by access to clipboard on means calling methods on java.awt.datatransfer.Transferable?
WARNING: Question with id="format-clipboard" has not been answered!

Performance and Scalability

Question (perf-startup): Does your module run any code on startup?
WARNING: Question with id="perf-startup" has not been answered!
Question (perf-exit): Does your module run any code on exit?
WARNING: Question with id="perf-exit" has not been answered!
Question (perf-scale): Which external criteria influence the performance of your program (size of file in editor, number of files in menu, in source directory, etc.) and how well your code scales?
WARNING: Question with id="perf-scale" has not been answered!
Question (perf-limit): Are there any hard-coded or practical limits in the number or size of elements your code can handle?
WARNING: Question with id="perf-limit" has not been answered!
Question (perf-mem): How much memory does your component consume? Estimate with a relation to the number of windows, etc.
WARNING: Question with id="perf-mem" has not been answered!
Question (perf-wakeup): Does any piece of your code wake up periodically and do something even when the system is otherwise idle (no user interaction)?
WARNING: Question with id="perf-wakeup" has not been answered!
Question (perf-progress): Does your module execute any long-running tasks?
WARNING: Question with id="perf-progress" has not been answered!
Question (perf-huge_dialogs): Does your module contain any dialogs or wizards with a large number of GUI controls such as combo boxes, lists, trees, or text areas?
WARNING: Question with id="perf-huge_dialogs" has not been answered!
Question (perf-menus): Does your module use dynamically updated context menus, or context-sensitive actions with complicated and slow enablement logic?
WARNING: Question with id="perf-menus" has not been answered!
Question (perf-spi): How the performance of the plugged in code will be enforced?
WARNING: Question with id="perf-spi" has not been answered!