/*

  * Licensed under the Apache License, Version 2.0 (the "License");

  * you may not use this file except in compliance with the License.

  * You may obtain a copy of the License at

  *

  *      http://www.apache.org/licenses/LICENSE-2.0

  *

  * Unless required by applicable law or agreed to in writing, software

  * distributed under the License is distributed on an "AS IS" BASIS,

  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  * See the License for the specific language governing permissions and

  * limitations under the License.

  */

 package org.apache.commons.classscan;

 import java.util.Collection;

 import java.util.Iterator;

 import org.apache.commons.classscan.model.MetaClass;

 /**

  * Metadata about a ClassLoader. This includes the jars that a ClassLoader loads

  * from and the Classes that are potentially available.

  */

 public interface MetaClassLoader {

     /**

      * Get the metadata about the parent of the associated ClassLoader.

      * 

      * @return The parent metadata. This will be null if the associated

      *         ClassLoader is the primordial ClassLoader.

      */

     MetaClassLoader getParent();

     /**

      * Get metadata about the locations from which the associated ClassLoader

      * loads Classes.

      * 

      * @return A read-only set of code locations

      */

     Collection<? extends MetaClassPathElement> getClassLocations();

     /**

      * Get metadata about a class locations

      * 

      * @param codeLocation

      *            The location of a folder, jar, or compressed code

      */

     MetaClassPathElement getClassLocation(String codeLocation);

     /**

      * Get metadata about the Classes from which the associated ClassLoader can

      * load.

      * 

      * @return A read-only set of class information

      */

     Iterator<? extends MetaClass> getMetaClasses();

     /**

      * Get metadata about a particular Class. This method will return only

      * classes defined by the associated ClassLoader. Classes defined by a

      * parent ClassLoader can be found using {@link #findMetaClass}.

      * 

      * @param className

      *            The name of the Class

      * @return The metadata about the Class; or null, if the class was not

      *         available to the associated ClassLoader

      */

     MetaClass getMetaClass(String className);

     /**

      * Find metadata about a particular Class. This method will first search up

      * the associated parent ClassLoader chain.

      * 

      * @param className

      *            The name of the Class

      * @return The metadata about the Class; or null, if the class was not

      *         available to the associated ClassLoader not its parent chain

      */

     MetaClass findMetaClass(String className);

     /**

      * Find all the implementors of an interface class. This method will search

      * in the associated ClassLoader and all parents.

      * 

      * @param interfaceToFind

      *            The non-null MetaClass associated with the

      * 

      * @return All discovered implementors of the desired interface

      */

     Collection<? extends MetaClass> findAllImplementors(String interfaceToFind);

 }