Eclipse

Initial Import

The RHQ codebase contains the necessary .classpath/.project files to import the project directly into Eclipse. To import the RHQ project into Eclipse, simple select File > New > Java Project from the main menu. Name the project "rhq" and select the radio button "Create project from existing source" and browse to the directory where you checked out the RHQ code. You can leave everything else alone and click the "Finish" button. This will load in the RHQ code under the project named "rhq".

Building

Eclipse builds the RHQ classpath from your local Maven repository. In order for Eclipse to successfully build the project, make sure you build RHQ via Maven first.

You also must set a custom Eclipse Classpath Variable called M2_REPO in order for Eclipse to find the RHQ dependencies in your local Maven repository. To set this variable, select Window > Preferences from the Eclipse main menu. Traverse to Java > Build Path > Classpath Variables and press the "New..." button. Create a new variable entry with the name "M2_REPO" with its path pointing to your local Maven repository (which is, by default, located in your home directory under the name .m2/repository.

In eclipse you may get errors of the kind 'modules/.../target/generated-sources/... missing source files error'. This is typically because the module in question has been removed from the core maven build. If you're a newby and don't care about these right now (which is likely), then you can get past the problem by changing to the (modules/...) directory and build that module only. For example, suppose the JIRA plugin caused the problem: cd ~/workspace/rhq/modules/plugins/jira mvn install-Dmaven.test.skip=true After successfully building and refreshing your Eclipse project, you should have resolved those missing source code errors.

The JMX plugin now supports the optional ability to discover running JVMs that do not have JMX remoting enabled (see bugzilla #703557). To do this, it relies on a JDK (specifically tools.jar). Because of this, you need to tell Eclipse where it can find tools.jar on your build machine (if it is available). Create an Eclipse Classpath Variable called JDK_HOME, under which Eclipse can find the lib/tools.jar. Once you create this Eclipse Classpath Variable, the JMX plugin will be able to be compilable in Eclipse.

Code formatting

If you plan on developing on the RHQ code base, you should be aware that the RHQ Eclipse project defines the Java code style in project-specified settings. You do not have to explicitly import any settings in order for these to take effect. If you do wish to make the RHQ code styles your Eclipse default, you can import the different templates that are found under /etc/eclipse-tools/templates.

Java Standard Code Format

The RHQ codebase conforms to the basic Java conventions format. The RHQ format profile was based off the built-in Eclipse "Java Conventions" format profile with the following changes:

• Maximum line length is 120 characters
• No tabs whatsoever
• Indentation is 4 spaces, with tab indentation being 8 spaces
• Default indentation for both wrapped lines and array initializers is "1" (which translates to 4 spaces)

EOL Characters

Please keep in mind that most files should not contain tabs or CRLF end-of-line markers unless specifically applicable for the file (e.g. Windows .bat files should have CRLF end-of-line markers).

If you are on Windows, you can make sure Eclipse stores files with the UNIX file line delimiter. You do this by going to the main menu Window > Preferences and traverse to the General > Workspace preferences section and change the "New text file line delimiter" to "Other - UNIX". While you are there, you might want to change the "Text File Encoding" to something like "UTF-8" to support some files that might contain international characters.

Reformat on Save Is Recommended

In order to keep the source code properly formatted, the RHQ project has a setting that forces your Java editor to reformat upon save. To set this up manually as your Eclipse default, from the main menu's Window > Preferences, traverse to Java > Editor > Save Actions and check "Perform the selected actions on save", "Format source code" and "Organize Imports". This is especially helpful if you prefer to work on source that is formatted in your own, custom format - when you are done editing the file, it will reformat itself when you save the file.

External Tools/Run/Debug Launch Configurations

The RHQ project contains some external tools, run and debug launch configurations that allow you to run the Maven builds and perform JPDA debugging directly from the Eclipse menu bar. Go to the main menu's Run option and you can select "External Tools", "Open Run Dialog" or "Open Debug Dialog" to see what is available if they do not show up in their drop-down buttons by default. Some example things that are available are:

• "RHQ Remote Debugging - Test" (for debugging unit tests when using -Dtest.debug in your Maven build)
• "RHQ Maven Build - DBSetup" (for cleaning your database and building a new schema)
• "RHQ Maven Build - Dev Profile" (for performing a mvn build with the -Pdev profile enabled)
• et. al.

Note that because these execute Maven directly, you must ensure that when you start Eclipse you have the "M2_HOME" environment variable set to appropriate values for your system (which you probably already do since it is required of Maven itself - see Building RHQ#InstallMaven2).

In order to use the Maven External Tools configurations (e.g. the "RHQ Maven Build" ones), you must define a "String Substitution Variable" in Eclipse called "MAVEN_EXE" whose value is either "mvn.bat" or "mvn" depending on which platform you are developing on ("mvn.bat" if on Windows, "mvn" if on Linux/UNIX - note this is not a full path, it is just the name of the executable file). This is the actual script executable name that is found in your Maven installation under $M2_HOME/bin. To set this String Substitution Variable in Eclipse, go to Window > Preferences from the main menu and traverse to Run/Debug > String Substitution. Click the "New" button and set the "Name" to "MAVEN_EXE" and the "Value" to the value appropriate to your platform (again, the value will be "mvn.bat" if on Windows, "mvn" on Linux/UNIX).

Part of the Maven build involves executing git to determine what SHA1 your local working copy is at (in order to create a build number). Because of this, you must have git in your PATH at the time you start Eclipse. (as of 11/20/2009, this is not working - will be fixed in the future)

XML Schema

RHQ contains several .xsd XML Schemas. If you are developing XML files that must conform to these XML Schemas, you can add the schemas to your Eclipse XML Catalog so you can get validation and auto-complete hints when writing those XML files. To do this, select Windows > Preferences from the main menu. Traverse to XML > XML Catalog and add the .xsd files found in modules/core/client-api/src/resources and modules/enterprise/server/xml-schemas_as User Specified Entries. There is a file _etc/eclipse-tools/templates/schema.xmlcatalog that you can use to bulk import these.

Now that you have some entries under "User Specified Entries" in your XML Catalog Entries, if you need to edit or create XML files that must to conform to those schemas, Eclipse will now validate them and provide you with auto-completion hints.

git

If you wish to keep your code base updated with the latest changes, you can synchronize it with git using an Eclipse GIT plugin (which you need to install separately). To do so, select the RHQ project from the Package Explorer view and from the right-mouse button popup menu, select Team > Share.... Follow the prompts to connect your project to the RHQ git repository. At this point, you can use the git plugin features to do things like commit code.

The latest Eclipse release has the EGit plugin repository already available out of box. Use the normal Install Update functionality to download and install the EGit plugin.

.

Hibernate

The RHQ project contains EJB3/JPA entities, with Hibernate as the JPA implementation.

To execute JPQL queries, you can run the server and go to the /admin/hibernate.jsp page.

Also, under /etc/eclipse-tools you will find the file hibernate.cfg.xml that you can use to load into the Hibernate Console to debug JPQL against the RHQ domain entities. If you want to do this, you must install the separate Hibernate Console plugin - see the hibernate.org for details. This is old and I don't know if these instructions are still valid!