Resolution:
Description:
============
Class scope on WebLogic 10.3.x Servers and why as-common.jar should not be placed on the JVM CLASSPATH (java.class.path) using the CLASSPATH environment variable / -cp JVM option.

Symptoms
========
When placing $AS_HOME/lib/as-common.jar on the CLASSPATH tol resolve referencing issues from classes within ECM.ear looking for classes in as-common.jar, the ClassNotFound errors are still thrown. This is because, while ECM.ear will now be able to see classes in $AS_HOME/lib/as-common.jar, classes in $AS_HOME/lib/as-common.jar will not be able to see needed classes in ECM.ear. The ClassNotFound error will still be thrown.  This is particularly so for com.tibco.mdm.infrastructure.cache.as.CacheInvokeSeeders. Further, placing the ECM classes (as in AllECMClasses.jar) on the CLASSPATH risks causing multiple versions of a class to be loaded onto the CLASSPATH, causing performance issues and additional errors.

Environment
============
All TIBCO MDM ECM.ear (and other ear file) versions and deployments on WebLogic 10.3.x servers.

Cause
=====
WebLogic uses a classloader hierarchy to structure and separate out classes into unique application contexts. The root in the classloader hierarchy is the bootstrap classloader, created and managed by the Java virtual machine (JVM) itself. This classloader loads the Java development kit (JDK) internal classes and java.* packages included in the JVM.

A second level classloader, the extensions classloader, is a child of the bootstrap classloader. The extensions classloader loads any JAR files placed in the extensions directory of the JDK. This is a convenient means to extending the JDK without adding entries to the classpath. However, anything in the extensions directory must be self-contained and can only refer to classes in the extensions directory or root classes.

The system classpath classloader extends the extensions classloader. The system classpath classloader loads the classes from the classpath of the JVM. Application-specific classloaders (including WebLogic Server classloaders) are children of the system classpath classloader.

The following application-specific classloaders are EJB-specific and Webapp-specific classloaders. Here is the order in which classes are loaded.

1. « System classpath loader » (« Bootstrap classloader »)
2. « WebLogic server classpath loader »
3. « Application classpath loader (« library-directory » then « APP-INF/lib »)
4. « EJB classpath loader »
5. « Webapp classpath » (WEB-INF/lib)

The important point to be aware of is that a class loaded by a higher level classloader cannot see a class from a class loader on the same or lower level. While a class loaded by the application classloader can reference a class loaded by the root classloader (for example, java.lang.String), a class loaded by the extensions classloader cannot see a class loaded by an application classloader.  Likewise, a class loaded by the application classloader cannot see a class loaded by another application classloader, nor a class loaded by one EJB be seen by a class loaded by another.

The importance of this for MDM becomes apparent when placing classes or class libraries on the CLASSPATH for a WebLogic JVM on which ECM.ear is running. While ECM.ear will be able to "see" a class in a class library provided on the CLASSPATH for the ECM.ear's WebLogic JVM, that class will not be able to "see" a subsequent class inside ECM.ear, causing a ClassNotFound exception. This occurs most often when users place $AS_HOME/lib/as-common.jar on the CLASSPATH, thinking this will resolve referencing issues from classes within ECM.ear looking for classes in as-common.jar.  While ECM.ear will now be able to see classes in $AS_HOME/lib/as-common.jar, classes in $AS_HOME/lib/as-common.jar will not be able to see needed classes in ECM.ear, so a ClassNotFound error will still be thrown. This is particularly so for com.tibco.mdm.infrastructure.cache.as.CacheInvokeSeeders.  Further, placing the ECM classes (as in AllECMClasses.jar) on the CLASSPATH risks causing multiple versions of a class to be loaded onto the CLASSPATH, causing performance issues and additional errors.

Resolution
=========

The correct response to providing a jar file needed by ECM.ear is to place that jar file inside the ECM.ear file (it it is not already there), so that it shares the same classloader context.

Class scope on WebLogic 10.3.x Servers and why as-common.jar should not be placed on the JVM CLASSPATH (java.class.path) using the CLASSPATH environment variable / -cp JVM option.