com.opensymphony.xwork2.util.finder

## Class ResourceFinder

- java.lang.Object
- - com.opensymphony.xwork2.util.finder.ResourceFinder

-     public class ResourceFinder
      extends Object

  Author:
    David Blevins

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ResourceFinder(String path)`
    `ResourceFinder(String path, ClassLoaderInterface classLoaderInterface)`
    `ResourceFinder(String path, ClassLoaderInterface classLoaderInterface, URL... urls)` Create a ResourceFinder instance for looking up resources (via ClassLoader or via specific URLs specifying resource locations).
    `ResourceFinder(String path, URL... urls)`
    `ResourceFinder(URL... urls)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `URL` | `find(String uri)`
    `List<URL>` | `findAll(String uri)`
    `List<Class>` | `findAllClasses(String uri)` Executes findAllStrings assuming the strings are the names of a classes that should be loaded and returned.
    `List<Class>` | `findAllImplementations(Class interfase)` Assumes the class specified points to a file in the classpath that contains the name of a class that implements or is a subclass of the specfied class.
    `List<Properties>` | `findAllProperties(String uri)` Finds the corresponding resources and reads them in as a properties files
    `List<String>` | `findAllStrings(String uri)` Reads the contents of the found URLs as a list of `String`'s and returns them.
    `List<Class>` | `findAvailableClasses(String uri)` Executes findAvailableStrings assuming the strings are the names of a classes that should be loaded and returned.
    `List<Class>` | `findAvailableImplementations(Class interfase)` Assumes the class specified points to a file in the classpath that contains the name of a class that implements or is a subclass of the specfied class.
    `List<Properties>` | `findAvailableProperties(String uri)` Finds the corresponding resources and reads them in as a properties files
    `List<String>` | `findAvailableStrings(String uri)` Reads the contents of the found URLs as a Strings and returns them.
    `Class` | `findClass(String uri)` Executes `findString(String)` assuming the contents URL found is the name of a class that should be loaded and returned.
    `Class` | `findImplementation(Class interfase)` Assumes the class specified points to a file in the classpath that contains the name of a class that implements or is a subclass of the specfied class.
    `Set<String>` | `findPackages(String uri)`
    `Map<URL,Set<String>>` | `findPackagesMap(String uri)`
    `Properties` | `findProperties(String uri)` Finds the corresponding resource and reads it in as a properties file
    `String` | `findString(String uri)` Reads the contents of the URL as a `String`'s and returns it.
    `Map<String,URL>` | `getResourcesMap(String uri)`
    `List<String>` | `getResourcesNotLoaded()` Returns a list of resources that could not be loaded in the last invoked findAvailable* or mapAvailable* methods.
    `Map<String,Class>` | `mapAllClasses(String uri)` Executes mapAllStrings assuming the value of each entry in the map is the name of a class that should be loaded.
    `Map<String,Class>` | `mapAllImplementations(Class interfase)` Assumes the class specified points to a directory in the classpath that holds files containing the name of a class that implements or is a subclass of the specified class.
    `Map<String,Properties>` | `mapAllProperties(String uri)` Finds the corresponding resources and reads them in as a properties files
    `Map<String,String>` | `mapAllStrings(String uri)` Reads the contents of all non-directory URLs immediately under the specified location and returns them in a map keyed by the file name.
    `Map<String,Class>` | `mapAvailableClasses(String uri)` Executes mapAvailableStrings assuming the value of each entry in the map is the name of a class that should be loaded.
    `Map<String,Class>` | `mapAvailableImplementations(Class interfase)` Assumes the class specified points to a directory in the classpath that holds files containing the name of a class that implements or is a subclass of the specified class.
    `Map<String,Properties>` | `mapAvailableProperties(String uri)` Finds the corresponding resources and reads them in as a properties files
    `Map<String,String>` | `mapAvailableStrings(String uri)` Reads the contents of all non-directory URLs immediately under the specified location and returns them in a map keyed by the file name.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ResourceFinder

          public ResourceFinder(URL... urls)

    - #### ResourceFinder

          public ResourceFinder(String path)

    - #### ResourceFinder

          public ResourceFinder(String path,
                                URL... urls)

    - #### ResourceFinder

          public ResourceFinder(String path,
                                ClassLoaderInterface classLoaderInterface)

    - #### ResourceFinder

          public ResourceFinder(String path,
                                ClassLoaderInterface classLoaderInterface,
                                URL... urls)

      Create a ResourceFinder instance for looking up resources (via ClassLoader or via specific URLs specifying resource locations). This class was functional in Struts 2.3.x, but broken for Struts 2.5.x (before 2.5.24), when dealing with JAR resources in certain circumstances. The current logic permits the base path to be "" (empty string), which is required to also match JAR entries rooted at "" and not just file entries rooted at "/".
      Parameters:
        `path` - Base path from which to look for resources (typically "xyz/abc/klm" form for file or jar contents).
        `classLoaderInterface` - ClassLoader to perform the resource lookup. If null, a default Thread ClassLoader will be used.
        `urls` - URLs (typically file: or jar:) within which to search for resources, instead of the ClassLoader. If null, fallback to a ClassLoader instead.

  - ### Method Detail

    - #### getResourcesNotLoaded

          public List<String> getResourcesNotLoaded()

      Returns a list of resources that could not be loaded in the last invoked findAvailable* or mapAvailable* methods.

      The list will only contain entries of resources that match the requirements of the last invoked findAvailable* or mapAvailable* methods, but were unable to be loaded and included in their results.

      The list returned is unmodifiable and the results of this method will change after each invocation of a findAvailable* or mapAvailable* methods.

      This method is not thread safe.
      Returns:
        not loaded resources

    - #### find

          public URL find(String uri)
                   throws IOException

      Throws:
        `IOException`

    - #### findAll

          public List<URL> findAll(String uri)
                            throws IOException

      Throws:
        `IOException`

    - #### findString

          public String findString(String uri)
                            throws IOException

      Reads the contents of the URL as a `String`'s and returns it.
      Parameters:
        `uri` - URL
      Returns:
        a stringified content of a resource
      Throws:
        `IOException` - if a resource pointed out by the uri param could not be find
      See Also:
        `ClassLoader.getResource(String)`

    - #### findAllStrings

          public List<String> findAllStrings(String uri)
                                      throws IOException

      Reads the contents of the found URLs as a list of `String`'s and returns them.
      Parameters:
        `uri` - URL
      Returns:
        a list of the content of each resource URL found
      Throws:
        `IOException` - if any of the found URLs are unable to be read.

    - #### findAvailableStrings

          public List<String> findAvailableStrings(String uri)
                                            throws IOException

      Reads the contents of the found URLs as a Strings and returns them. Individual URLs that cannot be read are skipped and added to the list of 'resourcesNotLoaded'
      Parameters:
        `uri` - URL
      Returns:
        a list of the content of each resource URL found
      Throws:
        `IOException` - if classLoader.getResources throws an exception

    - #### mapAllStrings

          public Map<String,String> mapAllStrings(String uri)
                                           throws IOException

      Reads the contents of all non-directory URLs immediately under the specified location and returns them in a map keyed by the file name.

      Any URLs that cannot be read will cause an exception to be thrown.

      Example classpath:

           META-INF/serializables/one
           META-INF/serializables/two
           META-INF/serializables/three
           META-INF/serializables/four/foo.txt

           ResourceFinder finder = new ResourceFinder("META-INF/");
           Map map = finder.mapAvailableStrings("serializables");
           map.contains("one");  // true
           map.contains("two");  // true
           map.contains("three");  // true
           map.contains("four");  // false

      Parameters:
        `uri` - URL
      Returns:
        a list of the content of each resource URL found
      Throws:
        `IOException` - if any of the urls cannot be read

    - #### mapAvailableStrings

          public Map<String,String> mapAvailableStrings(String uri)
                                                 throws IOException

      Reads the contents of all non-directory URLs immediately under the specified location and returns them in a map keyed by the file name.

      Individual URLs that cannot be read are skipped and added to the list of 'resourcesNotLoaded'

      Example classpath:

           META-INF/serializables/one
           META-INF/serializables/two      # not readable
           META-INF/serializables/three
           META-INF/serializables/four/foo.txt

           ResourceFinder finder = new ResourceFinder("META-INF/");
           Map map = finder.mapAvailableStrings("serializables");
           map.contains("one");  // true
           map.contains("two");  // false
           map.contains("three");  // true
           map.contains("four");  // false

      Parameters:
        `uri` - URL
      Returns:
        a list of the content of each resource URL found
      Throws:
        `IOException` - if classLoader.getResources throws an exception

    - #### findClass

          public Class findClass(String uri)
                          throws IOException,
                                 ClassNotFoundException

      Executes `findString(String)` assuming the contents URL found is the name of a class that should be loaded and returned.
      Parameters:
        `uri` - URL
      Returns:
        class that should be loaded
      Throws:
        `IOException` - in case of IO errors
        `ClassNotFoundException` - when class is not found

    - #### findAllClasses

          public List<Class> findAllClasses(String uri)
                                     throws IOException,
                                            ClassNotFoundException

      Executes findAllStrings assuming the strings are the names of a classes that should be loaded and returned.

      Any URL or class that cannot be loaded will cause an exception to be thrown.

      Parameters:
        `uri` - URL
      Returns:
        classes that should be loaded
      Throws:
        `IOException` - in case of IO errors
        `ClassNotFoundException` - when class is not found

    - #### findAvailableClasses

          public List<Class> findAvailableClasses(String uri)
                                           throws IOException

      Executes findAvailableStrings assuming the strings are the names of a classes that should be loaded and returned.

      Any class that cannot be loaded will be skipped and placed in the 'resourcesNotLoaded' collection.

      Parameters:
        `uri` - URL
      Returns:
        list of available classes
      Throws:
        `IOException` - if classLoader.getResources throws an exception

    - #### mapAllClasses

          public Map<String,Class> mapAllClasses(String uri)
                                          throws IOException,
                                                 ClassNotFoundException

      Executes mapAllStrings assuming the value of each entry in the map is the name of a class that should be loaded.

      Any class that cannot be loaded will be cause an exception to be thrown.

      Example classpath:

           META-INF/xmlparsers/xerces
           META-INF/xmlparsers/crimson

           ResourceFinder finder = new ResourceFinder("META-INF/");
           Map map = finder.mapAvailableStrings("xmlparsers");
           map.contains("xerces");  // true
           map.contains("crimson");  // true
           Class xercesClass = map.get("xerces");
           Class crimsonClass = map.get("crimson");

      Parameters:
        `uri` - URL
      Returns:
        map of all classes
      Throws:
        `IOException` - in case of IO errors
        `ClassNotFoundException` - when class is not found

    - #### mapAvailableClasses

          public Map<String,Class> mapAvailableClasses(String uri)
                                                throws IOException

      Executes mapAvailableStrings assuming the value of each entry in the map is the name of a class that should be loaded.

      Any class that cannot be loaded will be skipped and placed in the 'resourcesNotLoaded' collection.

      Example classpath:

           META-INF/xmlparsers/xerces
           META-INF/xmlparsers/crimson

           ResourceFinder finder = new ResourceFinder("META-INF/");
           Map map = finder.mapAvailableStrings("xmlparsers");
           map.contains("xerces");  // true
           map.contains("crimson");  // true
           Class xercesClass = map.get("xerces");
           Class crimsonClass = map.get("crimson");

      Parameters:
        `uri` - URL
      Returns:
        map of available classes
      Throws:
        `IOException` - if classLoader.getResources throws an exception

    - #### findImplementation

          public Class findImplementation(Class interfase)
                                   throws IOException,
                                          ClassNotFoundException

      Assumes the class specified points to a file in the classpath that contains the name of a class that implements or is a subclass of the specfied class.

      Any class that cannot be loaded will be cause an exception to be thrown.

      Example classpath:

           META-INF/java.io.InputStream    # contains the classname org.acme.AcmeInputStream
           META-INF/java.io.OutputStream

           ResourceFinder finder = new ResourceFinder("META-INF/");
           Class clazz = finder.findImplementation(java.io.InputStream.class);
           clazz.getName();  // returns "org.acme.AcmeInputStream"

      Parameters:
        `interfase` - a superclass or interface
      Returns:
        implementation class
      Throws:
        `IOException` - if the URL cannot be read
        `ClassNotFoundException` - if the class found is not loadable
        `ClassCastException` - if the class found is not assignable to the specified superclass or interface

    - #### findAllImplementations

          public List<Class> findAllImplementations(Class interfase)
                                             throws IOException,
                                                    ClassNotFoundException

      Assumes the class specified points to a file in the classpath that contains the name of a class that implements or is a subclass of the specfied class.

      Any class that cannot be loaded or assigned to the specified interface will be cause an exception to be thrown.

      Example classpath:

           META-INF/java.io.InputStream    # contains the classname org.acme.AcmeInputStream
           META-INF/java.io.InputStream    # contains the classname org.widget.NeatoInputStream
           META-INF/java.io.InputStream    # contains the classname com.foo.BarInputStream

           ResourceFinder finder = new ResourceFinder("META-INF/");
           List classes = finder.findAllImplementations(java.io.InputStream.class);
           classes.contains("org.acme.AcmeInputStream");  // true
           classes.contains("org.widget.NeatoInputStream");  // true
           classes.contains("com.foo.BarInputStream");  // true

      Parameters:
        `interfase` - a superclass or interface
      Returns:
        list of implementation classes
      Throws:
        `IOException` - if the URL cannot be read
        `ClassNotFoundException` - if the class found is not loadable
        `ClassCastException` - if the class found is not assignable to the specified superclass or interface

    - #### findAvailableImplementations

          public List<Class> findAvailableImplementations(Class interfase)
                                                   throws IOException

      Assumes the class specified points to a file in the classpath that contains the name of a class that implements or is a subclass of the specfied class.

      Any class that cannot be loaded or are not assignable to the specified class will be skipped and placed in the 'resourcesNotLoaded' collection.

      Example classpath:

           META-INF/java.io.InputStream    # contains the classname org.acme.AcmeInputStream
           META-INF/java.io.InputStream    # contains the classname org.widget.NeatoInputStream
           META-INF/java.io.InputStream    # contains the classname com.foo.BarInputStream

           ResourceFinder finder = new ResourceFinder("META-INF/");
           List classes = finder.findAllImplementations(java.io.InputStream.class);
           classes.contains("org.acme.AcmeInputStream");  // true
           classes.contains("org.widget.NeatoInputStream");  // true
           classes.contains("com.foo.BarInputStream");  // true

      Parameters:
        `interfase` - a superclass or interface
      Returns:
        list of implementation classes
      Throws:
        `IOException` - if classLoader.getResources throws an exception

    - #### mapAllImplementations

          public Map<String,Class> mapAllImplementations(Class interfase)
                                                  throws IOException,
                                                         ClassNotFoundException

      Assumes the class specified points to a directory in the classpath that holds files containing the name of a class that implements or is a subclass of the specified class.

      Any class that cannot be loaded or assigned to the specified interface will be cause an exception to be thrown.

      Example classpath:

           META-INF/java.net.URLStreamHandler/jar
           META-INF/java.net.URLStreamHandler/file
           META-INF/java.net.URLStreamHandler/http

           ResourceFinder finder = new ResourceFinder("META-INF/");
           Map map = finder.mapAllImplementations(java.net.URLStreamHandler.class);
           Class jarUrlHandler = map.get("jar");
           Class fileUrlHandler = map.get("file");
           Class httpUrlHandler = map.get("http");

      Parameters:
        `interfase` - a superclass or interface
      Returns:
        map of implementation classes
      Throws:
        `IOException` - if the URL cannot be read
        `ClassNotFoundException` - if the class found is not loadable
        `ClassCastException` - if the class found is not assignable to the specified superclass or interface

    - #### mapAvailableImplementations

          public Map<String,Class> mapAvailableImplementations(Class interfase)
                                                        throws IOException

      Assumes the class specified points to a directory in the classpath that holds files containing the name of a class that implements or is a subclass of the specified class.

      Any class that cannot be loaded or are not assignable to the specified class will be skipped and placed in the 'resourcesNotLoaded' collection.

      Example classpath:

           META-INF/java.net.URLStreamHandler/jar
           META-INF/java.net.URLStreamHandler/file
           META-INF/java.net.URLStreamHandler/http

           ResourceFinder finder = new ResourceFinder("META-INF/");
           Map map = finder.mapAllImplementations(java.net.URLStreamHandler.class);
           Class jarUrlHandler = map.get("jar");
           Class fileUrlHandler = map.get("file");
           Class httpUrlHandler = map.get("http");

      Parameters:
        `interfase` - a superclass or interface
      Returns:
        list of available implementation classes
      Throws:
        `IOException` - if classLoader.getResources throws an exception

    - #### findProperties

          public Properties findProperties(String uri)
                                    throws IOException

      Finds the corresponding resource and reads it in as a properties file

      Example classpath:

           META-INF/widget.properties

           ResourceFinder finder = new ResourceFinder("META-INF/");
           Properties widgetProps = finder.findProperties("widget.properties");

      Parameters:
        `uri` - URL
      Returns:
        corresponding resource as properties
      Throws:
        `IOException` - if the URL cannot be read or is not in properties file format

    - #### findAllProperties

          public List<Properties> findAllProperties(String uri)
                                             throws IOException

      Finds the corresponding resources and reads them in as a properties files

      Any URL that cannot be read in as a properties file will cause an exception to be thrown.

      Example classpath:

           META-INF/app.properties
           META-INF/app.properties
           META-INF/app.properties

           ResourceFinder finder = new ResourceFinder("META-INF/");
           List<Properties> appProps = finder.findAllProperties("app.properties");

      Parameters:
        `uri` - URL
      Returns:
        corresponding resource as list of properties
      Throws:
        `IOException` - if the URL cannot be read or is not in properties file format

    - #### findAvailableProperties

          public List<Properties> findAvailableProperties(String uri)
                                                   throws IOException

      Finds the corresponding resources and reads them in as a properties files

      Any URL that cannot be read in as a properties file will be added to the 'resourcesNotLoaded' collection.

      Example classpath:

           META-INF/app.properties
           META-INF/app.properties
           META-INF/app.properties

           ResourceFinder finder = new ResourceFinder("META-INF/");
           List<Properties> appProps = finder.findAvailableProperties("app.properties");

      Parameters:
        `uri` - URL
      Returns:
        corresponding resource as list of properties
      Throws:
        `IOException` - if classLoader.getResources throws an exception

    - #### mapAllProperties

          public Map<String,Properties> mapAllProperties(String uri)
                                                  throws IOException

      Finds the corresponding resources and reads them in as a properties files

      Any URL that cannot be read in as a properties file will cause an exception to be thrown.

      Example classpath:

           META-INF/jdbcDrivers/oracle.properties
           META-INF/jdbcDrivers/mysql.props
           META-INF/jdbcDrivers/derby

           ResourceFinder finder = new ResourceFinder("META-INF/");
           List<Properties> driversList = finder.findAvailableProperties("jdbcDrivers");
           Properties oracleProps = driversList.get("oracle.properties");
           Properties mysqlProps = driversList.get("mysql.props");
           Properties derbyProps = driversList.get("derby");

      Parameters:
        `uri` - URL
      Returns:
        corresponding resource as map of properties
      Throws:
        `IOException` - if the URL cannot be read or is not in properties file format

    - #### mapAvailableProperties

          public Map<String,Properties> mapAvailableProperties(String uri)
                                                        throws IOException

      Finds the corresponding resources and reads them in as a properties files

      Any URL that cannot be read in as a properties file will be added to the 'resourcesNotLoaded' collection.

      Example classpath:

           META-INF/jdbcDrivers/oracle.properties
           META-INF/jdbcDrivers/mysql.props
           META-INF/jdbcDrivers/derby

           ResourceFinder finder = new ResourceFinder("META-INF/");
           List<Properties> driversList = finder.findAvailableProperties("jdbcDrivers");
           Properties oracleProps = driversList.get("oracle.properties");
           Properties mysqlProps = driversList.get("mysql.props");
           Properties derbyProps = driversList.get("derby");

      Parameters:
        `uri` - URL
      Returns:
        corresponding resource as map of available properties
      Throws:
        `IOException` - if classLoader.getResources throws an exception

    - #### getResourcesMap

          public Map<String,URL> getResourcesMap(String uri)
                                          throws IOException

      Throws:
        `IOException`

    - #### findPackages

          public Set<String> findPackages(String uri)
                                   throws IOException

      Parameters:
        `uri` - URL
      Returns:
        set of subpackages from jars or dirs
      Throws:
        `IOException` - in case of IO errors

    - #### findPackagesMap

          public Map<URL,Set<String>> findPackagesMap(String uri)
                                               throws IOException

      Parameters:
        `uri` - URL
      Returns:
        a map of subpackages from jars or dirs
      Throws:
        `IOException` - in case of IO errors

Copyright © 2000–2023 Apache Software Foundation. All rights reserved.