Building with Eclipse

Install Eclipse

The Restlet project has been mainly developed using the popular Eclipse IDE. It by no mean prevents you from using another IDE like NetBeans or IDEA IntelliJ, but keep in mind that the project was structured to take advantage of Eclipse plug-ins mechanism. In Eclipse, plug-ins are Java projects that can have dependencies on other plug-ins and still be deployed in standard JAR files (with additional metadata).

If you don't have a recent version of Eclipse SDK (3.4 was the best choice at the time of writing), then consider installing a fresh copy from the Eclipse site.

Note also that it is recommended to have Java 5 installed as it is the build environment for Restlet 1.0, 1.1 and 1.2. Only the future Restlet 2.0 version will require Java 6. You should configure Eclipse to declare your Java 5 installation. For this, go into "Window/Preferences/Java/Installed JREs".

Select a workspace

As the Restlet project is composed of many plug-in projects, it is recommended to dedicate a complete workspace to it, or to structure your existing workspace using working sets (groups of projects). In the next steps we will create a new workspace.

Launch Eclipse and it should ask you to select the location of the workspace. Note that, if you already have installed and used Eclipse SDK, you can create a switch to a new workspace by using the "File / Switch workspace..." menu command.

If you already downloaded the Restlet source code using a SVN client like Tortoise SVN, for example following these instructions, you can indicate the value of %RESTLET_HOME% that you used. Alternatively, you can simply use your default workspace or enter a new one.

Install Subclipse [optional]

If you have already installed a SVN client like Tortoise SVN, you can perfectly rely on it for updating, checking in and out the project files. But, even in this case it is really nice to have an SVN integration available in Eclipse, for example to benefit from the status icon and to run SVN commands directly within Eclipse.

In addition, people often like to only rely on a SVN client integrated with Eclipse. CVS comes built-in in Eclipse 3.4 but for SVN you need to install a third-party plugin. An integrated SVN client will only be bundled with the future Eclipse 3.5 release.

For now, we recommend using the Subclipse plug-in from CollabNet. There are two ways to install it:

1. Standalone Subclipse by following these installation steps
2. Bundled with CollabNet Desktop for Eclipse by following these installation steps

The advantage of the second option is that you also get the Mylyn connector for Tigris.org that let's you access to the Restlet issue tracker right from Eclipse. Very cool stuff :-)

If later you find the labels added by Subclipse too invasive, you can remove them: go into Window/Preferences/Team/SVN/Label Decorations/Text.

Check out code from SVN [optional]

If you have already checked out the SVN repository, for example using TortoiseSVN, you can go to the next step.

Otherwise, open the SVN Repository Exploring perspective by selecting its entry via the "Window / Open Perspective / Others..." menu. In the "SVN Repository" tab, click on the SVN button with a "+" sign or select "New / Repository" in the context menu. In the "Add SVN Repository" dialog, enter "http://restlet.tigris.org/svn/restlet" in the Url text field. When prompted, enter a username of "guest" with a blank password or some other credentials if you have them.

Right-click on the "trunk" node and select "Checkout...". Select the option "Check out as a project in the workspace" and press "Finish". Once the process is complete, come back to the main Java perspective.

Import the Restlet projects

Go into the "Java" perspective. Select "File / Import..." in the main menu. In the "Import" wizard, select the "General / Existing Projects into Workspace" tree node and press "Next >". Now you can press "Browse..." to select the root directory. Point the file dialog to the root directory of your Restlet SVN working copy (%RESTLET_HOME% in our case) and press "Ok".

Eclipse will recursively inspect the folder and propose to import all the Restlet projects (modules, libraries and build). You can now press "Finish" to complete the import. Let Eclipse refresh the workspace until all imported project show an SVN overlay icon. As you can see the list of projects is quite long!

Group projects into working sets [optional]

In order to better manage these project, we will create Eclipse working sets to group them. In the Project Explorer view, select the shallow triangle icon on the upper right and click on "Select Working Set".

• Click on "New..." then "Java". Enter "Extensions" as the Working set name, select all the projects stating with "org.restlet.ext" and then "Finish"
• Click on "New..." then "Java". Enter "Core" as the Working set name, select all the projects starting with "org.restlet" that are not extensions and then "Finish"
• Click on "New..." then "Java". Enter "Libraries" as the Working set name, click on "Select All", deselect all the projects starting with "org.restlet" and then "Finish"

Back in the "Select Working Set", press the "Select All" button then "Ok". Now, in the "Project Explorer", click again on the triange and select "Top Level Elements/Working Sets". See how your projects are now nicely grouped!

Follow the code style

When collaborating on an open source project, you generally want to use a common code style to facilitate comparison between multiple revisions of a source file and speed-up SVN commits. Go into the "Window / Preferences..." menu.

First, we want to make sure that all developers use the same code clean ups. Select the "Java / Code Style / Clean Up" tree node, click on the "Import..." button and finally select the "%RESTLET_HOME%/build/tmpl/eclipse/codeCleanUp.xml" file.

Now, we want to make sure that all developers use the same code templates for new artifacts. Select the "Java / Code Style / Code Templates" tree node, click on the "Import..." button and finally select the "%RESTLET_HOME%/build/tmpl/eclipse/codeTemplates.xml" file.

Then, we need to ensure a consistent formatting of the source code. For this, select the "Java / Code Style / Formatter" tree node, click on the "Import..." button and finally select the "%RESTLET_HOME%/build/tmpl/eclipse/codeFormatter.xml" file.

Press "OK" to close the preferences dialog.

While developping new code for Restlet, you should also ensure that your class members are always sorted. Eclipse is of great help here with its code sorting feature. You can access this feature via the menu "Source / Sort Members". In the dialog, make sure that the "Sort all members" option is selected.

Setting-up Ant [optional]

As you may have seen in the guide "How-To Build", we rely on Ant to build the whole project. Eclipse has a nice support for Ant that you can leverage. Select "Window / Show View / Ant". Press the "Add Buildfiles" button in the Ant view (button with an ant and a plus sign) and select "org.restlet.build/build.xml". Now you can expand the "Restlet" node in the Ant view and select the targets that you want to execute.

That's it, you are now all set to help us develop the Restlet project!