1 //
2 // ========================================================================
3 // Copyright (c) 1995-2016 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.io.IOException;
23 import java.net.URL;
24 import java.util.Enumeration;
25
26 import org.eclipse.jetty.osgi.boot.utils.internal.DefaultFileLocatorHelper;
27 import org.osgi.framework.Bundle;
28
29 /**
30 * BundleFileLocatorHelper
31 * <p>
32 * From a bundle to its location on the filesystem. Assumes the bundle is not a
33 * jar.
34 */
35 public interface BundleFileLocatorHelper
36 {
37
38 /** The name of the custom implementation for this interface in a fragment. */
39 public static final String CLASS_NAME = "org.eclipse.jetty.osgi.boot.utils.FileLocatorHelperImpl";
40
41 /** The default instance supports felix and equinox */
42 public static BundleFileLocatorHelper DEFAULT = new DefaultFileLocatorHelper();
43
44 /**
45 * Works with equinox, felix, nuxeo and probably more. Not exactly in the
46 * spirit of OSGi but quite necessary to support self-contained webapps and
47 * other situations.
48 * <p>
49 * Currently only works with bundles that are not jar.
50 *
51 * @param bundle The bundle
52 * @return Its installation location as a file.
53 * @throws Exception if unable to get the install location
54 */
55 public File getBundleInstallLocation(Bundle bundle) throws Exception;
56
57 /**
58 * Locate a file inside a bundle.
59 *
60 * @param bundle the bundle
61 * @param path the path
62 * @return file the file object
63 * @throws Exception if unable to get the file
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 *
76 * @param bundle the bundle
77 * @return The jar(s) file that is either the bundle itself, either the jars
78 * embedded inside it.
79 * @throws Exception if unable to locate the jars
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 the bundle
88 * @param entryPath the entry path
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 <code>file://</code> or <code>jar://</code> 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. <code>file:</code>
98 * <code>jar:</code> or <code>http:</code> etc.).
99 *
100 * @param url the url
101 * @return a URL to the bundle entry that uses a common protocol
102 * @throws Exception if unable to get the local url
103 */
104 public URL getLocalURL(URL url) throws Exception;
105
106 /**
107 * Only useful for equinox: on felix we get the <code>file://</code> url already. Other
108 * OSGi implementations have not been tested
109 * <p>
110 * Get a URL to the content of the bundle entry that uses the <code>file:</code>
111 * protocol. The content of the bundle entry may be downloaded or extracted
112 * to the local file system in order to create a file: URL.
113 *
114 * @param url the url
115 * @return a URL to the content of the bundle entry that uses the file:
116 * protocol
117 * @throws Exception if unable to get the file url
118 */
119 public URL getFileURL(URL url) throws Exception;
120
121 }