Class Handlers

java.lang.Object
org.bzdev.protocols.Handlers

public class Handlers extends Object
Configuration class for protocol handlers. This class enables various protocol handlers by setting or modifying a system property for handlers defined in subpackages of the current package. Only the subpackages actually intended for use should be included in an application. Protocol Properties are set by setting system properties whose names start with "org.bzdev.protocols." followed by the name of the protocol or scheme, followed by a period and then the name of the property. When protocol handlers are enabled by calling Handlers.enable(), system properties starting with "org.bzdev.protocols." are read and stored under a key consisting of the remainder of the system-property key. Thus, a system property named org.bzdev.protocols.resource.path is used to set the path property for the resource protocol. A call to Handlers.get("resource.path") will return this property.

The supported schemes are

  • resource. This scheme looks up resources based on a class path whose entries are separated by the path-separator character ('|' on Unix/Linux systems) and that is stored in a system property named org.bzdev.protocols.resource.path. If this system property is not provided, the system class loader will be used as a default. The path entry $classpath indicates that the system class loader will be used to look for the resource, and may be included as a component in the class path. It should be the first entry when it is desirable to prevent other classes from overriding a resource that the system class loader would otherwise provide. The class path's components are directories, jar files, zip files, or URLs ("http", "https", "ftp", "file", or "jar") and must point to a directory or similar object, not a specific file. As a reminder, a "jar" URL starts with "jar", followed by a URL for the jar or zip file, followed by "!/", and then a path. The entries will be searched in the order they appear (left to right). The "resource" URL itself consists of the protocol specification, "resource:", followed by a path naming the resource. This path is added to the end of the URL for each entry until a resource can be found or the entry list is exhausted.
  • sresource. This scheme looks up resources using the system class loader.
For the sresource scheme, the handler simply uses the method ClassLoader.getSystemClassLoader() to find the system class loader and then uses the method ClassLoader.getResource(String) to obtain a URL that will allow access to the resource. This URL is used instead of the 'sresource' URL, so security is provided by the standard Java mechanisms. For the resource scheme, additional permissions have to be granted. The locations for the resource (typically JAR files, ZIP files, or directories, but possibly resources accessible over a network connection) are provided by the system property described above, and cannot be changed once enable() is called. In addition, the path portion of the URL (the part after "resource:"), is checked so that
  • the path does not contain any illegal characters: ones not allowed by RFC 3986. The character '\' specifically is not allowed as a literal character in the URL.
  • ".." entries in the path will not result in access to an ancestor of an entry in the list of resource locations.
After Java 8, a module system was added to Java and this places some constraints on the visibility of resources. Generally, a module must declare a package to be "open" for its resources to be accessible. The unnamed module (i.e., the code accessed via a classpath) is open. For named modules, the module-info.java file must explicitly indicate that a package is open (a Java command-line option can also be used, but there is no guarantee that this option will not be eliminated in future releases.) For the "resource" protocol, however, the files or directories explicitly listed by the org.bzdev.protocols.resource.path property are accessed through the file system, bypassing any constraints imposed by the Java module system with one exception: the path component $classpath will have its resources searched using the system class loader.
  • Constructor Details

    • Handlers

      public Handlers()
  • Method Details

    • enable

      public static void enable() throws SecurityException
      Enables protocol/scheme handlers. The handlers enabled are ones in the subpackages of org.bzdev.protocols. The property list that Handlers maintains is also initialized by searching the system properties for properties whose names start with "org.bzdev.protocols." with the remainder of the name used as the property name in the Handlers property list and the value of the system property as the corresponding value in the Handlers property list. Calls to enable() should be made only once - after the first call, subsequent calls are ignored.
      Throws:
      SecurityException
    • getProperty

      public static String getProperty(String key)
      Get a property. Properties are optionally used by schemes whose handlers are in subpackages of org.bzdev.protocols. This method is used to retrieve the value of one of these properties. A property obtained by this method is independent of one with the same key obtained by calling java.lang.System.getProperty.
      Parameters:
      key - the key for the property
      Returns:
      the property stored under the key; null if there is none.
    • sameFile

      public static boolean sameFile(URL u1, URL u2)
      Determine if two URLs reference the same file.
      Parameters:
      u1 - the first URL
      u2 - the second URL
      Returns:
      true if the URLs reference the same file; false otherwise.