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.spi.model;
015    
016    import java.io.IOException;
017    import java.io.InputStream;
018    import java.net.URL;
019    
020    import org.apache.commons.classscan.ClassPathElement;
021    import org.apache.commons.classscan.MetaClassPathElement;
022    import org.apache.commons.classscan.MetaRegistry;
023    import org.apache.commons.classscan.spi.ClassPathElementFactory;
024    
025    /**
026     * The entry point for providers to find/create information about the ClassPath and the classes 
027     * available from the ClassPath.
028     */
029    public interface SpiMetaRegistry extends MetaRegistry {
030    
031            /**
032             * Create SpiMetaClassPathElement from a ClassPathElement.  The ClassPathElement has 
033             * just the raw class path definition.  The SpiMetaClassPathElement contains the
034             * metadata about classes available at the class path location.
035             * 
036             * @param pathElement A location in the class path
037             * @return metadata for classes available at the given location 
038             */
039            SpiMetaClassPathElement createMetaClassPathElement(ClassPathElement pathElement);
040    
041            /**
042             * Create SpiMetaClass from a MetaClassPathElement.  The MetaClassPathElement has 
043             * the metadata about a base location.  The SpiMetaClass contains the
044             * metadata about the class defined in a stream of bytes.
045             * 
046             * @param metaClassPathElement The location of a class
047             * @param className The canonical name of the class
048             * @param byteStream The byte stream containing the class definition.  This stream should be closed when finished.
049             * @return The metadata about the class in the stream
050             * 
051             * @throws IOException
052             */
053            SpiMetaClass createMetaClass(MetaClassPathElement metaClassPathElement, String className, InputStream byteStream) throws IOException;
054    
055            /**
056             * Create a ClassPathElement from a URL.  The registry will invoke {@link ClassPathElementFactory}(s)
057             * sequentially until a factory returns a ClassPathElement for the given URL. 
058             * 
059             * @param url The base location of the class files
060             * @return null, if no ClassPathElementFactory supports the given URL; otherwise, a ClassPathElement
061             * @throws IOException
062             */
063            SpiClassPathElement createClassPathElement(URL url) throws IOException;
064    }