001    /*
002     * Licensed under the Apache License, Version 2.0 (the "License");
003     * you may not use this file except in compliance with the License.
004     * You may obtain a copy of the License at
005     *
006     *      http://www.apache.org/licenses/LICENSE-2.0
007     *
008     * Unless required by applicable law or agreed to in writing, software
009     * distributed under the License is distributed on an "AS IS" BASIS,
010     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011     * See the License for the specific language governing permissions and
012     * limitations under the License.
013     */
014    package org.apache.commons.classscan;
015    
016    import java.util.Collection;
017    import java.util.Iterator;
018    
019    import org.apache.commons.classscan.model.MetaClass;
020    
021    /**
022     * Metadata about a ClassLoader. This includes the jars that a ClassLoader loads
023     * from and the Classes that are potentially available.
024     */
025    public interface MetaClassLoader {
026        /**
027         * Get the metadata about the parent of the associated ClassLoader.
028         * 
029         * @return The parent metadata. This will be null if the associated
030         *         ClassLoader is the primordial ClassLoader.
031         */
032        MetaClassLoader getParent();
033    
034        /**
035         * Get metadata about the locations from which the associated ClassLoader
036         * loads Classes.
037         * 
038         * @return A read-only set of code locations
039         */
040        Collection<? extends MetaClassPathElement> getClassLocations();
041    
042        /**
043         * Get metadata about a class locations
044         * 
045         * @param codeLocation
046         *            The location of a folder, jar, or compressed code
047         */
048        MetaClassPathElement getClassLocation(String codeLocation);
049    
050        /**
051         * Get metadata about the Classes from which the associated ClassLoader can
052         * load.
053         * 
054         * @return A read-only set of class information
055         */
056        Iterator<? extends MetaClass> getMetaClasses();
057    
058        /**
059         * Get metadata about a particular Class. This method will return only
060         * classes defined by the associated ClassLoader. Classes defined by a
061         * parent ClassLoader can be found using {@link #findMetaClass}.
062         * 
063         * @param className
064         *            The name of the Class
065         * @return The metadata about the Class; or null, if the class was not
066         *         available to the associated ClassLoader
067         */
068        MetaClass getMetaClass(String className);
069    
070        /**
071         * Find metadata about a particular Class. This method will first search up
072         * the associated parent ClassLoader chain.
073         * 
074         * @param className
075         *            The name of the Class
076         * @return The metadata about the Class; or null, if the class was not
077         *         available to the associated ClassLoader not its parent chain
078         */
079        MetaClass findMetaClass(String className);
080    
081        /**
082         * Find all the implementors of an interface class. This method will search
083         * in the associated ClassLoader and all parents.
084         * 
085         * @param interfaceToFind
086         *            The non-null MetaClass associated with the
087         * 
088         * @return All discovered implementors of the desired interface
089         */
090        Collection<? extends MetaClass> findAllImplementors(String interfaceToFind);
091    }