001/*
002 * (C) Copyright 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
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 *
016 * Contributors:
017 *     Nuxeo - initial API and implementation
018 *
019 * $Id$
020 */
021
022package org.nuxeo.osgi;
023
024import java.io.File;
025import java.io.IOException;
026import java.net.URL;
027import java.util.Collection;
028import java.util.Enumeration;
029import java.util.jar.Manifest;
030
031/**
032 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
033 */
034public interface BundleFile {
035
036    /**
037     * Checks if this bundle is a JAR.
038     *
039     * @return true if the bundle is a JAR, false otherwise
040     */
041    boolean isJar();
042
043    /**
044     * Checks if this bundle is a directory (an exploded jar).
045     *
046     * @return true if the bundle is a directory, false otherwise
047     */
048    boolean isDirectory();
049
050    /**
051     * Gets this bundle symbolic name. If this bundle is an OSGi bundle, then the Bundle-SymbolicName manifest header is
052     * returned, otherwise null is returned.
053     *
054     * @return null if not an OSGi bundle, the OSGI bundle symbolic name otherwise
055     */
056    String getSymbolicName();
057
058    /**
059     * Gets the original file name of this bundle.
060     *
061     * @return the bundle file name
062     */
063    String getFileName();
064
065    /**
066     * Gets the original location of this bundle.
067     * <p>
068     * This is an URI string pointing to the original locatioon of the bundle.
069     *
070     * @return the location
071     */
072    String getLocation();
073
074    /**
075     * Gets the current location of the bundle as an URL (it may be different from the original location).
076     *
077     * @return the bundle url
078     */
079    URL getURL();
080
081    /**
082     * Gets the current location of the bundle as a file.
083     *
084     * @return the bundle file or null if the bundle is not a file
085     */
086    File getFile();
087
088    /**
089     * Gets the bundle manifest.
090     *
091     * @return the bundle manifest
092     */
093    Manifest getManifest();
094
095    /**
096     * Gets the entry at the given path in this bundle.
097     *
098     * @return the entry URL if any null otherwise
099     * @see org.osgi.framework.Bundle#getEntry(String)
100     */
101    URL getEntry(String name);
102
103    /**
104     * Returns an Enumeration of all the paths (<code>String</code> objects) to entries within the bundle whose longest
105     * sub-path matches the supplied path argument.
106     *
107     * @see org.osgi.framework.Bundle#getEntryPaths(String)
108     */
109    Enumeration<String> getEntryPaths(String path);
110
111    /**
112     * Finds entries in that bundle.
113     *
114     * @see org.osgi.framework.Bundle#findEntries(String, String, boolean)
115     */
116    Enumeration<URL> findEntries(String name, String pattern, boolean recurse);
117
118    /**
119     * Gets a list with nested bundles or null if none. The bundle Manifest headers Bundle-ClassPath and Class-Path will
120     * be used to retrieve nested jars.
121     *
122     * @param tmpDir optional temporary dir if the nested bundle should be extracted from an archive
123     */
124    Collection<BundleFile> getNestedBundles(File tmpDir) throws IOException;
125
126    /**
127     * Get a list with nested bundles or null if none. The bundle file will be scanned for nested JARs.
128     *
129     * @param tmpDir optional temporary dir if the nested bundle should be extracted from an archive
130     */
131    Collection<BundleFile> findNestedBundles(File tmpDir) throws IOException;
132
133    /**
134     * Close underlying file resources *
135     *
136     * @since 5.6
137     */
138    void close(OSGiAdapter osgi) throws IOException;
139
140}