KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > runtime > FileLocator


1 /*******************************************************************************
2  * Copyright (c) 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/

11 package org.eclipse.core.runtime;
12
13 import java.io.IOException JavaDoc;
14 import java.io.InputStream JavaDoc;
15 import java.net.URL JavaDoc;
16 import java.util.Map JavaDoc;
17 import org.eclipse.core.internal.runtime.Activator;
18 import org.eclipse.core.internal.runtime.FindSupport;
19 import org.eclipse.osgi.service.urlconversion.URLConverter;
20 import org.osgi.framework.Bundle;
21
22 /**
23  * This class contains collection of helper methods aimed at finding files in bundles.
24  * This class can only be used if OSGi plugin is available.
25  * <p>
26  * The class is not intended to be subclassed or instantiated by clients.
27  * </p>
28  * @since org.eclipse.equinox.common 3.2
29  */

30 public final class FileLocator {
31
32     private FileLocator() {
33         // prevent instantiation
34
}
35
36     /**
37      * Returns a URL for the given path in the given bundle. Returns <code>null</code> if the URL
38      * could not be computed or created.
39      * <p>
40      * find looks for this path in given bundle and any attached fragments.
41      * <code>null</code> is returned if no such entry is found. Note that
42      * there is no specific order to the fragments.
43      * </p><p>
44      * The following arguments may also be used
45      * <pre>
46      * $nl$ - for language specific information
47      * $os$ - for operating system specific information
48      * $ws$ - for windowing system specific information
49      * </pre>
50      * </p><p>
51      * A path of $nl$/about.properties in an environment with a default
52      * locale of en_CA will return a URL corresponding to the first place
53      * about.properties is found according to the following order:
54      * <pre>
55      * plugin root/nl/en/CA/about.properties
56      * fragment1 root/nl/en/CA/about.properties
57      * fragment2 root/nl/en/CA/about.properties
58      * ...
59      * plugin root/nl/en/about.properties
60      * fragment1 root/nl/en/about.properties
61      * fragment2 root/nl/en/about.properties
62      * ...
63      * plugin root/about.properties
64      * fragment1 root/about.properties
65      * fragment2 root/about.properties
66      * ...
67      * </pre>
68      * </p><p>
69      * The current environment variable values can be overridden using
70      * the override map argument or <code>null</code> can be specified
71      * if this is not desired.
72      * </p>
73      *
74      * @param bundle the bundle in which to search
75      * @param path file path relative to plug-in installation location
76      * @param override map of override substitution arguments to be used for
77      * any $arg$ path elements. The map keys correspond to the substitution
78      * arguments (eg. "$nl$" or "$os$"). The resulting
79      * values must be of type java.lang.String. If the map is <code>null</code>,
80      * or does not contain the required substitution argument, the default
81      * is used.
82      * @return a URL for the given path or <code>null</code>. The actual form
83      * of the returned URL is not specified.
84      */

85     public static URL JavaDoc find(Bundle bundle, IPath path, Map JavaDoc override) {
86         return FindSupport.find(bundle, path, override);
87     }
88
89     /**
90      * Same as {@link #findEntries(Bundle, IPath, Map)} except multiple entries
91      * can be returned if more than one entry matches the path in the host and
92      * any of its fragments.
93      *
94      * @param bundle the bundle in which to search
95      * @param path file path relative to plug-in installation location
96      * @param override map of override substitution arguments to be used for
97      * any $arg$ path elements. The map keys correspond to the substitution
98      * arguments (eg. "$nl$" or "$os$"). The resulting
99      * values must be of type java.lang.String. If the map is <code>null</code>,
100      * or does not contain the required substitution argument, the default
101      * is used.
102      * @return an array of entries which match the given path. An empty
103      * array is returned if no matches are found.
104      *
105      * @since org.eclipse.equinox.common 3.3
106      */

107     public static URL JavaDoc[] findEntries(Bundle bundle, IPath path, Map JavaDoc override) {
108         return FindSupport.findEntries(bundle, path, override);
109     }
110
111     /**
112      * Same as {@link #findEntries(Bundle, IPath)} except multiple entries
113      * can be returned if more than one entry matches the path in the host
114      * any of its fragments.
115      *
116      * @param bundle the bundle in which to search
117      * @param path file path relative to plug-in installation location
118      * @return an array of entries which match the given path. An empty
119      * array is returned if no matches are found.
120      *
121      * @since org.eclipse.equinox.common 3.3
122      */

123     public static URL JavaDoc[] findEntries(Bundle bundle, IPath path) {
124         return FindSupport.findEntries(bundle, path);
125     }
126
127     /**
128      * Returns an input stream for the specified file. The file path
129      * must be specified relative to this plug-in's installation location.
130      * Optionally, the path specified may contain $arg$ path elements that can
131      * be used as substitution arguments. If this option is used then the $arg$
132      * path elements are processed in the same way as {@link #find(Bundle, IPath, Map)}.
133      * <p>
134      * The caller must close the returned stream when done.
135      * </p>
136      *
137      * @param bundle the bundle in which to search
138      * @param file path relative to plug-in installation location
139      * @param substituteArgs <code>true</code> to process substitution arguments,
140      * and <code>false</code> for the file exactly as specified without processing any
141      * substitution arguments.
142      * @return an input stream
143      * @exception IOException if the given path cannot be found in this plug-in
144      */

145     public static InputStream JavaDoc openStream(Bundle bundle, IPath file, boolean substituteArgs) throws IOException JavaDoc {
146         return FindSupport.openStream(bundle, file, substituteArgs);
147     }
148
149     /**
150      * Converts a URL that uses a user-defined protocol into a URL that uses the file
151      * protocol. The contents of the URL may be extracted into a cache on the file-system
152      * in order to get a file URL.
153      * <p>
154      * If the protocol for the given URL is not recognized by this converter, the original
155      * URL is returned as-is.
156      * </p>
157      * @param url the original URL
158      * @return the converted file URL or the original URL passed in if it is
159      * not recognized by this converter
160      * @throws IOException if an error occurs during the conversion
161      */

162     public static URL JavaDoc toFileURL(URL JavaDoc url) throws IOException JavaDoc {
163         URLConverter converter = Activator.getURLConverter(url);
164         return converter == null ? url : converter.toFileURL(url);
165     }
166
167     /**
168      * Converts a URL that uses a client-defined protocol into a URL that uses a
169      * protocol which is native to the Java class library (file, jar, http, etc).
170      * <p>
171      * Note however that users of this API should not assume too much about the
172      * results of this method. While it may consistently return a file: URL in certain
173      * installation configurations, others may result in jar: or http: URLs.
174      * </p>
175      * <p>
176      * If the protocol is not recognized by this converter, then the original URL is
177      * returned as-is.
178      * </p>
179      * @param url the original URL
180      * @return the resolved URL or the original if the protocol is unknown to this converter
181      * @exception IOException if unable to resolve URL
182      * @throws IOException if an error occurs during the resolution
183      */

184     public static URL JavaDoc resolve(URL JavaDoc url) throws IOException JavaDoc {
185         URLConverter converter = Activator.getURLConverter(url);
186         return converter == null ? url : converter.resolve(url);
187     }
188
189 }
190
Popular Tags