com.jogamp.common.util

## Class JarUtil

- java.lang.Object
- - com.jogamp.common.util.JarUtil

-     public class JarUtil
      extends Object

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `JarUtil.Resolver` Interface allowing users to provide an URL resolver that will convert custom classloader URLs like Eclipse/OSGi bundleresource: URLs to normal jar: URLs.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JarUtil()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static int` | `extract(File dest, Map<String,String> nativeLibMap, JarFile jarFile, String nativeLibraryPath, boolean extractNativeLibraries, boolean extractClassFiles, boolean extractOtherFiles)` Extract the files of the given jar file.
    `static String` | `getJarBasename(String clazzBinName, ClassLoader cl)` The Class's `com.jogamp.common.GlueGenVersion` URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class` Jar basename `gluegen-rt.jar` will be returned.
    `static String` | `getJarBasename(URI classJarURI)` The Class's Jar URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class` Jar basename `gluegen-rt.jar` will be returned.
    `static String` | `getJarEntry(URI classJarURI)` Deprecated. Useless
    `static URI` | `getJarEntryURI(URI jarFileURI, String jarEntry)`
    `static JarFile` | `getJarFile(String clazzBinName, ClassLoader cl)`
    `static JarFile` | `getJarFile(URI jarFileURI)`
    `static URI` | `getJarFileURI(String jarSubUriS)`
    `static URI` | `getJarFileURI(String clazzBinName, ClassLoader cl)` The Class's `"com.jogamp.common.GlueGenVersion"` URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class"` Jar file URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/` will be returned.
    `static URI` | `getJarFileURI(URI jarSubUri)`
    `static URI` | `getJarFileURI(URI baseUri, String jarFileName)`
    `static URI` | `getJarSubURI(String clazzBinName, ClassLoader cl)` The Class's `com.jogamp.common.GlueGenVersion` URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class` Jar file's sub URI `sub_protocol:/some/path/gluegen-rt.jar` will be returned.
    `static URI` | `getJarSubURI(URI classJarURI)` The Class's Jar URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class` Jar file's sub URI `sub_protocol:/some/path/gluegen-rt.jar` will be returned.
    `static URI` | `getJarURI(String clazzBinName, ClassLoader cl)` The Class's `"com.jogamp.common.GlueGenVersion"` URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class"` will be returned.
    `static Map<String,String>` | `getNativeLibNames(JarFile jarFile)` Return a map from native-lib-base-name to entry-name.
    `static URI` | `getRelativeOf(Class<?> classFromJavaJar, String cutOffInclSubDir, String relResPath)` Locates the `Jar file URI` of a given resource relative to a given class's Jar's URI.
    `static boolean` | `hasJarURI(String clazzBinName, ClassLoader cl)` Returns `true` if the Class's `"com.jogamp.common.GlueGenVersion"` is loaded from a JarFile and hence has a Jar URI like URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class"`.
    `static void` | `setResolver(JarUtil.Resolver r)` Setting a custom `JarUtil.Resolver` instance.
    `static void` | `validateCertificates(Certificate[] rootCerts, JarFile jarFile)` Validate the certificates for each native Lib in the jar file.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### JarUtil

          public JarUtil()

  - ### Method Detail

    - #### setResolver

          public static void setResolver(JarUtil.Resolver r)
                                  throws IllegalArgumentException,
                                         IllegalStateException,
                                         SecurityException

      Setting a custom `JarUtil.Resolver` instance.
      Parameters:
        `r` - `JarUtil.Resolver` to use after querying class file URLs from the classloader.
      Throws:
        `IllegalArgumentException` - if the passed resolver is `null`
        `IllegalStateException` - if the resolver has already been set.
        `SecurityException` - if the security manager doesn't have the setFactory permission

    - #### hasJarURI

          public static boolean hasJarURI(String clazzBinName,
                          ClassLoader cl)

      Returns `true` if the Class's `"com.jogamp.common.GlueGenVersion"` is loaded from a JarFile and hence has a Jar URI like URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class"`.

      sub_protocol may be "file", "http", etc..

      Parameters:
        `clazzBinName` - "com.jogamp.common.GlueGenVersion"
        `cl` -
      Returns:
        true if the class is loaded from a Jar file, otherwise false.
      See Also:
        `#getJarURI(String, ClassLoader)}`

    - #### getJarURI

          public static URI getJarURI(String clazzBinName,
                      ClassLoader cl)
                               throws IllegalArgumentException,
                                      IOException,
                                      URISyntaxException

      The Class's `"com.jogamp.common.GlueGenVersion"` URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class"` will be returned.

      sub_protocol may be "file", "http", etc..

      Parameters:
        `clazzBinName` - "com.jogamp.common.GlueGenVersion"
        `cl` - ClassLoader to locate the JarFile
      Returns:
        "jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class"
      Throws:
        `IllegalArgumentException` - if the URI doesn't match the expected formatting or null arguments
        `IOException` - if the class's Jar file could not been found by the ClassLoader
        `URISyntaxException` - if the URI could not be translated into a RFC 2396 URI
      See Also:
        `IOUtil#getClassURL(String, ClassLoader)}`

    - #### getJarBasename

          public static String getJarBasename(URI classJarURI)
                                       throws IllegalArgumentException

      The Class's Jar URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class` Jar basename `gluegen-rt.jar` will be returned.

      sub_protocol may be "file", "http", etc..

      Parameters:
        `classJarURI` - as retrieved w/ `getJarURI("com.jogamp.common.GlueGenVersion", cl).toURI()`, i.e. `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class`
      Returns:
        `gluegen-rt.jar`
      Throws:
        `IllegalArgumentException` - if the URI doesn't match the expected formatting or is null
      See Also:
        `IOUtil#getClassURL(String, ClassLoader)}`

    - #### getJarBasename

          public static String getJarBasename(String clazzBinName,
                              ClassLoader cl)
                                       throws IllegalArgumentException,
                                              IOException,
                                              URISyntaxException

      The Class's `com.jogamp.common.GlueGenVersion` URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class` Jar basename `gluegen-rt.jar` will be returned.

      sub_protocol may be "file", "http", etc..

      Parameters:
        `clazzBinName` - `com.jogamp.common.GlueGenVersion`
        `cl` -
      Returns:
        `gluegen-rt.jar`
      Throws:
        `IllegalArgumentException` - if the URI doesn't match the expected formatting
        `IOException` - if the class's Jar file could not been found by the ClassLoader.
        `URISyntaxException` - if the URI could not be translated into a RFC 2396 URI
      See Also:
        `IOUtil#getClassURL(String, ClassLoader)}`

    - #### getJarSubURI

          public static URI getJarSubURI(URI classJarURI)
                                  throws IllegalArgumentException,
                                         URISyntaxException

      The Class's Jar URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class` Jar file's sub URI `sub_protocol:/some/path/gluegen-rt.jar` will be returned.

      sub_protocol may be "file", "http", etc..

      Parameters:
        `classJarURI` - as retrieved w/ `getJarURI("com.jogamp.common.GlueGenVersion", cl).toURI()`, i.e. `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class`
      Returns:
        `sub_protocol:/some/path/gluegen-rt.jar`
      Throws:
        `IllegalArgumentException` - if the URI doesn't match the expected formatting or is null
        `URISyntaxException` - if the URI could not be translated into a RFC 2396 URI
      See Also:
        `IOUtil#getClassURL(String, ClassLoader)}`

    - #### getJarEntry

          public static String getJarEntry(URI classJarURI)

      Deprecated. Useless
      The Class's Jar URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class` Jar file's entry `/com/jogamp/common/GlueGenVersion.class` will be returned.
      Parameters:
        `classJarURI` - as retrieved w/ `getJarURI("com.jogamp.common.GlueGenVersion", cl).toURI()`, i.e. `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class`
      Returns:
        `/com/jogamp/common/GlueGenVersion.class`
      See Also:
        `IOUtil#getClassURL(String, ClassLoader)}`

    - #### getJarSubURI

          public static URI getJarSubURI(String clazzBinName,
                         ClassLoader cl)
                                  throws IllegalArgumentException,
                                         IOException,
                                         URISyntaxException

      The Class's `com.jogamp.common.GlueGenVersion` URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class` Jar file's sub URI `sub_protocol:/some/path/gluegen-rt.jar` will be returned.

      sub_protocol may be "file", "http", etc..

      Parameters:
        `clazzBinName` - `com.jogamp.common.GlueGenVersion`
        `cl` -
      Returns:
        `sub_protocol:/some/path/gluegen-rt.jar`
      Throws:
        `IllegalArgumentException` - if the URI doesn't match the expected formatting
        `IOException` - if the class's Jar file could not been found by the ClassLoader
        `URISyntaxException` - if the URI could not be translated into a RFC 2396 URI
      See Also:
        `IOUtil#getClassURL(String, ClassLoader)}`

    - #### getJarFileURI

          public static URI getJarFileURI(String clazzBinName,
                          ClassLoader cl)
                                   throws IllegalArgumentException,
                                          IOException,
                                          URISyntaxException

      The Class's `"com.jogamp.common.GlueGenVersion"` URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class"` Jar file URI `jar:sub_protocol:/some/path/gluegen-rt.jar!/` will be returned.

      sub_protocol may be "file", "http", etc..

      Parameters:
        `clazzBinName` - "com.jogamp.common.GlueGenVersion"
        `cl` -
      Returns:
        "jar:sub_protocol:/some/path/gluegen-rt.jar!/"
      Throws:
        `IllegalArgumentException` - if the URI doesn't match the expected formatting or null arguments
        `IOException` - if the class's Jar file could not been found by the ClassLoader
        `URISyntaxException` - if the URI could not be translated into a RFC 2396 URI
      See Also:
        `IOUtil#getClassURL(String, ClassLoader)}`

    - #### getJarFileURI

          public static URI getJarFileURI(URI baseUri,
                          String jarFileName)
                                   throws IllegalArgumentException,
                                          URISyntaxException

      Parameters:
        `baseUri` - file:/some/path/
        `jarFileName` - gluegen-rt.jar (URI encoded)
      Returns:
        jar:file:/some/path/gluegen-rt.jar!/
      Throws:
        `URISyntaxException`
        `IllegalArgumentException` - null arguments

    - #### getJarFileURI

          public static URI getJarFileURI(URI jarSubUri)
                                   throws IllegalArgumentException,
                                          URISyntaxException

      Parameters:
        `jarSubUri` - file:/some/path/gluegen-rt.jar
      Returns:
        jar:file:/some/path/gluegen-rt.jar!/
      Throws:
        `IllegalArgumentException` - null arguments
        `URISyntaxException`

    - #### getJarFileURI

          public static URI getJarFileURI(String jarSubUriS)
                                   throws IllegalArgumentException,
                                          URISyntaxException

      Parameters:
        `jarSubUriS` - file:/some/path/gluegen-rt.jar (URI encoded)
      Returns:
        jar:file:/some/path/gluegen-rt.jar!/
      Throws:
        `IllegalArgumentException` - null arguments
        `URISyntaxException`

    - #### getJarEntryURI

          public static URI getJarEntryURI(URI jarFileURI,
                           String jarEntry)
                                    throws IllegalArgumentException,
                                           URISyntaxException

      Parameters:
        `jarFileURI` - jar:file:/some/path/gluegen-rt.jar!/
        `jarEntry` - com/jogamp/common/GlueGenVersion.class
      Returns:
        jar:file:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class
      Throws:
        `IllegalArgumentException` - null arguments
        `URISyntaxException`

    - #### getJarFile

          public static JarFile getJarFile(String clazzBinName,
                           ClassLoader cl)
                                    throws IOException,
                                           IllegalArgumentException,
                                           URISyntaxException

      Parameters:
        `clazzBinName` - com.jogamp.common.util.cache.TempJarCache
        `cl` - domain
      Returns:
        JarFile containing the named class within the given ClassLoader
      Throws:
        `IOException` - if the class's Jar file could not been found by the ClassLoader
        `IllegalArgumentException` - null arguments
        `URISyntaxException` - if the URI could not be translated into a RFC 2396 URI
      See Also:
        `#getJarFileURI(String, ClassLoader)}`

    - #### getJarFile

          public static JarFile getJarFile(URI jarFileURI)
                                    throws IOException,
                                           IllegalArgumentException,
                                           URISyntaxException

      Parameters:
        `jarFileURI` - jar:file:/some/path/gluegen-rt.jar!/
      Returns:
        JarFile as named by URI within the given ClassLoader
      Throws:
        `IllegalArgumentException` - null arguments
        `IOException` - if the Jar file could not been found
        `URISyntaxException`

    - #### getRelativeOf

          public static URI getRelativeOf(Class<?> classFromJavaJar,
                          String cutOffInclSubDir,
                          String relResPath)
                                   throws IllegalArgumentException,
                                          IOException,
                                          URISyntaxException

      Locates the `Jar file URI` of a given resource relative to a given class's Jar's URI.

             class's jar url path + cutOffInclSubDir + relResPath,

      Example #1

             classFromJavaJar = com.lighting.Test (in: file:/storage/TestLighting.jar)
             cutOffInclSubDir = lights/
             relResPath       = LightAssets.jar
             Result           : file:/storage/lights/LightAssets.jar

      Example #2

             classFromJavaJar = com.lighting.Test (in: file:/storage/lights/TestLighting.jar)
             cutOffInclSubDir = lights/
             relResPath       = LightAssets.jar
             Result           : file:/storage/lights/LightAssets.jar

      TODO: Enhance documentation!
      Parameters:
        `classFromJavaJar` - Used to get the root URI for the class's Jar URI.
        `cutOffInclSubDir` - The cut off included sub-directory prepending the relative resource path. If the root URI includes cutOffInclSubDir, it is no more added to the result.
        `relResPath` - The relative resource path. (URI encoded)
      Returns:
        The resulting resource URI, which is not tested.
      Throws:
        `IllegalArgumentException`
        `IOException`
        `URISyntaxException`

    - #### getNativeLibNames

          public static Map<String,String> getNativeLibNames(JarFile jarFile)

      Return a map from native-lib-base-name to entry-name.

    - #### extract

          public static final int extract(File dest,
                    Map<String,String> nativeLibMap,
                    JarFile jarFile,
                    String nativeLibraryPath,
                    boolean extractNativeLibraries,
                    boolean extractClassFiles,
                    boolean extractOtherFiles)
                                   throws IOException

      Extract the files of the given jar file.

      If `extractNativeLibraries` is true, native libraries are added to the given `nativeLibMap` with the base name to temp file location.
      A file is identified as a native library, if it's name complies with the running platform's native library naming scheme.
      Root entries are favored over non root entries in case of naming collisions.
      Example on a Unix like machine:

             mylib.jar!/sub1/libsour.so   -> sour  (mapped, unique name)
             mylib.jar!/sub1/libsweet.so           (dropped, root entry favored)
             mylib.jar!/libsweet.so       -> sweet (mapped, root entry favored)
             mylib.jar!/sweet.dll         ->       (dropped, not a unix library name)

      In order to be compatible with Java Web Start, we need to extract all root entries from the jar file.
      In this case, set all flags to true `extractNativeLibraries` . `extractClassFiles`, `extractOtherFiles`.

      Parameters:
        `dest` -
        `nativeLibMap` -
        `jarFile` -
        `nativeLibraryPath` - if not null, only extracts native libraries within this path.
        `extractNativeLibraries` -
        `extractClassFiles` -
        `extractOtherFiles` -
        `deepDirectoryTraversal` -
      Returns:
      Throws:
        `IOException`

    - #### validateCertificates

          public static final void validateCertificates(Certificate[] rootCerts,
                                  JarFile jarFile)
                                                 throws IOException,
                                                        SecurityException

      Validate the certificates for each native Lib in the jar file. Throws an IOException if any certificate is not valid.

                  Certificate[] rootCerts = Something.class.getProtectionDomain().
                                                  getCodeSource().getCertificates();

      Throws:
        `IOException`
        `SecurityException`