modulemanager.java

OSGI 的 源码实现,采用JAVA书写

/*
 * ModuleLoader - A generic, policy-driven class loader.
 * Copyright (c) 2004, Richard S. Hall
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 *   * Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *   * Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in
 *     the documentation and/or other materials provided with the
 *     distribution.
 *   * Neither the name of the ungoverned.org nor the names of its
 *     contributors may be used to endorse or promote products derived
 *     from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * Contact: Richard S. Hall ([e-mail])
 * Contributor(s):
 *
**/
package org.ungoverned.moduleloader;

import java.util.*;

/**
 * <p>
 * The <tt>ModuleManager</tt> class is the core facility for defining a
 * re-usable, policy-driven class loader for applications that require
 * flexible class loading mechanisms. The <tt>ModuleManager</tt> is not
 * class loader itself, but it supports the concept of a
 * <a href="Module.html"><tt>Module</tt></a>,
 * which is a unit of organization for application classes and resources.
 * The <tt>ModuleManager</tt> has only a handful of methods that allow
 * an application to add, remove, reset, and query modules; the intent
 * is to place as few assumptions in the <tt>ModuleManager</tt> as possible.
 * </p>
 * <p>
 * The idea is simple, allow the application to map itself into modules
 * however it sees fit and let the <tt>ModuleManager</tt> assume the
 * responsibility of managing the modules and loading classes and resources
 * from them as necessary via <a href="ModuleClassLoader.html"><tt>ModuleClassLoader</tt></a>s
 * that are associated with each module. In order to achieve this goal, though, the
 * <tt>ModuleManager</tt> must make at least one assumption on behalf of
 * the application. This assumption is that the loading of classes and resources
 * from the available modules must happen using a search algorithm
 * that is particular to the application itself. As a result of this assumption,
 * the <tt>ModuleManager</tt> requires that the application provide a concrete
 * implementation of the <a href="SearchPolicy.html"><tt>SearchPolicy</tt></a>
 * interface.
 * </p>
 * <p>
 * The search policy allows the <tt>ModuleLoader</tt> to let applications inject
 * their own particular class loading policies, without dictating strict or
 * constraining base assumptions. Of course, it is likely that many applications
 * will use the same or very similar search policies. Because of this, another
 * goal of the <tt>ModuleLoader</tt> approach is to foster a common library of
 * search policies that applications are free to use or customize as they see
 * fit. These common search policies are analagous to patterns, where each search
 * policy is viewable as a <i>class loading pattern</i>. Some initial search
 * policies included with the <tt>ModuleLoader</tt> are
 * <a href="search/ExhaustiveSearchPolicy.html"><tt>ExhaustiveSearchPolicy</tt></a>,
 * <a href="search/SelfContainedSearchPolicy.html"><tt>SelfContainedSearchPolicy</tt></a>, and
 * <a href="search/ImportSearchPolicy.html"><tt>ImportSearchPolicy</tt></a>.
 * </p>
 * <p>
 * Due to the fact that class loaders are tied to security and resource loading,
 * the search policy alone is not sufficient for the <tt>ModuleLoader</tt> to
 * perform its function. To fulfill these other purposes, the <tt>ModuleLoader</tt>
 * introduces another policy interface, called the <a href="URLPolicy.html"><tt>URLPolicy</tt></a>.
 * The <tt>URLPolicy</tt> allows the application to inject its particular policy
 * for to purposes:
 * </p>
 * <ol>
 *   <li>Creating the <tt>URL</tt> associated with loading a resource, such as
 *       the <tt>URL</tt> returned from a call to <tt>Class.getResource()</tt>.
 *   </li>
 *   <li>Creating the <tt>URL</tt> that will be associated with a class's
 *       <tt>CodeSource</tt> when defining the class for purposes of security
 *       and assigning permissions.
 *   </li>
 * </ol>
 * <p>
 * The <tt>ModuleLoader</tt> defines a default <tt>URLPolicy</tt>, called
 * <a href="DefaultURLPolicy.html"><tt>DefaultURLPolicy</tt></a>, that provides
 * a simple <tt>URLStreamHandler</tt> for accessing resources inside of modules
 * and that returns <tt>null</tt> for the <tt>CodeSource</tt> <tt>URL</tt>.
 * Applications only need to supply their own <tt>URLPolicy</tt> if the default
 * one does not provide the appropriate behavior.
 * </p>
 * <p>
 * It is possible for an application to create multiple instances of the
 * <tt>ModuleManager</tt> within a single JVM, but it is not possible to
 * share modules across multiple <tt>ModuleManager</tt>s. A given <tt>ModuleManager</tt>
 * can only have one <tt>SelectionPolicy</tt> and one <tt>URLPolicy</tt>.
 * </p>
 * @see org.ungoverned.moduleloader.Module
 * @see org.ungoverned.moduleloader.ModuleClassLoader
 * @see org.ungoverned.moduleloader.SearchPolicy
 * @see org.ungoverned.moduleloader.URLPolicy
 * @see org.ungoverned.moduleloader.DefaultURLPolicy
**/
public class ModuleManager
{
    private List m_moduleList = new ArrayList();
    private Map m_moduleMap = new HashMap();
    private SearchPolicy m_searchPolicy = null;
    private URLPolicy m_urlPolicy = null;
    private ModuleListener[] m_listeners = null;
    private static final ModuleListener[] m_noListeners = new ModuleListener[0];

    /**
     * <p>
     * Constructs a <tt>ModuleManager</tt> instance using the specified
     * search policy and the default <tt>URL</tt> policy.
     * </p>
     * @param searchPolicy the search policy that the instance should use.
     * @see org.ungoverned.moduleloader.SearchPolicy
    **/
    public ModuleManager(SearchPolicy searchPolicy)
    {
        this(searchPolicy, null);
    }

    /**
     * <p>
     * Constructs a <tt>ModuleManager</tt> instance using the specified
     * search policy and the specified <tt>URL</tt> policy.
     * </p>
     * @param searchPolicy the search policy that the instance should use.
     * @param urlPolicy the <tt>URL</tt> policy that the instance should use.
     * @see org.ungoverned.moduleloader.SearchPolicy
     * @see org.ungoverned.moduleloader.URLPolicy
    **/
    public ModuleManager(SearchPolicy searchPolicy, URLPolicy urlPolicy)
    {
        m_listeners = m_noListeners;
        m_searchPolicy = searchPolicy;
        m_searchPolicy.setModuleManager(this);

        if (urlPolicy == null)
        {
            m_urlPolicy = new DefaultURLPolicy();
        }
        else
        {
            m_urlPolicy = urlPolicy;
        }
    }

    /**
     * <p>
     * Returns the <tt>URL</tt> policy used by this instance.
     * </p>
     * @return the <tt>URL</tt> policy used by this instance.
     * @see org.ungoverned.moduleloader.URLPolicy
    **/
    public URLPolicy getURLPolicy()
    {
        return m_urlPolicy;
    }

    /**
     * <p>
     * Returns the search policy used by this instance.
     * </p>
     * @return the search policy used by this instance.
     * @see org.ungoverned.moduleloader.SearchPolicy
    **/
    public SearchPolicy getSearchPolicy()
    {
        return m_searchPolicy;
    }

    /**
     * <p>
     * Returns an array of all modules being managed by the
     * <tt>ModuleManager</tt> instance. The array contains a snapshot of
     * all modules in the <tt>ModuleManager</tt> at the time when this
     * method was called.
     * </p>
     * @return an array of all modules being managed by the <tt>ModuleManager</tt>
     *         instance.
     * @see org.ungoverned.moduleloader.Module
    **/
    public synchronized Module[] getModules()
    {
        Module[] modules = new Module[m_moduleList.size()];
        return (Module[]) m_moduleList.toArray(modules);
    }

    /**
     * <p>
     * Returns a module associated with the specified identifier.
     * </p>
     * @param id the identifier for the module to be retrieved.
     * @return the module associated with the identifier or <tt>null</tt>.
     * @see org.ungoverned.moduleloader.Module
    **/
    public synchronized Module getModule(String id)
    {
        return (Module) m_moduleMap.get(id);
    }

    /**
     * <p>
     * Adds a module to the module manager. The module will have the specified
     * unique identifier, with the associated attributes, resource sources, and
     * library sources. If the identifier is not unique, then an exception is
     * thrown.
     * </p>
     * @param id the unique identifier of the new module.
     * @param attributes an array of key-value attribute pairs to
     *        associate with the module.
     * @param resSources an array of <tt>ResourceSource</tt>s to associate
     *        with the module.
     * @param libSources an array of <tt>LibrarySource</tt>s to associate
     *        with the module.
     * @return the newly created module.
     * @throws java.lang.IllegalArgumentException if the module identifier
     *         is not unique.
     * @see org.ungoverned.moduleloader.Module
     * @see org.ungoverned.moduleloader.ResourceSource
     * @see org.ungoverned.moduleloader.LibrarySource
    **/
    public Module addModule(String id, Object[][] attributes,
        ResourceSource[] resSources, LibrarySource[] libSources)
    {
        Module module = null;

        // Use a synchronized block instead of synchronizing the
        // method, so we can fire our event outside of the block.
        synchronized (this)
        {
            if (m_moduleMap.get(id) == null)
            {
                module = new Module(this, id, attributes, resSources, libSources);
                m_moduleList.add(module);
                m_moduleMap.put(id, module);
            }
            else
            {
                throw new IllegalArgumentException("Module ID must be unique.");
            }
        }

        // Fire event here instead of inside synchronized block.
        fireModuleAdded(module);

        return module;
    }

    /**
     * <p>