/*

  * 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.spi.model;

 import java.io.IOException;

 import java.io.InputStream;

 import java.net.URL;

 import org.apache.commons.classscan.ClassPathElement;

 import org.apache.commons.classscan.MetaClassPathElement;

 import org.apache.commons.classscan.MetaRegistry;

 import org.apache.commons.classscan.spi.ClassPathElementFactory;

 /**

  * The entry point for providers to find/create information about the ClassPath and the classes 

  * available from the ClassPath.

  */

 public interface SpiMetaRegistry extends MetaRegistry {

         /**

          * Create SpiMetaClassPathElement from a ClassPathElement.  The ClassPathElement has 

          * just the raw class path definition.  The SpiMetaClassPathElement contains the

          * metadata about classes available at the class path location.

          * 

          * @param pathElement A location in the class path

          * @return metadata for classes available at the given location 

          */

         SpiMetaClassPathElement createMetaClassPathElement(ClassPathElement pathElement);

         /**

          * Create SpiMetaClass from a MetaClassPathElement.  The MetaClassPathElement has 

          * the metadata about a base location.  The SpiMetaClass contains the

          * metadata about the class defined in a stream of bytes.

          * 

          * @param metaClassPathElement The location of a class

          * @param className The canonical name of the class

          * @param byteStream The byte stream containing the class definition.  This stream should be closed when finished.

          * @return The metadata about the class in the stream

          * 

          * @throws IOException

          */

         SpiMetaClass createMetaClass(MetaClassPathElement metaClassPathElement, String className, InputStream byteStream) throws IOException;

         /**

          * Create a ClassPathElement from a URL.  The registry will invoke {@link ClassPathElementFactory}(s)

          * sequentially until a factory returns a ClassPathElement for the given URL. 

          * 

          * @param url The base location of the class files

          * @return null, if no ClassPathElementFactory supports the given URL; otherwise, a ClassPathElement

          * @throws IOException

          */

         SpiClassPathElement createClassPathElement(URL url) throws IOException;

 }