001: /*
002: * Copyright 2002-2007 the original author or authors.
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:
017: package org.springframework.core.io.support;
018:
019: import java.io.File;
020: import java.io.IOException;
021: import java.net.JarURLConnection;
022: import java.net.URL;
023: import java.net.URLConnection;
024: import java.util.Collections;
025: import java.util.Enumeration;
026: import java.util.Iterator;
027: import java.util.Set;
028: import java.util.jar.JarEntry;
029: import java.util.jar.JarFile;
030:
031: import org.apache.commons.logging.Log;
032: import org.apache.commons.logging.LogFactory;
033:
034: import org.springframework.core.CollectionFactory;
035: import org.springframework.core.io.DefaultResourceLoader;
036: import org.springframework.core.io.FileSystemResource;
037: import org.springframework.core.io.Resource;
038: import org.springframework.core.io.ResourceLoader;
039: import org.springframework.core.io.UrlResource;
040: import org.springframework.util.AntPathMatcher;
041: import org.springframework.util.Assert;
042: import org.springframework.util.PathMatcher;
043: import org.springframework.util.ResourceUtils;
044: import org.springframework.util.StringUtils;
045:
046: /**
047: * A {@link ResourcePatternResolver} implementation that is able to resolve a
048: * specified resource location path into one or more matching Resources.
049: * The source path may be a simple path which has a one-to-one mapping to a
050: * target {@link org.springframework.core.io.Resource}, or alternatively
051: * may contain the special "<code>classpath*:</code>" prefix and/or
052: * internal Ant-style regular expressions (matched using Spring's
053: * {@link org.springframework.util.AntPathMatcher} utility).
054: * Both of the latter are effectively wildcards.
055: *
056: * <p><b>No Wildcards:</b>
057: *
058: * <p>In the simple case, if the specified location path does not start with the
059: * <code>"classpath*:</code>" prefix, and does not contain a PathMatcher pattern,
060: * this resolver will simply return a single resource via a
061: * <code>getResource()</code> call on the underlying <code>ResourceLoader</code>.
062: * Examples are real URLs such as "<code>file:C:/context.xml</code>", pseudo-URLs
063: * such as "<code>classpath:/context.xml</code>", and simple unprefixed paths
064: * such as "<code>/WEB-INF/context.xml</code>". The latter will resolve in a
065: * fashion specific to the underlaying <code>ResourceLoader</code> (e.g.
066: * <code>ServletContextResource</code> for a <code>WebApplicationContext</code>).
067: *
068: * <p><b>Ant-style Patterns:</b>
069: *
070: * <p>When the path location contains an Ant-style pattern, e.g.:
071: * <pre>
072: * /WEB-INF/*-context.xml
073: * com/mycompany/**/applicationContext.xml
074: * file:C:/some/path/*-context.xml
075: * classpath:com/mycompany/**/applicationContext.xml</pre>
076: * the resolver follows a more complex but defined procedure to try to resolve
077: * the wildcard. It produces a <code>Resource</code> for the path up to the last
078: * non-wildcard segment and obtains a <code>URL</code> from it. If this URL is
079: * not a "<code>jar:</code>" URL or container-specific variant (e.g.
080: * "<code>zip:</code>" in WebLogic, "<code>wsjar</code>" in WebSphere", etc.),
081: * then a <code>java.io.File</code> is obtained from it, and used to resolve the
082: * wildcard by walking the filesystem. In the case of a jar URL, the resolver
083: * either gets a <code>java.net.JarURLConnection</code> from it, or manually parse
084: * the jar URL, and then traverse the contents of the jar file, to resolve the
085: * wildcards.
086: *
087: * <p><b>Implications on portability:</b>
088: *
089: * <p>If the specified path is already a file URL (either explicitly, or
090: * implicitly because the base <code>ResourceLoader</code> is a filesystem one,
091: * then wildcarding is guaranteed to work in a completely poratable fashion.
092: *
093: * <p>If the specified path is a classpath location, then the resolver must
094: * obtain the last non-wildcard path segment URL via a
095: * <code>Classloader.getResource()</code> call. Since this is just a
096: * node of the path (not the file at the end) it is actually undefined
097: * (in the ClassLoader Javadocs) exactly what sort of a URL is returned in
098: * this case. In practice, it is usually a <code>java.io.File</code> representing
099: * the directory, where the classpath resource resolves to a filesystem
100: * location, or a jar URL of some sort, where the classpath resource resolves
101: * to a jar location. Still, there is a portability concern on this operation.
102: *
103: * <p>If a jar URL is obtained for the last non-wildcard segment, the resolver
104: * must be able to get a <code>java.net.JarURLConnection</code> from it, or
105: * manually parse the jar URL, to be able to walk the contents of the jar,
106: * and resolve the wildcard. This will work in most environments, but will
107: * fail in others, and it is strongly recommended that the wildcard
108: * resolution of resources coming from jars be thoroughly tested in your
109: * specific environment before you rely on it.
110: *
111: * <p><b><code>classpath*:</code> Prefix:</b>
112: *
113: * <p>There is special support for retrieving multiple class path resources with
114: * the same name, via the "<code>classpath*:</code>" prefix. For example,
115: * "<code>classpath*:META-INF/beans.xml</code>" will find all "beans.xml"
116: * files in the class path, be it in "classes" directories or in JAR files.
117: * This is particularly useful for autodetecting config files of the same name
118: * at the same location within each jar file. Internally, this happens via a
119: * <code>ClassLoader.getResources()</code> call, and is completely portable.
120: *
121: * <p>The "classpath*:" prefix can also be combined with a PathMatcher pattern in
122: * the rest of the location path, for example "classpath*:META-INF/*-beans.xml".
123: * In this case, the resolution strategy is fairly simple: a
124: * <code>ClassLoader.getResources()</code> call is used on the last non-wildcard
125: * path segment to get all the matching resources in the class loader hierarchy,
126: * and then off each resource the same PathMatcher resoltion strategy described
127: * above is used for the wildcard subpath.
128: *
129: * <p><b>Other notes:</b>
130: *
131: * <p><b>WARNING:</b> Note that "<code>classpath*:</code>" when combined with
132: * Ant-style patterns will only work reliably with at least one root directory
133: * before the pattern starts, unless the actual target files reside in the file
134: * system. This means that a pattern like "<code>classpath*:*.xml</code>" will
135: * <i>not</i> retrieve files from the root of jar files but rather only from the
136: * root of expanded directories. This originates from a limitation in the JDK's
137: * <code>ClassLoader.getResources()</code> method which only returns file system
138: * locations for a passed-in empty String (indicating potential roots to search).
139: *
140: * <p><b>WARNING:</b> Ant-style patterns with "classpath:" resources are not
141: * guaranteed to find matching resources if the root package to search is available
142: * in multiple class path locations. This is because a resource such as<pre>
143: * com/mycompany/package1/service-context.xml
144: * </pre>may be in only one location, but when a path such as<pre>
145: * classpath:com/mycompany/**/service-context.xml
146: * </pre>is used to try to resolve it, the resolver will work off the (first) URL
147: * returned by <code>getResource("com/mycompany");</code>. If this base package
148: * node exists in multiple classloader locations, the actual end resource may
149: * not be underneath. Therefore, preferably, use "<code>classpath*:<code>" with the same
150: * Ant-style pattern in such a case, which will search <i>all</i> class path
151: * locations that contain the root package.
152: *
153: * @author Juergen Hoeller
154: * @author Colin Sampaleanu
155: * @since 1.0.2
156: * @see #CLASSPATH_ALL_URL_PREFIX
157: * @see org.springframework.util.AntPathMatcher
158: * @see org.springframework.core.io.ResourceLoader#getResource(String)
159: * @see java.lang.ClassLoader#getResources(String)
160: */
161: public class PathMatchingResourcePatternResolver implements
162: ResourcePatternResolver {
163:
164: protected final Log logger = LogFactory.getLog(getClass());
165:
166: private final ResourceLoader resourceLoader;
167:
168: private PathMatcher pathMatcher = new AntPathMatcher();
169:
170: /**
171: * Create a new PathMatchingResourcePatternResolver with a DefaultResourceLoader.
172: * <p>ClassLoader access will happen via the thread context class loader.
173: * @see org.springframework.core.io.DefaultResourceLoader
174: */
175: public PathMatchingResourcePatternResolver() {
176: this .resourceLoader = new DefaultResourceLoader();
177: }
178:
179: /**
180: * Create a new PathMatchingResourcePatternResolver with a DefaultResourceLoader.
181: * @param classLoader the ClassLoader to load classpath resources with,
182: * or <code>null</code> for using the thread context class loader
183: * @see org.springframework.core.io.DefaultResourceLoader
184: */
185: public PathMatchingResourcePatternResolver(ClassLoader classLoader) {
186: this .resourceLoader = new DefaultResourceLoader(classLoader);
187: }
188:
189: /**
190: * Create a new PathMatchingResourcePatternResolver.
191: * <p>ClassLoader access will happen via the thread context class loader.
192: * @param resourceLoader the ResourceLoader to load root directories and
193: * actual resources with
194: */
195: public PathMatchingResourcePatternResolver(
196: ResourceLoader resourceLoader) {
197: Assert.notNull(resourceLoader,
198: "ResourceLoader must not be null");
199: this .resourceLoader = resourceLoader;
200: }
201:
202: /**
203: * Return the ResourceLoader that this pattern resolver works with.
204: */
205: public ResourceLoader getResourceLoader() {
206: return this .resourceLoader;
207: }
208:
209: /**
210: * Return the ClassLoader that this pattern resolver works with
211: * (never <code>null</code>).
212: */
213: public ClassLoader getClassLoader() {
214: return getResourceLoader().getClassLoader();
215: }
216:
217: /**
218: * Set the PathMatcher implementation to use for this
219: * resource pattern resolver. Default is AntPathMatcher.
220: * @see org.springframework.util.AntPathMatcher
221: */
222: public void setPathMatcher(PathMatcher pathMatcher) {
223: Assert.notNull(pathMatcher, "PathMatcher must not be null");
224: this .pathMatcher = pathMatcher;
225: }
226:
227: /**
228: * Return the PathMatcher that this resource pattern resolver uses.
229: */
230: public PathMatcher getPathMatcher() {
231: return this .pathMatcher;
232: }
233:
234: public Resource getResource(String location) {
235: return getResourceLoader().getResource(location);
236: }
237:
238: public Resource[] getResources(String locationPattern)
239: throws IOException {
240: Assert.notNull(locationPattern,
241: "Location pattern must not be null");
242: if (locationPattern.startsWith(CLASSPATH_ALL_URL_PREFIX)) {
243: // a class path resource (multiple resources for same name possible)
244: if (getPathMatcher().isPattern(
245: locationPattern.substring(CLASSPATH_ALL_URL_PREFIX
246: .length()))) {
247: // a class path resource pattern
248: return findPathMatchingResources(locationPattern);
249: } else {
250: // all class path resources with the given name
251: return findAllClassPathResources(locationPattern
252: .substring(CLASSPATH_ALL_URL_PREFIX.length()));
253: }
254: } else {
255: // Only look for a pattern after a prefix here
256: // (to not get fooled by a pattern symbol in a strange prefix).
257: int prefixEnd = locationPattern.indexOf(":") + 1;
258: if (getPathMatcher().isPattern(
259: locationPattern.substring(prefixEnd))) {
260: // a file pattern
261: return findPathMatchingResources(locationPattern);
262: } else {
263: // a single resource with the given name
264: return new Resource[] { getResourceLoader()
265: .getResource(locationPattern) };
266: }
267: }
268: }
269:
270: /**
271: * Find all class location resources with the given location via the ClassLoader.
272: * @param location the absolute path within the classpath
273: * @return the result as Resource array
274: * @throws IOException in case of I/O errors
275: * @see java.lang.ClassLoader#getResources
276: * @see #convertClassLoaderURL
277: */
278: protected Resource[] findAllClassPathResources(String location)
279: throws IOException {
280: String path = location;
281: if (path.startsWith("/")) {
282: path = path.substring(1);
283: }
284: Enumeration resourceUrls = getClassLoader().getResources(path);
285: Set result = CollectionFactory.createLinkedSetIfPossible(16);
286: while (resourceUrls.hasMoreElements()) {
287: URL url = (URL) resourceUrls.nextElement();
288: result.add(convertClassLoaderURL(url));
289: }
290: return (Resource[]) result.toArray(new Resource[result.size()]);
291: }
292:
293: /**
294: * Convert the given URL as returned from the ClassLoader into a Resource object.
295: * <p>The default implementation simply creates a UrlResource instance.
296: * @param url a URL as returned from the ClassLoader
297: * @return the corresponding Resource object
298: * @see java.lang.ClassLoader#getResources
299: * @see org.springframework.core.io.Resource
300: */
301: protected Resource convertClassLoaderURL(URL url) {
302: return new UrlResource(url);
303: }
304:
305: /**
306: * Find all resources that match the given location pattern via the
307: * Ant-style PathMatcher. Supports resources in jar files and zip files
308: * and in the file system.
309: * @param locationPattern the location pattern to match
310: * @return the result as Resource array
311: * @throws IOException in case of I/O errors
312: * @see #doFindPathMatchingJarResources
313: * @see #doFindPathMatchingFileResources
314: * @see org.springframework.util.PathMatcher
315: */
316: protected Resource[] findPathMatchingResources(
317: String locationPattern) throws IOException {
318: String rootDirPath = determineRootDir(locationPattern);
319: String subPattern = locationPattern.substring(rootDirPath
320: .length());
321: Resource[] rootDirResources = getResources(rootDirPath);
322: Set result = CollectionFactory.createLinkedSetIfPossible(16);
323: for (int i = 0; i < rootDirResources.length; i++) {
324: Resource rootDirResource = rootDirResources[i];
325: if (isJarResource(rootDirResource)) {
326: result.addAll(doFindPathMatchingJarResources(
327: rootDirResource, subPattern));
328: } else {
329: result.addAll(doFindPathMatchingFileResources(
330: rootDirResource, subPattern));
331: }
332: }
333: if (logger.isDebugEnabled()) {
334: logger.debug("Resolved location pattern ["
335: + locationPattern + "] to resources " + result);
336: }
337: return (Resource[]) result.toArray(new Resource[result.size()]);
338: }
339:
340: /**
341: * Determine the root directory for the given location.
342: * <p>Used for determining the starting point for file matching,
343: * resolving the root directory location to a <code>java.io.File</code>
344: * and passing it into <code>retrieveMatchingFiles</code>, with the
345: * remainder of the location as pattern.
346: * <p>Will return "/WEB-INF" for the pattern "/WEB-INF/*.xml",
347: * for example.
348: * @param location the location to check
349: * @return the part of the location that denotes the root directory
350: * @see #retrieveMatchingFiles
351: */
352: protected String determineRootDir(String location) {
353: int prefixEnd = location.indexOf(":") + 1;
354: int rootDirEnd = location.length();
355: while (rootDirEnd > prefixEnd
356: && getPathMatcher().isPattern(
357: location.substring(prefixEnd, rootDirEnd))) {
358: rootDirEnd = location.lastIndexOf('/', rootDirEnd - 2) + 1;
359: }
360: if (rootDirEnd == 0) {
361: rootDirEnd = prefixEnd;
362: }
363: return location.substring(0, rootDirEnd);
364: }
365:
366: /**
367: * Return whether the given resource handle indicates a jar resource
368: * that the <code>doFindPathMatchingJarResources</code> method can handle.
369: * <p>The default implementation checks against the URL protocols
370: * "jar", "zip" and "wsjar" (the latter are used by BEA WebLogic Server
371: * and IBM WebSphere, respectively, but can be treated like jar files).
372: * @param resource the resource handle to check
373: * (usually the root directory to start path matching from)
374: * @see #doFindPathMatchingJarResources
375: * @see org.springframework.util.ResourceUtils#isJarURL
376: */
377: protected boolean isJarResource(Resource resource)
378: throws IOException {
379: return ResourceUtils.isJarURL(resource.getURL());
380: }
381:
382: /**
383: * Find all resources in jar files that match the given location pattern
384: * via the Ant-style PathMatcher.
385: * @param rootDirResource the root directory as Resource
386: * @param subPattern the sub pattern to match (below the root directory)
387: * @return the Set of matching Resource instances
388: * @throws IOException in case of I/O errors
389: * @see java.net.JarURLConnection
390: * @see org.springframework.util.PathMatcher
391: */
392: protected Set doFindPathMatchingJarResources(
393: Resource rootDirResource, String subPattern)
394: throws IOException {
395: URLConnection con = rootDirResource.getURL().openConnection();
396: String jarFileUrl = null;
397: String rootEntryPath = null;
398: JarFile jarFile = null;
399: boolean newJarFile = false;
400:
401: if (con instanceof JarURLConnection) {
402: // Should usually be the case for traditional JAR files.
403: JarURLConnection jarCon = (JarURLConnection) con;
404: jarFileUrl = jarCon.getJarFileURL().toExternalForm();
405: JarEntry jarEntry = jarCon.getJarEntry();
406: rootEntryPath = (jarEntry != null ? jarEntry.getName() : "");
407: jarFile = jarCon.getJarFile();
408: } else {
409: // No JarURLConnection -> need to resort to URL file parsing.
410: // We'll assume URLs of the format "jar:path!/entry", with the protocol
411: // being arbitrary as long as following the entry format.
412: // We'll also handle paths with and without leading "file:" prefix.
413: String urlFile = rootDirResource.getURL().getFile();
414: int separatorIndex = urlFile
415: .indexOf(ResourceUtils.JAR_URL_SEPARATOR);
416: jarFileUrl = urlFile.substring(0, separatorIndex);
417: if (jarFileUrl.startsWith(ResourceUtils.FILE_URL_PREFIX)) {
418: jarFileUrl = jarFileUrl
419: .substring(ResourceUtils.FILE_URL_PREFIX
420: .length());
421: }
422: jarFileUrl = ResourceUtils.FILE_URL_PREFIX + jarFileUrl;
423: rootEntryPath = urlFile.substring(separatorIndex
424: + ResourceUtils.JAR_URL_SEPARATOR.length());
425: jarFile = new JarFile(jarFileUrl);
426: newJarFile = true;
427: }
428:
429: try {
430: if (logger.isDebugEnabled()) {
431: logger
432: .debug("Looking for matching resources in jar file ["
433: + jarFileUrl + "]");
434: }
435: if (!"".equals(rootEntryPath)
436: && !rootEntryPath.endsWith("/")) {
437: // Root entry path must end with slash to allow for proper matching.
438: // The Sun JRE does not return a slash here, but BEA JRockit does.
439: rootEntryPath = rootEntryPath + "/";
440: }
441: Set result = CollectionFactory.createLinkedSetIfPossible(8);
442: for (Enumeration entries = jarFile.entries(); entries
443: .hasMoreElements();) {
444: JarEntry entry = (JarEntry) entries.nextElement();
445: String entryPath = entry.getName();
446: if (entryPath.startsWith(rootEntryPath)) {
447: String relativePath = entryPath
448: .substring(rootEntryPath.length());
449: if (getPathMatcher()
450: .match(subPattern, relativePath)) {
451: result.add(rootDirResource
452: .createRelative(relativePath));
453: }
454: }
455: }
456: return result;
457: } finally {
458: // Close jar file, but only if freshly obtained -
459: // not from JarURLConnection, which might cache the file reference.
460: if (newJarFile) {
461: jarFile.close();
462: }
463: }
464: }
465:
466: /**
467: * Find all resources in the file system that match the given location pattern
468: * via the Ant-style PathMatcher.
469: * @param rootDirResource the root directory as Resource
470: * @param subPattern the sub pattern to match (below the root directory)
471: * @return the Set of matching Resource instances
472: * @throws IOException in case of I/O errors
473: * @see #retrieveMatchingFiles
474: * @see org.springframework.util.PathMatcher
475: */
476: protected Set doFindPathMatchingFileResources(
477: Resource rootDirResource, String subPattern)
478: throws IOException {
479: File rootDir = null;
480: try {
481: rootDir = rootDirResource.getFile().getAbsoluteFile();
482: } catch (IOException ex) {
483: if (logger.isDebugEnabled()) {
484: logger
485: .debug(
486: "Cannot search for matching files underneath "
487: + rootDirResource
488: + " because it does not correspond to a directory in the file system",
489: ex);
490: }
491: return Collections.EMPTY_SET;
492: }
493: return doFindMatchingFileSystemResources(rootDir, subPattern);
494: }
495:
496: /**
497: * Find all resources in the file system that match the given location pattern
498: * via the Ant-style PathMatcher.
499: * @param rootDir the root directory in the file system
500: * @param subPattern the sub pattern to match (below the root directory)
501: * @return the Set of matching Resource instances
502: * @throws IOException in case of I/O errors
503: * @see #retrieveMatchingFiles
504: * @see org.springframework.util.PathMatcher
505: */
506: protected Set doFindMatchingFileSystemResources(File rootDir,
507: String subPattern) throws IOException {
508: if (logger.isDebugEnabled()) {
509: logger
510: .debug("Looking for matching resources in directory tree ["
511: + rootDir.getPath() + "]");
512: }
513: Set matchingFiles = retrieveMatchingFiles(rootDir, subPattern);
514: Set result = CollectionFactory
515: .createLinkedSetIfPossible(matchingFiles.size());
516: for (Iterator it = matchingFiles.iterator(); it.hasNext();) {
517: File file = (File) it.next();
518: result.add(new FileSystemResource(file));
519: }
520: return result;
521: }
522:
523: /**
524: * Retrieve files that match the given path pattern,
525: * checking the given directory and its subdirectories.
526: * @param rootDir the directory to start from
527: * @param pattern the pattern to match against,
528: * relative to the root directory
529: * @return the Set of matching File instances
530: * @throws IOException if directory contents could not be retrieved
531: */
532: protected Set retrieveMatchingFiles(File rootDir, String pattern)
533: throws IOException {
534: if (!rootDir.isDirectory()) {
535: throw new IllegalArgumentException("Resource path ["
536: + rootDir + "] does not denote a directory");
537: }
538: String fullPattern = StringUtils.replace(rootDir
539: .getAbsolutePath(), File.separator, "/");
540: if (!pattern.startsWith("/")) {
541: fullPattern += "/";
542: }
543: fullPattern = fullPattern
544: + StringUtils.replace(pattern, File.separator, "/");
545: Set result = CollectionFactory.createLinkedSetIfPossible(8);
546: doRetrieveMatchingFiles(fullPattern, rootDir, result);
547: return result;
548: }
549:
550: /**
551: * Recursively retrieve files that match the given pattern,
552: * adding them to the given result list.
553: * @param fullPattern the pattern to match against,
554: * with preprended root directory path
555: * @param dir the current directory
556: * @param result the Set of matching File instances to add to
557: * @throws IOException if directory contents could not be retrieved
558: */
559: protected void doRetrieveMatchingFiles(String fullPattern,
560: File dir, Set result) throws IOException {
561: if (logger.isDebugEnabled()) {
562: logger.debug("Searching directory ["
563: + dir.getAbsolutePath()
564: + "] for files matching pattern [" + fullPattern
565: + "]");
566: }
567: File[] dirContents = dir.listFiles();
568: if (dirContents == null) {
569: throw new IOException(
570: "Could not retrieve contents of directory ["
571: + dir.getAbsolutePath() + "]");
572: }
573: boolean dirDepthNotFixed = (fullPattern.indexOf("**") != -1);
574: for (int i = 0; i < dirContents.length; i++) {
575: String currPath = StringUtils.replace(dirContents[i]
576: .getAbsolutePath(), File.separator, "/");
577: if (dirContents[i].isDirectory()
578: && (dirDepthNotFixed || StringUtils
579: .countOccurrencesOf(currPath, "/") < StringUtils
580: .countOccurrencesOf(fullPattern, "/"))) {
581: doRetrieveMatchingFiles(fullPattern, dirContents[i],
582: result);
583: }
584: if (getPathMatcher().match(fullPattern, currPath)) {
585: result.add(dirContents[i]);
586: }
587: }
588: }
589:
590: }
|