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