cogImprove Java's ClassLoader APIs and add ability to register URL stream handlers
Developed by

XWiki Development Team

0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise


Exists since XWiki 2.0.1.


This module uses code originally written by Dawid Kurzyniec and released to the public domain.

Compared to the standard Java Class loading API, this module adds:

  • Namespacing
  • Ability to add URLs to an already constructed URLClassLoader
  • Several bugfixes and improvements. From its Javadoc:
    * Equivalent of but without bugs related to ill-formed URLs and with customizable JAR caching
     * policy. The standard URLClassLoader accepts URLs containing spaces and other characters which are forbidden in the
     * URI syntax, according to the RFC 2396. As a workaround to this problem, Java escapes and un-escapes URLs in various
     * arbitrary places; however, this is inconsistent and leads to numerous problems with URLs referring to local files
     * with spaces in the path. SUN acknowledges the problem, but refuses to modify the behavior for compatibility reasons;
     * see Java Bug Parade 4273532, 4466485.
     * <p>
     * Additionally, the JAR caching policy used by URLClassLoader is system-wide and inflexible: once downloaded JAR files
     * are never re-downloaded, even if one creates a fresh instance of the class loader that happens to have the same URL
     * in its search path. In fact, that policy is a security vulnerability: it is possible to crash any URL class loader,
     * thus affecting potentially separate part of the system, by creating URL connection to one of the URLs of that class
     * loader search path and closing the associated JAR file. See Java Bug Parade 4405789, 4388666, 4639900.
     * <p>
     * This class avoids these problems by 1) using URIs instead of URLs for the search path (thus enforcing strict syntax
     * conformance and defining precise escaping semantics), and 2) using custom URLStreamHandler which ensures
     * per-classloader JAR caching policy.

In addition it allows registering new URL Stream handlers (this is used for example by the jars parameter of the Script Macro).

Adding a new URL Stream Handler

This is useful for example if you wish to add a new way to reference a JAR when using the Script Macro. For example imagine you wish to retrieve the JAR from a remote Maven Repository by passing only a groupId, artifactId and a version. You could implement a new Stream Handler to be able to write something like:

{{groovy jars="groupId:artifactId:version"}}

To do so, Implements a component implementing the org.xwiki.classloader.ExtendedURLStreamHandler role. 

Example: AttachmentURLStreamHandler

public class AttachmentURLStreamHandler extends URLStreamHandler implements ExtendedURLStreamHandler

Created by Vincent Massol on 2014/07/04 14:19

Get Connected