CAS development at JASIG is currently hosted in Git. Yale production deployment standards are currently based on Subversion. Fortunately, Yale has been able to meet its requirements while using the standard distributed JAR file artifacts from JASIG, so there is no need to do local management of the JASIG source. During development it is useful to read source and sometimes debug into a JASIG module, so the first step is to obtain a full vanilla source copy of the release you will be installing as your base. You can check it out with Git or obtain a zip file from JASIG. This source may be checked into Yale SVN, but that is simply for convenience.
The preferred mechanism for local configuration is called the "WAR Overylay" method. This is an option of the Maven plugin that manages projects where the POM indicates "war" as the type of packaging (the type of artifact produced by the project). WAR Overlay processing is triggered when a "war" project has a dependency that is itself also a "war". With an overlay, the plugin reads the dependency WAR file in, replaces or adds files from the current project, and then writes the resulting merged/updated WAR file out to the repository.
Source Build
The standard JASIG CAS project has a parent "cas-server" directory with a POM of type "pom". This project doesn't create anything itself. It contains the common parameters and dependency management for the subprojects that are distributed as subdirectories of the parent directory. A list of Modules in this parent POM indicate the subprojects that Maven should buildsource and configuration files are stored in the Yale Subversion repository at https://svn.its.yale.edu/repos/cas. If you are updating the current release, everything you need will be there. If you are upgrading to a new release of CAS, you need to obtain a copy of that release from JASIG. CAS releases are distributed as a zip file, but they are also checked into Git. Unless you are contributing updates back to JASIG, there is no need to access Git, but there is no problem using it as the source if you feel comfortable with that.
CAS development has traditionally used the Eclipse IDE. Choose the J2EE development configuration because it will come with support for WAR projects. It has been necessary to add support for Subversion and Maven to the base J2EE distribution, and it is recommended that you install the JBoss tools, at least the tool that starts and stops the JBoss server.
Eclipse has its own project structure, but it will create an Eclipse project from a directory that contains a Maven POM. You just have to tell Eclipse that you are importing a Maven project. Typically Eclipse will create an Eclipse project for the parent directory (cas-server) and then a separate Eclipse project for each subdirectory of the parent that has a POM file. There will be some error messages for features like AspectJ that the JASIG POM uses but that the Eclipse plugin does not directly support. You can ignore such messages, because your actual compile, packaging, and deployment will be done running Maven and Eclipse is just a powerful file editor. When Eclipse does not find its own project files in a directory and therefore creates a project from the POM, it uses some default templates for some project options. If these defaults are wrong (say by choosing Java 1.6 as the compile level when you are running 1.7) then you may have to go back and manually change the options project by project.
In production deployment Jenkins compiles the source to produce JAR and WAR artifacts in the Yale Artifactory server. It then deploys the WAR artifact to the DEV, TEST, and PROD servers. In sandbox development on your desktop machine you create Eclipse shadow versions of the Jenkins Compile and Install jobs by using the Run Configurations ... settings to create Compile CAS and Install CAS Run jobs. Both jobs run Maven under Eclipse to do the same thing that Maven does under Jenkins. You choose an "install" target and the artifacts will be generated and stored in the local repository.
The development sandbox can be a Windows, Mac, or Linux machine.
CAS development uses the Eclipse IDE (J2EE development configuration) with the Subversion and Maven plugins. On your desktop "sandbox" machine, CAS is deployed to a local copy of the JBoss server. In production, CAS is built and deployed using Jenkins.
In Maven, a POM with a packaging type of "pom" contains only documentation, parameters, and dependency configuration info. It is used to configure other projects, but generates no artifact. The parent "cas-server" directory is a "pom" project. A "jar" project compiles Java source and combines the resulting *.class files and any resource data files into a zip file with an extension of ".jar". This is an artifact that is stored in the repository and is used by other projects. A simple "war" project has some optional Java source that will be compiled into the WEB-INF/classes directory, and a special src/main/webapp resource directory that contains the HTML, JSP, XML, CSS, and other Web data files. Any JAR files that are listed as a dependency in a war-type POM are included in the WEB-INF/lib directory. The classes, resources, and libraries are then zipped up and stored as a WAR artifact.
CAS has traditionally been created using the "WAR Overlay" technique of Maven. First, the cas-server-webapp directory builds a conventional WAR from its own files and dependencies. This is a generic starting point WAR file with all the basic JAR files and XML configuration. Then a second type "war" project is run that (in the standard JASIG CAS distribution) is called cas-server-uber-webapp. What makes it different from a standard type "war" Maven project is that the first dependency in this project is the cas-server-webapp.war file build by the previous step.
A "WAR Overlay" project depends on an initial vanilla prototype WAR file as its starting point. Everything in that WAR will be copied to a new WAR file with a new name and version, unless a replacement file with the same name is found in the WAR Overlay. When Yale or any other CAS customer is building their own configuration of CAS, the WAR Overlay project directory provides a convenient place to store the Yale configuration changes that replace the prototype files of the same name in the previously run generic cas-server-webapp type "war" project.
If you made no changes at all to JASIG code, the WAR Overlay project is actually the only thing you would need to check out and edit. Yale would never need to locally compile any CAS source, because the JASIG repsitory version of the cas-server-webapp.war artifact for that release version number would be perfectly good input to the WAR Overlay process. However, having a local copy of all the source is useful for debugging and documentation.
Source Build
CAS is distributed as a cas-server directory with a bunch of subdirectories and a POM file. The subdirectories are JAR and WAR projects. The POM file contains a certain amount of boilerplate for JASIG and the CAS project, plus two things that are important. The parameters and dependency management section ensure that all elements of CAS are compiled or built with the same version of library modules (quartz for timer scheduling, hibernate for object to database mapping, etc.). Then a list of <module> statements indicate which subdirectory projects are to be run, and the order in which they are run, when Maven processes the parent POM. The possible modules include:
- cas-server-core - This is the single really big project that contains most of CAS Server code and build the big JAR library artifact. It is built first and all the other projects depend on it and the classes in the JAR file.
- cas-server-webapp - This is a dummy WAR file that contains the vanilla version of the JSP, CSS, HTML, and the XML files that configure Spring and everything else. The dependencies in this project load the basic required JAR libraries into WEB-INF/lib. This WAR is not intended to install or run on its own. It is the input to the second step WAR overlay where additional library jar files will be added and some of these initial files will be replaced with Yale customizations.
- Additional optional extension subprojects of CAS supporting specific features. For example, the cas-server-support-ldap module is needed if you are going to authenticate netid Netid passwords to AD using LDAP protocol (you can authenticate to AD using Kerberos, in which case you don't need this module). A JASIG standard distribution includes all possible subprojects and the parent cas-server POM file builds all of them. To save development time, you can comment out the subproject <module> statement in the parent POM of modules you don't use. Disk space is cheap, and deleting the subdirectory of modules you don't use may be confusing.
- Yale CAS extension JAR projects. For example, the cas-server-expired-password-change module is the Yale version of what CAS subsequently added as a feature called "LPPE". Yale continues to use its code because the Yale Netid system involves databases and services beyond simply the Active Directory component and support
- cas-server-uber-webapp - This is the "sample" version of the local customization WAR Overlay project. This directory may be renamed to match the artifact name that the POM builds, which is also the artifact name spedified in the Jenkins Install job. However it is named and wherever it is located, Yale customization is (unless it is impossible) stored in this the WAR Overlay project directory. If we need Java code, we put this source here and it is compiled and ends up in WEB-INF/classes. We replace some standard JSP and CSS files to get the Yale look and feel and wording. The XML files that configure Spring and therefore CAS behavior are here. This project must always be the last module executed. The cas-server-webapp project is a dependency, so it is the base WAR file that will be updated. This project replaces JSP, CSS, and XML files in the base WAR with identically named files from this project. It adds new files and library jars (from the dependency list of this project). Details will be described below, but this is where all the action happens.
...