<?xml version="1.0" encoding="UTF-8"?>
<chapter id="classloading">
   <title>Classloading</title>

   <para>This chapter describes the class loading abilities of the Fungal kernel.</para>

   <section id="classloaders">
     <title>Class loading architecture</title>

      <para>Fungal features a 3-tier classloader architecture:</para>

      <orderedlist>
        <listitem>
          <para>Application classloader (AppCL).</para>
          <para>Top-level classloader that loads the Fungal kernel. This class loader is
            controlled by the application that uses the kernel.</para>
        </listitem>
        <listitem>
          <para>Kernel classloader (KernelCL).</para>
          <para>A class loader with AppCL as its parent which loads
            all libraries used by the kernel.</para>
        </listitem>
        <listitem>
          <para>Deployment classloader (DCL).</para>
          <para>Each deployment can run in its own classloader with KernelCL as its parent.</para>
        </listitem>
      </orderedlist>

      <para>The application using the Fungal kernel chooses what should be located in the
        application classloader (AppCL). Typically the Fungal kernel is bundled in this
        classloader.</para>

      <para>The kernel classloader model is chosen using the <code>KernelConfiguration.classLoader()
        </code> method which takes a classloader type. This layer is typically using the
        <code>TYPE_PARENT_FIRST</code> type for a "flat" classloader model for its libraries or
        the <code>TYPE_EXPORT</code> type for an environment where multiple versions of the same
        library are deployed in the global scope.</para>

      <para>The default configuration for the kernel is <code>TYPE_PARENT_FIRST</code> as specified
        in <code>KernelConfiguration.classLoader()</code>.</para>

      <para>The deployment classloader is specific to the application and can involve more than
        one layer of classloaders. Typically this layer uses <code>TYPE_PARENT_FIRST</code> for a
        configuration where the environment's libraries have precedence or <code>TYPE_PARENT_LAST</code>
        if libraries bundled with the application has precedence.</para>

   </section>

   <section id="fungal_classloading_types">
     <title>Class loader types</title>
     
     <para>The Fungal kernel class loader mechanisms are controlled through
       the</para>
     
     <programlisting>
com.github.fungal.api.classloading.ClassLoaderFactory
     </programlisting>
     
     <para>class which creates class loaders based on the parameters given.</para>
     
     <para>The following types are supported:</para>
     
     <itemizedlist>
       <listitem>
         <para><code>TYPE_PARENT_FIRST</code></para>
         <para>The parent class loader is checked before the child class loader.</para>
       </listitem>
       <listitem>
         <para><code>TYPE_PARENT_LAST</code></para>
         <para>The parent class loader is after the child class loader.</para>
       </listitem>
       <listitem>
         <para><code>TYPE_EXPORT</code></para>
         <para>This class loader type can be compared to the OSGi class loader model
           where each Java library that contains OSGi manifest information will be isolated.
           This allows multiple versions of the same library to be active at the same time and
           will allow deployment to declare their dependencies on a specific library version.</para>
         <para>Note, that this type is not a valid OSGi class loader model implementation, but
           only borrows some of the ideas in that model.</para>
       </listitem>
     </itemizedlist>
     
     <para>All class loader types are implemented as a <code>com.github.fungal.api.classloading.KernelClassLoader</code>
       which extends the <code>java.net.URLClassLoader</code> class.</para>

   </section>
</chapter>
