Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

If you were hoping for a list of 20 steps that you can apply without thinking, it won't do you any good. Fortunately, the Maven plugin is perfectly able to rebuild the projects correctly starting from the bare POM, so often the only thing you have to do is scrap an existing incorrect Eclipse project configuration and have a new one rebuilt.

The End Result

The first step There is no way to be sure what problems you encounter and in what order. There is a sequence that works in one place at one time, but change a release of this or a version of that and problems pop up somewhere else. So the best idea is to describe the target result. Then desired end result and then work back to a sequence of "repairfixups" steps will demonstrate how to clear errors and rebuild the projects to achieve this desired end that will solve various problems that can appear in the path to the desired result.

When you start Eclipse, you choose a Workspace directory. The default is the directory Eclipse works in a "workspace" directory. Much of the configuration (the SVN repositories), and the project settings, and often the checked out source are stored in this directory  The default is {user-home}/workspace but you can choose another name in the startup dialog or, if you have already set some workspace directory to be the default used every time, you can choose an alternative with the File - Choose Workspace menu option. The following This process involves some trial and error , so it may be and occasionally it is a good idea to toss everything and start over again from scratch. So I recommend that you initially install all this into an empty workspace directory rather than mix it in with existing projects.

When things are done, there will a new empty test workspace that you can discard and start over.be a "cas3" project (at least that is the name you get automatically if you check out the source from SVN) that contains all the source of the parent Maven project and all its subprojects (modules). If you exit Eclipse, navigate to the workspace directory and its cas3 subdirectory and type "mvn install" then the batch version of Maven should build everything according to the vanilla JA-SIG instructions. This is the directory you would have gotten if you had not used Eclipse at all.

In addition, when you run Eclipse there will appear to be additional Eclipse projects in the workspace for every subdirectory/module. That is, there will be a cas-server-core project and so on down to cas-server-webapp. Each will be a real Eclipse project just as each subdirectory is a real Maven project with its own POM. However, while these Eclipse projects display in the Project Explorer view as if they were peers of the cas3 project, they will actually be located in the subdirectories of cas3 that are also Maven module subdirectories.

In other words, the Maven view of  CAS as a parent Maven project with individual modules each of which produces an artifact will be almost exactly replicated as Eclipse projects. The Eclipse projects will have the same logical structure and dependencies as the Maven projects from which they were constructed.

The Problems

Your results may vary. Do not do this while driving or operating machinery. However, using current software the author has experienced the following problems:

  • The .classpath checked in with the CAS 3.4.2 and earlier servers was based on an older model where there was just one big "cas3" project and all the subprojects/modules were represented as Build Path Source directories in that one project. If you check out from SVN, there is no way to avoid getting the .classpath file and starting out with this old and now deprecated project design. So you have to manually delete all these source directories and create the separate subdirectory/module projects manually.
  • The checked in .classpath file contains a configured Source directory that does not exist. The only way to fix this is to manually delete the entry.
  • The Eclipse Maven plugin seems to have a problem with the "enforcer" Maven plugin. This is an optional Maven module that checks to make sure that you are using the right version of Maven and the right level of JDK. Unfortunately, these checks are not helpful and, if you want, you can certainly build and run CAS with a later version of both Maven and the JDK. However, if you leave the "enforcer" plugin configured in the top level POM (in the "cas3" project) it tends to generate Maven build errors that screw up the project generation. So it is a good idea to delete this one entry in the POM before you do anything serious with Maven.
  • There are some HTML fragments in the cas-server-webapp directory that will generate error messages after everything builds. Ignore these errors.

Zip or SVN

The CAS 3 source is available from the www.jasig.org Web site as a downloadable zip file. The easiest approach is to expand this zip file in a directory, delete any .project and .classpath files contained in it, and then use this directory as the source of an Eclipse Import (of a directory filled with Maven projects). CAS 3 can also be checked out from the Subversion repository. This gives you This is certainly adequate for those who are just exploring the CAS source and do not intend to do any  development.

Serious developers, however, want to check out their source from the JA-SIG Subversion repository. That way they can compare any files they change with the original and can apply bug fixes and other updates as the code changes. SVN also provides access to the current unreleased code ("the trunk") and provides developers with the ability to track bug fixes that others have checked in and (for authorized developers) to commit changes. Eclipse can only synchronize with SVN if it checked the source out of the SVN repository before you made any changes.

So the first step will be to create a single "cas3" project directory containing all the CAS 3 source. This directory can be the unzipped download from JA-SIG or it can be checked out from SVN. If this is done right, however, this project will just be a container for everything else. From the Eclipse point of view, it isn't even important that this be regarded as a Java project. It will have no source files, it needs no classpath, and Eclipse will not "build" it. From the Maven point of view, this is a parent project containing a POM that references subproject modules.

Each module subdirectory is a Maven project in its own right and current best practice is to create a corresponding Eclipse project. Eclipse will do this automatically if you use the "File - Import ... - Maven - Existing Maven Projects" sequence from the menus. If the CAS3 project is open, Eclipse will discover the POM files in each of the subdirectories and list each subdirectory as an Eclipse project that it is prepared to generate. Although the Eclipse Project Explorer will list each of these projects as a peer (at the same level) as the cas3 project, they are actually subdirectories inside the cas3 directory.

If you get this structure right (one big "cas3" directory/project containing all the source files but regarded by Eclipse as having no Java source directories to compile, then one project per subdirectory that compiles and builds the source for that one module) then the Eclipse Maven plugin is prepared to get the rest of the Eclipse project configuration right (or close to right) if you take steps to clean up the residue of any misconfiguration left behind by the original JA-SIG filesthat will become part of the next version of CAS.

Eclipse has SVN support and can easily check out the entire "trunk" or any prior version of the code (such as the cas-server-3.4.2 which, at the time this is written, is the latest release). However, when you check out from subversion, Eclipse does not give you the option of omitting the .project and .classpath files if they exist, and before you will be given interactive access to the project it will have used these files to initially configure the project.

Check Out

Display the SVN Repository Exploiring Perspective (Window - Open Perspective - Other - SVN Repository Exploring). If the JA-SIG repository has not already been added, right lick in the SVN Repositories view and choose New ... Repository Location. The URL is https:source.jasign.org and that becomes the name of the Repository. Expand this repository as a tree, expand "cas3". Now decide if you want to work on the unreleased next version of the server ("trunk") or one of the numbered previous releases ("tags"). Expanding "trunk" or one of the "tags" should show a pom.xml file and subdirectories including "cas-server-core". Choose the directory ("trunk" or "cas-server-3.4.2") right click, and choose Check Out...

Unfortunately, the "cas-server-This may take a few minutes, longer if you have a slow internet connection. When it is done, switch back to the Java or J2EE perspective.

Delete Source Directories

If you check out version 3.4.2 from SVN, or forget to delete the .project and .classpath from a zip file, you will get a single " and earlier releases (but not the "trunk" or later releases) of the CAS server have checked in .project and .classpath files that do not reflect current Eclipse Maven practices. However, there is no option in Eclipse to check out everything except these two files, and when Eclipse checks out a directory containing a .project file it processes it before you can stop it. So the first step after checkout is to undo the incorrect structure they createcas3" project in which every source subdirectory of every Maven subproject/module is an Eclipse Build Path source directory. Select all of them Image Added
Then right click on the entire selected group and from the context menu select Build Path - Remove from Build Path
Image Added
This will remove the configuration of all the existing source directories, but it leaves the one broken configuration of the non-existing source directory. Right click the cas3 project line at the top, chose Build Path - Configure Build Path. Choose the Source tab
Image Added
Select this missing directory and click the Remove button.

Delete the Enforcer Plugin

At the bottom of the cas3 project, open the pom.xml file. This brings up the Eclipse Maven plugin POM editor. Select the plugins tab at the bottom Image Added
In the CAS 3.4.2 server the first plugin will be the maven-enforcer plugin. Select it and the details of the entry will appear on the right. Image Added
Press the Delete button to remove the entry. You want to do this before you import the subproject/modules because if the line is present, it can screw up the import process.

Generate the Subprojects/Modules

Right click in the Project Explorer empty area and from the context menu select Import ... From the dialog choose Maven - Existing Maven Projects Image Added
The next panel will display all the POM projects that the Eclipse Maven plugin found in the cas3 project directory. Image Added

You can accept the default and import all of them, or if you are only interested in a subset of the projects this might be a good point to save some time and effort and turn off the checkbox on the projects you do not care to work with. When you are done, each selected Maven project will be turned into a peer project of cas3 in the workspace.
Image Added

Note that there will be an HTML validation error on the webapp project, but that is inevitable and is not a real issue.