GrailsResourceUtils (Grails 3.3.10)
Date: 2019-05-20

Package: org.grails.io.support

## [Java] Class GrailsResourceUtils

- org.grails.io.support.GrailsResourceUtils

- Utility methods for resource handling / figuring out class names.

  Authors:
    Graeme Rocher
    Juergen Hoeller
  Since:
    2.0

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `static java.lang.String` | `CLASSPATH_URL_PREFIX` | Pseudo URL prefix for loading from the class path: "classpath:"
    `static java.lang.String` | `CLASS_EXTENSION` |
    `static java.util.regex.Pattern[]` | `COMPILER_ROOT_PATTERNS` |
    `static java.lang.String` | `DOMAIN_DIR_PATH` |
    `static java.util.regex.Pattern` | `DOMAIN_PATH_PATTERN` |
    `static java.lang.String` | `FILE_URL_PREFIX` | URL prefix for loading from the file system: "file:"
    `static java.lang.String` | `GRAILS_APP_DIR` | The name of the Grails application directory
    `static java.util.regex.Pattern` | `GRAILS_RESOURCE_PATTERN_EIGHTH_MATCH` |
    `static java.util.regex.Pattern` | `GRAILS_RESOURCE_PATTERN_ELEVENTH_MATCH` |
    `static java.util.regex.Pattern` | `GRAILS_RESOURCE_PATTERN_FIFTH_MATCH` |
    `static java.util.regex.Pattern` | `GRAILS_RESOURCE_PATTERN_FIRST_MATCH` |
    `static java.util.regex.Pattern` | `GRAILS_RESOURCE_PATTERN_FOURTH_MATCH` |
    `static java.util.regex.Pattern` | `GRAILS_RESOURCE_PATTERN_NINTH_MATCH` |
    `static java.util.regex.Pattern` | `GRAILS_RESOURCE_PATTERN_SECOND_MATCH` |
    `static java.util.regex.Pattern` | `GRAILS_RESOURCE_PATTERN_SEVENTH_MATCH` |
    `static java.util.regex.Pattern` | `GRAILS_RESOURCE_PATTERN_SIXTH_MATCH` |
    `static java.util.regex.Pattern` | `GRAILS_RESOURCE_PATTERN_TENTH_MATCH` |
    `static java.util.regex.Pattern` | `GRAILS_RESOURCE_PATTERN_THIRD_MATCH` |
    `static java.lang.String` | `JAR_URL_SEPARATOR` |
    `static java.lang.String` | `REGEX_FILE_SEPARATOR` |
    `static java.util.regex.Pattern` | `RESOURCE_PATH_PATTERN` |
    `static java.util.regex.Pattern` | `SPRING_SCRIPTS_PATH_PATTERN` |
    `static java.lang.String` | `URL_PROTOCOL_CODE_SOURCE` | URL protocol for an entry from an OC4J jar file: "code-source"
    `static java.lang.String` | `URL_PROTOCOL_FILE` | URL protocol for a file in the file system: "file"
    `static java.lang.String` | `URL_PROTOCOL_JAR` | URL protocol for an entry from a jar file: "jar"
    `static java.lang.String` | `URL_PROTOCOL_VFS` | URL protocol for a JBoss VFS resource: "vfs"
    `static java.lang.String` | `URL_PROTOCOL_VFSZIP` | URL protocol for an entry from a JBoss jar file: "vfszip"
    `static java.lang.String` | `URL_PROTOCOL_WSJAR` | URL protocol for an entry from a WebSphere jar file: "wsjar"
    `static java.lang.String` | `URL_PROTOCOL_ZIP` | URL protocol for an entry from a zip file: "zip"
    `static java.lang.String` | `VIEWS_DIR_PATH` | The path to the views directory
    `static java.lang.String` | `VIEWS_DIR_PATH_NO_SLASH` | The path to the views directory without a trailing slash
    `static java.lang.String` | `WEB_APP_DIR` | The name of the Web app dir within Grails
    `static java.lang.String` | `WEB_INF` | The relative path to the WEB-INF directory
    `static java.util.regex.Pattern[]` | `grailsAppResourcePatterns` |
    `static java.util.regex.Pattern[]` | `patterns` |

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `static java.lang.String` | `appendPiecesForUri(java.lang.String... pieces)` Takes any number of Strings and appends them into a uri, making sure that a forward slash is inserted between each piece and making sure that no duplicate slashes are in the uri
    `` | `static java.lang.String` | `applyRelativePath(java.lang.String path, java.lang.String relativePath)` Apply the given relative path to the given path, assuming standard Java folder separation (i.e. "/" separators).
    `` | `static java.lang.String` | `classPackageAsResourcePath(java.lang.Class<?> clazz)` Given an input class object, return a string which consists of the class's package name as a pathname, i.e., all dots ('.') are replaced by slashes ('/').
    `` | `static java.lang.String` | `cleanPath(java.lang.String path)` Normalize the path by suppressing sequences like "path/.." and inner simple dots.
    `` | `static java.net.URL` | `extractJarFileURL(java.net.URL jarUrl)` Extract the URL for the actual jar file from the given URL (which may point to a resource in a jar file or to a jar file itself).
    `` | `static Resource` | `getAppDir(Resource resource)`
    `` | `static java.lang.String` | `getArtefactDirectory(java.lang.String path)` Takes a file path and returns the name of the folder under grails-app i.e:
    `` | `static java.lang.String` | `getClassName(Resource resource)` Gets the class name of the specified Grails resource
    `` | `static java.lang.String` | `getClassName(java.lang.String path)` Returns the class name for a Grails resource.
    `` | `static java.lang.String` | `getClassNameForClassFile(java.lang.String rootDir, java.lang.String path)` Returns the class name for a compiled class file
    `` | `static java.io.File` | `getFile(java.net.URL resourceUrl, java.lang.String description)` Resolve the given resource URL to a `java.io.File`, i.e. to a file in the file system.
    `` | `static java.io.File` | `getFile(java.net.URI resourceUri, java.lang.String description)` Resolve the given resource URI to a `java.io.File`, i.e. to a file in the file system.
    `` | `static java.io.File` | `getFile(java.net.URI resourceUri)` Resolve the given resource URI to a `java.io.File`, i.e. to a file in the file system.
    `` | `static java.lang.String` | `getFilename(java.lang.String path)` Extract the filename from the given path, e.g.
    `` | `static java.lang.String` | `getPathFromBaseDir(java.lang.String path)` Gets the path relative to the project base directory.
    `` | `static java.lang.String` | `getPathFromRoot(java.lang.String path)` Get the path relative to an artefact folder under grails-app i.e:
    `` | `static java.lang.String` | `getRelativeInsideWebInf(Resource resource)` Takes a Grails resource (one located inside the grails-app dir) and gets its relative path inside the WEB-INF directory when deployed.
    `` | `static java.lang.String` | `getStaticResourcePathForResource(Resource resource, java.lang.String contextPath)` Retrieves the static resource path for the given Grails resource artifact (controller/taglib etc.)
    `` | `static Resource` | `getViewsDir(Resource resource)`
    `` | `static java.lang.Object` | `instantiateFromConfig(groovy.util.ConfigObject config, java.lang.String configKey, java.lang.String defaultClassName)`
    `` | `static java.lang.Object` | `instantiateFromFlatConfig(java.util.Map<java.lang.String, java.lang.Object> flatConfig, java.lang.String configKey, java.lang.String defaultClassName)`
    `` | `static boolean` | `isDomainClass(java.net.URL url)` Checks whether the file referenced by the given url is a domain class
    `` | `static boolean` | `isFileURL(java.net.URL url)` Determine whether the given URL points to a resource in the file system, that is, has protocol "file" or "vfs".
    `` | `static boolean` | `isGrailsPath(java.lang.String path)` Checks whether the specified path is a Grails path.
    `` | `static boolean` | `isGrailsResource(Resource r)` Checks whether the specific resources is a Grails resource.
    `` | `static boolean` | `isJarURL(java.net.URL url)` Determine whether the given URL points to a resource in a jar file, that is, has protocol "jar", "zip", "wsjar" or "code-source".
    `` | `static boolean` | `isProjectSource(java.lang.String path)` Checks whether the specified path is a Grails path.
    `` | `static boolean` | `isProjectSource(Resource r)` Checks whether the specified path is a Grails path.
    `` | `static java.net.URI` | `toURI(java.net.URL url)` Create a URI instance for the given URL, replacing spaces with "%20" quotes first.
    `` | `static java.net.URI` | `toURI(java.lang.String location)` Create a URI instance for the given location String, replacing spaces with "%20" quotes first.
    `` | `static void` | `useCachesIfNecessary(java.net.URLConnection con)`

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class java.lang.Object` | `java.lang.Object#wait(long, int), java.lang.Object#wait(long), java.lang.Object#wait(), java.lang.Object#equals(java.lang.Object), java.lang.Object#toString(), java.lang.Object#hashCode(), java.lang.Object#getClass(), java.lang.Object#notify(), java.lang.Object#notifyAll()`

- - ### Field Detail

    - #### public static final java.lang.String CLASSPATH_URL_PREFIX

      Pseudo URL prefix for loading from the class path: "classpath:"

    - #### public static final java.lang.String CLASS_EXTENSION

    - #### public static java.util.regex.Pattern[] COMPILER_ROOT_PATTERNS

    - #### public static final java.lang.String DOMAIN_DIR_PATH

    - #### public static java.util.regex.Pattern DOMAIN_PATH_PATTERN

    - #### public static final java.lang.String FILE_URL_PREFIX

      URL prefix for loading from the file system: "file:"

    - #### public static final java.lang.String GRAILS_APP_DIR

      The name of the Grails application directory

    - #### public static final java.util.regex.Pattern GRAILS_RESOURCE_PATTERN_EIGHTH_MATCH

    - #### public static final java.util.regex.Pattern GRAILS_RESOURCE_PATTERN_ELEVENTH_MATCH

    - #### public static final java.util.regex.Pattern GRAILS_RESOURCE_PATTERN_FIFTH_MATCH

    - #### public static final java.util.regex.Pattern GRAILS_RESOURCE_PATTERN_FIRST_MATCH

    - #### public static final java.util.regex.Pattern GRAILS_RESOURCE_PATTERN_FOURTH_MATCH

    - #### public static final java.util.regex.Pattern GRAILS_RESOURCE_PATTERN_NINTH_MATCH

    - #### public static final java.util.regex.Pattern GRAILS_RESOURCE_PATTERN_SECOND_MATCH

    - #### public static final java.util.regex.Pattern GRAILS_RESOURCE_PATTERN_SEVENTH_MATCH

    - #### public static final java.util.regex.Pattern GRAILS_RESOURCE_PATTERN_SIXTH_MATCH

    - #### public static final java.util.regex.Pattern GRAILS_RESOURCE_PATTERN_TENTH_MATCH

    - #### public static final java.util.regex.Pattern GRAILS_RESOURCE_PATTERN_THIRD_MATCH

    - #### public static final java.lang.String JAR_URL_SEPARATOR

    - #### public static final java.lang.String REGEX_FILE_SEPARATOR

    - #### public static java.util.regex.Pattern RESOURCE_PATH_PATTERN

    - #### public static java.util.regex.Pattern SPRING_SCRIPTS_PATH_PATTERN

    - #### public static final java.lang.String URL_PROTOCOL_CODE_SOURCE

      URL protocol for an entry from an OC4J jar file: "code-source"

    - #### public static final java.lang.String URL_PROTOCOL_FILE

      URL protocol for a file in the file system: "file"

    - #### public static final java.lang.String URL_PROTOCOL_JAR

      URL protocol for an entry from a jar file: "jar"

    - #### public static final java.lang.String URL_PROTOCOL_VFS

      URL protocol for a JBoss VFS resource: "vfs"

    - #### public static final java.lang.String URL_PROTOCOL_VFSZIP

      URL protocol for an entry from a JBoss jar file: "vfszip"

    - #### public static final java.lang.String URL_PROTOCOL_WSJAR

      URL protocol for an entry from a WebSphere jar file: "wsjar"

    - #### public static final java.lang.String URL_PROTOCOL_ZIP

      URL protocol for an entry from a zip file: "zip"

    - #### public static final java.lang.String VIEWS_DIR_PATH

      The path to the views directory

    - #### public static final java.lang.String VIEWS_DIR_PATH_NO_SLASH

      The path to the views directory without a trailing slash

    - #### public static final java.lang.String WEB_APP_DIR

      The name of the Web app dir within Grails

    - #### public static final java.lang.String WEB_INF

      The relative path to the WEB-INF directory

    - #### public static final java.util.regex.Pattern[] grailsAppResourcePatterns

    - #### public static final java.util.regex.Pattern[] patterns

  - ### Method Detail

    - #### public static java.lang.String appendPiecesForUri(java.lang.String... pieces)

      Takes any number of Strings and appends them into a uri, making sure that a forward slash is inserted between each piece and making sure that no duplicate slashes are in the uri

           Input: ""
           Output: ""

           Input: "/alpha", "/beta", "/gamma"
           Output: "/alpha/beta/gamma

           Input: "/alpha/, "/beta/", "/gamma"
           Output: "/alpha/beta/gamma

           Input: "/alpha/", "/beta/", "/gamma/"
           Output "/alpha/beta/gamma/

           Input: "alpha", "beta", "gamma"
           Output: "alpha/beta/gamma

      Parameters:
        `pieces` - Strings to concatenate together into a uri
      Returns:
        a uri

    - #### public static java.lang.String applyRelativePath(java.lang.String path, java.lang.String relativePath)

      Apply the given relative path to the given path, assuming standard Java folder separation (i.e. "/" separators).

      Parameters:
        `path` - the path to start from (usually a full file path)
        `relativePath` - the relative path to apply (relative to the full file path above)
      Returns:
        the full file path that results from applying the relative path

    - #### public static java.lang.String classPackageAsResourcePath(java.lang.Class<?> clazz)

      Given an input class object, return a string which consists of the class's package name as a pathname, i.e., all dots ('.') are replaced by slashes ('/'). Neither a leading nor trailing slash is added. The result could be concatenated with a slash and the name of a resource and fed directly to `ClassLoader.getResource()`. For it to be fed to `Class.getResource` instead, a leading slash would also have to be prepended to the returned value.

      Parameters:
        `clazz` - the input class. A `null` value or the default (empty) package will result in an empty string ("") being returned.
      Returns:
        a path which represents the package name
      See Also:
        java.lang.ClassLoader#getResource
        java.lang.Class#getResource

    - #### public static java.lang.String cleanPath(java.lang.String path)

      Normalize the path by suppressing sequences like "path/.." and inner simple dots.

      The result is convenient for path comparison. For other uses, notice that Windows separators ("\") are replaced by simple slashes.

      Parameters:
        `path` - the original path
      Returns:
        the normalized path

    - #### public static java.net.URL extractJarFileURL(java.net.URL jarUrl)

      Extract the URL for the actual jar file from the given URL (which may point to a resource in a jar file or to a jar file itself).

      throws:
        MalformedURLException if no valid jar file URL could be extracted
      Parameters:
        `jarUrl` - the original URL
      Returns:
        the URL for the actual jar file

    - #### public static Resource getAppDir(Resource resource)

    - #### public static java.lang.String getArtefactDirectory(java.lang.String path)

      Takes a file path and returns the name of the folder under grails-app i.e: Input: /usr/joe/project/grails-app/domain/com/mystartup/Book.groovy Output: domain

      Parameters:
        `path` - The path
      Returns:
        The domain or null if not known

    - #### public static java.lang.String getClassName(Resource resource)

      Gets the class name of the specified Grails resource

      Parameters:
        `resource` - The Spring Resource
      Returns:
        The class name or null if the resource is not a Grails class

    - #### public static java.lang.String getClassName(java.lang.String path)

      Returns the class name for a Grails resource.

      Parameters:
        `path` - The path to check
      Returns:
        The class name or null if it doesn't exist

    - #### public static java.lang.String getClassNameForClassFile(java.lang.String rootDir, java.lang.String path)

      Returns the class name for a compiled class file

      Parameters:
        `path` - The path to check
      Returns:
        The class name or null if it doesn't exist

    - #### public static java.io.File getFile(java.net.URL resourceUrl, java.lang.String description)

      Resolve the given resource URL to a `java.io.File`, i.e. to a file in the file system.

      throws:
        java.io.FileNotFoundException if the URL cannot be resolved to a file in the file system
      Parameters:
        `resourceUrl` - the resource URL to resolve
        `description` - a description of the original resource that the URL was created for (for example, a class path location)
      Returns:
        a corresponding File object

    - #### public static java.io.File getFile(java.net.URI resourceUri, java.lang.String description)

      Resolve the given resource URI to a `java.io.File`, i.e. to a file in the file system.

      throws:
        FileNotFoundException if the URL cannot be resolved to a file in the file system
      Parameters:
        `resourceUri` - the resource URI to resolve
        `description` - a description of the original resource that the URI was created for (for example, a class path location)
      Returns:
        a corresponding File object

    - #### public static java.io.File getFile(java.net.URI resourceUri)

      Resolve the given resource URI to a `java.io.File`, i.e. to a file in the file system.

      throws:
        FileNotFoundException if the URL cannot be resolved to a file in the file system
      Parameters:
        `resourceUri` - the resource URI to resolve
      Returns:
        a corresponding File object

    - #### public static java.lang.String getFilename(java.lang.String path)

      Extract the filename from the given path, e.g. "mypath/myfile.txt" -> "myfile.txt".

      Parameters:
        `path` - the file path (may be `null`)
      Returns:
        the extracted filename, or `null` if none

    - #### public static java.lang.String getPathFromBaseDir(java.lang.String path)

      Gets the path relative to the project base directory. Input: /usr/joe/project/grails-app/conf/BootStrap.groovy Output: grails-app/conf/BootStrap.groovy

      Parameters:
        `path` - The path
      Returns:
        The path relative to the base directory or null if it can't be established

    - #### public static java.lang.String getPathFromRoot(java.lang.String path)

      Get the path relative to an artefact folder under grails-app i.e: Input: /usr/joe/project/grails-app/conf/BootStrap.groovy Output: BootStrap.groovy Input: /usr/joe/project/grails-app/domain/com/mystartup/Book.groovy Output: com/mystartup/Book.groovy

      Parameters:
        `path` - The path to evaluate
      Returns:
        The path relative to the root folder grails-app

    - #### public static java.lang.String getRelativeInsideWebInf(Resource resource)

      Takes a Grails resource (one located inside the grails-app dir) and gets its relative path inside the WEB-INF directory when deployed.

      Parameters:
        `resource` - The Grails resource, which is a file inside the grails-app dir
      Returns:
        The relative URL of the file inside the WEB-INF dir at deployment time or null if it cannot be established

    - #### public static java.lang.String getStaticResourcePathForResource(Resource resource, java.lang.String contextPath)

      Retrieves the static resource path for the given Grails resource artifact (controller/taglib etc.)

      Parameters:
        `resource` - The Resource
        `contextPath` - The additonal context path to prefix
      Returns:
        The resource path

    - #### public static Resource getViewsDir(Resource resource)

    - #### @java.lang.SuppressWarnings("unchecked") public static java.lang.Object instantiateFromConfig(groovy.util.ConfigObject config, java.lang.String configKey, java.lang.String defaultClassName)

    - #### public static java.lang.Object instantiateFromFlatConfig(java.util.Map<java.lang.String, java.lang.Object> flatConfig, java.lang.String configKey, java.lang.String defaultClassName)

    - #### public static boolean isDomainClass(java.net.URL url)

      Checks whether the file referenced by the given url is a domain class

      Parameters:
        `url` - The URL instance
      Returns:
        true if it is a domain class

    - #### public static boolean isFileURL(java.net.URL url)

      Determine whether the given URL points to a resource in the file system, that is, has protocol "file" or "vfs".

      Parameters:
        `url` - the URL to check
      Returns:
        whether the URL has been identified as a file system URL

    - #### public static boolean isGrailsPath(java.lang.String path)

      Checks whether the specified path is a Grails path.

      Parameters:
        `path` - The path to check
      Returns:
        true if it is a Grails path

    - #### public static boolean isGrailsResource(Resource r)

      Checks whether the specific resources is a Grails resource. A Grails resource is a Groovy or Java class under the grails-app directory

      Parameters:
        `r` - The resource to check
      Returns:
        True if it is a Grails resource

    - #### public static boolean isJarURL(java.net.URL url)

      Determine whether the given URL points to a resource in a jar file, that is, has protocol "jar", "zip", "wsjar" or "code-source".

      "zip" and "wsjar" are used by BEA WebLogic Server and IBM WebSphere, respectively, but can be treated like jar files. The same applies to "code-source" URLs on Oracle OC4J, provided that the path contains a jar separator.

      Parameters:
        `url` - the URL to check
      Returns:
        whether the URL has been identified as a JAR URL

    - #### public static boolean isProjectSource(java.lang.String path)

      Checks whether the specified path is a Grails path.

      Parameters:
        `path` - The path to check
      Returns:
        true if it is a Grails path

    - #### public static boolean isProjectSource(Resource r)

      Checks whether the specified path is a Grails path.

      Parameters:
        `r` - The resoruce to check
      Returns:
        true if it is a Grails path

    - #### public static java.net.URI toURI(java.net.URL url)

      Create a URI instance for the given URL, replacing spaces with "%20" quotes first.

      Furthermore, this method works on JDK 1.4 as well, in contrast to the `URL.toURI()` method.

      throws:
        URISyntaxException if the URL wasn't a valid URI
      Parameters:
        `url` - the URL to convert into a URI instance
      Returns:
        the URI instance
      See Also:
        java.net.URL#toURI()

    - #### public static java.net.URI toURI(java.lang.String location)

      Create a URI instance for the given location String, replacing spaces with "%20" quotes first.

      throws:
        URISyntaxException if the location wasn't a valid URI
      Parameters:
        `location` - the location String to convert into a URI instance
      Returns:
        the URI instance

    - #### public static void useCachesIfNecessary(java.net.URLConnection con)