Eclipse Configuration

These are instructions for setting up Eclipse for development on the Shibboleth software projects in Java. Some of the settings are now global, and mandatory, to ensure code formatting and style, and are no longer maintained within the project repositories, so it is a requirement for developers to create an Eclipse workspace specific to Shibboleth and apply some of the settings globally to get them applied to the imported Maven projects.

Max Memory

By default, as of the 2019-09 release, Eclipse will use up to 1024MB of memory. This seems to be sufficient for most of what we do.

If you need more, for example if you have a lot of large projects open at once, this can be adjusted. Edit your eclipse.ini file and adjust the -Xmx###m setting appropriately. On Windows and on most Linux distributions the eclipse.ini file is located in the same directory as the Eclipse executable. On macOS, control-click on the executable, select Show Package Contents and then go to Contents/Eclipse/eclipse.ini.

Plugins

You must install the following plugins. The easiest way is to use the Marketplace (Help -> Eclipse Marketplace):

• M2E Maven Integration for Eclipse

  • This is generally installed with other JDT components, but may be explicitly needed if starting from a bare install.

• TestNG for Eclipse

  • Install the version from the Marketplace if it is available. If it does not appear to be available, try adding https://dl.bintray.com/testng-team/testng-eclipse-release/ as a repository and installing from there.

• Checkstyle Plug-in

  • Install the version from the Marketplace if it is available. If it does not appear to be available, try adding https://checkstyle.org/eclipse-cs/ as a repository and installing from there.

  • If you browse to that site there is a draggable link you can pull into eclipse to do the install (only confirmed on Windows)

Required Configuration

The following configuration, set via the Preferences window, is required when working with Shibboleth.

• Java → Code Style → Clean Up → Import via cleanup.xml

  • Then activate the Shibboleth profile.

• Java → Code Style → Code Templates → Import via codetemplates.xml

  • Check the box at the bottom to automatically apply standard templates to new files and classes.

  • Note: this configuration includes the Shibboleth project's standard Apache 2 license header. Code contributed to the Shibboleth project must contain this header. However, if you are not planning to contribute the code you'll probably want to change this.

• Java → Code Style → Formatter → Import via formatter.xml

  • Then activate the Shibboleth profile.

• General → Editors → Text Editors → Insert spaces for tabs → check

• XML → XML Files → Editor → Line Width → 120

• XML → XML Files → Editor → Indent Using Spaces → selected

• XML → XML Files → Editor → Indentation Size → 4

The follow configuration is default in the 'Mars' release of eclipse (4.5) but should be checked.

• General → Editors → Text Editors → Show line numbers → check

• Java → Code Style → Add '@Override' annotation for new overriding methods → check (Note: requirement reversed at developers meeting 2013-12-20) 

Recommended Configuration

It is recommended that you set the following Eclipse Preferences to the given value. This is not required but the following options are all there for various reasons: help in debugging, code formatting/style, better IDE performance, etc.

It is also strongly suggested that the JDT compiler settings contained in this settings file be used, as this turns on annotation-based analysis of null behaviors in the code. This page captures some hints and tips on cleaning projects when these setting are first used

• General → Show heap status → check

• General → Startup and Shutdown → Confirm exit when closing last window → uncheck

• General → Startup and Shutdown → Plug-ins activated on startup → Mylyn .* → uncheck

• Java → Editor → Folding → Comments → check

• Java → Editor → Folding → Inner Types → check

• Java → Compiler → Javadoc

  • Malformed Javadoc Comment

    • ... as visible as: Private

    • Validate tag arguments: ticked

      • Report non visible references: ticked

      • Report deprecated references: unticked

  • Missing Javadoc tags: Warning (but Error might be a better idea)

    • ... as visible as: Private

    • Ignore in overriding and implementing methods: ticked

    • Ignore method type parameters: unticked (perhaps a mistake)

  • Missing Javadoc comments: Ignore

• Maven → Download Artifact Sources → check

• Maven → Download Artifact JavaDoc → check

• Maven → User Interface → Open XML page in the POM editor by default → check

The follow configuration is default from the 'Mars' release of eclipse (4.5) but can be checked.

• General → Appearance → Enabled animations → uncheck

• General → Editors → Structured Text Editors → Enable Folding → check

• Install/Update → Automatic Updates → Automatically find new updates and notify me → check

• Maven → Download repository index updates on startup → uncheck

For development with the IdP V3 and V4 code, it is also recommended to add this XML Catalog into the Eclipse configuration.  Do this after you have added and imported the projects.

• File → Import →  XML → XML Catalog.

• Select the file parent/resources/eclipse/user_catalog.xml

Importing Projects

In order to work with a project in Eclipse you need to get it from Source Control System and get it in to Eclipse. Here's the general steps.

1. Check out the project trunk/branch from the Git repository.
   Note: you should perform this checkout from the command line

2. In Eclipse, select File -> Import then Maven -> Existing Maven Projects

   1. If the project is a monolithic project, or a multi-module project with the parent project in the root (e.g., java-shib-shared), select the directory created in step 1 as the Root Directory

   2. If the project is a multi-module project with the parent as a sibling (e.g., java-opensaml or java-identity-provider), select the *-parent directory, located as a child directory of the project directory created in step 1, as the Root Directory

3. Press the Okay button and wait while Eclipse builds everything, updates its caches, has a cup of tea and whatever else takes it so long.

External Debugging

Java generally allows for debugging by connecting to a process and by asking a process to connect to the debugger. With respect to Jetty, the former did not work for Scott, but the latter did work.

First, create a Java Debug... configuration for one of the projects and set Connection Type to "Standard (Socket Listen)". You can select the port and connection limit as required.

To start Jetty in a typical way from the command line and ask it to connect to Eclipse on port 8888:

This stopped on breakpoints and seemed to behave in the expected ways. Obviously it could be tricky if the project code state doesn't match what's inside Jetty.