Eclipse and OpenNMS
Subscribe

From OpenNMS

Jump to: navigation, search

Developing OpenNMS with Eclipse

Eclipse 4.2 Juno (or higher) is the recommended version of Eclipse to use because its support for Maven via the m2e plugin works the best with all of the OpenNMS maven plugins and dependencies. The easiest thing to do is download Eclipse IDE for Java EE Developers.

Do not use the eclipse provided by your distribution (Ubuntu 10.04's Eclipse is broken for instance), it's probably patched and some plugins won't install properly. I know you feel dirty installing applications outside of your favorite package manager...

Code Conventions

First, you'll want to configure Eclipse to use the OpenNMS code conventions.

Install Eclipse Plugins

Go to Help -> Install New Software... and install the plugins from these update sites:

If Eclipse won't let you add the EGit URL, and claims that it's a "duplicate", you should be able to enable that built-in site by clicking on the "Additional Software Sources" or "Available Software Sites" link in the Install New Software dialog, finding it in the (large) list of built-in sites, and checking the box.

Current versions (OpenNMS 1.7+)

These instructions are for OpenNMS 1.7 and newer. If you are working on an earlier version of OpenNMS, you should really consider upgrading, and if that's not (yet) possible, see the next section for instructions that work with OpenNMS 1.6 and earlier.

  • Create and enter a directory in your home directory called rcs:
    mkdir ~/rcs; cd ~/rcs
    This will be where any development project you work on gets checked out.
  • Next check out the opennms code:
    git clone git://github.com/OpenNMS/opennms.git
    (for details, see Developing with Git). If you intend to make changes or add features, I suggest you create your own local branch tracking master or 1.8
  • Then, compile at least once to get everything in a working state.
    ./compile.pl
  • Startup eclipse with a generous heap space (if you can afford it) to prevent memory problems during builds. If you import the entire OpenNMS tree, you will need about 2GB of heap to build and debug the code. On Linux:
    eclipse  -vmargs -Xmx2G
    For most developers who only import specific modules that they are working on, a smaller value of 1G should be sufficient. On Mac OS X, you can edit Eclipse.app/Contents/MacOS/eclipse.ini and adjust the existing "-Xmx" option.
  • Go to File->Import and select Maven->Existing Maven Projects
  • Select your ~/rcs/opennms directory as your root, and select all projects. Hit "Finish" to import. (This will take a while to do the first build.)
    • You may want to deselect "opennms-tools" when importing, since it contains projects that have external (private) dependencies.
    • If you are behind a proxy, do not forget to configure it in ~/.m2/settings.xml
  • Select all projects, right-click, and choose Maven->Update Project Configuration
    • This will catch all of the "generated" sources in the projects, and you should get a clean build
    • If after completing this step you still have errors about missing configuration classes, you might need to right-click target/generated-sources/castor, and select Build Path -> Use As Source Folder from the context menu for that project. (Current projects needing this are: opennms-config, opennms-dao, opennms-qosdaemon, opennms-reporting, opennms-webapp, org.opennms.features.reporting.availability, jasper-extensions, drools-correlation-engine). For jira-troubleticketer and opennms-integration-otrs you might need to add target/generated-sources/axistools/wsdl2java to the build path. (TODO: For some reason if you Maven->Update Project Configuration for these projects, the build path gets reset and you have to re-add the castoror wsdl2java paths again. Any ideas on how to fix this?)
    • UPDATE: A good fix to pull in sources which are generated in the target directory is to use the build-helper-maven-plugin documented at http://mojo.codehaus.org/build-helper-maven-plugin/

     <plugin>
       <groupId>org.codehaus.mojo</groupId>
       <artifactId>build-helper-maven-plugin</artifactId>
       <executions>
         <execution>
           <id>add-source</id>
           <phase>generate-sources</phase>
           <goals>
             <goal>add-source</goal>
           </goals>
           <configuration>
             <sources>
               <source>${project.build.directory}/generated-sources/castor</source>
             </sources>
           </configuration>
         </execution>
       </executions>
     </plugin>

    • If you you get the problem "The project '<foo>' does not have any GWT SDKs on its build path", then right click on the named project, goto "Build Path/Add Libraries", select "Google Web Toolkit" and click Next, then click "Finish" to use the default SDK.
    • If Eclipse continually rebuilds the "sms-monitor" project, you can just delete it from your workspace (but don't let Eclipse delete its files!).

The above method uses m2eclipse because we're now using a number of more complicated frameworks that don't work well with the "mvn eclipse:eclipse" method.

Gotchas/Tips & Tricks

  • Sometimes when starting up, some of the XML files will fail to validate and you'll get one or more "Problem"s appear, of type "XML Problem" with some horribly long and unhelpful description. It seems to be something like an inability to find the referenced XSDs or similar. To clear them without rebuilding or nuking things, double click on the Problem to open the affected file, then right click on the editor and choose "Validate". The XML will be re-validated and the Problem removed
  • Sometimes you can get "Unknown" validation errors in opennms-webapp. There's no actual content in the problem message, but if you open the pom.xml in which case you might see some complaint. (Mine said something about the lack of useDefaultDelimiters field/setter on a bean in the Maven plugin, but grep showed nothing so I think it was a side-effect of the real problem). Performing an interrupting manual builds seems to have left a "classes" and "lib" directory, and a configuration.properties file, in opennms-webapp/src/main/webapp/WEB-INF/. On deleting those directories and files, reopening eclipse, validating and rebuilding the project, the problems went away. (Finding that solution, however, took 6 hours of waiting for repeated cleans, compiles, assembles, imports, eclipse, git clones and other shenanigans)
  • Some projects might generate a Plugin execution not covered by lifecycle configuration within eclipse when they are added. See http://wiki.eclipse.org/M2E_plugin_execution_not_covered for more information. You can use the quick-fix on the problem pom.xml to ignore the plugin error. Then in the added pluginManagement section change the ignore to execute to that m2eclipse will execute the action as part of an Eclipse workspace full or incremental build. (An example of this is features/remote-poller/pom.xml. M2eclipse does not know what to do with goals for gmaven-plugin. So you can add lifecycle-mapping for the 3 goals, execute, compile, and testCompile, and the errors in eclipse will go away.) One thing you will notice when you add this quick fix, is that your command line compiles will generate warnings due to these missing maven plugins. The best way to get rid of these warnings is to place the lifecycle-mapping plugin management section inside a property activated profile.
<profile>
  <id>m2e</id>
  <activation>
    <property>
      <name>m2e.version</name>
    </property>
  </activation>
  <build>
    <pluginManagement>
      <plugins>
        <!--This plugin's configuration is used to store Eclipse m2e settings only. It has no influence on the Maven build itself. -->
        <plugin>
          <groupId>org.eclipse.m2e</groupId>
          <artifactId>lifecycle-mapping</artifactId>
          <version>1.0.0</version>
          <configuration>
            <lifecycleMappingMetadata>
              <pluginExecutions>
                <pluginExecution>
                  <pluginExecutionFilter>
                    <groupId>org.codehaus.mojo</groupId>
                    <artifactId>build-helper-maven-plugin</artifactId>
                    <versionRange>[1.8,)</versionRange>
                    <goals>
                      <goal>add-source</goal>
                    </goals>
                  </pluginExecutionFilter>
                  <action>
                    <ignore/>
                  </action>
                </pluginExecution>
                  </pluginExecutions>
            </lifecycleMappingMetadata>
          </configuration>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
</profile>

OpenNMS 1.6 and Earlier

These instructions are for OpenNMS 1.6 and earlier. If you are developing on a newer version of OpenNMS, please see the previous section, "Current instructions." Speaking of current, do you really want to be developing with an old version of OpenNMS? There are newer stable and unstable branches available and we suggest you use them instead of old, unsupported code.

  • Create and enter a directory in your home directory called rcs:
    mkdir ~/rcs; cd ~/rcs
    This will be where any development project you work on gets checked out.
  • Next check out the opennms code (for details, see Developing with Git):
git clone git://github.com/OpenNMS/opennms.git
git checkout -b 1.6 origin/1.6
  • Set up the .project and .classpath files for eclipse so that eclipse can build the code:
cd opennms
./build.sh install # this will take some time
./build.sh eclipse:eclipse
  • Open eclipse and create a new workspace
    • Go to Window->Preferences and select Java->Build Path->Classpath Variables...
    • Add a classpath variable called M2_REPO and set its value to <your home dir>/.m2/repository. (Note: eclipse does not accept the '~' character)
  • Go to File->Import... and select General->Existing Projects into Workspace and set the root directory to ~/rcs/opennms. This will show a list of projects that are available. Select them all and click ok.

The only problem with this method is that you are unable to edit files at the top-level of the OpenNMS tree. In particular you can't edit the pom.xml of the parent project.

Note: this method works best because OpenNMS 1.6 and earlier do not yet use OSGi or other advanced tools that cause issues with the default Maven Eclipse plugin ("mvn eclipse:eclipse").

* Tip - Make sure that you every now and then either tar/backup/copy your Eclipse workspace folder.

Troubleshooting

It could be possible that Eclipse hang during building the workspace. This is also possible if you're using SpringSource Tools Suite.

  • check the log file in your workspace located in <your-workspace>/.metadata/.log
  • If you have java.lang.OutOfMemoryError: PermGen space problems, increase the memory for Java Virtual Machine in Eclipse.ini or STS.ini