Confluence Plugin Development in NetBeans

Posted by admin on April 27th, 2014 filed in Development, Java, NetBeans, Wiki

Atlassian recommends using Eclipse for Confluence Plugin Development, but I already had NetBeans IDE 8 installed, so in the following I’ll write about how that worked out.

NetBeans IDE supports Maven projects well, but Confluence plugins rely on several frameworks, not all of which NetBeans handles out-of-the-box.

Don’t Listen to Outdated Atlassian Docs :-P

First, ignore Atlassian’s Configure NetBeans to use the SDK advice to modify the POM.xml for NetBeans. The doc advises to add some repository configuration, which is unecessary and counterproductive: Adding the suggested properties packaged unnecessary stuff, and increased the generated plugin file size from 1MB to 65MB for me. Such a large plugin can no longer even be loaded by Confluence. Compiling a small plugin should take < 2 minutes, and the JAR should be in the kb range, otherwise something is off! Other users also warn against this outdated advice in the comments under the doc. Creating a New Project

Main tip here: Don’t use NetBeans to create a new Maven project when you develop Confluence plugins. The Atlassian SDK includes Maven-based commandline tools for creating a plugin skeleton.

As all Confluence tutorials tell you, you create a Confluence plugin in the Terminal by running the create-atlas-confluence-plugin command. This Atlassian SDK command creates a skeleton project and asks you interactively for properties (such as projectid for the project name, etc).

Configuring NetBeans Maven Support

In NetBeans, I recommend the following project setup:

  1. Go to Tools -> Plugins. Make sure that you have the Maven and Java SE plugins.
  2. Go to Tools -> Options -> Java -> Maven. I configured the Maven home by browsing to the same Maven directory as the Atlassian SDK is using (your MVN_HOME variable minus the bin…bat part). Optionally, you can switch the SDK to a more current version of Maven and set NetBeans up to use the same.
  3. Important: Click “Index now” and wait.
  4. Open the Atlassian SDK-created skeleton project in NetBeans: The IDE detects the POM.xml file and recognizes it as Maven Java project. The project appears in the NetBeans Projects tab.
    Tip: If the project says “unloadable” now, read “Troubleshooting” below.
  5. Familiarize yourself with the following project directories: Source Packages (contains Java files), Other Sources (contains xml, soy, JavaScript, localizable strings, etc), Dependencies (overview of your Maven-controlled dependencies), and Project Files (contains the official POM.xml, and your personal NetBeans properties).
  6. Right-click Dependencies in the Project window, and tell NetBeans to download Javadoc. Wait.
  7. Open the Project properties, go to Sources, and select UTF-8 Encoding (NetBeans will modify the POM.xml file). Confluence does support JDK 7, even though the default POM.xml says “1.6”, so change the JDK to 7 or 8 here, too (again, NetBeans will modify the POM.xml for you)
.

Setting Up the Clean/Run/Build Buttons

NetBeans uses default Maven goals for actions such as clean and build. For Confluence Development, however, you want to use Atlassian’s atlas-mvn tools and goals. For example, you run atlas-package instead of some default mvn build goal. Here’s how I replaced NetBeans’ default maven run goal by the corresponding atlas-mvn command:

  1. Open the project properties, go to Actions, and select ‘Run Project’.
  2. Under ‘Execute Goals’, enter
    com.atlassian.maven.plugins:maven-amps-dispatcher-plugin:4.2.20:run
    Note: 

The version number depends on the most current release of the SDK, check which version you are using in atlas-version.
  3. I redefined the build goal as package (instead of install).
  4. Similarly, I redefined the clean and build goal as package clean (instead of install clean).

Now, pressing F6 in the IDE builds the plugin, and starts running a local Confluence instance!

Running a Confluence Server From NetBeans

NetBeans builds and packages the plugin, builds and runs the Confluence server, and installs the plugin. Beware, this takes a long while the first time. From here on, the behaviour is the same as the official atlas-run tutorials.

[INFO] confluence started successfully in 633s at http://localhost:1990/confluence
[INFO] Type Ctrl-D to shutdown gracefully
[INFO] Type Ctrl-C to exit
[INFO] [talledLocalContainer] INFO: Server startup in 12345 ms

As soon as you see “started successfully” in the NetBeans Output window, switch to a web browser.

I recommend Firefox or Chrome, which also have web dev tools (shift-F5 or F12). Browse to the above localhost path to access your temporary Confluence instance. Your plugin is already bundled in it! See my other blog entry about Confluence FastDev for (generic, not NetBeans-related) Confluence development tips.

Tip: To quit the server, don’t click Stop in the NetBeans Output window, this does not shut down the server process. Type ctrl-D in the output window to prevent your Memory filling up with half-forgotten undead Java processes.

Use Built-in File History and Diff

When developing and debugging your Confluence plugins, you typically install the plugin, and go through a longer workflow to test the latest feature you added. You create a page from your custom blueprint, you use your custom macro in the editor, etc… If you notice at any time that one of your changes broke the plugin, NetBeans can help you revert to a previous version of your code.

If your on your own, you do not need to set up external file version control, since NetBeans’ built-in File History is integrated into the Editor window. NetBeans automatically creates a snapshot every time you save a file, so you can compare file versions and revert individual changes. You toggle between editor and history by clicking the Source and History buttons.

Similarly, to undelete a file in your Project, right-click the directory it was in, and choose History -> Revert Deleted.

You can even compare one of your project files with another file that is not part of any NetBeans-loaded project. This is handy when you are learning from downloaded example code!

  1. Open the Favorites window.
  2. Add your Plugin project, as well as the sample project, as Favorites.
  3. Ctrl-click to select the two files to compare.
  4. Right-click the selected files and choose Tools -> Diff to get a great visual comparison and merge tool.

Configuring Colors in the Output Window

A small but avoidable pet peeve of mine: I don’t like that in the NetBeans Output window, Warnings are highlighted with a yellow font on a white background. It makes warnings quite hard to read.

  1. So off to the Tools -> Options menu we go. The important thing to know is that the “Fonts and Colors” tab only contains options for the code editor.
  2. You find the Output windows‘s settings under “Miscellaneous”! To find them, you can alternatively enter “output” into the options search box (the top right), or right-click the Output window and choose “Settings…” Note that you can only right-click if there is output in the Output window.
  3. Here I customized this so-called Orange to a darker shade [255,64,0].

Confluence Plugin Dev With NetBeans – What Doesn’t Work?

NetBeans 8 has no support for Soy files. Confluence Blueprint plugins use SOY templates to define wizard panels. You can open and edit them in NetBeans alright, but you will get useless HTML syntax warnings. Also the standard HTML syntax highlighting will only be partially meaningful.

Tip: Hover the yellow warning icon in the very first
 line of each SOY file. Then click the yellow warning to disable the unnecessary HTML checking for these files.

Refactoring doesn’t work for Confluence plugins projects in any IDE. NetBeans knows Java, it knows CSS, it knows POM.xml files, it knows project.properties files. However it doesn’t know anything about the structure of a Confluence plugin project, nor how Confluence weaves its pieces together through keys and the atlassian-plugin.xml file.

Tip: Unless you merely refactor a private method or field in a Java class, you have to use the textual “Find…” on the project and refactor manually. Don’t forget that when you rename a file, you must manually update all references to it in the atlassian-plugin.xml file!

NetBeans messes with the POM.xml file and can break it. :( The NetBeans Maven support politely offers to fix missing imports and search Maven dependencies for you. If you accept, this may change (and break) the scope of existing dependencies in the POM.xml file. Mainly, NetBeans really likes to overwrite this <scope>provided</scope> line here with <type>jar</type> — which doesn’t work.



        <dependency>
            <groupId>com.atlassian.confluence.plugins</groupId>
            <artifactId>confluence-create-content-plugin</artifactId>
            <version>${create.content.version}</version> 
            <scope>provided</scope> 
        </dependency>

Warning: Every time you get weird build failures and vague complaints about Beans, make sure that the confluence-create-content-plugin dependency’s scope is still “provided” and not “jar” or anything else!

Troubleshooting Unloadable Maven Projects

First tip: Before you do anything in the IDE, clean and package the plugin from the command line at least once, to exclude basic sources of error. Only if that succeeds, and you know that the skeleton plugin was set up correctly by the Atlassian SDK, continue in the IDE.

When I opened a fresh skeleton project for the first time, NetBeans declared the Maven project unloadable and warned “…project could not be loaded… something is wrong with your POM”. In this case:

  1. Cancel out of NetBeans’ offer to resolve project problems. We want to start by fixing the POM.
  2. Open the NetBeans Favorites window, right-click in it, and add your broken Plugin project directory as Favorite. The Favorites window lets you open any text or image file outside a working project.
  3. Open the POM.xml and look for yellow warning marks in the editor.
  4. Ignore the warning for <packaging>atlassian-plugin</packaging> — this line is actually correct.
  5. If NetBeans points out a missing version property for the Maven SDK configuration, find out the version of your Maven client (Tools -> Options -> Java -> Maven in NetBeans, or run atlas-version on the commandline). Add the Maven <version> to your POM as follows:
        <build>
            ...
                <plugin>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <configuration>
                        <source>1.7</source>
                        <target>1.7</target>
                    </configuration>
                    <version>2.5</version>
                </plugin>
            </plugins>
        </build>

    See also: Confluence Plugin Version Resolution Exception.

  6. Generally, verify everything here that has a version number in it, and make sure it fits your reality. The generated skeleton POM is outdated!
  7. Finally, right-click the project and select Project Properties. Tell NetBeans to Resolve Problems. NetBeans runs a priming build that should make the Maven project loadable.

Comments are closed.