001    /**
002     *
003     * Copyright 2005 The Apache Software Foundation
004     *
005     *  Licensed under the Apache License, Version 2.0 (the "License");
006     *  you may not use this file except in compliance with the License.
007     *  You may obtain a copy of the License at
008     *
009     *     http://www.apache.org/licenses/LICENSE-2.0
010     *
011     *  Unless required by applicable law or agreed to in writing, software
012     *  distributed under the License is distributed on an "AS IS" BASIS,
013     *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     *  See the License for the specific language governing permissions and
015     *  limitations under the License.
016     */
017    package org.apache.geronimo.kernel.classloader;
018    
019    import java.net.URL;
020    import java.io.InputStream;
021    import java.io.IOException;
022    import java.util.jar.Manifest;
023    import java.util.jar.Attributes;
024    import java.security.cert.Certificate;
025    
026    /**
027     * This is a handle (a connection) to some resource, which may
028     * be a class, native library, text file, image, etc. Handles are returned
029     * by a ResourceFinder. A resource handle allows easy access to the resource data
030     * (using methods {@link #getInputStream} or {@link #getBytes}) as well as
031     * access resource metadata, such as attributes, certificates, etc.
032     * <p/>
033     * As soon as the handle is no longer in use, it should be explicitly
034     * {@link #close}d, similarly to I/O streams.
035     *
036     * @version $Rev: 410741 $ $Date: 2006-05-31 21:35:48 -0700 (Wed, 31 May 2006) $
037     */
038    public interface ResourceHandle {
039        /**
040         * Return the name of the resource. The name is a "/"-separated path
041         * name that identifies the resource.
042         */
043        String getName();
044    
045        /**
046         * Returns the URL of the resource.
047         */
048        URL getUrl();
049    
050        /**
051         * Does this resource refer to a directory.  Directory resources are commly used
052         * as the basis for a URL in client application.  A directory resource has 0 bytes for it's content. 
053         */
054        boolean isDirectory();
055    
056        /**
057         * Returns the CodeSource URL for the class or resource.
058         */
059        URL getCodeSourceUrl();
060    
061        /**
062         * Returns and InputStream for reading this resource data.
063         */
064        InputStream getInputStream() throws IOException;
065    
066        /**
067         * Returns the length of this resource data, or -1 if unknown.
068         */
069        int getContentLength();
070    
071        /**
072         * Returns this resource data as an array of bytes.
073         */
074        byte[] getBytes() throws IOException;
075    
076        /**
077         * Returns the Manifest of the JAR file from which this resource
078         * was loaded, or null if none.
079         */
080        Manifest getManifest() throws IOException;
081    
082        /**
083         * Return the Certificates of the resource, or null if none.
084         */
085        Certificate[] getCertificates();
086    
087        /**
088         * Return the Attributes of the resource, or null if none.
089         */
090        Attributes getAttributes() throws IOException;
091    
092        /**
093         * Closes a connection to the resource indentified by this handle. Releases
094         * any I/O objects associated with the handle.
095         */
096        void close();
097    }