After LAMS 2.3 release, one of the task was to migrate to JBoss 5. As its architecture is
significantly different to previously used 4.0.2, the task involves multiple changes in
configuration. It have also led to several other upgrades, as JBoss 5 is more prepared for new
technologies than it supports the old ones.
Here you will find a guide how to start using JBoss 5 with LAMS. Below is a list of issues
encountered during work on this task. Some of them are still unresolved. This document will be
updated as work continues.
1. Download the JBoss 5.1. It is available here:
During development, version 5.1.0.CR1 has been used.
2. Unzip, rename the server directory to "jboss-5".
3. For LAMS, the default path for Windows is "D:\jboss-5" and for Linux is "/usr/local/jboss-5"
4. In Eclipse, check out the project from JBoss 5 branch.
5. Change the <JBOSS_HOME> classpath variable to the directory where you have your server located.
6. There is a bug in Eclipse that prevents the JBoss 5 server to be added "as is" to the list of
Copy "mail.jar" from <JBOSS_HOME>\common\lib to <JBOSS_HOME>\server\default\lib.
Add the JBoss 5 server to the server list in Eclipse.
Remove the copied "mail.jar".
7. Edit the Run\Debug configuration. Add the following parameter to VM options:
It is required, as JBoss developers made configuration files parsing more strict, but still have not
corrected the files delivered with the distribution. Lack of this parameter will result in error of
parsing one of the core server config files.
During development, the following parameters were used:
-Dprogram.name=run.bat -Xms128m -Xmx512m -XX:MaxPermSize=256m -Dxb.builder.useUnorderedSequence=true
8. Build and deploy the project. Run the server.
Here you will find some important issues encountered when working on JBoss 5.
1. NEW LIBRARIES
Several libraries are not deployed any more. They were removed either from lams_build\lib or
Latest versions of these libraries are distributed with JBoss 5, put into directory available for
all servers (<JBOSS_HOME>\common\lib) and LAMS makes use of them now. These libraries are Hibernate
3.3.1.GA, log4j, sfl4j and several other bound with servlets.
2. SERVER CONFIGURATION FILES
Server configuration files has been changed.
log4j.xml is now jboss-log4j.xml. No major changes in content were required.
login-config.xml stays pretty much the same.
jboss-service.xml has a quite different structure and responsibilities now, but only a minor change
to the version distributed with JBoss 5 was needed.
Tomcat - the service is more hidden now. We put our config files into jbossweb.sar. Their
structure is changed, but they contain pretty much the same information as before.
See the config files for comments.
3. CLASS LOADERS & DEPLOYMENT DESCRIPTOR
Class loading is working differently than in previous version. In 4.0.2 all of our JARs in LAMS
EAR were also available for Spring and Hibernate (for unknown reason, because in fact they should not).
In JBoss 5 deployers and services have more separated class loaders, so we need to let each of them
know where the libraries are, separately.
Even when deploying JARs and WARs inside LAMS, different Class Loaders are used. This leads to some
errors as the same class loaded by two different Class Loaders is not the same class any more and
can not be linked to (like in inheritance in classes in different modules).
It was required for all the modules to use the same libraries. By default, if JARs are put into
<EAR>\lib directory, they are available to all EAR modules. But in LAMS we put libraries straight
into LAMS EAR root directory. A way to change the default library directory location was needed.
This required changes in META-INF\application.xml file. Version 5 of the specification is now in
use, rather than 1.3. It allowed to point to lams.ear dir as the library directory. It also made
"Third party JARs" part in application.xml file obsolete, since all the JARs are now visible to all
the modules without listing.
Another issue is that application.xml file structure is more restrictive now. Our Tool Deployer was
adding <module> tags with the deployed tools to the end of that XML file. It was incorrect even for
1.3 version, but it was ignored. Now if we have <module> tags at the end of the file,
<library-directory> (tag to change the library directory location) is not read at all and class
loaders can not find LAMS JARs.
Tool Deployer was altered. New modules are now appended just before <security-role> tags instead at
the end of the document, so the desired structure is obtained.
4. XML PARSER
There were problems with gnujaxp.jar library. It seems that LAMS is using it with jfreechart in Q&A
tool (only?). That library had to be removed, otherwise it caused errors when parsing XML
configuration files. After reading some forums,
other people having similar problems have been found. They suggest switching to some other parser if
it is possible.
It was not attempted yet, but if gnujaxp.jar is required after all, it should be taken from LAMS EAR
and moved to Q&A tool private library. If it is used by other modules too, another approach needs to
We were using JBoss Cache 1.4.2. It was deployed as a MBean in a separate service declared in
local-service.xml. It was available by JMX as "jboss.cache:service=TreeCache".
The new idea was to use the latest JBoss Cache 3.1.0 - they promise marvellous things to happen when
using it. This leads to significant changes in deployment procedure.
The standard (Tree) Cache was used, rather that PojoCache. Since we use Hibernate, there is no point
in using the fine-grained version, which is PojoCache.
Cache 3 requires new libraries: jbosscache-core.jar (Cache itself), jgroups-all.jar (new version of
JGroups) and hibernate-jbosscache2.jar (for Hibernate to use the new Cache; it is designed for Cache
2, but it is backward compatible).
Previously used libraries were removed.
JBoss 5 introduces a new way to obtain Cache, instead of using JMX. It is called Cache Manager and
allows management of multiple Cache instances. This approach was not used, as our needs are small
and we only have one, local instance of Cache.
The suggested way of deploying Cache is to use new JBoss 5 functionality, "-jboss-beans.xml"
deployments. It is similar to "-service.xml" deployment, but the declared beans do not have to be
Mbeans. They can be simple beans used to build the service. Beans can be exposed to JMX by using
annotations. This link gives a good overview of the idea:
For LAMS purpose, "lams-cache-jboss-beans.xml" was written. It contains the previous Cache
configuration, deployed in the new way.
But there is problem with Hibernate integration. For Cache 3 there is no more a service provider
implemented. There is a new idea of Region Factory. This document explains it:
All in all, in Hibernate properties only this parameter is added instead of cache provider, for example:
But the above class looks for the Cache config file and builds its own instance. This is not what we
want, as we need access to cache from CacheAction in Admin. This Action connects to cache using JMX
and allows direct Cache manipulation, including lookup.
So we need a separately deployed Cache instance, like the way we did before.
It is impossible to expose to JMX the Cache instance itself, as we declare a bean as
which is an interface. Interfaces can not be MBeans, since they do not inherit from Object. In Cache
2 the Cache bean was CacheImpl which was a concrete class. In Cache 3 it is constructed by
CacheFactory and we have only the interface, which can not be exposed.
Then, there is CacheJmxWrapper class. It wraps the Cache and allows JMX exposition.
Since in Hibernate we do not create local instance of Cache, we need to access the deployed one
somehow. MultiplexedJBossCacheRegionFactory uses Cache Manager, but we do not use that approach. So
we are left with JndiSharedJBossCacheRegionFactory. It allows accessing Cache instance by JNDI. But
we have it only in JMX. So we need to expose it to JNDI.
In JBoss 5 documentation there is a chapter concerning Cache JNDI exposure, but it says that at the
time of writing of this document, this functionality is not yet implemented and they are working on it.
Standard <jndi-name> tag does not work - parser will not read it.
There is a solution explained in:
It gets the cache from JMX and exposes it to JNDI.
But Hibernate will not accept it, because the exposed interface is CacheJmxWrapperMBean and not
Cache itself! For Admin it is OK, but for Hibernate it's not.
So, we need to expose the Cache itself and no good way to do it has been found. JBoss developers
promise this functionality in the future, but it is not said when exactly.
Currently SharedJBossCacheRegionFactory is used and a local instance of Cache is created. It is not
exposed to JMX, so Admin does not have access to Cache. Starting Cache lookup throws an exception.
As this is not vital functionality, we can leave it for the time being. We have a brand new JBoss
Cache 3.1.0 for Hibernate and we can tune it for our needs. As soon as a fully functional version of
LAMS on JBoss 5 gets deployed and tuning process is started, Cache will be one of the targets.
As soon as JBoss developers make a way to easily register Cache in JNDI available, our Cache access
will be reimplement (easy, almost everything is written). We can also skip JMX exposure then, as
most probably there is a way to get Cache from JNDI in Admin.
6. SPRING, PATHS AND WILDCARDS
In several spots in config files in LAMS, Ant-style patterns are used.
In each module in web.xml (and sometimes xdoclet/web-settings.xml, since it is the source for
building web.xml) "locatorFactorySelector" parameter was using wildcards. They were removed, because
in LAMS currently there is only one beanRefContext.xml file. If there will be a need for multiple
files of that type, wildcards can be reintroduced.
File beanRefContext.xml uses wildcards to collect Application Context files from the deployed tools.
Central Hibernate Session Factory uses wildcards to collect *.hbm.mxl files from the deployed tools.
JBoss 5 is using VFS (Virtual File System) which has bugs when it comes to Ant-style pattern
resolution. If a resolve path is inside JAR, content can not be read. These JIRAs are bound with
The last one states that there is a solution, but it will not work in our case. It was described at:
A person responsible for it confirmed that there is no good solution as for now, but a JIRA will be
created. Till that time, Application Context and *.hbm.xml files are
explicitly listed. This means that list of the deployed tools is fixed and any changes in
lams_build\build.xml file require also changes in beanRefContext.xml and commonContext.xml in
There also might be a a requirement to use a newer version of Spring. It will be rather easy, since
it is very backwards compatible and attempts to use version 2.5.5 were successful without any
During development, it was discovered that there are problems with flow of cookies between LAMS modules.
Part of the problems were bound with Single Sign On (SSO). It was needed to be enabled in
jbossweb.sar/server.xml. This allowed a single SSO cookie for all WARs.
Unfortunately, it seems that JSESSIONID cookie life cycle management changed in JBoss 5. We create
such a cookie ourselves to keep record of shared session ID (we want to have a single session for
all WARs). We set path to "/" and it worked before. In JBoss 5 this cross-context cookie is ignored
and a new one is created for every tool module. This way we can not access, for example, user data,
which was stored in the main session.
The fix is: use JSESSIONSSOID as an shared session indicator. This cookie is shared correctly, so a
value saved there can be used to learn shared session ID. This could have been the solution from the
very start, but there might be a reason not to do that (clustering issues?). As for now, it works
This issue will be analysed again and reconsidered.
Along with JBoss 5, Hibernate 3.3.1 is shipped. LAMS is using it now. This leads to several changes
in the code. Some of them are done, but there might be some more, not yet discovered.
It seems that Hibernate 3.3 is more strict that the previous version and it does not allow
comparison like <object>=<object_id> any more, and that is what we had in MessageSeqDAO in the Forum
tool. We might encounter similar things in other parts of the project, but fixing them will be easy.
Also, this JIRA is related to Hibernate upgrade:
The description says:
"While exporting Learning Designs, an XML file with serialized Activity classes is created. This
includes Hibernate Collections. For example Q&A contains Questions, which are stored as Hibernate
After upgrading to a new Hibernate version these XML files become unreadable as Collection classes
are different. They can not be deserialized anymore. We need to write a filter that will convert the
previously created XML files into readable versions for new Hibernate. This will most probably
involve extracting important data from a XML file and feeding it to a new XML structure, which is
compatible with the new Hibernate version.
Another approach which involves usage of old Hibernate classes for importing is also considered."
9. MISSING FORWARDS
There are some warnings from Struts - they say it can not find forward "success" in some cases,
but it does not break anything.
Current JBoss 5 configuration is quite disappointing when it comes to effectiveness. With LAMS deployed, it consumes about 400 MB. The start up process is also significantly slower. There is
still much work to be done.
It is now possible to deploy LAMS on JBoss 5, despite our custom config files and some tricky
dependencies. The migration did not bring expected benefits yet, but there is a large area of
changes which can be done to improve it.
Upgrading to new technologies allows more possibilities when it comes to solving issues and choosing
development paths in the future.