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

    • 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