| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| --> |
| <!DOCTYPE api-answers PUBLIC "-//NetBeans//DTD Arch Answers//EN" "../../nbbuild/antsrc/org/netbeans/nbbuild/Arch.dtd" [ |
| <!ENTITY api-questions SYSTEM "../../nbbuild/antsrc/org/netbeans/nbbuild/Arch-api-questions.xml"> |
| ]> |
| |
| <api-answers |
| question-version="1.25" |
| author="mkleint@netbeans.org" |
| > |
| |
| &api-questions; |
| |
| |
| <!-- |
| <question id="arch-overall" when="init"> |
| Describe the overall architecture. |
| <hint> |
| What will be API for |
| <a href="http://openide.netbeans.org/tutorial/api-design.html#design.apiandspi"> |
| clients and what support API</a>? |
| What parts will be pluggable? |
| How will plug-ins be registered? Please use <code><api type="export"/></code> |
| to describe your general APIs. |
| If possible please provide |
| simple diagrams. |
| </hint> |
| </question> |
| --> |
| <answer id="arch-overall"> |
| <ul> |
| <li> |
| <api group="java" name="MavenProjectAPI" type="export" category="friend"> |
| <p> |
| The Maven Project API provides some miscellaneous friend APIs and SPIs relating to |
| Maven projects. |
| </p> |
| </api> |
| </li> |
| </ul> |
| </answer> |
| |
| |
| |
| |
| |
| |
| <!-- |
| <question id="arch-usecases" when="init"> |
| Describe the main <a href="http://openide.netbeans.org/tutorial/api-design.html#usecase"> |
| use cases</a> of the new API. Who will use it at |
| what circumstances and what will be the typical code to write |
| to use the module. |
| </question> |
| --> |
| <answer id="arch-usecases"> |
| <p> |
| API/SPI to be used by modules wanting to enhance the maven project's integration in the IDE. |
| </p> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="resources-read" when="final"> |
| Does your module read any resources from layers? For what purpose? |
| |
| <hint> |
| As this is some kind of intermodule dependency, it is a kind of API. |
| Please describe it and classify according to |
| <a href="http://openide.netbeans.org/tutorial/api-design.html#categories"> |
| common stability categories</a>. |
| </hint> |
| </question> |
| --> |
| <answer id="resources-read"> |
| <api group="layer" name="MavenProjectCustomizer" type="export" category="official"> |
| <p> |
| "Projects/org-netbeans-modules-maven/Customizer" folder's content is used to construct the project's customizer. |
| It's content is expected to be <code>ProjectCustomizer.CompositeCategoryProvider</code> instances. |
| The lookup passed to the panels contains an instance of <code>Project</code> and <code>org.netbeans.modules.maven.api.customizer.ModelHandle</code> |
| Please note that the latter is not part of any public APIs and you need friend dependency to make use of it. |
| </p> |
| </api> |
| <api group="layer" name="MavenLogicalViewProvider" type="export" category="official"> |
| <p> |
| "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 <code>NodeFactory</code> instances. |
| </p> |
| </api> |
| <api group="layer" name="MavenLookup" type="export" category="official"> |
| <p> |
| "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 <code>LookupProvider</code> instances. Maven project provides <code>LookupMerger</code>s |
| for <code>Sources</code>, <code>PrivilegedTemplates</code>, <code>RecommendedTemplates</code> and other classes. Implementations added by 3rd parties |
| will be merged into a single instance in the project's lookup. |
| </p> |
| </api> |
| <api group="layer" name="MavenPackagingLookup" type="export" category="devel"> |
| <p> |
| <code>Projects/org-netbeans-modules-maven/<packaging-type>/Lookup</code> is added to the project's additional Lookup. The content is expected |
| to contain packaing-specific services and processors, for example, <a href="@TOP@/org/netbans/modules/maven/api/execute/PrerequisitesChecker.html">PrerequisitesCheckers</a>. |
| In addition, <code>Projects/org-netbeans-modules-maven/_any/Lookup</code> defines services that act after the packaging-specific ones. |
| </p> |
| For the details and examples, see description in <a href="@TOP@/org/netbeans/modules/maven/api/execute/PrerequisitesChecker.html">PrerequisitesChecker javadoc</a>. |
| </api> |
| <api group="layer" name="PluginLookup" type="export" category="official"> |
| <p> |
| 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 <code>Projects/org-netbeans-modules-maven/<plugin-id>/Lookup</code> 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 <a href="@TOP@/org/netbeans/modules/maven/api/NbMavenProject.html">NbMavenProject javadoc for details/examples</a>. |
| </p> |
| </api> |
| <api group="layer" name="MavenActions" type="export" category="official"> |
| <p> |
| "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 <code>Action</code> instances. |
| </p> |
| </api> |
| |
| <api group="layer" name="MavenArchetypes" type="export" category="official"> |
| <p> |
| "Projects/org-netbeans-modules-maven/Archetypes" folder contains fileobjects |
| that represent archetypes. The archetypes are defined by the following file attributes: |
| </p> |
| <table> |
| <tbody> |
| <tr><td>groupId</td><td>mandatory</td><td></td></tr> |
| <tr><td>artifactId</td><td>mandatory</td><td></td></tr> |
| <tr><td>version</td><td>mandatory</td><td></td></tr> |
| <tr><td>repository</td><td>optional</td><td>url of the archetype's repository</td></tr> |
| <tr><td>nameBundleKey</td><td>optional</td><td>key in bundle file that holds localized name</td></tr> |
| <tr><td>descriptionBundleKey</td><td>optional</td><td>key in bundle file that holds localized description</td></tr> |
| </tbody> |
| </table> |
| </api> |
| |
| <api group="lookup" name="ActionConfiguration" type="import" category="official"> |
| <p> |
| Project API clients may place <a href="@org-netbeans-modules-projectapi@/org/netbeans/spi/project/ProjectConfiguration.html">ProjectConfiguration</a> |
| instance in the <b>context Lookup</b> passed to <a href="@org-netbeans-modules-projectapi@/org/netbeans/spi/project/ActionProvider.html##isActionEnabled-java.lang.String-org.openide.util.Lookup-">ActionProvider.isActionEnabled()</a> or |
| <a href="@org-netbeans-modules-projectapi@/org/netbeans/spi/project/ActionProvider.html##invokeAction-java.lang.String-org.openide.util.Lookup-">ActionProvider.invokeAction()</a>. 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 <a href="@TOP@/org/netbeans/modules/maven/api/NbMavenProject.html">NbMavenProject</a> documentation. |
| </p> |
| </api> |
| |
| </answer> |
| |
| |
| <answer id="exec-property"> |
| <p> |
| <api category="devel" group="property" name="netbeans.ignore.jdk.bootclasspath" type="export"> |
| The maven support recognizes special tag in <q>maven-compiler-plugin</q> configuration |
| that instructs the IDE to <em>not</em> put JDK libraries on a classpath. One can use:<pre> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-compiler-plugin</artifactId> |
| <configuration> |
| <compilerArguments> |
| <bootclasspath>netbeans.ignore.jdk.bootclasspath</bootclasspath> |
| </compilerArguments> |
| </configuration> |
| </plugin> |
| </pre> |
| section in <code>pom.xml</code> to <em>suppress</em> the JDK libraries. |
| </api> |
| </p> |
| <p> |
| <api category="devel" group="systemproperty" name="org.netbeans.modules.maven.execute.AbstractOutputHandler.SLEEP_DELAY" type="export"> |
| 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). |
| </api> |
| </p> |
| |
| <p> |
| <api category="devel" group="branding" name="org.netbeans.modules.maven.options.DEFAULT_REUSE_OUTPUT" type="export"> |
| Brand the <code>DEFAULT_REUSE_OUTPUT</code> key in a |
| <code>org.netbeans.modules.maven.options.Bundle</code> file |
| with one of the values <code>true</code> or <code>false</code> |
| to specify the default behavior of reusing output by your application. |
| Use <code>never</code> value, if the reuse shall never be done, |
| regardless of the settings value. |
| </api> |
| <api category="devel" group="branding" name="org.netbeans.modules.maven.api.execute.DEFAULT_COMPILE_ON_SAVE" type="export"> |
| Brand the <code>DEFAULT_COMPILE_ON_SAVE</code> key in a |
| <code>org.netbeans.modules.maven.api.execute.Bundle</code> file |
| with one of the values <code>all</code> or <code>none</code> |
| to specify the default behavior of compile on save in Maven |
| projects. |
| </api> |
| <api category="stable" group="property" name="exec.vmArgs" type="export"> |
| The plugin exports Java VM parameters to be used for application execution in <code>${exec.vmArgs}</code> |
| property that can be used in action mappings or Maven pom.xml. |
| </api> |
| <api category="stable" group="property" name="exec.appArgs" type="export"> |
| The plugin exports application parameters to be used for application execution in <code>${exec.appArgs}</code> |
| property that can be used in action mappings or Maven pom.xml. |
| </api> |
| <api category="private" group="property" name="NbIde." type="export"> |
| Properties designed to be read only by NB IDE code, and <b>not passed</b> to Maven can be prefixed by this prefix. |
| Maven module uses such properties to communicate between services that participate on maven launch internally. |
| </api> |
| <api category="devel" group="lookup" name="ExplicitProcessParameters" type="export"> |
| Project actions that execute user application (run, debug) accept additional VM and application |
| arguments as a series of <a href="@org-netbeans-modules-extexecution-base@/org/netbeans/api/extexecution/base/ExplicitProcessParameters.html"> |
| ExplicitProcessParameters</a> instance(s) in the action's Lookup. See <a href="@org-netbeans-modules-extexecution-base@/org/netbeans/api/extexecution/base/ExplicitProcessParameters.html"> |
| ExplicitProcessParameters</a> javadoc for more details. |
| </api> |
| <api category="devel" group="branding" name="org.netbeans.modules.maven.indexer.api.DEFAULT_CREATE_INDEX" type="export"> |
| Brand the <code>DEFAULT_CREATE_INDEX</code> key in |
| <code>org.netbeans.modules.maven.indexer.api.Bundle</code> file |
| with one of the values <code>true</code> or <code>false</code> |
| to control (usually to disable with <code>DEFAULT_CREATE_INDEX=false</code>) |
| the default behavior automatic maven index downloading. |
| </api> |
| <api category="devel" group="branding" name="org.netbeans.modules.maven.indexer.api.DEFAULT_UPDATE_FREQ" type="export"> |
| Brand the <code>DEFAULT_UPDATE_FREQ</code> key in |
| <code>org.netbeans.modules.maven.indexer.api.Bundle</code> file |
| with one of the values: |
| <ul> |
| <li><code>0</code> - once a week</li> |
| <li><code>1</code> - once a day</li> |
| <li><code>2</code> - on each startup</li> |
| <li><code>3</code> - never</li> |
| </ul> |
| to control (usually to disable with <code>DEFAULT_UPDATE_FREQ=3</code>) |
| the default behavior automatic maven index downloading. |
| </api> |
| </p> |
| |
| </answer> |
| |
| <answer id="resources-file"> |
| <p> |
| <api category="stable" group="java.io.File" name="nbactions.xml" type="export"> |
| <p> |
| NetBeans Maven support recognizes special file(s) that can be placed |
| next to a <code>pom.xml</code>. These files contain description of |
| bindings between NetBeans UI actions (compile, run, debug, etc.) and |
| the actual Maven goals to execute. |
| </p> |
| <p> |
| Primary name of the file is <code>nbactions.xml</code>. In |
| addition to this, there can be other <code>nbactions-profile.xml</code> |
| 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: |
| </p> |
| <pre> |
| <?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> |
| </pre> |
| <p> |
| 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. |
| </p> |
| </api> |
| <api category="stable" group="property" name="jpda.attach" type="export"> |
| <p> |
| 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 |
| <a onclick="target='_blank'" href="https://github.com/simpligility/android-maven-plugin/pull/584">enhancement</a> |
| in the Maven Android plugin: |
| </p> |
| <pre> |
| <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> |
| </pre> |
| <p> |
| Value of <code>jpda.attach</code> property can either be <code>true</code> |
| and in such case the IDE finds an empty port and sets values of |
| <code>jpda.attach.port</code> and <code>jpda.attach.address</code> |
| properties accordingly, or it can be directly specified |
| <code>address:port</code> or just port number to connect to. |
| </p> |
| </api> |
| <api category="stable" group="property" name="jpda.attach.trigger" type="export"> |
| <p> |
| 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 <a href="https://software.intel.com/en-us/multi-os-engine">Multi-OS Engine</a>: |
| </p> |
| <pre> |
| <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> |
| </pre> |
| <p> |
| Value of <code>jpda.attach.trigger</code> property is the expected text. |
| </p> |
| </api> |
| </p> |
| </answer> |
| |
| </api-answers> |
