## org.springframework.core.io.support
Class PathMatchingResourcePatternResolver

    java.lang.Object
      org.springframework.core.io.support.PathMatchingResourcePatternResolver

All Implemented Interfaces:
  ResourceLoader, ResourcePatternResolver

Direct Known Subclasses:
  PortletContextResourcePatternResolver, ServletContextResourcePatternResolver

    public class PathMatchingResourcePatternResolver

extends Object
implements ResourcePatternResolver

A `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 `Resource`, or alternatively may contain the special "`classpath*:`" prefix and/or internal Ant-style regular expressions (matched using Spring's `AntPathMatcher` utility). Both of the latter are effectively wildcards.

No Wildcards:

In the simple case, if the specified location path does not start with the `"classpath*:`" prefix, and does not contain a PathMatcher pattern, this resolver will simply return a single resource via a `getResource()` call on the underlying `ResourceLoader`. Examples are real URLs such as "`file:C:/context.xml`", pseudo-URLs such as "`classpath:/context.xml`", and simple unprefixed paths such as "`/WEB-INF/context.xml`". The latter will resolve in a fashion specific to the underlying `ResourceLoader` (e.g. `ServletContextResource` for a `WebApplicationContext`).

Ant-style Patterns:

When the path location contains an Ant-style pattern, e.g.:

     /WEB-INF/*-context.xml
     com/mycompany/**/applicationContext.xml
     file:C:/some/path/*-context.xml
     classpath:com/mycompany/**/applicationContext.xml

the resolver follows a more complex but defined procedure to try to resolve the wildcard. It produces a `Resource` for the path up to the last non-wildcard segment and obtains a `URL` from it. If this URL is not a "`jar:`" URL or container-specific variant (e.g. "`zip:`" in WebLogic, "`wsjar`" in WebSphere", etc.), then a `java.io.File` is obtained from it, and used to resolve the wildcard by walking the filesystem. In the case of a jar URL, the resolver either gets a `java.net.JarURLConnection` from it, or manually parse the jar URL, and then traverse 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 `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 obtain the last non-wildcard path segment URL via a `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 a URL is returned in this case. In practice, it is usually a `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 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 `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 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.

`classpath*:` Prefix:

There is special support for retrieving multiple class path resources with the same name, via the "`classpath*:`" prefix. For example, "`classpath*:META-INF/beans.xml`" will find all "beans.xml" files in the class path, be it in "classes" directories or in JAR files. This is particularly useful for autodetecting config files of the same name at the same location within each jar file. Internally, this happens via a `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 `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 subpath.

Other notes:

WARNING: Note that "`classpath*:`" when combined with Ant-style patterns will only work reliably with at least one root directory before the pattern starts, unless the actual target files reside in the file system. This means that a pattern like "`classpath*:*.xml`" will not retrieve files from the root of jar files but rather only from the root of expanded directories. This originates from a limitation in the JDK's `ClassLoader.getResources()` method which only returns file system locations for a passed-in empty String (indicating potential roots to search).

WARNING: Ant-style patterns with "classpath:" resources are not guaranteed to find matching resources if the root 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

         classpath:com/mycompany/**/service-context.xml

is used to try to resolve it, the resolver will work off the (first) URL returned by `getResource("com/mycompany");`. If this base package node exists in multiple classloader locations, the actual end resource may not be underneath. Therefore, preferably, use "`classpath*:`" with the same Ant-style pattern in such a case, which will search all class path locations that contain the root package.

Since:
  1.0.2
Author:
  Juergen Hoeller, Colin Sampaleanu
See Also:
  `ResourcePatternResolver.CLASSPATH_ALL_URL_PREFIX`, `AntPathMatcher`, `ResourceLoader.getResource(String)`, `ClassLoader.getResources(String)`

Field Summary

Fields inherited from interface org.springframework.core.io.support.ResourcePatternResolver
`CLASSPATH_ALL_URL_PREFIX`

Fields inherited from interface org.springframework.core.io.ResourceLoader
`CLASSPATH_URL_PREFIX`

Constructor Summary
`PathMatchingResourcePatternResolver()` Create a new PathMatchingResourcePatternResolver with a DefaultResourceLoader.
`PathMatchingResourcePatternResolver(ClassLoader classLoader)` Create a new PathMatchingResourcePatternResolver with a DefaultResourceLoader.
`PathMatchingResourcePatternResolver(ResourceLoader resourceLoader)` Create a new PathMatchingResourcePatternResolver.

Method Summary
`protected Resource` `convertClassLoaderURL(URL url)` Convert the given URL as returned from the ClassLoader into a Resource object.
`protected String` `determineRootDir(String location)` Determine the root directory for the given location.
`protected Set` `doFindMatchingFileSystemResources(File rootDir, String subPattern)` Find all resources in the file system that match the given location pattern via the Ant-style PathMatcher.
`protected Set` `doFindPathMatchingFileResources(Resource rootDirResource, String subPattern)` Find all resources in the file system that match the given location pattern via the Ant-style PathMatcher.
`protected Set` `doFindPathMatchingJarResources(Resource rootDirResource, String subPattern)` Find all resources in jar files that match the given location pattern via the Ant-style PathMatcher.
`protected void` `doRetrieveMatchingFiles(String fullPattern, File dir, Set result)` Recursively retrieve files that match the given pattern, adding them to the given result list.
`protected Resource[]` `findAllClassPathResources(String location)` Find all class location resources with the given location via the ClassLoader.
`protected Resource[]` `findPathMatchingResources(String locationPattern)` Find all resources that match the given location pattern via the Ant-style PathMatcher.
`ClassLoader` `getClassLoader()` Return the ClassLoader that this pattern resolver works with (never `null`).
`protected JarFile` `getJarFile(String jarFileUrl)` Resolve the given jar file URL into a JarFile object.
`PathMatcher` `getPathMatcher()` Return the PathMatcher that this resource pattern resolver uses.
`Resource` `getResource(String location)` Return a Resource handle for the specified resource.
`ResourceLoader` `getResourceLoader()` Return the ResourceLoader that this pattern resolver works with.
`Resource[]` `getResources(String locationPattern)` Resolve the given location pattern into Resource objects.
`protected boolean` `isJarResource(Resource resource)` Return whether the given resource handle indicates a jar resource that the `doFindPathMatchingJarResources` method can handle.
`protected Resource` `resolveRootDirResource(Resource original)` Resolve the specified resource for path matching.
`protected Set` `retrieveMatchingFiles(File rootDir, String pattern)` Retrieve files that match the given path pattern, checking the given directory and its subdirectories.
`void` `setPathMatcher(PathMatcher pathMatcher)` Set the PathMatcher implementation to use for this resource pattern resolver.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### PathMatchingResourcePatternResolver

    public PathMatchingResourcePatternResolver()

  Create a new PathMatchingResourcePatternResolver with a DefaultResourceLoader.

  ClassLoader access will happen via the thread context class loader.

  See Also:
    `DefaultResourceLoader`

### PathMatchingResourcePatternResolver

    public PathMatchingResourcePatternResolver(ClassLoader classLoader)

  Create a new PathMatchingResourcePatternResolver with a DefaultResourceLoader.

  Parameters:
    `classLoader` - the ClassLoader to load classpath resources with, or `null` for using the thread context class loader
  See Also:
    `DefaultResourceLoader`

### PathMatchingResourcePatternResolver

    public PathMatchingResourcePatternResolver(ResourceLoader resourceLoader)

  Create a new PathMatchingResourcePatternResolver.

  ClassLoader access will happen via the thread context class loader.

  Parameters:
    `resourceLoader` - the ResourceLoader to load root directories and actual resources with

Method Detail

### getResourceLoader

    public ResourceLoader getResourceLoader()

  Return the ResourceLoader that this pattern resolver works with.

### getClassLoader

    public ClassLoader getClassLoader()

  Return the ClassLoader that this pattern resolver works with (never `null`).

  Specified by:
    `getClassLoader` in interface `ResourceLoader`
  Returns:
    the ClassLoader (never `null`)

### setPathMatcher

    public void setPathMatcher(PathMatcher pathMatcher)

  Set the PathMatcher implementation to use for this resource pattern resolver. Default is AntPathMatcher.

  See Also:
    `AntPathMatcher`

### getPathMatcher

    public PathMatcher getPathMatcher()

  Return the PathMatcher that this resource pattern resolver uses.

### getResource

    public Resource getResource(String location)

  Description copied from interface: `ResourceLoader`
  Return a Resource handle for the specified resource. The handle should always be a reusable resource descriptor, allowing for multiple `InputStreamSource.getInputStream()` calls.

  - Must support fully qualified URLs, e.g. "file:C:/test.dat".
  - Must support classpath pseudo-URLs, e.g. "classpath:test.dat".
  - Should support relative file paths, e.g. "WEB-INF/test.dat". (This will be implementation-specific, typically provided by an ApplicationContext implementation.)

  Note that a Resource handle does not imply an existing resource; you need to invoke `Resource.exists()` to check for existence.

  Specified by:
    `getResource` in interface `ResourceLoader`
  Parameters:
    `location` - the resource location
  Returns:
    a corresponding Resource handle
  See Also:
    `ResourceLoader.CLASSPATH_URL_PREFIX`, `Resource.exists()`, `InputStreamSource.getInputStream()`

### getResources

    public Resource[] getResources(String locationPattern)
                            throws IOException

  Description copied from interface: `ResourcePatternResolver`
  Resolve the given location pattern into Resource objects.

  Overlapping resource entries that point to the same physical resource should be avoided, as far as possible. The result should have set semantics.

  Specified by:
    `getResources` in interface `ResourcePatternResolver`
  Parameters:
    `locationPattern` - the location pattern to resolve
  Returns:
    the corresponding Resource objects
  Throws:
    `IOException` - in case of I/O errors

### findAllClassPathResources

    protected Resource[] findAllClassPathResources(String location)
                                            throws IOException

  Find all class location resources with the given location via the ClassLoader.

  Parameters:
    `location` - the absolute path within the classpath
  Returns:
    the result as Resource array
  Throws:
    `IOException` - in case of I/O errors
  See Also:
    `ClassLoader.getResources(java.lang.String)`, `convertClassLoaderURL(java.net.URL)`

### convertClassLoaderURL

    protected Resource convertClassLoaderURL(URL url)

  Convert the given URL as returned from the ClassLoader into a Resource object.

  The default implementation simply creates a UrlResource instance.

  Parameters:
    `url` - a URL as returned from the ClassLoader
  Returns:
    the corresponding Resource object
  See Also:
    `ClassLoader.getResources(java.lang.String)`, `Resource`

### findPathMatchingResources

    protected Resource[] findPathMatchingResources(String locationPattern)
                                            throws IOException

  Find all resources that match the given location pattern via the Ant-style PathMatcher. Supports resources in jar files and zip files and in the file system.

  Parameters:
    `locationPattern` - the location pattern to match
  Returns:
    the result as Resource array
  Throws:
    `IOException` - in case of I/O errors
  See Also:
    `doFindPathMatchingJarResources(org.springframework.core.io.Resource, java.lang.String)`, `doFindPathMatchingFileResources(org.springframework.core.io.Resource, java.lang.String)`, `PathMatcher`

### determineRootDir

    protected String determineRootDir(String location)

  Determine the root directory for the given location.

  Used for determining the starting point for file matching, resolving the root directory location to a `java.io.File` and passing it into `retrieveMatchingFiles`, with the remainder of the location as pattern.

  Will return "/WEB-INF" for the pattern "/WEB-INF/*.xml", for example.

  Parameters:
    `location` - the location to check
  Returns:
    the part of the location that denotes the root directory
  See Also:
    `retrieveMatchingFiles(java.io.File, java.lang.String)`

### resolveRootDirResource

    protected Resource resolveRootDirResource(Resource original)
                                       throws IOException

  Resolve the specified resource for path matching.

  The default implementation detects an Equinox OSGi "bundleresource:" / "bundleentry:" URL and resolves it into a standard jar file URL that can be traversed using Spring's standard jar file traversal algorithm.

  Parameters:
    `original` - the resource to resolfe
  Returns:
    the resolved resource (may be identical to the passed-in resource)
  Throws:
    `IOException` - in case of resolution failure

### isJarResource

    protected boolean isJarResource(Resource resource)
                             throws IOException

  Return whether the given resource handle indicates a jar resource that the `doFindPathMatchingJarResources` method can handle.

  The default implementation checks against the URL protocols "jar", "zip" and "wsjar" (the latter are used by BEA WebLogic Server and IBM WebSphere, respectively, but can be treated like jar files).

  Parameters:
    `resource` - the resource handle to check (usually the root directory to start path matching from)
  Throws:
    `IOException`
  See Also:
    `doFindPathMatchingJarResources(org.springframework.core.io.Resource, java.lang.String)`, `ResourceUtils.isJarURL(java.net.URL)`

### doFindPathMatchingJarResources

    protected Set doFindPathMatchingJarResources(Resource rootDirResource,
                                                 String subPattern)
                                          throws IOException

  Find all resources in jar files that match the given location pattern via the Ant-style PathMatcher.

  Parameters:
    `rootDirResource` - the root directory as Resource
    `subPattern` - the sub pattern to match (below the root directory)
  Returns:
    the Set of matching Resource instances
  Throws:
    `IOException` - in case of I/O errors
  See Also:
    `JarURLConnection`, `PathMatcher`

### getJarFile

    protected JarFile getJarFile(String jarFileUrl)
                          throws IOException

  Resolve the given jar file URL into a JarFile object.

  Throws:
    `IOException`

### doFindPathMatchingFileResources

    protected Set doFindPathMatchingFileResources(Resource rootDirResource,
                                                  String subPattern)
                                           throws IOException

  Find all resources in the file system that match the given location pattern via the Ant-style PathMatcher.

  Parameters:
    `rootDirResource` - the root directory as Resource
    `subPattern` - the sub pattern to match (below the root directory)
  Returns:
    the Set of matching Resource instances
  Throws:
    `IOException` - in case of I/O errors
  See Also:
    `retrieveMatchingFiles(java.io.File, java.lang.String)`, `PathMatcher`

### doFindMatchingFileSystemResources

    protected Set doFindMatchingFileSystemResources(File rootDir,
                                                    String subPattern)
                                             throws IOException

  Find all resources in the file system that match the given location pattern via the Ant-style PathMatcher.

  Parameters:
    `rootDir` - the root directory in the file system
    `subPattern` - the sub pattern to match (below the root directory)
  Returns:
    the Set of matching Resource instances
  Throws:
    `IOException` - in case of I/O errors
  See Also:
    `retrieveMatchingFiles(java.io.File, java.lang.String)`, `PathMatcher`

### retrieveMatchingFiles

    protected Set retrieveMatchingFiles(File rootDir,
                                        String pattern)
                                 throws IOException

  Retrieve files that match the given path pattern, checking the given directory and its subdirectories.

  Parameters:
    `rootDir` - the directory to start from
    `pattern` - the pattern to match against, relative to the root directory
  Returns:
    the Set of matching File instances
  Throws:
    `IOException` - if directory contents could not be retrieved

### doRetrieveMatchingFiles

    protected void doRetrieveMatchingFiles(String fullPattern,
                                           File dir,
                                           Set result)
                                    throws IOException

  Recursively retrieve files that match the given pattern, adding them to the given result list.

  Parameters:
    `fullPattern` - the pattern to match against, with preprended root directory path
    `dir` - the current directory
    `result` - the Set of matching File instances to add to
  Throws:
    `IOException` - if directory contents could not be retrieved

Copyright © 2002-2008 The Spring Framework.
``