No Wildcards: + *
The source path may be a simple path which has a one-to-one mapping to a + * target {@link org.springframework.core.io.Resource}, or alternatively may + * contain the special "{@code classpath*:}" prefix and/or internal Ant-style + * path patterns (matched using Spring's {@link AntPathMatcher} utility). Both + * of the latter are effectively wildcards. + * + *
In the simple case, if the specified location path does not start with the - * {@code "classpath*:}" prefix, and does not contain a PathMatcher pattern, - * this resolver will simply return a single resource via a + * {@code "classpath*:}" prefix and does not contain a {@link PathMatcher} + * pattern, this resolver will simply return a single resource via a * {@code getResource()} call on the underlying {@code ResourceLoader}. * Examples are real URLs such as "{@code file:C:/context.xml}", pseudo-URLs * such as "{@code classpath:/context.xml}", and simple unprefixed paths @@ -90,14 +90,14 @@ import org.springframework.util.StringUtils; * fashion specific to the underlying {@code ResourceLoader} (e.g. * {@code ServletContextResource} for a {@code WebApplicationContext}). * - *
Ant-style Patterns: + *
When the path location contains an Ant-style pattern, e.g.: + *
When the path location contains an Ant-style pattern, for example: *
* /WEB-INF/*-context.xml - * com/mycompany/**/applicationContext.xml + * com/example/**/applicationContext.xml * file:C:/some/path/*-context.xml - * classpath:com/mycompany/**/applicationContext.xml+ * classpath:com/example/**/applicationContext.xml * the resolver follows a more complex but defined procedure to try to resolve * the wildcard. It produces a {@code Resource} for the path up to the last * non-wildcard segment and obtains a {@code URL} from it. If this URL is not a @@ -108,31 +108,31 @@ import org.springframework.util.StringUtils; * {@code java.net.JarURLConnection} from it, or manually parses the jar URL, and * then traverses the contents of the jar file, to resolve the wildcards. * - *
Implications on portability: + *
If the specified path is already a file URL (either explicitly, or * implicitly because the base {@code ResourceLoader} is a filesystem one), * then wildcarding is guaranteed to work in a completely portable fashion. * - *
If the specified path is a classpath location, then the resolver must + *
If the specified path is a class path location, then the resolver must * obtain the last non-wildcard path segment URL via a * {@code Classloader.getResource()} call. Since this is just a * node of the path (not the file at the end) it is actually undefined * (in the ClassLoader Javadocs) exactly what sort of URL is returned in * this case. In practice, it is usually a {@code java.io.File} representing - * the directory, where the classpath resource resolves to a filesystem - * location, or a jar URL of some sort, where the classpath resource resolves + * the directory, where the class path resource resolves to a filesystem + * location, or a jar URL of some sort, where the class path resource resolves * to a jar location. Still, there is a portability concern on this operation. * *
If a jar URL is obtained for the last non-wildcard segment, the resolver * must be able to get a {@code java.net.JarURLConnection} from it, or - * manually parse the jar URL, to be able to walk the contents of the jar, - * and resolve the wildcard. This will work in most environments, but will + * manually parse the jar URL, to be able to walk the contents of the jar + * and resolve the wildcard. This will work in most environments but will * fail in others, and it is strongly recommended that the wildcard * resolution of resources coming from jars be thoroughly tested in your * specific environment before you rely on it. * - *
{@code classpath*:} Prefix: + *
There is special support for retrieving multiple class path resources with * the same name, via the "{@code classpath*:}" prefix. For example, @@ -142,22 +142,22 @@ import org.springframework.util.StringUtils; * at the same location within each jar file. Internally, this happens via a * {@code ClassLoader.getResources()} call, and is completely portable. * - *
The "classpath*:" prefix can also be combined with a PathMatcher pattern in - * the rest of the location path, for example "classpath*:META-INF/*-beans.xml". - * In this case, the resolution strategy is fairly simple: a - * {@code ClassLoader.getResources()} call is used on the last non-wildcard - * path segment to get all the matching resources in the class loader hierarchy, - * and then off each resource the same PathMatcher resolution strategy described - * above is used for the wildcard sub pattern. + *
The "{@code classpath*:}" prefix can also be combined with a {@code PathMatcher} + * pattern in the rest of the location path — for example, + * "{@code classpath*:META-INF/*-beans.xml"}. In this case, the resolution strategy + * is fairly simple: a {@code ClassLoader.getResources()} call is used on the last + * non-wildcard path segment to get all the matching resources in the class loader + * hierarchy, and then off each resource the same {@code PathMatcher} resolution + * strategy described above is used for the wildcard sub pattern. * - *
Other notes: + *
As of Spring Framework 6.0, if {@link #getResources(String)} is invoked - * with a location pattern using the "classpath*:" prefix it will first search + *
As of Spring Framework 6.0, if {@link #getResources(String)} is invoked with + * a location pattern using the "{@code classpath*:}" prefix it will first search * all modules in the {@linkplain ModuleLayer#boot() boot layer}, excluding * {@linkplain ModuleFinder#ofSystem() system modules}. It will then search the - * classpath using {@link ClassLoader} APIs as described previously and return the - * combined results. Consequently, some of the limitations of classpath searches + * class path using {@link ClassLoader} APIs as described previously and return the + * combined results. Consequently, some of the limitations of class path searches * may not apply when applications are deployed as modules. * *
WARNING: Note that "{@code classpath*:}" when combined with @@ -168,26 +168,26 @@ import org.springframework.util.StringUtils; * root of expanded directories. This originates from a limitation in the JDK's * {@code ClassLoader.getResources()} method which only returns file system * locations for a passed-in empty String (indicating potential roots to search). - * This {@code ResourcePatternResolver} implementation is trying to mitigate the + * This {@code ResourcePatternResolver} implementation tries to mitigate the * jar root lookup limitation through {@link URLClassLoader} introspection and - * "java.class.path" manifest evaluation; however, without portability guarantees. + * "{@code java.class.path}" manifest evaluation; however, without portability + * guarantees. * - *
WARNING: Ant-style patterns with "classpath:" resources are not - * guaranteed to find matching resources if the root package to search is available + *
WARNING: Ant-style patterns with "{@code classpath:}" resources are not + * guaranteed to find matching resources if the base package to search is available * in multiple class path locations. This is because a resource such as *
- * com/mycompany/package1/service-context.xml - *- * may be in only one location, but when a path such as + * com/example/package1/service-context.xml + * may exist in only one class path location, but when a location pattern such as *
- * classpath:com/mycompany/**/service-context.xml - *+ * classpath:com/example/**/service-context.xml * is used to try to resolve it, the resolver will work off the (first) URL - * returned by {@code getResource("com/mycompany");}. If this base package node - * exists in multiple classloader locations, the actual end resource may not be - * underneath. Therefore, preferably, use "{@code classpath*:}" with the same - * Ant-style pattern in such a case, which will search all class path - * locations that contain the root package. + * returned by {@code getResource("com/example")}. If the {@code com/example} base + * package node exists in multiple class path locations, the actual desired resource + * may not be present under the {@code com/example} base package in the first URL. + * Therefore, preferably, use "{@code classpath*:}" with the same Ant-style pattern + * in such a case, which will search all class path locations that contain + * the base package. * * @author Juergen Hoeller * @author Colin Sampaleanu @@ -249,19 +249,21 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol /** - * Create a new PathMatchingResourcePatternResolver with a DefaultResourceLoader. + * Create a {@code PathMatchingResourcePatternResolver} with a + * {@link DefaultResourceLoader}. *
ClassLoader access will happen via the thread context class loader. - * @see org.springframework.core.io.DefaultResourceLoader + * @see DefaultResourceLoader */ public PathMatchingResourcePatternResolver() { this.resourceLoader = new DefaultResourceLoader(); } /** - * Create a new PathMatchingResourcePatternResolver. + * Create a {@code PathMatchingResourcePatternResolver} with the supplied + * {@link ResourceLoader}. *
ClassLoader access will happen via the thread context class loader. - * @param resourceLoader the ResourceLoader to load root directories and - * actual resources with + * @param resourceLoader the {@code ResourceLoader} to load root directories + * and actual resources with */ public PathMatchingResourcePatternResolver(ResourceLoader resourceLoader) { Assert.notNull(resourceLoader, "ResourceLoader must not be null"); @@ -269,8 +271,9 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol } /** - * Create a new PathMatchingResourcePatternResolver with a DefaultResourceLoader. - * @param classLoader the ClassLoader to load classpath resources with, + * Create a {@code PathMatchingResourcePatternResolver} with a + * {@link DefaultResourceLoader} and the supplied {@link ClassLoader}. + * @param classLoader the ClassLoader to load class path resources with, * or {@code null} for using the thread context class loader * at the time of actual resource access * @see org.springframework.core.io.DefaultResourceLoader @@ -281,7 +284,7 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol /** - * Return the ResourceLoader that this pattern resolver works with. + * Return the {@link ResourceLoader} that this pattern resolver works with. */ public ResourceLoader getResourceLoader() { return this.resourceLoader; @@ -294,9 +297,10 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol } /** - * Set the PathMatcher implementation to use for this - * resource pattern resolver. Default is AntPathMatcher. - * @see org.springframework.util.AntPathMatcher + * Set the {@link PathMatcher} implementation to use for this + * resource pattern resolver. + *
Default is {@link AntPathMatcher}. + * @see AntPathMatcher */ public void setPathMatcher(PathMatcher pathMatcher) { Assert.notNull(pathMatcher, "PathMatcher must not be null"); @@ -304,7 +308,7 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol } /** - * Return the PathMatcher that this resource pattern resolver uses. + * Return the {@link PathMatcher} that this resource pattern resolver uses. */ public PathMatcher getPathMatcher() { return this.pathMatcher; @@ -353,8 +357,8 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol /** * Find all class location resources with the given location via the ClassLoader. - * Delegates to {@link #doFindAllClassPathResources(String)}. - * @param location the absolute path within the classpath + *
Delegates to {@link #doFindAllClassPathResources(String)}.
+ * @param location the absolute path within the class path
* @return the result as Resource array
* @throws IOException in case of I/O errors
* @see java.lang.ClassLoader#getResources
@@ -364,15 +368,16 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
String path = stripLeadingSlash(location);
Set Called by {@link #findAllClassPathResources(String)}.
+ * @param path the absolute path within the class path (never a leading slash)
* @return a mutable Set of matching Resource instances
* @since 4.1.1
*/
@@ -386,20 +391,21 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
}
if (!StringUtils.hasLength(path)) {
// The above result is likely to be incomplete, i.e. only containing file system references.
- // We need to have pointers to each of the jar files on the classpath as well...
+ // We need to have pointers to each of the jar files on the class path as well...
addAllClassLoaderJarRoots(cl, result);
}
return result;
}
/**
- * Convert the given URL as returned from the ClassLoader into a {@link Resource},
- * applying to path lookups without a pattern ({@link #findAllClassPathResources}).
+ * Convert the given URL as returned from the configured
+ * {@link #getClassLoader() ClassLoader} into a {@link Resource}, applying
+ * to path lookups without a pattern (see {@link #findAllClassPathResources}).
* As of 6.0.5, the default implementation creates a {@link FileSystemResource}
* in case of the "file" protocol or a {@link UrlResource} otherwise, matching
- * the outcome of pattern-based classpath traversal in the same resource layout,
+ * the outcome of pattern-based class path traversal in the same resource layout,
* as well as matching the outcome of module path searches.
- * @param url a URL as returned from the ClassLoader
+ * @param url a URL as returned from the configured ClassLoader
* @return the corresponding Resource object
* @see java.lang.ClassLoader#getResources
* @see #doFindAllClassPathResources
@@ -422,8 +428,8 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
}
/**
- * Search all {@link URLClassLoader} URLs for jar file references and add them to the
- * given set of resources in the form of pointers to the root of the jar file content.
+ * Search all {@link URLClassLoader} URLs for jar file references and add each to the
+ * given set of resources in the form of a pointer to the root of the jar file content.
* @param classLoader the ClassLoader to search (including its ancestors)
* @param result the set of resources to add jar roots to
* @since 4.1.1
@@ -457,7 +463,7 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
}
if (classLoader == ClassLoader.getSystemClassLoader()) {
- // "java.class.path" manifest evaluation...
+ // JAR "Class-Path" manifest header evaluation...
addClassPathManifestEntries(result);
}
@@ -476,16 +482,17 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
}
/**
- * Determine jar file references from the "java.class.path." manifest property and add them
- * to the given set of resources in the form of pointers to the root of the jar file content.
+ * Determine jar file references from {@code Class-Path} manifest entries (which
+ * are added to the {@code java.class.path} JVM system property by the system
+ * class loader) and add each to the given set of resources in the form of
+ * a pointer to the root of the jar file content.
* @param result the set of resources to add jar roots to
* @since 4.3
*/
protected void addClassPathManifestEntries(Set Supports resources in OSGi bundles, JBoss VFS, jar files, zip files,
+ * and file systems.
* @param locationPattern the location pattern to match
* @return the result as Resource array
* @throws IOException in case of I/O errors
- * @see #doFindPathMatchingJarResources
- * @see #doFindPathMatchingFileResources
+ * @see #determineRootDir(String)
+ * @see #resolveRootDirResource(Resource)
+ * @see #isJarResource(Resource)
+ * @see #doFindPathMatchingJarResources(Resource, URL, String)
+ * @see #doFindPathMatchingFileResources(Resource, String)
* @see org.springframework.util.PathMatcher
*/
protected Resource[] findPathMatchingResources(String locationPattern) throws IOException {
@@ -607,29 +618,39 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
}
/**
- * Resolve the specified resource for path matching.
- * By default, Equinox OSGi "bundleresource:" / "bundleentry:" URL will be
- * resolved into a standard jar file URL that be traversed using Spring's
- * standard jar file traversal algorithm. For any preceding custom resolution,
- * override this method and replace the resource handle accordingly.
+ * Resolve the supplied root directory resource for path matching.
+ * By default, {@link #findPathMatchingResources(String)} resolves Equinox
+ * OSGi "bundleresource:" and "bundleentry:" URLs into standard jar file URLs
+ * that will be traversed using Spring's standard jar file traversal algorithm.
+ * For any custom resolution, override this template method and replace the
+ * supplied resource handle accordingly.
+ * The default implementation of this method returns the supplied resource
+ * unmodified.
* @param original the resource to resolve
- * @return the resolved resource (may be identical to the passed-in resource)
+ * @return the resolved resource (may be identical to the supplied resource)
* @throws IOException in case of resolution failure
+ * @see #findPathMatchingResources(String)
*/
protected Resource resolveRootDirResource(Resource original) throws IOException {
return original;
}
/**
- * Return whether the given resource handle indicates a jar resource
- * that the {@link #doFindPathMatchingJarResources} method can handle.
- * By default, the URL protocols "jar", "zip", "vfszip, and "wsjar"
- * will be treated as jar resources. This template method allows for
- * detecting further kinds of jar-like resources, e.g. through
- * {@code instanceof} checks on the resource handle type.
- * @param resource the resource handle to check
- * (usually the root directory to start path matching from)
- * @see #doFindPathMatchingJarResources
+ * Determine if the given resource handle indicates a jar resource that the
+ * {@link #doFindPathMatchingJarResources} method can handle.
+ * {@link #findPathMatchingResources(String)} delegates to
+ * {@link ResourceUtils#isJarURL(URL)} to determine whether the given URL
+ * points to a resource in a jar file, and only invokes this method as a fallback.
+ * This template method therefore allows for detecting further kinds of
+ * jar-like resources — for example, via {@code instanceof} checks on
+ * the resource handle type.
+ * The default implementation of this method returns {@code false}.
+ * @param resource the resource handle to check (usually the root directory
+ * to start path matching from)
+ * @return {@code true} if the given resource handle indicates a jar resource
+ * @throws IOException in case of I/O errors
+ * @see #findPathMatchingResources(String)
+ * @see #doFindPathMatchingJarResources(Resource, URL, String)
* @see org.springframework.util.ResourceUtils#isJarURL
*/
protected boolean isJarResource(Resource resource) throws IOException {
@@ -638,7 +659,7 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
/**
* Find all resources in jar files that match the given location pattern
- * via the Ant-style PathMatcher.
+ * via the Ant-style {@link #getPathMatcher() PathMatcher}.
* @param rootDirResource the root directory as Resource
* @param rootDirUrl the pre-resolved root directory URL
* @param subPattern the sub pattern to match (below the root directory)
@@ -691,7 +712,7 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
}
catch (ZipException ex) {
if (logger.isDebugEnabled()) {
- logger.debug("Skipping invalid jar classpath entry [" + urlFile + "]");
+ logger.debug("Skipping invalid jar class path entry [" + urlFile + "]");
}
return Collections.emptySet();
}
@@ -746,7 +767,8 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
/**
* Find all resources in the file system of the supplied root directory that
- * match the given location sub pattern via the Ant-style PathMatcher.
+ * match the given location sub pattern via the Ant-style {@link #getPathMatcher()
+ * PathMatcher}.
* @param rootDirResource the root directory as a Resource
* @param subPattern the sub pattern to match (below the root directory)
* @return a mutable Set of matching Resource instances
@@ -924,8 +946,8 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
}
/**
- * If it's a "file:" URI, use FileSystemResource to avoid duplicates
- * for the same path discovered via class-path scanning.
+ * If it's a "file:" URI, use {@link FileSystemResource} to avoid duplicates
+ * for the same path discovered via class path scanning.
*/
private Resource convertModuleSystemURI(URI uri) {
return (ResourceUtils.URL_PROTOCOL_FILE.equals(uri.getScheme()) ?
diff --git a/spring-core/src/main/java/org/springframework/util/ResourceUtils.java b/spring-core/src/main/java/org/springframework/util/ResourceUtils.java
index af5b6746b96..6909a65c54d 100644
--- a/spring-core/src/main/java/org/springframework/util/ResourceUtils.java
+++ b/spring-core/src/main/java/org/springframework/util/ResourceUtils.java
@@ -1,5 +1,5 @@
/*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -100,6 +100,7 @@ public abstract class ResourceUtils {
* @return whether the location qualifies as a URL
* @see #CLASSPATH_URL_PREFIX
* @see java.net.URL
+ * @see #toURL(String)
*/
public static boolean isUrl(@Nullable String resourceLocation) {
if (resourceLocation == null) {
@@ -125,6 +126,7 @@ public abstract class ResourceUtils {
* "classpath:" pseudo URL, a "file:" URL, or a plain file path
* @return a corresponding URL object
* @throws FileNotFoundException if the resource cannot be resolved to a URL
+ * @see #toURL(String)
*/
public static URL getURL(String resourceLocation) throws FileNotFoundException {
Assert.notNull(resourceLocation, "Resource location must not be null");
@@ -165,6 +167,7 @@ public abstract class ResourceUtils {
* @return a corresponding File object
* @throws FileNotFoundException if the resource cannot be resolved to
* a file in the file system
+ * @see #getFile(URL)
*/
public static File getFile(String resourceLocation) throws FileNotFoundException {
Assert.notNull(resourceLocation, "Resource location must not be null");
@@ -196,6 +199,7 @@ public abstract class ResourceUtils {
* @return a corresponding File object
* @throws FileNotFoundException if the URL cannot be resolved to
* a file in the file system
+ * @see #getFile(URL, String)
*/
public static File getFile(URL resourceUrl) throws FileNotFoundException {
return getFile(resourceUrl, "URL");
@@ -236,6 +240,7 @@ public abstract class ResourceUtils {
* @throws FileNotFoundException if the URL cannot be resolved to
* a file in the file system
* @since 2.5
+ * @see #getFile(URI, String)
*/
public static File getFile(URI resourceUri) throws FileNotFoundException {
return getFile(resourceUri, "URI");
@@ -267,6 +272,7 @@ public abstract class ResourceUtils {
* i.e. has protocol "file", "vfsfile" or "vfs".
* @param url the URL to check
* @return whether the URL has been identified as a file system URL
+ * @see #isJarURL(URL)
*/
public static boolean isFileURL(URL url) {
String protocol = url.getProtocol();
@@ -275,10 +281,12 @@ public abstract class ResourceUtils {
}
/**
- * Determine whether the given URL points to a resource in a jar file.
- * i.e. has protocol "jar", "war, ""zip", "vfszip" or "wsjar".
+ * Determine whether the given URL points to a resource in a jar file
+ * — for example, whether the URL has protocol "jar", "war, "zip",
+ * "vfszip", or "wsjar".
* @param url the URL to check
* @return whether the URL has been identified as a JAR URL
+ * @see #isJarFileURL(URL)
*/
public static boolean isJarURL(URL url) {
String protocol = url.getProtocol();
@@ -293,6 +301,7 @@ public abstract class ResourceUtils {
* @param url the URL to check
* @return whether the URL has been identified as a JAR file URL
* @since 4.1
+ * @see #extractJarFileURL(URL)
*/
public static boolean isJarFileURL(URL url) {
return (URL_PROTOCOL_FILE.equals(url.getProtocol()) &&
@@ -305,6 +314,7 @@ public abstract class ResourceUtils {
* @param jarUrl the original URL
* @return the URL for the actual jar file
* @throws MalformedURLException if no valid jar file URL could be extracted
+ * @see #extractArchiveURL(URL)
*/
public static URL extractJarFileURL(URL jarUrl) throws MalformedURLException {
String urlFile = jarUrl.getFile();
@@ -366,6 +376,7 @@ public abstract class ResourceUtils {
* @return the URI instance
* @throws URISyntaxException if the URL wasn't a valid URI
* @see java.net.URL#toURI()
+ * @see #toURI(String)
*/
public static URI toURI(URL url) throws URISyntaxException {
return toURI(url.toString());
@@ -377,6 +388,7 @@ public abstract class ResourceUtils {
* @param location the location String to convert into a URI instance
* @return the URI instance
* @throws URISyntaxException if the location wasn't a valid URI
+ * @see #toURI(URL)
*/
public static URI toURI(String location) throws URISyntaxException {
return new URI(StringUtils.replace(location, " ", "%20"));
@@ -389,6 +401,7 @@ public abstract class ResourceUtils {
* @return the URL instance
* @throws MalformedURLException if the location wasn't a valid URL
* @since 6.0
+ * @see java.net.URL#URL(String)
*/
public static URL toURL(String location) throws MalformedURLException {
// Equivalent without java.net.URL constructor - for building on JDK 20+
@@ -414,6 +427,7 @@ public abstract class ResourceUtils {
* @return the relative URL instance
* @throws MalformedURLException if the end result is not a valid URL
* @since 6.0
+ * @see java.net.URL#URL(URL, String)
*/
public static URL toRelativeURL(URL root, String relativePath) throws MalformedURLException {
// # can appear in filenames, java.net.URL should not treat it as a fragment
@@ -429,9 +443,10 @@ public abstract class ResourceUtils {
/**
* Set the {@link URLConnection#setUseCaches "useCaches"} flag on the
- * given connection, preferring {@code false} but leaving the
- * flag at {@code true} for JNLP based resources.
+ * given connection, preferring {@code false} but leaving the flag at
+ * {@code true} for JNLP based resources.
* @param con the URLConnection to set the flag on
+ * @see URLConnection#setUseCaches
*/
public static void useCachesIfNecessary(URLConnection con) {
con.setUseCaches(con.getClass().getSimpleName().startsWith("JNLP"));