com.jdotsoft.jarloader

Class JarClassLoader

java.lang.Object

java.lang.ClassLoader

com.jdotsoft.jarloader.JarClassLoader

public class JarClassLoader
extends ClassLoader

This class loader loads classes, native libraries and resources from the top JAR and from JARs inside top JAR. The loading process looks through JARs hierarchy and allows their tree structure, i.e. nested JARs.

The top JAR and nested JARs are included in the classpath and searched for the class or resource to load. The nested JARs could be located in any directories or subdirectories in a parent JAR.

All directories or subdirectories in the top JAR and nested JARs are included in the library path and searched for a native library. For example, the library "Native.dll" could be in the JAR root directory as "Native.dll" or in any directory as "lib/Native.dll" or "abc/xyz/Native.dll".

This class delegates class loading to the parent class loader and successfully loads classes, native libraries and resources when it works not in a JAR environment.

Create a launcher class to start your class com.mycompany.MyApp main() method to start your application

 public class MyAppLauncher {
     public static void main(String[] args) {
         JarClassLoader jcl = new JarClassLoader();
         try {
             jcl.invokeMain("com.mycompany.MyApp", args);
         } catch (Throwable e) {
             e.printStackTrace();
         }
     }
 }
 

An application could be started in two different environments:
1. Application is started from an exploded JAR with dependent resources locations defined in a classpath. Command line to start the application could point to the main class e.g. MyApp.main() or to the MyAppLauncher.main() class (see example above). The application behavior in both cases is identical. Application started with MyApp.main() uses system class loader and resources loaded from a file system. Application started with MyAppLauncher.main() uses JarClassLoader which transparently passes class loading to the system class loader.
2. Application is started from a JAR with dependent JARs and other resources inside the main JAR. Application must be started with MyAppLauncher.main() and JarClassLoader will load MyApp.main() and required resources from the main JAR.

The launcher class for the Java applet is very similar to application launcher.

 public class MyAppletLauncher extends JApplet {
     private JarClassLoader jcl;

     @Override
     public void init() {
         jcl = new JarClassLoader();
         try {
             jcl.initApplet("com.mycompany.MyApplet", this);
         } catch (Throwable e) {
             e.printStackTrace();
         }
     }

     @Override
     public void start() {
         jcl.startApplet();
     }

     @Override
     public void stop() {
         jcl.stopApplet();
     }

     @Override
     public void destroy() {
         jcl.destroyApplet();
     }
 }
 

The applet launcher class could have both main() and applet related methods for UI class which could be started as an application or an applet. This technique is very convenient to develop an applet and test it as an application.

Use VM parameters in the command line for logging settings (examples):

• -DJarClassLoader.logger=[filename] for logging into the file. The default is console.
• -DJarClassLoader.logger.level=INFO for logging level. The default level is ERROR. See also JarClassLoader.LogLevel.
• -DJarClassLoader.logger.area=CLASS,RESOURCE for logging area. The default area is ALL. See also JarClassLoader.LogArea. Multiple logging areas could be specified with ',' delimiter.

Known issues: some temporary files created by class loader are not deleted on application exit because JVM does not close handles to them. See details in shutdown().

See also discussion How load library from jar file? Unfortunately, the native method java.lang.ClassLoader$NativeLibrary.unload() is package accessed in a package accessed inner class. Moreover, it's called from finalizer. This does not allow releasing the native library handle and delete the temporary library file. Option to explore: use JNI function UnregisterNatives(). See also native code in ...\jdk\src\share\native\java\lang\ClassLoader.class

Version:

$Revision: 1.39 $

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	JarClassLoader.LogArea
static class	JarClassLoader.LogLevel

Field Summary

Fields

Modifier and Type	Field and Description
static String	KEY_LOGGER VM parameter key to turn on logging to file or console.
static String	KEY_LOGGER_AREA VM parameter key to define log area.
static String	KEY_LOGGER_LEVEL VM parameter key to define log level.
static String	TMP_SUB_DIRECTORY Sub directory name for temporary files.

Constructor Summary

Constructors

Constructor and Description
JarClassLoader() Default constructor.
JarClassLoader(ClassLoader parent) Constructor.

Method Summary

Modifier and Type	Method and Description
void	destroyApplet() Call this method to destroy the applet from your launcher class MyAppletLauncher.destroy() method.
protected String	findLibrary(String sLib)
protected URL	findResource(String sName)
Enumeration<URL>	findResources(String sName)
String	getManifestMainClass() Returns the name of the jar file main class, or null if no "Main-Class" manifest attributes was defined.
void	initApplet(String sClass, JApplet appletParent) Call this method to initialize an applet from your launcher class MyAppletLauncher.init() method.
void	invokeMain(String sClass, String[] args) Invokes main() method on class with provided parameters.
boolean	isLaunchedFromJar() Checks how the application was loaded: from JAR or file system.
protected Class<?>	loadClass(String sClassName, boolean bResolve) Class loader JavaDoc encourages overriding findClass(String) in derived class rather than overriding this method.
void	startApplet() Call this method to start the applet from your launcher class MyAppletLauncher.start() method.
void	stopApplet() Call this method to stop the applet from your launcher class MyAppletLauncher.stop() method.

Methods inherited from class java.lang.ClassLoader

clearAssertionStatus, defineClass, defineClass, defineClass, defineClass, definePackage, findClass, findLoadedClass, findSystemClass, getClassLoadingLock, getPackage, getPackages, getParent, getResource, getResourceAsStream, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, loadClass, registerAsParallelCapable, resolveClass, setClassAssertionStatus, setDefaultAssertionStatus, setPackageAssertionStatus, setSigners

Methods inherited from class java.lang.Object

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

Field Detail

KEY_LOGGER

public static final String KEY_LOGGER

VM parameter key to turn on logging to file or console.

See Also:

Constant Field Values

KEY_LOGGER_LEVEL

public static final String KEY_LOGGER_LEVEL

VM parameter key to define log level. Valid levels are defined in JarClassLoader.LogLevel. Default value is JarClassLoader.LogLevel.ERROR.

See Also:

Constant Field Values

KEY_LOGGER_AREA

public static final String KEY_LOGGER_AREA

VM parameter key to define log area. Valid areas are defined in JarClassLoader.LogArea. Default value is JarClassLoader.LogArea.ALL. Multiple areas could be specified with ',' delimiter (no spaces!).

See Also:

Constant Field Values

TMP_SUB_DIRECTORY

public static final String TMP_SUB_DIRECTORY

Sub directory name for temporary files.

JarClassLoader extracts all JARs and native libraries into temporary files and makes the best attempt to clean these files on exit.

The sub directory is created in the directory defined in a system property "java.io.tmpdir". Verify the content of this directory periodically and empty it if required. Temporary files could accumulate there if application was killed.

See Also:

Constant Field Values

Constructor Detail

JarClassLoader

public JarClassLoader()

Default constructor. Defines system class loader as a parent class loader.

JarClassLoader

public JarClassLoader(ClassLoader parent)

Constructor.

Parameters:

parent - class loader parent.

Method Detail

isLaunchedFromJar

public boolean isLaunchedFromJar()

Checks how the application was loaded: from JAR or file system.

Returns:

true if application was started from JAR.

getManifestMainClass

public String getManifestMainClass()

Returns the name of the jar file main class, or null if no "Main-Class" manifest attributes was defined.

Returns:

Main class declared in JAR's manifest.

invokeMain

public void invokeMain(String sClass,
                       String[] args)
                throws Throwable

Invokes main() method on class with provided parameters.

Parameters:

sClass - class name in form "MyClass" for default package or "com.abc.MyClass" for class in some package

args - arguments for the main() method or null.

Throws:

Throwable - wrapper for many exceptions thrown while

(1) main() method lookup: ClassNotFoundException, SecurityException, NoSuchMethodException

(2) main() method launch: IllegalArgumentException, IllegalAccessException (disabled)

(3) Actual cause of InvocationTargetException

See Also:

JarClassLoader class from Oracle Java Tutorials, JarClassLoader source code

initApplet

public void initApplet(String sClass,
                       JApplet appletParent)
                throws Throwable

Call this method to initialize an applet from your launcher class MyAppletLauncher.init() method.

Parameters:

sClass - class name in form "MyClass" for default package or "com.abc.MyClass" for class in some package

appletParent - parent applet from a launcher.

Throws:

Throwable - wrapper for many exceptions thrown while applet instantiation and calling init() method.

startApplet

public void startApplet()

Call this method to start the applet from your launcher class MyAppletLauncher.start() method.

stopApplet

public void stopApplet()

Call this method to stop the applet from your launcher class MyAppletLauncher.stop() method.

destroyApplet

public void destroyApplet()

Call this method to destroy the applet from your launcher class MyAppletLauncher.destroy() method.

loadClass

protected Class<?> loadClass(String sClassName,
                             boolean bResolve)
                      throws ClassNotFoundException

Class loader JavaDoc encourages overriding findClass(String) in derived class rather than overriding this method. This does not work for loading classes from a JAR. Default implementation of loadClass() is able to load a class from a JAR without calling findClass().

Overrides:

loadClass in class ClassLoader

Throws:

ClassNotFoundException

findResource

protected URL findResource(String sName)

Overrides:

findResource in class ClassLoader

Returns:

A URL object for reading the resource, or null if the resource could not be found. Example URL: jar:file:C:\...\some.jar!/resources/InnerText.txt

See Also:

ClassLoader.findResource(java.lang.String)

findResources

public Enumeration<URL> findResources(String sName)
                               throws IOException

Overrides:

findResources in class ClassLoader

Returns:

An enumeration of URL objects for the resources

Throws:

IOException

See Also:

ClassLoader.findResources(java.lang.String)

findLibrary

protected String findLibrary(String sLib)

Overrides:

findLibrary in class ClassLoader

Returns:

The absolute path of the native library.

See Also:

ClassLoader.findLibrary(java.lang.String)