com.jogamp.common.util
Class JarUtil

java.lang.Object
  extended by com.jogamp.common.util.JarUtil

public class JarUtil
extends Object


Nested Class Summary
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
JarUtil()
           
 
Method Summary
static int extract(File dest, Map<String,String> nativeLibMap, JarFile jarFile, 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)
          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.
static URI getJarEntryURI(URI jarFileURI, String jarEntry)
           
static JarFile getJarFile(String clazzBinName, ClassLoader cl)
           
static JarFile getJarFile(URI jarFileURI)
           
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 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)
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
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

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

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,
                                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 -
deepDirectoryTraversal -
extractNativeLibraries -
extractClassFiles -
extractOtherFiles -
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