...
Tomcat only supports the basic Servlet functions while JBoss supports the entire suite of J2EE standard services. When an application decides to use a standard API that is part of J2EE but is not installed in Tomcat, they have to include their own copy of the support library. For example, CAS has JPA support for the Ticket Cache. JPA is built into JBoss and every other J2EE server, but to get that service in Tomcat you have to include a copy of Hibernate (or another JPA implementation) in your WAR.
This creates a potential conflict when CAS comes with a Maven project that includes into the WAR duplicate copies (sometimes at slightly different version levels) of services that JBoss supplies out of the box. Do you continue to use the CAS copy of the service, do you shift over to use the JBoss built in version, and if you do nothing then does the code work at all.
The most complex problem deals with the generic problem of "logging", because there are so many different interfaces, implementations, and libraries all concurrently in use in most applications.
Logging is pretty much the same no matter which library or implementation you choose. There are some slight differences that give way to what seems like a dozen different competing solutions to the same problem (log4j, slf4j, Commons logging, JBoss logging, ...). Among the various optional modules of CAS, and then among all the JAR file libraries that CAS includes, there is some code that uses each available interface. Since this is typical, the libraries are designed to all coexist with each other and they can nicely interoperate. It a standalone application, or in Tomcat, they automatically discover each other and work out their differences. However, when you run a bunch of applications inside a server like JBoss, there are two different ways you might like to operate.
In some cases you want JBoss to control all the logs for all the applications so you have a single unified logging system.
Alternately, the developer of each application may want a separate log for that application that the developer controls independently of JBoss and the other applications.
On paper it should be possible to configure either solution, but in practice we have not figured out how to get JBoss logging to do everything we want for CAS. So at Yale CAS runs under JBoss completely separated from the JBoss logging services and the JBoss provided logging libraries. This is accomplished by adding a JBoss specific configuration file, WEB-INF/jobss-deployment-structure.xml. This file, among other things, lists libraries that JBoss would normally make available to an application that runs under it but where CAS wants to use its own version of the library (or to have no version of library at all). Generally speaking, the Yale CAS version of this file excludes all the expected and obscure logging related libraries for all the logging APIs.
To get the exact opposite result, that is to replace some library that CAS normally includes in WEB-INF/lib with a version of the same code that JBoss supplies as a built in service, the Maven configuration is changed to indicate that the library is "provided" by the server environment.
Maven Dependency Management is supposed to provide the ability to force a specific release of a dependent library across the entire build process. However, building CAS is complicated because it involves compiling the Core library, and then the optional libraries, and then separately assembling them in the Webapp project.Then on top of that, the Yale customizations are added to the vanilla WAR using the CAS recommended technique of Maven "WAR Overlay".
When the dust settles, you occasionally have JBoss complains when CAS attempts to include in WEB-INF/lib:
- Libraries that should not be explicitly included because they are now part of Java (XML libraries like xalan and xerces).
- Libraries that duplicate function that is built into JBoss and any other full J2EE server (hibernate, JAXB).
So any library that causes trouble is excluded during the Yale Maven project that builds the final WAR. In addition, the JASIG code add a persistence.xml file in WEB-INF/classes that causes trouble for JBoss, so it is removed.
JBoss provides a number of optional libraries that are not part of the J2EE standard but are commonly used by applications. The biggest problem is JAR files associated with any of the dozen or so "logging" frameworks (log4j, slf4j, commons logging) which all come in JBoss along with its own JBoss logging. JBoss by default tends to replace your logging jar file with its own, but that doesn't generally work. The only way to reliably get all the logs you want is to include a WEB-INF/jboss-deployment-structure.xml with exclude statements for all the log related JAR files. Then logging for CAS is controlled by the CAS log4j.xml file and not the JBoss logging configuration.
Maven Dependency MisManagement
After all the processing, we occasionally find two different versions of the same library included in WEB-INF/lib (example: commons.io Version 2.0 and 2.4). Probably one version was added by the vanilla CAS build process, and then a second version number was unintentionally added during the Yale customizations. You might spend a week of trial and error trying to figure out what you don't understand about Maven Dependency Management syntax, but there is a brute force solution to delete the libraries you don't want (and while you are at it the libraries that conflict with the JBoss enviroment) by specifying the undesirable JAR files in the "packagingExcludes" tag of the maven-war-plugin configuration in the Yale Webapp POM. Basically, this is a place to put in a last minute override and delete of files that you do not want copied to the final WAR artifact.
Project Structure
CAS is distributed as a top level "parent" Maven project contains a set of "subprojects" in subdirectories. The POM at the top "parent" level lists the subprojects that are to be compiled.
Every CAS Server requires the cas-server-core subproject which contains about 95% of the CAS code. Yale also uses the cas-server-support-ldap optional subproject to access Active Directory using LDAP protocol to authenticate users and passwords.
Yale includes the cas-server-integration-ehcache project to use Ehcache as the ticket replication mechanism for CAS clustering.
CAS includes the cas-server-support-trusted project, although at any given time it may not be used. "Trusted" means that CAS allows some external agency to authenticate users. If we ever use the ability of the F5 to validate X.509 User Certificates and to turn the validated netid into an extended HTTP Header, then the code in this project will provide the support or at least provide a model for the use of this support.
The only Yale optional subproject that is fully used is cas-server-expired-password-change. This supports the Yale custom mechanism to check if passwords have been changed in the last year and redirect the user to the Netid (Change your Password) application if necessary.
The cas-server-preferences module is a Yale customization that was never used but which poses no particular problem if the user navigates to /cas/preferences he is supposed to be presented with a menu of options to customize CAS behavior on this browser. Selections are saved as a Cookie, which is then available to customize the CAS behavior in all subsequent logins. It could be used to enable CAS options that we don't want to present to a user unless he specifically requested themcontaining subdirectories each of which is a Maven subproject that builds a component (a JAR or WAR file). The order in which the subprojects are processed is determined by the order of <module> statements in the parent. You build first files that other projects use, and later the projects that use them. Generally you build server-core first, then the optional JAR files. You have to create the WAR after you have built all the JAR files that go into it.
The parent project is supposed to provide global dependency management. That is, it should ensure that every project that uses commons.io uses Version 2.4 and that in the end it is Version 2.4 of the JAR file that ends up in the WAR and therefore is used at run time.
Unfortunately, the JASIG parent project also includes some "open source project legal boilerplat" steps that insure that copyleft statements are in order and that all the Gnu and Apache license statements for included libraries are properly disclosed. That is important for JASIG, but Yale does not need it for its internal modifications and releases and we don't have the expertise to conform to build NOTICE and other boilerplate files. We do, however, need the dependency management because we include code that uses commons.io and we also have to compile against Version 2.4 just like everyone else.
So the first step in adapting any new CAS release is to merge the previous Yale top level project POM with the new one from JASIG.
First, you have to remove the reference to a undistributed JASIG parent (that is a parent to your parent) that is referenced only by a URL and stored on a JASIG server. That drags in the legal boilerplate processing.
Then you have to make sure that you update the version numbers at the end to be the new version numbers distributed by JASIG. You should also make sure that any new dependency management entries have been added. If there are changes to the Maven plugin configurations, you have to read the manual and figure out if they are helpful or a problem.
Then you copy over the Yale custom projects (expired-password-change, preferences, CushyTicketRegistry, and the Yale-webapp or "cas-server-war" project). They become additional subdirectories.
Now for the big step. Yale does not want to make changes to JASIG project source, but sometimes there are problems that only show up when you run in JBoss, or bugs in code that supports features that Yale does not need or use, and we may make some custom changes to a JASIG project if it is important.
So the starting point would ideally be that we do not build local custom copies of any JASIG subproject but only build the new Yale custom projects. If that is going to be the case, then you would comment out all the JASIG <module> statements in the parent project (because we would then use vanilla JASIG JAR and template-WAR files from the JASIG repository) and you would add <module> files for each Yale project subdirectory you just copied over.
If you make a single change to any JASIG project, you have to give it a new Yale Version ID to distinguish it from the vanilla artifact, then change the version number of dependencies in other projects.
Note that the vanilla cas-server-webapp project creates a Template WAR file that is then modified by the Yale-webapp project which uses the recommended technique of WAR Overlay process. WAR Overlay can add new files and replace old files in a WAR, but it is not automatically able to change the version number of dependencies.
Therefore, suppose you start with a vanilla cas-server-core for release "3.5.2.1" (and all the JASIG modules are commented out). However, there is a bug and you have to change one line of code. You now have to create a Yale modified artifact with a new release ID. At this point Yale takes advantage of the fact that JASIG starts out at 3.*.* releases, so Yale can number its release 1.*.* without conflict. The corresponding Yale releases to 3.5 are Yale's 1.1, so you uncomment the <module> for server-core in the parent project, and in the server-core POM you change the release from 3.5.2.1 to 1.1.x-SNAPSHOT (whatever the current Yale version is for all the other Yale projects).
Bugfixes typically don't change method signatures, so it probably doesn't matter if a project compiling source to build a JAR uses 3.5.2.1 or 1.1.x-SNAPSHOT during the compile. However, the cas-server-webapp project Version 3.5.2.1 if it is not changed will have included the cas-server-core JAR Version 3.5.2.1 and that JAR will be in the WEB-INF/lib. So either you have to also modify the cas-server-webapp project to be Version 1.1.x-SNAPSHOT and to depend on the 1.1.x-SNAPSHOT Version of server-core, or else you are going to have to make the Yale-webapp WAR Overlay project both delete the 3.5.2.1 server-core JAR file (by adding it to the exclude list in the maven-war-plugin configuration in the POM) and then add the 1.1.x-SNAPSHOT JAR file (by changing the version number in the Dependency list).
Yale developed a package of optional CAS code under the brand name CUSHY. All the CUSHY code is in the cas-server-support-CusyTicketRegistry project, but while the entire project is built, currently CAS at Yale only uses one bean based on one class (CushyClusterConfiguration) and ignores the rest of the code. The CushyClusterConfiguration bean is added to the TicketRegistry XML Spring configuration file to configure Ehcache after discovering the current environment (sandbox, dev, test, prod). Echache needs a configuration file that lists all the other nodes in the cluster. Without this bean, we would need to keep a separate configuration file for each server and the Jenkins install job would have to install the correct file on each machine. Automatically configuring the file based on discovering the hostname of the current machine is much simpler.
...