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.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 *
32 *
33 * From a bundle to its location on the filesystem. Assumes the bundle is not a
34 * jar.
35 *
36 * @author hmalphettes
37 */
38 public interface BundleFileLocatorHelper
39 {
40
41 /** The name of the custom implementation for this interface in a fragment. */
42 public static final String CLASS_NAME = "org.eclipse.jetty.osgi.boot.utils.FileLocatorHelperImpl";
43
44 /** The default instance supports felix and equinox */
45 public static BundleFileLocatorHelper DEFAULT = new DefaultFileLocatorHelper();
46
47 /**
48 * Works with equinox, felix, nuxeo and probably more. Not exactly in the
49 * spirit of OSGi but quite necessary to support self-contained webapps and
50 * other situations.
51 * <p>
52 * Currently only works with bundles that are not jar.
53 * </p>
54 *
55 * @param bundle The bundle
56 * @return Its installation location as a file.
57 * @throws Exception
58 */
59 public File getBundleInstallLocation(Bundle bundle) throws Exception;
60
61 /**
62 * Locate a file inside a bundle.
63 *
64 * @param bundle
65 * @param path
66 * @return file object
67 * @throws Exception
68 */
69 public File getFileInBundle(Bundle bundle, String path) throws Exception;
70
71 /**
72 * If the bundle is a jar, returns the jar. If the bundle is a folder, look
73 * inside it and search for jars that it returns.
74 * <p>
75 * Good enough for our purpose (TldLocationsCache when it scans for tld
76 * files inside jars alone. In fact we only support the second situation for
77 * development purpose where the bundle was imported in pde and the classes
78 * kept in a jar.
79 * </p>
80 *
81 * @param bundle
82 * @return The jar(s) file that is either the bundle itself, either the jars
83 * embedded inside it.
84 */
85 public File[] locateJarsInsideBundle(Bundle bundle) throws Exception;
86
87 /**
88 * Helper method equivalent to Bundle#getEntry(String entryPath) except that
89 * it searches for entries in the fragments by using the findEntries method.
90 *
91 * @param bundle
92 * @param entryPath
93 * @return null or all the entries found for that path.
94 */
95 public Enumeration<URL> findEntries(Bundle bundle, String entryPath);
96
97 /**
98 * Only useful for equinox: on felix we get the file:// or jar:// url
99 * already. Other OSGi implementations have not been tested
100 * <p>
101 * Get a URL to the bundle entry that uses a common protocol (i.e. file:
102 * jar: or http: etc.).
103 * </p>
104 *
105 * @return a URL to the bundle entry that uses a common protocol
106 */
107 public URL getLocalURL(URL url) throws Exception;
108
109 /**
110 * Only useful for equinox: on felix we get the file:// url already. Other
111 * OSGi implementations have not been tested
112 * <p>
113 * Get a URL to the content of the bundle entry that uses the file:
114 * protocol. The content of the bundle entry may be downloaded or extracted
115 * to the local file system in order to create a file: URL.
116 *
117 * @return a URL to the content of the bundle entry that uses the file:
118 * protocol
119 * </p>
120 * @throws IOException
121 * @throws Exception
122 */
123 public URL getFileURL(URL url) throws Exception;
124
125 }