...
- 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 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 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.
Sanity requires that all of the components of the final CAS Server be compiled and tested with the same version of any library JAR file on which it depends. Unfortunately, there is no automatic way to get this right. Typically, version numbers will be specified in the POM file of the parent cas-server project and as long as that is inherited by all the JASIG projects and all the Yale custom projects, then everything will be in sync and the right library will be in the WAR file. There are two sources of potential problems: JBoss may require (or strongly recommend) that you use a later version of some library than the version JASIG was configured to use, or Yale customizations may require a newer version. The only sensible solution is to change the POM file in the parent cas-server project and then recompile everything to use it. Under no circumstances should the WAR Overlay project introduce a different version of a library being used by other component modules. WAR Overlay only replaces identically named files, and it would include both libraries if the base compoenents depend on Generally you run the vanilla JASIG cas-server project POM once on your sandbox machine and a target of "install". This compiles all the source files, builds all the JAR and WAR files, and stores them in the local Maven repository on the machine. There are other ways to get the artifacts from the Yale Artifactory server or from JASIG, but compiling them is the easiest way and you probably need the project source anyway. After that, you technically only have to run the WAR Overlay project unless you make a change to any JASIG projects. However, in practice you may find it necessary to change the Version numbers in the parameters and dependency management section of the parent POM if you discover that the JBoss server you deploy to wants a different version of any standard library. Then you want to recompile everything to maintain sanity.
The WAR Overlay project can contain new dependency statements that include JAR files not used by JASIG CAS, but it should never try to introduce a different version number of a library that CAS has already introduced. The Overlay mechanism replaces identically named files, but it will not notice that quartz-1.6.1.jar and the WAR Overlay project introduced a second dependency on in WEB-INF/lib from the cas-server-webapp prototype project is a different version of the same library as quartz-1.6.2.jar .
This produces some tension in the preferred directory structure during development. It is a convention to put subprojects as subdirectories of the parent project. This structure mixes Yale custom JAR file project subdirectories and the Yale version of the WAR Overlay project subdirectory into the directory tree of the standard JASIG CAS distribution. It reflects the logical structure of the build process (sanity) but then mixes JASIG and Yale subdirectories (not best practice).
Although it is the common practice, Maven does not require the parent POM to be in the parent directory. So you can have a mostly vanilla JASIG source directory and a separate directory with just the Yale JAR projects and the WAR Overlay project. This separates the building of the JASIG standard source from the building of the Yale code, but that creates two separate source build jobs and requires you to remember to rebuild the standard JASIG components any time a dependency version number changes. So you can shoot yourself in the foot here, and you need two different Jenkins production source build jobs for the separate directories.
Look at subversion to see which of the two approaches has most recently been checked in. If you strongly prefer the other, feel free to use it for the next release. Do not feel bad if the person who next installs CAS changes it back.
in the WAR Overlay project.
There are now two ways to organize the projects. You can put everything in the cas-server directory, starting with the JASIG subdirectories and then adding the Yale subdirectories. Then adjust the parent POM in cas-server to build what you want to build each time you run the Build job under Eclipse. Alternately, you can separate the entire JASIG source tree from the Yale project directories. You can also build the JASIG artifacts first with one job and then build the Yale artifacts with a second job, or you can create a single job that builds both at once. There are advantages and disadvantages to either approach, and on a sandbox feel free to use whichever structure seems most comfortable.
It is a common Maven convention to make the parent POM a parent directory and the <module> POMs listed in the parent subdirectories of the parent. However, the child projects reference the parent by the artifact name and version from the local Maven repository, and the parent can reference modules by path expressions. So any arrangement of directories can be made to work. However, remember that the Jenkins "trunk build" job reads Maven source projects checked into Subversion, compiles them, and stores them as artifacts in the Yale Artifactory server. So if at the end of development you end up checking in two directory trees to the Yale SVN repository, you are going to need to Jenkins build jobs.
The POM in a vanilla JASIG component subproject will have a Version number that corresponds to CAS releases (3.5.2). The POM in a Yale customization subcomponent will have a Version number that corresponds to the Yale CAS installation "Release" number for Jenkins tracking (1.1.0-SNAPSHOT). Since The artifact name and version number in the WAR Overlay project has the Yale version number, and that is the WAR that actually gets copied over to JBoss and installed, that is the version number that will be a parameter to the Jenkins jobmust match the artifact name and version number of the Jenkins Install job parameters.
The Installer
CAS has a Yale standard Installer project. By convention, the WAR file is downloaded from Artifactory and is then copied to the JBoss deploy directory by an Ant script running under a separate Maven projectYale has a convention that there is a separate Install job. This job reads a Maven project from SVN that contains parameters and an Ant script. Maven runs Ant, and Ant downloads the artifact from Artifactory (in this case, the WAR file produced by the WAR Overlay project) and copies it with some variable substitution to the deploy directory of JBoss.
The Installer is driven by an install.properties file. This file contains passwords used to access AD and databases, so it is not checked into SVN. Get a copy of this file saved by the last person who worked on CAS saved in some more secure or private file area and add it to the project directory after checking the Installer project out of SVN.
Standalone.xml
In JBoss 5 the datasource definitions for databases and an XML file configuring JBoss JNDI were generated during the Installer step and copied to the JBoss deploy directory. This is no longer the way to do things for JBoss EAP 6.1. Production services has to make sure that the configuration file for the JBoss instance contains the XML to define datasources and JNDItheory, the developer of a project does not have passwords for the production databases, so runtime parameters are provided from a source outside the WAR. A common Yale convention was to build XML files defining each database as a JBoss Datasource and creating a service that stuffed a group of parameters into the JBoss JNDI space where they could be read at runtime using the built in java.naming classes. The Install job used to build these XML files.
However, the JBoss EAP 6.1 rewrite has changed the JBoss best practice. Now both Datasources and JNDI values are stored in the main "subsystem" configuration file. In the sandbox, this is the standalone.xml file in the /config subdirectory of the JBoss server. You need to get a copy of an appropriate configuration file for your JBoss and install it yourself. Production services will be responsible for providing the file in DEV, TEST, and PROD, but you need to notify them if you add something during sandbox development so they can also add it to the versions they manage.
To Work on Current Release
Check out from SVN the current version of the cas-server source. (If the Yale source is in a separate directory check it out too, but it has probably been added as subdirectories of the cas-server directory.) Check Also check out the Installer project directory. Get a copy of install.properties for the Installer project and make sure the jboss.deploy.dir points to the location where you put JBoss on your sandbox.
If it is at all possible, make changes only to the WAR Overlay project subdirectory.
...