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 }