Class ResourceLocator


  • public final class ResourceLocator
    extends 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.

    • Method Detail

      • of

        public static ResourceLocator of​(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​(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​(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:
        IllegalArgumentException - if the path is neither a file nor a URL
      • ofUrl

        public static ResourceLocator ofUrl​(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​(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​(Class<?> cls,
                                                  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​(URL url)
        Creates a resource from a URL.
        Parameters:
        url - the URL to wrap
        Returns:
        the resource locator
      • getLocator

        public 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 BeanByteSource 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 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 CharSource getCharSource​(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​(Object obj)
        Checks if this locator equals another locator.

        The comparison checks the locator string.

        Overrides:
        equals in class 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 Object
        Returns:
        the hash code
      • toString

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

        This can be parsed using of(String).

        Overrides:
        toString in class Object
        Returns:
        the descriptive string