Class ResourceLocator


  • public final class ResourceLocator
    extends java.lang.Object
    A locator for a resource, specified as a file, URL, path or classpath resource.

    An instance of this class provides access to a resource, such as a configuration file. The resource data is accessed using CharSource or ByteSource.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String CLASSPATH_URL_PREFIX
      The prefix for classpath resource locators.
      static java.lang.String FILE_URL_PREFIX
      The prefix for file resource locators.
      static java.lang.String URL_PREFIX
      The prefix for URL resource locators.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean equals​(java.lang.Object obj)
      Checks if this locator equals another locator.
      com.google.common.io.ByteSource getByteSource()
      Gets the byte source to access the resource.
      com.google.common.io.CharSource getCharSource()
      Gets the char source to access the resource using UTF-8.
      com.google.common.io.CharSource getCharSource​(java.nio.charset.Charset charset)
      Gets the char source to access the resource specifying the character set.
      java.lang.String getLocator()
      Gets the string form of the locator.
      int hashCode()
      Returns a suitable hash code for the locator.
      static ResourceLocator of​(java.lang.String locator)
      Creates a resource from a string locator.
      static ResourceLocator ofClasspath​(java.lang.Class<?> cls, java.lang.String resourceName)
      Creates a resource locator for a classpath resource which is associated with a class.
      static ResourceLocator ofClasspath​(java.lang.String resourceName)
      Creates a resource from a fully qualified resource name.
      static ResourceLocator ofClasspathUrl​(java.net.URL url)
      Creates a resource from a URL.
      static ResourceLocator ofFile​(java.io.File file)
      Creates a resource from a File.
      static ResourceLocator ofPath​(java.nio.file.Path path)
      Creates a resource from a Path.
      static ResourceLocator ofUrl​(java.net.URL url)
      Creates a resource from a URL.
      java.lang.String toString()
      Returns a string describing the locator.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • CLASSPATH_URL_PREFIX

        public static final java.lang.String CLASSPATH_URL_PREFIX
        The prefix for classpath resource locators.
        See Also:
        Constant Field Values
      • FILE_URL_PREFIX

        public static final java.lang.String FILE_URL_PREFIX
        The prefix for file resource locators.
        See Also:
        Constant Field Values
      • URL_PREFIX

        public static final java.lang.String URL_PREFIX
        The prefix for URL resource locators.
        See Also:
        Constant Field Values
    • Method Detail

      • of

        public static ResourceLocator of​(java.lang.String locator)
        Creates a resource from a string locator.

        This accepts locators starting with 'classpath:', 'url:' or 'file:'. It also accepts unprefixed locators, treated as files.

        Parameters:
        locator - the string form of the resource locator
        Returns:
        the resource locator
      • ofFile

        public static ResourceLocator ofFile​(java.io.File file)
        Creates a resource from a File.

        Windows separators are converted to UNIX style. This takes no account of possible '/' characters in the name.

        Parameters:
        file - the file to wrap
        Returns:
        the resource locator
      • ofPath

        public static ResourceLocator ofPath​(java.nio.file.Path path)
        Creates a resource from a Path.

        This will return either a file locator or a URL locator.

        Parameters:
        path - path to the file to wrap
        Returns:
        the resource locator
        Throws:
        java.lang.IllegalArgumentException - if the path is neither a file nor a URL
      • ofUrl

        public static ResourceLocator ofUrl​(java.net.URL url)
        Creates a resource from a URL.
        Parameters:
        url - path to the file to wrap
        Returns:
        the resource locator
      • ofClasspath

        public static ResourceLocator ofClasspath​(java.lang.String resourceName)
        Creates a resource from a fully qualified resource name.

        If the resource name does not start with a slash '/', one will be prepended. Use ofClasspath(Class, String) to get a relative resource.

        In Java 9 and later, resources can be encapsulated due to the module system. As such, this method is caller sensitive. It finds the class of the method that called this one, and uses that to search for resources using Class.getResource(String).

        Parameters:
        resourceName - the resource name, which will have a slash '/' prepended if missing
        Returns:
        the resource locator
      • ofClasspath

        public static ResourceLocator ofClasspath​(java.lang.Class<?> cls,
                                                  java.lang.String resourceName)
        Creates a resource locator for a classpath resource which is associated with a class.

        The classpath is searched using the same method as Class.getResource.

        • If the resource name starts with '/' it is treated as an absolute path relative to the classpath root
        • Otherwise the resource name is treated as a path relative to the package containing the class
        Parameters:
        cls - the class used to find the resource
        resourceName - the resource name
        Returns:
        the resource locator
      • ofClasspathUrl

        public static ResourceLocator ofClasspathUrl​(java.net.URL url)
        Creates a resource from a URL.
        Parameters:
        url - the URL to wrap
        Returns:
        the resource locator
      • getLocator

        public java.lang.String getLocator()
        Gets the string form of the locator.

        The string form of the locator describes the location of the resource.

        Returns:
        the locator string
      • getByteSource

        public com.google.common.io.ByteSource getByteSource()
        Gets the byte source to access the resource.

        A byte source is a supplier of data. The source itself is neither opened nor closed.

        Returns:
        the byte source
      • getCharSource

        public com.google.common.io.CharSource getCharSource()
        Gets the char source to access the resource using UTF-8.

        A char source is a supplier of data. The source itself is neither opened nor closed.

        This method handles Unicode Byte Order Marks.

        Returns:
        the char source
      • getCharSource

        public com.google.common.io.CharSource getCharSource​(java.nio.charset.Charset charset)
        Gets the char source to access the resource specifying the character set.

        A char source is a supplier of data. The source itself is neither opened nor closed.

        Parameters:
        charset - the character set to use
        Returns:
        the char source
      • equals

        public boolean equals​(java.lang.Object obj)
        Checks if this locator equals another locator.

        The comparison checks the locator string.

        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - the other locator, null returns false
        Returns:
        true if equal
      • hashCode

        public int hashCode()
        Returns a suitable hash code for the locator.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the hash code
      • toString

        public java.lang.String toString()
        Returns a string describing the locator.

        This can be parsed using of(String).

        Overrides:
        toString in class java.lang.Object
        Returns:
        the descriptive string