Primary Sources of Info

Keys to Understanding JBoss, the Platform

  • Fall in love with JMX. This is the backbone of the platform.
  • Class loading is totally nutty in JBoss (compared to other J2EE servers); commit to learning it and save yourself some grief.
    • Most notably, there is a totally new concept of a "repository" introduced. Distinguish the difference between a ULR and a UCL and you've nailed it.

JBoss 4.2 is…

Component Version Description
JBoss Application Server 4.2.0
Hibernate 3.2.4 SP1
Hibernate Entity Manager 3.2.1
Hibernate Annotations 3.2.1
JBoss Seam 1.2.1
JBoss EJB3 RC10
JBoss Web (embedded Tomcat 6.0) 2.0.0
JBoss Cache 1.4.1 SP3
JGroups (for Caching and Clustering) 2.4.1 SP3
JBossMQ 4.2.0
JBoss Transactions 4.2.3 SP4
JBoss Web Services (JBossWS) 1.2.1
JBoss AOP 1.5.5
JBoss Remoting 2.2.0 SP4
JBoss Serialization 1.0.3

How Classloading Works in JBoss

  • Only the top-level module can specify the class loader scoping (i.e. EARs and SARs); contained modules (EJBs and WARs) attempts to affect class loader scoping are ignored.
  • Isolation between deployments (i.e. EARs)
    • the <loader-repository>(JMX Object Name for Class Loading Repository)</loader-repository> tag is used to name a solo class repo.
    • This is called creating a "class loading domain"
  • "PARENT_LAST" style
    • In the <loader-repository /> tag, include:
  • It is important to note that the "parent" here refers to the parent REPOSITORY. In otherwords, there is ALWAYS a single Unified Loader Repository (ULR). When you isolate a module by defining a new <loader-repository /> in that module, that new repository becomes a child of the ULR. The "java2ParentDelegation" flag, then indicates whether this child repo should have visibility into the ULR.
  • Note that java2ParentDelegation is OFF/false by default. In other words, scoped deployments are isolated from the ULR by default.
  • Careful! This isolation only refers to the "class cache"! A child repo inherits the package mapping of its parent. This means that the set of UCLs of the parent are still consulted when looking for a class.
    • It is accurate to think that a child ULR's package map is merged with its parent's package map. During this merge, the child's UCLs are listed FIRST, so they will "win" where a child's UCLs load classes for a Java package also loaded by one (or more) of the parent's UCLs.

The Theory

  • Each module (EAR, WAR, JAR) gets a Unified Class Loader (UCL).
  • If there are JARs present in server/default/lib, then a UCL is created for those libraries. This is the first UCL in the scheme.
  • But by default these class loaders point to the same Unified Loader Repository (repo).
    • A the repo is comprised of two elements: the class cache (i.e. loaded class definitions) and a package map.
      • the package map is a mapping from Java package name to UCL . This way, the repo can quicky figure out which UCL can satisfy a request for a class. Where two or more UCLs can load classes in the same package, the order in which the UCLs are added is the order in which they are searched.


  • Turn on logging
  • Use the JMX Console
    • Look for "JMImplementation:name=Default,service=LoaderRepository"
    • You can tell the order of UCLs in a ULR by inspecting the addedOrder attribute.


General Tips

General Resources

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License