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

  - ### Method Summary

    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)

  - ### 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–2018 Apache Software Foundation. All rights reserved.