<?xml version="1.0"?>
<document>
    <properties>
        <title>Jackrabbit Extension Framework - Extension Classes</title>
    </properties>
    <body>
        <section name="Extension Classes">
            <p>
                The extension declaration may also contain the (fully
                qualified) name of a class implementing the extension.
                Besides finding extension descriptions the Jackrabbit Extension
                Framework is also able to create instances of extensions
                and prime them with the extension descriptor, which
                defined how to instantiate the extension.
            </p>
            <p>
                This page contains information on how class implementing
                the extensions are loaded how the extensions are then
                instantiated.
            </p>

            <subsection name="Loading">
                <p>
                    All access to the Jackrabbit Extensions Framework goes
                    through an instance of the
                    <code>ExtensionManager</code>
                    class, which is created using a
                    <code>Session</code>
                    and a class loader. While the session is used to
                    access the repository and also confines access to a
                    certain workspace, the class loader provided is
                    actually the basis for loading extension classes.
                </p>
                <p>
                    As has been noted in the
                    <a href="index.html#Introduction">Introduction</a>
                    one of the advantages of the Jackrabbit Extension Framework
                    is its ability to load extension classes from the
                    repository, an extension may be packaged complete
                    with the descriptor, optional configuration and the
                    Java classes and/or archives implementing the
                    extensions. To be able to load the classes from the
                    repository, the Jackrabbit Extension Framework uses
                    instances of the <code>RepositoryClassLoader</code>
                    provided by the <code>classloader</code> project.
                </p>
                <p>
                    The extension manager creates a separate instance of
                    the
                    <code>RepositoryClassLoader</code>
                    for each extension type accessed. The class path
                    defined by an extension is added to that class
                    loader before trying to load the class through that
                    class loader. The class loader created by the
                    extension manager is linked into the system class
                    loader hierarchy by using the application provided
                    class loader given to the constructor of the
                    extension manager as its parent class loader.
                </p>
                <p>
                    Please be aware of an issue raising from the fact
                    that class may be loaded through a class loader
                    which is a child of the application's class loader:
                    While extensions have access to all the classes
                    provided by the repository class loader as well as
                    the application class loader and all its parents,
                    the application has no access to the classes loaded
                    through the repository class loader. This is easily
                    fixed by having the extensions implement interfaces
                    which are loaded through the application class
                    loader and to which the extension instances loaded
                    through the extension manager may be cast.
                </p>
            </subsection>

            <subsection name="Instantiation">
                <p>
                    The extension declaration may also contain the
                    (fully qualified) name of a class implementing the
                    extension. If so, the Jackrabbit Extension Framework
                    provides support functionality to load and
                    instantiate the respective class using either of two
                    constructors:
                </p>
                <ul>
                    <li>
                        If the class has a (public) constructor taking
                        an object of type
                        <code>
                            org.apache.jackrabbit.extension.ExtensionDescriptor
                        </code>
                        this constructor is used to instanti-ate the
                        extension instance.
                    </li>
                    <li>
                        Otherwise if the class has a (public) default
                        constructor this constructor is used to
                        in-stantiated the extension interface.
                    </li>
                    <li>
                        Otherwise the extension cannot be instantiated.
                    </li>
                </ul>
                <p>
                    If the extension cannot be instantiated through the
                    constructor taking the
                    <code>ExtensionDescriptor</code>
                    the application is responsible to provide the
                    relevant information to the extension instance if
                    required.
                </p>
            </subsection>
        </section>
    </body>
</document>