1 //
2 // ========================================================================
3 // Copyright (c) 1995-2013 Mort Bay Consulting Pty. Ltd.
4 // ------------------------------------------------------------------------
5 // All rights reserved. This program and the accompanying materials
6 // are made available under the terms of the Eclipse Public License v1.0
7 // and Apache License v2.0 which accompanies this distribution.
8 //
9 // The Eclipse Public License is available at
10 // http://www.eclipse.org/legal/epl-v10.html
11 //
12 // The Apache License v2.0 is available at
13 // http://www.opensource.org/licenses/apache2.0.php
14 //
15 // You may elect to redistribute this code under either of these licenses.
16 // ========================================================================
17 //
18
19 package org.eclipse.jetty.osgi.boot.utils;
20
21 import java.io.File;
22 import java.net.URL;
23 import java.util.Enumeration;
24
25 import org.eclipse.jetty.osgi.boot.utils.internal.DefaultFileLocatorHelper;
26 import org.osgi.framework.Bundle;
27
28 /**
29 * From a bundle to its location on the filesystem. Assumes the bundle is not a
30 * jar.
31 *
32 * @author hmalphettes
33 */
34 public interface BundleFileLocatorHelper
35 {
36
37 /** The name of the custom implementation for this interface in a fragment. */
38 public static final String CLASS_NAME = "org.eclipse.jetty.osgi.boot.utils.FileLocatorHelperImpl";
39
40 /** The default instance supports felix and equinox */
41 public static BundleFileLocatorHelper DEFAULT = new DefaultFileLocatorHelper();
42
43 /**
44 * Works with equinox, felix, nuxeo and probably more. Not exactly in the
45 * spirit of OSGi but quite necessary to support self-contained webapps and
46 * other situations.
47 * <p>
48 * Currently only works with bundles that are not jar.
49 * </p>
50 *
51 * @param bundle The bundle
52 * @return Its installation location as a file.
53 * @throws Exception
54 */
55 public File getBundleInstallLocation(Bundle bundle) throws Exception;
56
57 /**
58 * Locate a file inside a bundle.
59 *
60 * @param bundle
61 * @param path
62 * @return file object
63 * @throws Exception
64 */
65 public File getFileInBundle(Bundle bundle, String path) throws Exception;
66
67 /**
68 * If the bundle is a jar, returns the jar. If the bundle is a folder, look
69 * inside it and search for jars that it returns.
70 * <p>
71 * Good enough for our purpose (TldLocationsCache when it scans for tld
72 * files inside jars alone. In fact we only support the second situation for
73 * development purpose where the bundle was imported in pde and the classes
74 * kept in a jar.
75 * </p>
76 *
77 * @param bundle
78 * @return The jar(s) file that is either the bundle itself, either the jars
79 * embedded inside it.
80 */
81 public File[] locateJarsInsideBundle(Bundle bundle) throws Exception;
82
83 /**
84 * Helper method equivalent to Bundle#getEntry(String entryPath) except that
85 * it searches for entries in the fragments by using the findEntries method.
86 *
87 * @param bundle
88 * @param entryPath
89 * @return null or all the entries found for that path.
90 */
91 public Enumeration<URL> findEntries(Bundle bundle, String entryPath);
92
93 /**
94 * Only useful for equinox: on felix we get the file:// or jar:// url
95 * already. Other OSGi implementations have not been tested
96 * <p>
97 * Get a URL to the bundle entry that uses a common protocol (i.e. file:
98 * jar: or http: etc.).
99 * </p>
100 *
101 * @return a URL to the bundle entry that uses a common protocol
102 */
103 public URL getLocalURL(URL url);
104
105 /**
106 * Only useful for equinox: on felix we get the file:// url already. Other
107 * OSGi implementations have not been tested
108 * <p>
109 * Get a URL to the content of the bundle entry that uses the file:
110 * protocol. The content of the bundle entry may be downloaded or extracted
111 * to the local file system in order to create a file: URL.
112 *
113 * @return a URL to the content of the bundle entry that uses the file:
114 * protocol
115 * </p>
116 */
117 public URL getFileURL(URL url);
118
119 }