Package org.apache.struts2.util.finder

# Class ResourceFinder

java.lang.Object
org.apache.struts2.util.finder.ResourceFinder

public class ResourceFinder extends Object

Author:
  David Blevins

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ResourceFinder(String path)`
  `ResourceFinder(String path, URL... urls)`
  `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(URL... urls)`

- ## Method Summary

  Modifier and Type
  Method
  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 Details

  - ### 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 Details

  - ### 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