BOF jars and class loading

BOF uses a custom class loader system which relies very much on correct packaging of jars in the module definition.

Jars must be categorized in Composer as interface jars, implementation jars or mixed jars (don’t use this category). Interface jars are loaded into a common class loader, which makes its classes visible to all other modules (but nobody else). Implementation and mixed jars are always loaded into module-specific class loaders and that class loader is a “parent last” class loader – that is, it prefers its own classes to those in any other class loader. If you miscategorize a jar, or put a class in an inappropriate jar your module won’t work. Fortunately, it’s easy to explain what belongs where.

Typically, most code belongs in one or more implementation jars, in particular the primary class. This will be hidden from the rest of the world. This has the advantage that you cannot screw up anybody else by including classes in implementation jars.

That leaves interface jars – what goes in them? Not all interfaces need go into an interface jar – but all public interfaces should. Also any exceptions or factories that appear in your module’s public interface. You should be careful, in exceptions, to avoid transitively exposing other classes. Interface jars are loaded into a common (per DFC instance) class loader that is visible to every module, but not to your client code. These same interface jars must be packaged with any true client code that accesses your module. Note that not all modules require a public interface at all – for example a TBO might just override a method from DfSysObject and not have an interface at all.

So, you must get into the habit of packaging your code into interface and implementation jars. You might also want to use java libraries. These are just collections of jars that can be shared across modules. Each java library can be flagged as sandboxed or not. Jars from a sandboxed java library are loaded into the module-specific class loaders whereas jars from a non-sandboxed java library are loaded into the same class loader as the interface jars (see BOF class loaders).

In order to facilitate the packaging of classes into interface and implementation jars we recommend that you use separate source directories. The alternative of using ant scripts to do the packaging on a class by class basis is fraught with risk and difficult to diagnose errors.