ilog.views.util

Class IlvClassLoaderUtil

java.lang.Object

ilog.views.util.IlvClassLoaderUtil

public class IlvClassLoaderUtil
extends Object

This class contains utility functions for registering class loaders and for looking up classes and resources.

Class loaders are designed to allow plugins (NetBeans, Eclipse, ...) to live in separate worlds and even to allow incompatible versions of the same class to coexist in the same JVM. Class loaders are opaque objects that can serve requests for classes and resources, given their name.

For resources and classes that are packaged within the same module or plugin, one can use the class loader of the executing class: Simply use getClass().getResource(...) or Class.forName(...). For accessing resources and classes that are packaged in a different module or plugin, or that are made accessible by the user in his environment (of which we don't know how it looks like), JViews uses the functions in this class: forName(java.lang.Class<?>, java.lang.String), getResource(java.lang.Class<?>, java.lang.String), getResourceAsStream(java.lang.Class<?>, java.lang.String). You can use these functions as well.

Through registerClassLoader(java.lang.ClassLoader) you can specify additional class loaders to be considered in the lookup process. These can be class loaders of application modules or plugins.

The functions in this class use the singleton instance of this class. The default lookup order is as follows:

1. They try the current thread's context class loader first. This class loader is customizable: The user can call Thread.currentThread().setContextClassLoader(...) before invoking JViews methods. This class loader is also able to emulate a list of class loaders: The user can implement a "MultiplexingClassLoader" if he needs to combine multiple class loaders into a single one (but this is rarely needed).
2. Then they try the class loaders registered through registerClassLoader(java.lang.ClassLoader).
3. Finally they fall back to the class loader of a class callingClass, which is the class from which you are operating.

Using the method setDelegate(IlvClassLoaderUtil), you can replace the singleton instance of this class with an instance of your subclass of yours, possibly overriding the methods forNameImpl(java.lang.Class<?>, java.lang.String), getResourceImpl(java.lang.Class<?>, java.lang.String), getResourceAsStreamImpl(java.lang.Class<?>, java.lang.String).

Background: http://www.javaworld.com/javaworld/javaqa/2003-06/01-qa-0606-load.html

Since:

JViews 8.1

Constructor Summary

Constructors

Constructor and Description
IlvClassLoaderUtil() Creates a new instance of IlvClassLoaderUtil.

Method Summary

Modifier and Type	Method and Description
static Class<?>	forName(Class<?> callingClass, String className) Returns a class put in place by the user.
Class<?>	forNameImpl(Class<?> callingClass, String className) Returns a class put in place by the user.
static ClassLoader	getClassLoaderInstance() Returns a ClassLoader that uses the lookup mechanism of this class.
static IlvClassLoaderUtil	getDefaultInstance() Returns the default instance of this class.
static IlvClassLoaderUtil	getDelegate() Returns the currently installed instance of this class.
static List<ClassLoader>	getRegisteredClassLoaders() Returns the list of registered class loaders.
static URL	getResource(Class<?> callingClass, String name) Returns the URL of a resource put in place by the user.
static InputStream	getResourceAsStream(Class<?> callingClass, String name) Returns a stream opened to read from a resource put in place by the user.
InputStream	getResourceAsStreamImpl(Class<?> callingClass, String name) Returns a stream opened to read from a resource put in place by the user.
URL	getResourceImpl(Class<?> callingClass, String name) Returns the URL of a resource put in place by the user.
static void	registerClassLoader(ClassLoader cl) Registers a class loader used for loading classes and resources.
static void	registerClassLoaderLifetimeListener(ClassLoader loader, ClassLoaderLifetimeListener listener) Registers a ClassLoaderLifetimeListener to be invoked when the given ClassLoader stops being actively used.
static void	setDelegate(IlvClassLoaderUtil newInstance) Replaces the currently installed instance of this class.
static void	unregisterClassLoader(ClassLoader cl) Unregisters a class loader used for loading classes and resources, and executes the ClassLoaderLifetimeListeners registered for the class loader.
static void	unregisterClassLoaderLifetimeListener(ClassLoader loader, ClassLoaderLifetimeListener listener) Unregisters a ClassLoaderLifetimeListener from being associated with a given ClassLoader.
static void	unregisterClassLoaderLifetimeListeners(ClassLoader loader) Unregisters all ClassLoaderLifetimeListeners associated with a given ClassLoader.

Methods inherited from class java.lang.Object

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

Constructor Detail

IlvClassLoaderUtil

public IlvClassLoaderUtil()

Creates a new instance of IlvClassLoaderUtil.

See Also:

setDelegate(IlvClassLoaderUtil)

Method Detail

registerClassLoaderLifetimeListener

public static void registerClassLoaderLifetimeListener(ClassLoader loader,
                                                       ClassLoaderLifetimeListener listener)

Registers a ClassLoaderLifetimeListener to be invoked when the given ClassLoader stops being actively used. The listener will be invoked once only: when unregisterClassLoader(ClassLoader) is called on the class loader.

You can register the same listener many times for a given ClassLoader; it will nevertheless be stored only once and be executed only once.

Since:

JViews 8.5

See Also:

unregisterClassLoader(ClassLoader), unregisterClassLoaderLifetimeListener(ClassLoader, ClassLoaderLifetimeListener)

unregisterClassLoaderLifetimeListener

public static void unregisterClassLoaderLifetimeListener(ClassLoader loader,
                                                         ClassLoaderLifetimeListener listener)

Unregisters a ClassLoaderLifetimeListener from being associated with a given ClassLoader.

Since:

JViews 8.5

See Also:

registerClassLoaderLifetimeListener(ClassLoader, ClassLoaderLifetimeListener)

unregisterClassLoaderLifetimeListeners

public static void unregisterClassLoaderLifetimeListeners(ClassLoader loader)

Unregisters all ClassLoaderLifetimeListeners associated with a given ClassLoader.

Since:

JViews 8.5

registerClassLoader

public static void registerClassLoader(ClassLoader cl)

Registers a class loader used for loading classes and resources.

Note: If you use this method during the startup of an Eclipse plug-in, you also have to use unregisterClassLoader(ClassLoader) during the shutdown of the same Eclipse plug-in.

Parameters:

cl - classloader used when searching a class or resource

See Also:

forName(Class, String), getResource(Class, String), getResourceAsStream(Class, String)

unregisterClassLoader

public static void unregisterClassLoader(ClassLoader cl)

Unregisters a class loader used for loading classes and resources, and executes the ClassLoaderLifetimeListeners registered for the class loader.

Note: If an Eclipse plug-in uses the JViews API, it should call this method during its shutdown, even if it did not use registerClassLoader(ClassLoader) during its startup.

Parameters:

cl - classloader used when searching a class or resource

See Also:

forName(Class, String), getResource(Class, String), getResourceAsStream(Class, String), registerClassLoaderLifetimeListener(ClassLoader, ClassLoaderLifetimeListener)

getRegisteredClassLoaders

public static List<ClassLoader> getRegisteredClassLoaders()

Returns the list of registered class loaders.

Returns:

an unmodifiable list of class loaders

forNameImpl

public Class<?> forNameImpl(Class<?> callingClass,
                            String className)
                     throws ClassNotFoundException

Returns a class put in place by the user. This method tries the following class loaders to load the class associated with the supplied name, className:

• the classloader from the current Thread.
• the classloaders registered by using registerClassLoader(ClassLoader)./li>
• the classloader at the caller location.
• Class.forName./li>

Parameters:

callingClass - the source for current class loader

className - the name of class to load

Returns:

the Class object for the class with the specified name.

Throws:

LinkageError - if the linkage fails

ExceptionInInitializerError - if the initialization provoked by this method fails

ClassNotFoundException - if the class cannot be located

See Also:

registerClassLoader(ClassLoader), unregisterClassLoader(ClassLoader)

getResourceImpl

public URL getResourceImpl(Class<?> callingClass,
                           String name)

Returns the URL of a resource put in place by the user.

Parameters:

callingClass - the source for current class loader

name - The name of the desired resource, using the same conventions as for the ClassLoader.getResource method: an absolute resource name, with the leading slash removed.

Returns:

a java.net.URL object, or null if the resource was not found

Throws:

IllegalArgumentException - if the name argument is syntactically incorrect

See Also:

registerClassLoader(ClassLoader), unregisterClassLoader(ClassLoader)

getResourceAsStreamImpl

public InputStream getResourceAsStreamImpl(Class<?> callingClass,
                                           String name)

Returns a stream opened to read from a resource put in place by the user.

Parameters:

callingClass - the source for current class loader

name - The name of the desired resource, using the same conventions as for the ClassLoader.getResource method: an absolute resource name, with the leading slash removed.

Returns:

a InputStream object, or null if the resource was not found

Throws:

IllegalArgumentException - if the name argument is syntactically incorrect

See Also:

registerClassLoader(ClassLoader), unregisterClassLoader(ClassLoader)

getDefaultInstance

public static IlvClassLoaderUtil getDefaultInstance()

Returns the default instance of this class.

getDelegate

public static IlvClassLoaderUtil getDelegate()

Returns the currently installed instance of this class.

setDelegate

public static void setDelegate(IlvClassLoaderUtil newInstance)

Replaces the currently installed instance of this class.

forName

public static Class<?> forName(Class<?> callingClass,
                               String className)
                        throws ClassNotFoundException

Returns a class put in place by the user. This method invokes forNameImpl(java.lang.Class<?>, java.lang.String) of the current instance.

Parameters:

callingClass - the source for current class loader

className - the name of class to load

Returns:

the Class object for the class with the specified name.

Throws:

LinkageError - if the linkage fails

ExceptionInInitializerError - if the initialization provoked by this method fails

ClassNotFoundException - if the class cannot be located

See Also:

forNameImpl(Class, String), registerClassLoader(ClassLoader), unregisterClassLoader(ClassLoader)

getResource

public static URL getResource(Class<?> callingClass,
                              String name)

Returns the URL of a resource put in place by the user. This method invokes getResourceImpl(java.lang.Class<?>, java.lang.String) of the current instance.

Parameters:

callingClass - the source for current class loader

name - The name of the desired resource, using the same conventions as for the ClassLoader.getResource method: an absolute resource name, with the leading slash removed.

Returns:

a java.net.URL object, or null if the resource was not found

Throws:

IllegalArgumentException - if the name argument is syntactically incorrect

See Also:

registerClassLoader(ClassLoader), unregisterClassLoader(ClassLoader)

getResourceAsStream

public static InputStream getResourceAsStream(Class<?> callingClass,
                                              String name)

Returns a stream opened to read from a resource put in place by the user. This method invokes getResourceAsStreamImpl(java.lang.Class<?>, java.lang.String) of the current instance.

Parameters:

callingClass - the source for current class loader

name - The name of the desired resource, using the same conventions as for the ClassLoader.getResource method: an absolute resource name, with the leading slash removed.

Returns:

an InputStream object, or null if the resource was not found

Throws:

IllegalArgumentException - if the name argument is syntactically incorrect

See Also:

registerClassLoader(ClassLoader), unregisterClassLoader(ClassLoader)

getClassLoaderInstance

public static ClassLoader getClassLoaderInstance()

Returns a ClassLoader that uses the lookup mechanism of this class. If it cannot be created, e.g. in an applet environment, this method returns another ClassLoader, possibly null.