pluginregistry.java

java插件系统源码

/*****************************************************************************
 * Java Plug-in Framework (JPF)
 * Copyright (C) 2004-2007 Dmitry Olshansky
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 *****************************************************************************/
package org.java.plugin.registry;

import java.net.URL;
import java.util.Collection;
import java.util.Map;
import java.util.Set;

import org.java.plugin.ObjectFactory;
import org.java.plugin.PathResolver;
import org.java.plugin.PluginManager;
import org.java.plugin.util.ExtendedProperties;

/**
 * Root interface to get access to all meta-information about discovered
 * plug-ins. All objects accessible from the registry are immutable. You
 * can imagine registry as a read-only storage of full information about
 * discovered plug-ins. There is only one exception from this rule: internal
 * state of registry, plug-in descriptors and plug-in elements can be modified
 * indirectly by {@link #register(URL[]) registering} or
 * {@link #unregister(String[]) un-registering} plug-ins with this
 * registry. If your code is interested to be notified on all modifications
 * of plug-ins set, you can
 * {@link #registerListener(PluginRegistry.RegistryChangeListener) register}
 * an implementation of {@link PluginRegistry.RegistryChangeListener} with this
 * registry.
 * <p><i>Notes on unique ID's (UID's)</i></p>
 * <p>
 * There are two types of identifiers in the API: ID's and UID's. ID is an
 * identifier that is unique within set of elements of the same type. UID is
 * an identifier that unique globally within registry space. ID is usually
 * defined by developer in plug-in manifest. UID always combined automatically
 * from several other plug-in "parts". All plug-in elements have method
 * {@link org.java.plugin.registry.Identity#getId() getId()} that come from
 * basic {@link org.java.plugin.registry.Identity} interface, but not all
 * elements have UID - only those that inherits
 * {@link org.java.plugin.registry.UniqueIdentity}interface.
 * </p>
 * <p>There are several utility methods available in this interface that aimed
 * to build UID from different plug-in "parts" and also split UID to it's
 * original elements: {@link #makeUniqueId(String, Version)},
 * {@link #makeUniqueId(String, String)}, {@link #extractPluginId(String)},
 * {@link #extractId(String)} and {@link #extractVersion(String)}.
 * </p>
 * 
 * @see org.java.plugin.ObjectFactory#createRegistry()
 * 
 * @version $Id: PluginRegistry.java,v 1.8 2007/01/05 13:22:10 ddimon Exp $
 */
public interface PluginRegistry {
    /**
     * Registers plug-ins and plug-in fragments in this registry. Note that
     * this method not makes plug-ins available for activation
     * by any {@link PluginManager} instance as it is not aware of any manager.
     * Using this method just makes plug-in meta-data available for reading from
     * this registry.
     * <p>
     * If more than one version of the same plug-in or plug-in fragment given,
     * the only latest version should be registered. If some plug-in or plug-in
     * fragment already registered it should be ignored by this method. Client
     * application have to un-register such plug-ins first before registering
     * their newest versions.
     * @param manifests array of manifest locations
     * @return map where keys are URL's and values are registered plug-ins
     *         or plug-in fragments, URL's for unprocessed manifests are
     *         not included
     * @throws ManifestProcessingException if manifest processing error has
     *         occurred (optional behavior)
     * 
     * @see PluginManager#publishPlugins(PluginManager.PluginLocation[])
     */
    Map register(URL[] manifests) throws ManifestProcessingException;
    
    /**
     * Reads basic information from a plug-in or plug-in fragment manifest.
     * @param manifest manifest data URL
     * @return manifest info
     * @throws ManifestProcessingException if manifest data can't be read
     */
    ManifestInfo readManifestInfo(URL manifest)
            throws ManifestProcessingException;
    
    /**
     * Unregisters plug-ins and plug-in fragments with given ID's
     * (including depending plug-ins and plug-in fragments).
     * @param ids ID's of plug-ins and plug-in fragments to be
     *        unregistered
     * @return collection of UID's of actually unregistered plug-ins and plug-in
     *         fragments
     */
    Collection unregister(String[] ids);
    
    /**
     * Returns descriptor of plug-in with given ID.
     * <br>
     * If plug-in descriptor with given ID can't be found or such plug-in
     * exists but is damaged this method have to throw an
     * {@link IllegalArgumentException}. In other words, this method
     * shouldn't return <code>null</code>.
     * @param pluginId plug-id ID
     * @return plug-in descriptor
     */
    PluginDescriptor getPluginDescriptor(String pluginId);
    
    /**
     * Checks if plug-in exists and is in valid state. If this method
     * returns <code>true</code>, the method
     * {@link #getPluginDescriptor(String)} should always return valid plug-in
     * descriptor.
     * @param pluginId plug-in ID
     * @return <code>true</code> if plug-in exists and valid
     */
    boolean isPluginDescriptorAvailable(String pluginId);
    
    /**
     * Returns collection of descriptors of all plug-ins that was successfully
     * populated by this registry.
     * @return collection of {@link PluginDescriptor} objects
     */
    Collection getPluginDescriptors();

    /**
     * Looks for extension point. This method have throw an
     * {@link IllegalArgumentException} if requested extension point
     * can't be found or is in invalid state.
     * @param pluginId plug-in ID
     * @param pointId extension point ID
     * @return plug-in extension point
     * @see ExtensionPoint#isValid()
     */
    ExtensionPoint getExtensionPoint(String pluginId, String pointId);

    /**
     * Looks for extension point.
     * @param uniqueId extension point unique ID
     * @return plug-in extension point
     * @see #getExtensionPoint(String, String)
     */
    ExtensionPoint getExtensionPoint(String uniqueId);
    
    /**
     * Checks if extension point exists and is in valid state. If this method
     * returns <code>true</code>, the method
     * {@link #getExtensionPoint(String, String)} should always return valid
     * extension point.
     * @param pluginId plug-in ID
     * @param pointId extension point ID
     * @return <code>true</code> if extension point exists and valid
     */
    boolean isExtensionPointAvailable(String pluginId, String pointId);
    
    /**
     * Checks if extension point exists and is in valid state.
     * @param uniqueId extension point unique ID
     * @return <code>true</code> if extension point exists and valid
     * @see #isExtensionPointAvailable(String, String)
     */
    boolean isExtensionPointAvailable(String uniqueId);

    /**
     * Returns collection of descriptors of all plug-in fragments that was
     * successfully populated by this registry.
     * @return collection of {@link PluginFragment} objects
     */
    Collection getPluginFragments();
    
    /**
     * Utility method that recursively collects all plug-ins that depends on
     * the given plug-in.
     * @param descr descriptor of plug-in to collect dependencies for
     * @return collection of {@link PluginDescriptor plug-in descriptors}
     *         that depend on given plug-in
     */
    Collection getDependingPlugins(PluginDescriptor descr);

    /**
     * Performs integrity check of all registered plug-ins and generates result
     * as a collection of standard report items.
     * @param pathResolver optional path resolver
     * @return integrity check report
     */
    IntegrityCheckReport checkIntegrity(PathResolver pathResolver);
    
    /**
     * Performs integrity check of all registered plug-ins and generates result
     * as a collection of standard report items.
     * @param pathResolver optional path resolver
     * @param includeRegistrationReport if <code>true</code>, the plug-ins
     *                                  registration report will be included
     *                                  into resulting report
     * @return integrity check report
     */
    IntegrityCheckReport checkIntegrity(PathResolver pathResolver,
            boolean includeRegistrationReport);
    
    /**
     * @return plug-ins registration report for this registry
     */
    IntegrityCheckReport getRegistrationReport();
    
    /**
     * Constructs unique identifier for some plug-in element from it's ID.
     * @param pluginId plug-in ID
     * @param elementId element ID
     * @return unique ID
     */
    String makeUniqueId(String pluginId, String elementId);
    
    /**
     * Constructs unique identifier for plug-in with given ID.
     * @param pluginId plug-in ID
     * @param version plug-in version identifier
     * @return unique plug-in ID
     */
    String makeUniqueId(String pluginId, Version version);
    
    /**
     * Extracts plug-in ID from some unique identifier.
     * @param uniqueId unique ID
     * @return plug-in ID
     */
    String extractPluginId(String uniqueId);

    /**
     * Extracts plug-in element ID from some unique identifier.
     * @param uniqueId unique ID
     * @return element ID
     */
    String extractId(String uniqueId);
    
    /**
     * Extracts plug-in version identifier from some unique identifier
     * (plug-in or plug-in fragment).
     * @param uniqueId unique ID
     * @return plug-in version identifier
     */
    Version extractVersion(String uniqueId);
    
    /**
     * Registers plug-in registry change event listener. If given listener has
     * been registered before, this method should throw an
     * {@link IllegalArgumentException}.
     * @param listener new registry change event listener
     */
    void registerListener(RegistryChangeListener listener);
    
    /**
     * Unregisters registry change event listener. If given listener hasn't been
     * registered before, this method should throw an
     * {@link IllegalArgumentException}.
     * @param listener registered listener
     */
    void unregisterListener(RegistryChangeListener listener);
    
    /**
     * Configures this registry instance. Usually this method is called from
     * {@link ObjectFactory object factory} implementation.
     * @param config registry configuration data
     */
    void configure(ExtendedProperties config);
    
    /**
     * Plug-in registry changes callback interface.
     * @version $Id: PluginRegistry.java,v 1.8 2007/01/05 13:22:10 ddimon Exp $
     */
    interface RegistryChangeListener {
        /**
         * This method will be called by the framework when changes are made
         * on registry (via {@link PluginRegistry#register(URL[])} or
         * {@link PluginRegistry#unregister(String[])} methods).
         * @param data registry changes data
         */
        void registryChanged(RegistryChangeData data);
    }
    
    /**
     * Registry changes data holder interface.
     * @version $Id: PluginRegistry.java,v 1.8 2007/01/05 13:22:10 ddimon Exp $
     */
    interface RegistryChangeData {
        /**
         * @return collection of ID's of newly added plug-ins
         */
        Set addedPlugins();
        
        /**
         * @return collection of ID's of removed plug-ins
         */
        Set removedPlugins();
        
        /**
         * @return collection of ID's of changed plug-ins
         */
        Set modifiedPlugins();
        
        /**
         * @return collection of unique ID's of newly connected extensions
         */
        Set addedExtensions();
        
        /**
         * @param extensionPointUid unique ID of extension point to filter
         *                          result
         * @return collection of unique ID's of newly connected extensions
         */
        Set addedExtensions(String extensionPointUid);
        
        /**
         * @return collection of unique ID's of disconnected extensions
         */
        Set removedExtensions();
        
        /**
         * @param extensionPointUid unique ID of extension point to filter
         *                          result
         * @return collection of unique ID's of disconnected extensions
         */
        Set removedExtensions(String extensionPointUid);

        /**
         * @return collection of unique ID's of modified extensions
         */
        Set modifiedExtensions();

        /**
         * @param extensionPointUid unique ID of extension point to filter
         *                          result
         * @return collection of unique ID's of modified extensions
         */
        Set modifiedExtensions(String extensionPointUid);
    }
    
    /**
     * Manifest info holder interface.
     * 
     * @see PluginRegistry#readManifestInfo(URL)
     * @version $Id: PluginRegistry.java,v 1.8 2007/01/05 13:22:10 ddimon Exp $
     */
    interface ManifestInfo {
        /**
         * @return plug-in or plug-in fragment identifier
         */
        String getId();
        
        /**
         * @return plug-in or plug-in fragment version identifier
         */
        Version getVersion();
        
        /**
         * @return plug-in or plug-in fragment vendor
         */
        String getVendor();
        
        /**
         * @return plug-in identifier this, fragment contributes to or
         *         <code>null</code> if this info is for plug-in manifest
         */
        String getPluginId();
        
        /**
         * @return plug-in version identifier, this fragment contributes to or
         *         <code>null</code> if this info is for plug-in manifest
         */
        Version getPluginVersion();
        
        /**
         * @return plug-in version matching rule or <code>null</code> if this
         *         info is for plug-in manifest
         */
        String getMatchingRule();
    }
}