root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 8 Packages Projects Releases Wiki Activity

Overhaul Javadoc for PathMatchingResourcePatternResolver

This commit is contained in:
Sam Brannen 2023-11-19 14:27:41 +01:00
parent 194747a80c
commit 69049a4b0f
1 changed files with 118 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

213
spring-core/src/main/java/org/springframework/core/io/support/PathMatchingResourcePatternResolver.java
View File

@ -71,18 +71,18 @@ import org.springframework.util.StringUtils;
/**
* A {@link ResourcePatternResolver} implementation that is able to resolve a
* specified resource location path into one or more matching Resources.
* 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 regular expressions (matched using Spring's
* {@link org.springframework.util.AntPathMatcher} utility).
* Both of the latter are effectively wildcards.
*
* <p><b>No Wildcards:</b>
* <p>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.
*
* <h3>No Wildcards</h3>
*
* <p>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}).
*
* <p><b>Ant-style Patterns:</b>
* <h3>Ant-style Patterns</h3>
*
* <p>When the path location contains an Ant-style pattern, e.g.:
* <p>When the path location contains an Ant-style pattern, for example:
* <pre class="code">
* /WEB-INF/*-context.xml
* com/mycompany/**&#47;applicationContext.xml
* com/example/**&#47;applicationContext.xml
* file:C:/some/path/*-context.xml
* classpath:com/mycompany/**&#47;applicationContext.xml</pre>
* classpath:com/example/**&#47;applicationContext.xml</pre>
* 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.
*
* <p><b>Implications on portability:</b>
* <h3>Implications on Portability</h3>
*
* <p>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.
*
* <p>If the specified path is a classpath location, then the resolver must
* <p>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.
*
* <p>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.
*
* <p><b>{@code classpath*:} Prefix:</b>
* <h3>{@code classpath*:} Prefix</h3>
*
* <p>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.
*
* <p>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.
* <p>The "{@code classpath*:}" prefix can also be combined with a {@code PathMatcher}
* pattern in the rest of the location path &mdash; 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.
*
* <p><b>Other notes:</b>
* <h3>Other Notes</h3>
*
* <p>As of Spring Framework 6.0, if {@link #getResources(String)} is invoked
* with a location pattern using the "classpath*:" prefix it will first search
* <p>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.
*
* <p><b>WARNING:</b> 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.
*
* <p><b>WARNING:</b> Ant-style patterns with "classpath:" resources are not
* guaranteed to find matching resources if the root package to search is available
* <p><b>WARNING:</b> 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
* <pre class="code">
* com/mycompany/package1/service-context.xml
* </pre>
* may be in only one location, but when a path such as
* com/example/package1/service-context.xml</pre>
* may exist in only one class path location, but when a location pattern such as
* <pre class="code">
* classpath:com/mycompany/**&#47;service-context.xml
* </pre>
* classpath:com/example/**&#47;service-context.xml</pre>
* 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 <i>all</i> 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 <i>all</i> 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}.
* <p>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}.
* <p>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.
* <p>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
* <p>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
@ -370,9 +374,10 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
}
/**
* Find all class location resources with the given path via the ClassLoader.
* Called by {@link #findAllClassPathResources(String)}.
* @param path the absolute path within the classpath (never a leading slash)
* Find all class path resources with the given path via the configured
* {@link #getClassLoader() ClassLoader}.
* <p>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
*/
@ -393,13 +398,14 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
}
/**
* 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}).
* <p>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
@ -476,8 +482,10 @@ 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
*/
@ -542,14 +550,18 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
}
/**
* Find all resources that match the given location pattern via the
* Ant-style PathMatcher. Supports resources in OSGi bundles, JBoss VFS,
* jar files, zip files, and file systems.
* Find all resources that match the given location pattern via the Ant-style
* {@link #getPathMatcher() PathMatcher}.
* <p>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 {
@ -606,29 +618,39 @@ public class PathMatchingResourcePatternResolver implements ResourcePatternResol
}
/**
* Resolve the specified resource for path matching.
* <p>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.
* <p>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.
* <p>For any custom resolution, override this template method and replace the
* supplied resource handle accordingly.
* <p>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.
* <p>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.
* <p>{@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.
* <p>This template method therefore allows for detecting further kinds of
* jar-like resources &mdash; for example, via {@code instanceof} checks on
* the resource handle type.
* <p>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 {
@ -637,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)
@ -745,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
@ -923,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()) ?