GlueGen: com.jogamp.common.util.JarUtil Class Reference

GlueGen v2.6.0-rc-20250712 GlueGen, Native Binding Generator for Java™ (public API).

Classes | Static Public Member Functions | List of all members
com.jogamp.common.util.JarUtil Class Reference
Collaboration diagram for com.jogamp.common.util.JarUtil:

## Classes

interface | Resolver
| Interface allowing users to provide an URL resolver that will convert custom classloader URLs like Eclipse/OSGi bundleresource: URLs to normal jar: URLs. More...

## Static Public Member Functions

static void | setResolver (final Resolver r) throws IllegalArgumentException, IllegalStateException, SecurityException
| Setting a custom `Resolver` instance. More...
static boolean | hasJarUri (final String clazzBinName, final 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"`. More...
static Uri | getJarUri (final String clazzBinName, final 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. More...
static Uri.Encoded | getJarBasename (final 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. More...
static Uri.Encoded | getJarBasename (final String clazzBinName, final 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. More...
static Uri.Encoded | getJarEntry (final Uri classJarUri)
| 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. More...
static Uri | getJarFileUri (final String clazzBinName, final 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. More...
static Uri | getJarFileUri (final Uri baseUri, final Uri.Encoded jarFileName) throws IllegalArgumentException, URISyntaxException
static Uri | getJarFileUri (final Uri jarSubUri) throws IllegalArgumentException, URISyntaxException
static Uri | getJarFileUri (final Uri.Encoded jarSubUriS) throws IllegalArgumentException, URISyntaxException
static Uri | getJarEntryUri (final Uri jarFileUri, final Uri.Encoded jarEntry) throws IllegalArgumentException, URISyntaxException
static JarFile | getJarFile (final String clazzBinName, final ClassLoader cl) throws IOException, IllegalArgumentException, URISyntaxException
static JarFile | getJarFile (final Uri jarFileUri) throws IOException, IllegalArgumentException, URISyntaxException
static Uri | getRelativeOf (final Class<?> classFromJavaJar, final Uri.Encoded cutOffInclSubDir, final Uri.Encoded relResPath) throws IllegalArgumentException, IOException, URISyntaxException
| Locates the `Jar file Uri` of a given resource relative to a given class's Jar's Uri. More...
static Map< String, String > | getNativeLibNames (final JarFile jarFile)
| Return a map from native-lib-base-name to entry-name. More...
static final int | extract (final File dest, final Map< String, String > nativeLibMap, final JarFile jarFile, final String nativeLibraryPath, final boolean extractNativeLibraries, final boolean extractClassFiles, final boolean extractOtherFiles) throws IOException
| Extract the files of the given jar file. More...
static final void | validateCertificates (final Certificate[] rootCerts, final JarFile jarFile) throws IOException, SecurityException
| Validate the certificates for each native Lib in the jar file. More...

## Detailed Description

Definition at line 54 of file JarUtil.java.

## Member Function Documentation

## ◆ extract()

static final int com.jogamp.common.util.JarUtil.extract | ( | final File | dest,
|  | final Map< String, String > | nativeLibMap,
|  | final JarFile | jarFile,
|  | final String | nativeLibraryPath,
|  | final boolean | extractNativeLibraries,
|  | final boolean | extractClassFiles,
|  | final boolean | extractOtherFiles
| ) |  | throws IOException

static

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

Exceptions

  IOException |

Definition at line 549 of file JarUtil.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ getJarBasename() [1/2]

static Uri.Encoded com.jogamp.common.util.JarUtil.getJarBasename | ( | final String | clazzBinName,
|  | final ClassLoader | cl
| ) |  | throws IllegalArgumentException, IOException, URISyntaxException

static

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`

Exceptions

  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)`

Definition at line 248 of file JarUtil.java.

Here is the call graph for this function:

## ◆ getJarBasename() [2/2]

static Uri.Encoded com.jogamp.common.util.JarUtil.getJarBasename | ( | final Uri | classJarUri | ) | throws IllegalArgumentException

static

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)`, i.e. `jar:sub_protocol:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class`

Returns
  `gluegen-rt.jar`

Exceptions

  IllegalArgumentException | if the Uri doesn't match the expected formatting or is null

See also
  `IOUtil#getClassURL(String, ClassLoader)`

Definition at line 189 of file JarUtil.java.

Here is the caller graph for this function:

## ◆ getJarEntry()

static Uri.Encoded com.jogamp.common.util.JarUtil.getJarEntry | ( | final Uri | classJarUri | ) |

static

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)`, 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)`

Definition at line 261 of file JarUtil.java.

Here is the call graph for this function:

## ◆ getJarEntryUri()

static Uri com.jogamp.common.util.JarUtil.getJarEntryUri | ( | final Uri | jarFileUri,
|  | final Uri.Encoded | jarEntry
| ) |  | throws IllegalArgumentException, URISyntaxException

static

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

Exceptions

  IllegalArgumentException | null arguments
  URISyntaxException |

Definition at line 362 of file JarUtil.java.

Here is the call graph for this function:

## ◆ getJarFile() [1/2]

static JarFile com.jogamp.common.util.JarUtil.getJarFile | ( | final String | clazzBinName,
|  | final ClassLoader | cl
| ) |  | throws IOException, IllegalArgumentException, URISyntaxException

static

Parameters

  clazzBinName | com.jogamp.common.util.cache.TempJarCache
  cl | domain

Returns
  JarFile containing the named class within the given ClassLoader

Exceptions

  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)`

Definition at line 378 of file JarUtil.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ getJarFile() [2/2]

static JarFile com.jogamp.common.util.JarUtil.getJarFile | ( | final Uri | jarFileUri | ) | throws IOException, IllegalArgumentException, URISyntaxException

static

Parameters

  jarFileUri | jar:file:/some/path/gluegen-rt.jar!/

Returns
  JarFile as named by Uri within the given ClassLoader

Exceptions

  IllegalArgumentException | null arguments
  IOException | if the Jar file could not been found
  URISyntaxException |

Definition at line 389 of file JarUtil.java.

## ◆ getJarFileUri() [1/4]

static Uri com.jogamp.common.util.JarUtil.getJarFileUri | ( | final String | clazzBinName,
|  | final ClassLoader | cl
| ) |  | throws IllegalArgumentException, IOException, URISyntaxException

static

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:<i>sub_protocol</i>:/some/path/gluegen-rt.jar!/"

Exceptions

  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)`

Definition at line 303 of file JarUtil.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ getJarFileUri() [2/4]

static Uri com.jogamp.common.util.JarUtil.getJarFileUri | ( | final Uri | baseUri,
|  | final Uri.Encoded | jarFileName
| ) |  | throws IllegalArgumentException, URISyntaxException

static

Parameters

  baseUri | file:/some/path/
  jarFileName | gluegen-rt.jar (Uri encoded)

Returns
  jar:file:/some/path/gluegen-rt.jar!/

Exceptions

  URISyntaxException |
  IllegalArgumentException | null arguments

Definition at line 322 of file JarUtil.java.

Here is the call graph for this function:

## ◆ getJarFileUri() [3/4]

static Uri com.jogamp.common.util.JarUtil.getJarFileUri | ( | final Uri | jarSubUri | ) | throws IllegalArgumentException, URISyntaxException

static

Parameters

  jarSubUri | file:/some/path/gluegen-rt.jar

Returns
  jar:file:/some/path/gluegen-rt.jar!/

Exceptions

  IllegalArgumentException | null arguments
  URISyntaxException |

Definition at line 335 of file JarUtil.java.

Here is the call graph for this function:

## ◆ getJarFileUri() [4/4]

static Uri com.jogamp.common.util.JarUtil.getJarFileUri | ( | final Uri.Encoded | jarSubUriS | ) | throws IllegalArgumentException, URISyntaxException

static

Parameters

  jarSubUriS | file:/some/path/gluegen-rt.jar (Uri encoded)

Returns
  jar:file:/some/path/gluegen-rt.jar!/

Exceptions

  IllegalArgumentException | null arguments
  URISyntaxException |

Definition at line 348 of file JarUtil.java.

Here is the call graph for this function:

## ◆ getJarUri()

static Uri com.jogamp.common.util.JarUtil.getJarUri | ( | final String | clazzBinName,
|  | final ClassLoader | cl
| ) |  | throws IllegalArgumentException, IOException, URISyntaxException

static

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:<i>sub_protocol</i>:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class"

Exceptions

  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)`

Definition at line 139 of file JarUtil.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ getNativeLibNames()

static Map< String, String > com.jogamp.common.util.JarUtil.getNativeLibNames | ( | final JarFile | jarFile | ) |

static

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

Definition at line 493 of file JarUtil.java.

Here is the call graph for this function:

## ◆ getRelativeOf()

static Uri com.jogamp.common.util.JarUtil.getRelativeOf | ( | final Class<?> | classFromJavaJar,
|  | final Uri.Encoded | cutOffInclSubDir,
|  | final Uri.Encoded | relResPath
| ) |  | throws IllegalArgumentException, IOException, URISyntaxException

static

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,

or with `cutOffInclSubDir` being `null` just

      class's jar url path + relResPath,

Example #1

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

Example #2

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

Example #3

      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 | Optional cut off included sub-directory prepending the relative resource path. If the root Uri includes cutOffInclSubDir, it is no more added to the result. Parameter will be ignored if `null`.
  relResPath | The relative resource path. (Uri encoded)

Returns
  The resulting resource Uri, which is not tested.

Exceptions

  IllegalArgumentException |
  IOException |
  URISyntaxException |

Definition at line 459 of file JarUtil.java.

Here is the call graph for this function:

## ◆ hasJarUri()

static boolean com.jogamp.common.util.JarUtil.hasJarUri | ( | final String | clazzBinName,
|  | final ClassLoader | cl
| ) |  |

static

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)`

Definition at line 116 of file JarUtil.java.

Here is the call graph for this function:

## ◆ setResolver()

static void com.jogamp.common.util.JarUtil.setResolver | ( | final Resolver | r | ) | throws IllegalArgumentException, IllegalStateException, SecurityException

static

Setting a custom `Resolver` instance.

Parameters

  r | `Resolver` to use after querying class file URLs from the classloader.

Exceptions

  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

Definition at line 86 of file JarUtil.java.

Here is the caller graph for this function:

## ◆ validateCertificates()

static final void com.jogamp.common.util.JarUtil.validateCertificates | ( | final Certificate[] | rootCerts,
|  | final JarFile | jarFile
| ) |  | throws IOException, SecurityException

static

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();

Definition at line 696 of file JarUtil.java.

The documentation for this class was generated from the following file:

- src/java/com/jogamp/common/util/JarUtil.java