Interface ResourceFactory

All Known Subinterfaces:
ResourceFactory.Closeable, ResourceFactory.LifeCycle
All Known Implementing Classes:
MountedPathResourceFactory, PathResourceFactory, URLResourceFactory
public interface ResourceFactory

ResourceFactory is the source of new Resource instances.

Some Resource objects have an internal allocation / release model, that the ResourceFactory is responsible for. Once a ResourceFactory is stopped, the Resource objects created from that ResourceFactory are released.

A ResourceFactory.LifeCycle tied to a Jetty Container

    ResourceFactory.LifeCycle resourceFactory = ResourceFactory.of(container);
    Resource resource = resourceFactory.newResource(ref);

The use of of(Container) results in a ResourceFactory.LifeCycle that is tied to a specific Jetty Container such as a Server, ServletContextHandler, or WebAppContext. This will free the Resource instances created by the ResourceFactory once the container that manages it is stopped.

A ResourceFactory.Closeable that exists within a try-with-resources call

    try (ResourceFactory.Closeable resourceFactory = ResourceFactory.closeable()) {
        Resource resource = resourceFactory.newResource(ref);
    }

The use of closeable() results in a ResourceFactory that only exists for the duration of the try-with-resources code block, once this try-with-resources is closed, all Resource objects associated with that ResourceFactory are freed as well.

A ResourceFactory that lives at the JVM level

    ResourceFactory resourceFactory = ResourceFactory.root();
    Resource resource = resourceFactory.newResource(ref);

The use of root() results in a ResourceFactory that exists for the life of the JVM, and the resources allocated via this ResourceFactory will not be freed until the JVM exits.

Supported URI Schemes

By default, the following schemes are supported by Jetty.

file
The standard Java file:/path/to/dir/ syntax
jar
The standard Java jar:file:/path/to/file.jar!/ syntax
jrt
The standard Java jrt:module-name syntax

Special Note: An effort is made to discover any new schemes that might be present at JVM startup (eg: graalvm and resource: scheme). At startup Jetty will access an internal Jetty resource (found in the jetty-util jar) and seeing what scheme it is using to access it, and will register it with a call to registerResourceFactory(String, ResourceFactory).

Supporting more Schemes

You can register a new URI scheme to a ResourceFactory implementation using the registerResourceFactory(String, ResourceFactory) method, which will cause all new uses of ResourceFactory to use this newly registered scheme. 

    URLResourceFactory urlResourceFactory = new URLResourceFactory();
    urlResourceFactory.setConnectTimeout(1000);
    ResourceFactory.registerResourceFactory("https", urlResourceFactory);

    URI web = URI.create("https://jetty.org/");
    Resource resource = ResourceFactory.root().newResource(web);

  • Field Details

    • LOG

      static final org.slf4j.Logger LOG

  • Method Details

    • combine

      static Resource combine(List<Resource> resources)

      Make a directory Resource containing a collection of other directory Resources

      Parameters:
      resources - multiple directory Resources to combine as a single resource. Order is significant.
      Returns:
      A CombinedResource for multiple resources; or a single Resource if only 1 is passed; or null if none are passed. The returned Resource will always return true from Resource.isDirectory()
      Throws:
      IllegalArgumentException - if a non-directory resource is passed.

    • combine

      static Resource combine(Resource... resources)

      Make a directory Resource containing a collection of directory Resources

      Parameters:
      resources - multiple directory Resources to combine as a single resource. Order is significant.
      Returns:
      A CombinedResource for multiple resources; or a single Resource if only 1 is passed; or null if none are passed. The returned Resource will always return true from Resource.isDirectory()
      Throws:
      IllegalArgumentException - if a non-directory resource is passed.

    • newResource

      Resource newResource(URI uri)
      Construct a resource from a uri.
      Parameters:
      uri - A URI.
      Returns:
      A Resource object.

    • newSystemResource

      @Deprecated(since="12.0.2", forRemoval=true) default Resource newSystemResource(String resource)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use newClassLoaderResource(String) or newClassLoaderResource(String, boolean) instead, will be removed in Jetty 12.1.0

      Construct a Resource from a string reference into classloaders.

      Parameters:
      resource - Resource as string representation
      Returns:
      The new Resource
      Throws:
      IllegalArgumentException - if string is blank
      See Also:

    • newClassLoaderResource

      default Resource newClassLoaderResource(String resource, boolean searchSystemClassLoader)

      Construct a Resource from a search of ClassLoaders.

      Search order is:

      1. java.lang.Thread.currentThread().getContextClassLoader().getResource(String)
      2. ResourceFactory.class.getClassLoader().getResource(String)
      3. (optional) java.lang.ClassLoader.getSystemResource(String)

      See ClassLoader.getResource(String) for rules on resource name parameter.

      If a provided resource name starts with a / (example: /org/example/ClassName.class) then the non-slash version is also tried against the same ClassLoader (example: org/example/ClassName.class).

      Parameters:
      resource - the resource name to find in a classloader
      searchSystemClassLoader - true to search ClassLoader.getSystemResource(String), false to skip
      Returns:
      The new Resource, which may be a CombinedResource if multiple directory resources are found.
      Throws:
      IllegalArgumentException - if resource name or resulting URL from ClassLoader is invalid.

    • newClassLoaderResource

      default Resource newClassLoaderResource(String resource)

      Construct a Resource from a search of ClassLoaders.

      Convenience method .newClassLoaderResource(resource, true)

      Parameters:
      resource - string representation of resource to find in a classloader
      Returns:
      The new Resource
      Throws:
      IllegalArgumentException - if string is blank
      See Also:

    • newClassPathResource

      @Deprecated(since="12.0.2", forRemoval=true) default Resource newClassPathResource(String resource)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use newClassLoaderResource(String, boolean) instead, will be removed in Jetty 12.1.0

      Construct a Resource from a search of ClassLoaders.

      Convenience method .newClassLoaderResource(resource, false)

      Parameters:
      resource - the relative name of the resource
      Returns:
      Resource
      Throws:
      IllegalArgumentException - if string is blank
      See Also:

    • newMemoryResource

      default Resource newMemoryResource(URL url)

      Load a URL into a memory resource.

      A Memory Resource is created from a the contents of URL.openStream() and kept in memory from that point forward. Never accessing the URL again to refresh it's contents.

      Parameters:
      url - the URL to load into memory
      Returns:
      Resource, or null if url points to a location that does not exist
      Throws:
      IllegalArgumentException - if URL is null
      See Also:

    • newResource

      default Resource newResource(String resource)
      Construct a resource from a string.
      Parameters:
      resource - A URL or filename.
      Returns:
      A Resource object, or null if the string points to a location that does not exist
      Throws:
      IllegalArgumentException - if resource is invalid

    • newResource

      default Resource newResource(Path path)
      Construct a Resource from provided path.
      Parameters:
      path - the path
      Returns:
      the Resource for the provided path, or null if the path does not exist
      Throws:
      IllegalArgumentException - if path is null

    • newResource

      default Resource newResource(List<URI> uris)
      Construct a possible combined Resource from a list of URIs.
      Parameters:
      uris - the URIs
      Returns:
      the Resource for the provided URIs, or null if all of the provided URIs do not exist
      Throws:
      IllegalArgumentException - if list of URIs is empty or null

    • newResource

      default Resource newResource(URL url)
      Construct a Resource from a provided URL.
      Parameters:
      url - the URL
      Returns:
      the Resource for the provided URL, or null if the url points to a location that does not exist
      Throws:
      IllegalArgumentException - if url is null

    • newJarFileResource

      default Resource newJarFileResource(URI uri)
      Construct a Resource from a file: based URI that is mountable (eg: a jar file).
      Parameters:
      uri - the URI
      Returns:
      the Resource, mounted as a FileSystem, or null if the uri points to a location that does not exist.
      Throws:
      IllegalArgumentException - if provided URI is not "file" scheme.

    • asResource

      default Resource asResource(Object obj)
      Convert an anonymous Object to a Resource.

      The supported types: Path, String, URI, URL, and Resource

      Parameters:
      obj - if the object to convert
      Returns:
      the Resource representing the provided obj
      Throws:
      IllegalArgumentException - if the object is none of the supported types.

    • split

      default List<Resource> split(String str)
      Split a string of references, that may be split with ',', or ';', or '|' into a List of Resource.

      Each part of the input string could be path references (unix or windows style), string URI references, or even glob references (eg: /path/to/libs/*).

      If the result of processing the input segment is a java archive, it will not automatically be mounted, the caller must perform the mount if necessary

      Parameters:
      str - the input string of references
      Returns:
      list of resources

    • split

      default List<Resource> split(String str, boolean unwrap)

    • split

      default List<Resource> split(String str, String delim)

    • split

      default List<Resource> split(String str, String delims, boolean unwrap)
      Split a string of references by provided delims into a List of Resource.

      Each part of the input string could be path references (unix or windows style), string URI references, or even glob references (eg: /path/to/libs/*). Note: that if you use the : character in your delims, then URI references will be impossible.

      If the result of processing the input segment is a java archive it will not be automatically mounted, the caller must mount if necessary

      Parameters:
      str - the input string of references
      delims - the list of delimiters
      unwrap - if true jar:file references will be unwrapped back to just the container
      Returns:
      list of resources

    • isSupported

      static boolean isSupported(String str)
      Test to see if provided string is supported.
      Parameters:
      str - the string to test
      Returns:
      true if it is supported

    • isSupported

      static boolean isSupported(URI uri)
      Test to see if provided uri is supported.
      Parameters:
      uri - the uri to test
      Returns:
      true if it is supported

    • registerResourceFactory

      static void registerResourceFactory(String scheme, ResourceFactory resourceFactory)
      Register a new ResourceFactory that can handle the specific scheme for the Resource API.

      This allows

      Parameters:
      scheme - the scheme to support (eg: `ftp`, `http`, `resource`, etc)
      resourceFactory - the ResourceFactory to be responsible for the registered scheme.
      Throws:
      IllegalArgumentException - if scheme is blank
      See Also:

    • unregisterResourceFactory

      static ResourceFactory unregisterResourceFactory(String scheme)
      Unregister a scheme that is supported by the Resource API.
      Parameters:
      scheme - the scheme to unregister
      Returns:
      the existing ResourceFactory that was registered to that scheme.
      Throws:
      IllegalArgumentException - if scheme is blank
      See Also:

    • root

      static ResourceFactory root()
      The JVM wide (root) ResourceFactory.

      Resources allocated this way are not released until the JVM is closed.

      If you have a ResourceFactory need that needs to clean up it's resources at runtime, use closeable() or lifecycle() instead.

      Returns:
      the JVM wide ResourceFactory.
      See Also:

    • closeable

      static ResourceFactory.Closeable closeable()
      A ResourceFactory that can close it's opened resources using the Java standard AutoCloseable techniques.
      Returns:
      a ResourceFactory that can be closed in a try-with-resources code block

    • lifecycle

      static ResourceFactory.LifeCycle lifecycle()
      A ResourceFactory that implements the Jetty LifeCycle.

      This style of ResourceFactory can be attached to the normal Jetty LifeCycle to clean up it's allocated resources.

      Returns:
      the ResourceFactory that implements LifeCycle

    • of

      @Deprecated(since="12.0.8", forRemoval=true) static ResourceFactory of(Resource baseResource)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use Resource.resolve(String)
      A new ResourceFactory from a provided Resource, to base newResource(URI) and newResource(String) calls against.
      Parameters:
      baseResource - the resource to base this ResourceFactory from
      Returns:
      the ResourceFactory that builds from the Resource

    • of

      static ResourceFactory of(Container container)
      A new ResourceFactory tied to a Jetty Component Container, to allow its allocated resources to be cleaned up during the normal component lifecycle behavior.

      This is safe to call repeatedly against the same Container, the first call will create a ResourceFactory from lifecycle() and add it as managed to the Container, subsequent calls will return the same ResourceFactory from the provided Container.

      Parameters:
      container - the container this ResourceFactory belongs to
      Returns:
      the ResourceFactory that belongs to this container