001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *   http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    package org.apache.felix.moduleloader;
020    
021    import java.io.IOException;
022    import java.io.InputStream;
023    import java.util.Enumeration;
024    
025    public interface IContent
026    {
027        /**
028         * <p>
029         * This method must be called when the content is no longer needed so
030         * that any resourses being used (e.g., open files) can be closed. Once
031         * this method is called, the content is no longer usable. If the content
032         * is already closed, then calls on this method should have no effect.
033         * </p>
034        **/
035        void close();
036    
037        /**
038         * <p>
039         * This method determines if the specified named entry is contained in
040         * the associated content. The entry name is a relative path with '/'
041         * separators.
042         * </p>
043         * @param name The name of the entry to find.
044         * @return <tt>true</tt> if a corresponding entry was found, <tt>false</tt>
045         *         otherwise.
046        **/
047        boolean hasEntry(String name);
048    
049        /**
050         * <p>
051         * Returns an enumeration of entry names as <tt>String</tt> objects.
052         * An entry name is a path constructed with '/' as path element
053         * separators and is relative to the root of the content. Entry names
054         * for entries that represent directories should end with the '/'
055         * character.
056         * </p>
057         * @returns An enumeration of entry names or <tt>null</tt>.
058        **/
059        Enumeration getEntries();
060    
061        /**
062         * <p>
063         * This method returns the named entry as an array of bytes.
064         * </p>
065         * @param name The name of the entry to retrieve as a byte array.
066         * @return An array of bytes if the corresponding entry was found, <tt>null</tt>
067         *         otherwise.
068        **/
069        byte[] getEntryAsBytes(String name);
070    
071        /**
072         * <p>
073         * This method returns the named entry as an input stream.
074         * </p>
075         * @param name The name of the entry to retrieve as an input stream.
076         * @return An input stream if the corresponding entry was found, <tt>null</tt>
077         *         otherwise.
078         * @throws <tt>java.io.IOException</tt> if any error occurs.
079        **/
080        InputStream getEntryAsStream(String name) throws IOException;
081    
082        /**
083         * <p>
084         * This method returns the named entry as an <tt>IContent</tt> Typically,
085         * this method only makes sense for entries that correspond to some form
086         * of aggregated resource (e.g., an embedded JAR file or directory), but
087         * implementations are free to interpret this however makes sense. This method
088         * should return a new <tt>IContent</tt> instance for every invocation and
089         * the caller is responsible for opening and closing the returned content
090         * object.
091         * </p>
092         * @param name The name of the entry to retrieve as an <tt>IContent</tt>.
093         * @return An <tt>IContent</tt> instance if a corresponding entry was found,
094         *         <tt>null</tt> otherwise.
095        **/
096        IContent getEntryAsContent(String name);
097    
098        /**
099         * <p>
100         * This method returns the named entry as a file in the file system for
101         * use as a native library. It may not be possible for all content
102         * implementations (e.g., memory only) to implement this method, in which
103         * case it is acceptable to return <tt>null</tt>. Since native libraries
104         * can only be associated with a single class loader, this method should
105         * return a unique file per request.
106         * </p>
107         * @param name The name of the entry to retrieve as a file.
108         * @return A string corresponding to the absolute path of the file if a
109         *         corresponding entry was found, <tt>null</tt> otherwise.
110        **/
111        String getEntryAsNativeLibrary(String name);
112    }