Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

« Previous Version 5 Next »

If you are just installing CAS "as is" it is not necessary to create the source development projects. Simple configuration can be performed using the WAR Overlay mechanism. You create an Eclipse Project to generate a WAR artifact (give it your own group, name, and version), and you make it dependent on the specific JA-SIG CAS WAR artifact. Then you populate the project with any configuration files that have local customizations. When Maven runs, it reads in the JA-SIG WAR file, keeps any files that are not overridden, replaces any files with versions you provided in your project, and then writes out the WAR containing your customizations.

However, if you want to work with the CAS 3 source, then you want to check out that source from the JA-SIG SVN repository and create the Eclipse projects that will allow development. Unfortunately, this never works as expected. There is always something wrong. Sometimes it is an error in the JA-SIG files, and sometimes it is a difference between the way that Eclipse and Maven used to work and the way they work today.

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

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 desired end result and then work back to a sequence of "fixups" that will solve various problems that can appear in the path to the desired result.

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. This process involves some trial and error 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 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). 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") that 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...

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 "cas3" project in which every source subdirectory of every Maven subproject/module is an Eclipse Build Path source directory. Select all of them
Then right click on the entire selected group and from the context menu select Build Path - Remove from Build Path

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

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
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.
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
The next panel will display all the POM projects that the Eclipse Maven plugin found in the cas3 project directory.

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.

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

  • No labels