Installation

Install the latest version of Eclipse IDE for Enterprise Java and Web Developers. Be sure to install the 64 bit "Enterprise Java and Web" version.

Need Enterprise version?

A 32 bit Eclipse will not run on a 64 bit Java installation so be careful not to install the 32 bit. The non-enterprise version will not be able to run a web application in a standalone Tomcat, and it lacks some plugins that you would otherwise need to install separately. If you need a minimalistic development environment, you should be able to code with the non-enterprise version though.

With a single installation of Eclipse you can have as many workspaces as you like. For big projects involving multiple branches and many people, you might want to create at least two workspaces, one for your own development and another one for checking other people’s work or for deployment. It is very convenient to create a different shortcut for each workspace. Using the "-data" command line option you can specify which workspace you want to use. For example:

C:\local\Eclipses\eclipse-jee-2019-09-R\eclipse.exe -data "C:\work\wspaces\myCoding"
C:\local\Eclipses\eclipse-jee-2019-09-R\eclipse.exe -data "C:\work\wspaces\myRelease"

Create a workspace for the bookstore tutorial:

C:\local\Eclipses\eclipse-jee-2019-09-R\eclipse.exe -data "C:\work\wspaces\yadaTutorial"

Run Eclipse with the chosen workspace and click on the "Workbench" or "Hide" icon to the right of the "Welcome to Eclipse" page.

Update your installation with "Help > Check for Updates" and follow the instructions. Failing to do so might prevent you from adding a Tomcat server later.

From the "Window > Preferences > Gradle" dialog set the "Java home" entry to your JDK installation, which would be C:\Local\jdk21 if you followed the instructions above.

Setting Gradle Java Home

When the Gradle Java Home is not set, Eclipse will run Gradle with the java version used to run itself and this may cause all sort of errors like "java facet mismatch" or "supplied phased action failed".

Set the editors file encoding to UTF-8, at least "General > Workspace > Text file encoding" and "Web > CSS Files > Encoding":

Eclipse file encoding
Figure 1. Eclipse file encoding

The "New text file line delimiter" shown in the above image is also better set to "Unix".

Also set UTF-8 in the "Content Types > Text > Java Properties File > Default encoding" field and be sure to click on "Update" before applying the changes:

Eclipse file encoding
Figure 2. Eclipse file encoding

Add the previously donwloaded JRE as a new Runtime in "Window > Preferences > Java > Installed JREs" and set it as the default. Also set the "Window > Preferences > Java > Compiler > JDK Compliance" accordingly (that would be "21" for Java 21). You should also set "Store information about method parameters (usable via reflection)" to use simpler method signatures in Spring controllers (no @RequestParam is needed).

In order to better spot errors and stack traces, you should considerably increase the console output buffer or remove the limit altogether using the "Window > Preferences > Run/Debug > Console" options:

Console output limit
Figure 3. Console output limit

Connect to GIT

Add the repositories

The Yada Framework sources are hosted on the public GitHub site. To access the GitHub repository use your GitHub credentials on the yadaframework repo. The git url should be git@github.com:xtianus/yadaframework.git.

Since 2021 the preferred method for connecting to GitHub is ssh. If you didn’t do so already, you should create a pair of SSH private/public keys and upload the public one to GitHub here. The keys can be generated on Windows using PuttyGen. The public one to upload to GitHub is the text shown in the "authorized_keys" box of PuttyGen. The private one to keep on your computer must be exported via the "Conversions > Export OpenSSH key" menu without a passphrase.

Once you have the repository credentials, connect Eclipse:

  • Open the SSH2 preferences dialog from "Window > Preferences"

  • browse to the location of your private GitHub OpenSSH key

GitHub ssh key
Figure 4. GitHub ssh key

  • Open the "git perspective" from "Window > Perspective > Open Perspective"

  • On the left of the workspace you should see the "Git Repositories" panel

  • Click on "Clone a Git repository" and add the needed information

Clone the Git repository
Figure 5. Clone the Git repository
Clone the Git repository
Figure 6. Clone the Git repository

On the "Branch Selection" dialog you should NOT select "master" but the latest versioned branch, for example "0.7.3".

On the "Local Destination" dialog you need to select a local folder where to clone the repository. Here we assume that you are going to create a new Eclipse project called MySiteProject (will be explained later) and add it to a git repository called mysite. It is very important that you store both the Yada Framework repository and your application repository in a common parent folder that is specific to the current project, for example C:\work\git-mysite, otherwise relative paths in the build file won’t work and you’ll have to customise them.

For the bookstore example we create a common git folder called C:\work\git-yadabookstore that will contain the "yadaframework" git repo.

You should create your base git folder before proceeding. The Yada Framework will have to be cloned inside this folder, with a name of "yadaframework":

Repository destination folder
Figure 7. Repository destination folder

At the end, when you later also add the "mysite" git and web project, the filesystem structure will be like the following, where "mysite" is any new project that uses the Yada Framework:

C:\work\git-mysite
  mysite
    .git
    MySiteProject
  yadaframework
    .git
    docs
    YadaDocs
    YadaTools
    YadaWeb
    ... and other folders

When you have connected the yada repository, you can switch to the "Java Perspective" in Eclipse.

The First Project

Creating the Project

Create a new Eclipse Project using "File > New > Project…​ > Gradle > Gradle Project" menu. Use any name you like ("MySiteProject" in the above example) and accept all defaults. Two new Java projects will be created in your workspace.

For the bookstore example the project name will be YadaBookstore

Since Gradle 7 the wizard creates a lib subproject because that’s how the Gradle developers want to structure all projects. We want to keep things simple so we’re going to restructure the layout in order to have a single project instead.

The following fixProject.sh bash script can be used in order to get rid of the lib subproject:

	#!/bin/bash
	# Fix Buildship generated Eclipse project

	projectFolder=$1

	sed -i "s/include('lib')//g" $projectFolder/settings.gradle

	mv $projectFolder/lib/bin $projectFolder
	mv $projectFolder/lib/src $projectFolder
	mv $projectFolder/lib/.classpath $projectFolder
	mv $projectFolder/lib/build.gradle $projectFolder
	rm -rf $projectFolder/lib
	rm -rf $projectFolder/src/main/java/*
	rm -rf $projectFolder/src/test/java/*

You can find a version of it in YadaTools/scripts/fixProject.sh. It should be run in the parent folder of the project passing the project folder itself as an argument:

fixProject.sh MySiteProject

We don’t currently provide a Windows equivalent so you should run the above script under a windows version of bash. Git for windows provides such a program in a path like C:\Program Files\Git\git-bash.exe. The "Windows Subsystem for Linux" also installs a bash executable.

After the project has been fixed, select the old projects in Eclipse and do a "refresh" accepting to delete the lib project when prompted.

Optional: edit the /MySiteProject/gradle/wrapper/gradle-wrapper.properties file changing the distributionUrl to match the version of Gradle that you want to use. For example distributionUrl=https\://services.gradle.org/distributions/gradle-7.6-bin.zip. This is only needed if the gradle you want to use is not yet available in Eclipse. Right-click the project and choose "Gradle > Refresh Gradle Project" to update the version of Gradle used.

You can choose to add an external Tomcat server or use the embedded version. In the first case, you should be using the "Enterprise" version of Eclipse. If not, you should at least install the "Eclipse Web Tools Platform" (WTP) plugin.

The bookstore application will use Tomcat embedded, so no need to install any standalone server.

Importing the YadaFramework Projects

After connecting to the GitHub repository as explained above, you can import the needed projects using the "File > Import…​ > Gradle > Existing Gradle Project" menu.

The Yada projects will be located in the git folder you chose before, not along with the new project just created. This may be confusing because the Import dialog will initially open in the workspace and you will have to browse to the git folder instead. After adding the new project to git as explained later, all projects will be found in the git folder.

To import most Yada Framework projects at once you could just import the "YadaWebCommerce" project and rely on dependency resolution to automatically import everything else. Don’t worry about Gradle versions here: the version used will be the one configured inside the imported projects.

Import the YadaWebCommerce project
Figure 8. Import the YadaWebCommerce project

The YadaTools project should also be imported because you will later need to copy some files from it.

If the imported projects have any errors, first of all right-click and choose "Gradle > Refresh Gradle Project". If it complains about some unbound system library, open "Properties > Java build path > Libraries" and remove the library.

You should now have, in your workspace, the following Yada projects:

  • YadaTools

  • YadaWeb

  • YadaWebCMS

  • YadaWebCommerce

  • YadaWebSecurity

Saving to git

The next step is to create a git repository to store your projects. You must definitely use git to store your files, because after sharing the project to the repo it will be moved to the same root folder of the Yada projects so that relative paths in the build file will work effortlessly.

For a quick test, you can just create a local repository. It must reside in the same root folder that was used when cloning Yada, that was C:\work\git-mysite in the previous example. The name can be anything you like. Here we use 'mysite':

Create a local git repository
Figure 9. Create a local git repository

In the bookstore tutorial the git folder would be C:\work\git-yadabookstore\yadabookstore

You can also use any public provider like GitHub or a private server installation based for example on GitLab and clone the repository locally, being careful to create the correct directory tree.

When using GitLab, let it create a default readme.md file so that you’ll be able to check out the repository easily (there should be a similar option on GitHub). Then add the repository location to the Git Perspective as done for the Yada Framework.

After the repository has been added to Eclipse, to add your project to the git repository right-click on it and choose "Team > Share Project…​". In the dialog you should just select the correct repository and accept the defaults. The resulting filesystem structure will be as follows:

C:\work\git-mysite
  mysite
    .git
    MySiteProject
  yadaframework
    .git
    docs
    YadaDocs
    YadaTools
    YadaWeb
    ... and other stuff

Finally edit .gitignore in the root of your project to make it look like the following:

.gitignore
/.gradle/
/build/
/bin/
/.gitattributes
/.settings/
/.classpath
/.project
!gradle-wrapper.jar
/.sass/
**/res/css/*.min.*
**/res/js/*.min.*

If you don’t see the file, you should change the workspace filter. Next to the "Package Explorer" title there’s a menu icon containing the "Filters…​" item. Ensure that ".* resources" is NOT selected.