Top Description Inners Fields Methods
org.eclipse.jetty.util.resource

public Interface ResourceFactory

Known Direct Subinterfaces
org.eclipse.jetty.util.resource.ResourceFactory.Closeable, org.eclipse.jetty.util.resource.ResourceFactory.LifeCycle
Known Direct Implementers
org.eclipse.jetty.util.resource.ResourceFactoryInternals.CompositeResourceFactory, org.eclipse.jetty.util.resource.URLResourceFactory, org.eclipse.jetty.util.resource.MountedPathResourceFactory, org.eclipse.jetty.util.resource.PathResourceFactory
Imports
java.net.URI, .URISyntaxException, .URL, java.nio.file.Path, java.util.ArrayList, .List, .Objects, java.util.function.Function, org.eclipse.jetty.util.StringUtil, .URIUtil, org.eclipse.jetty.util.component.Container, .Dumpable, org.slf4j.Logger, .LoggerFactory

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 org.eclipse.jetty.util.component.Container

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

The use of ResourceFactory#of(Container) results in a ResourceFactory.LifeCycle that is tied to a specific Jetty org.eclipse.jetty.util.component.Container such as a Server, ServletContextHandler, or WebAppContext. This will free the Resource instances created by the org.eclipse.jetty.util.resource.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 ResourceFactory#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 ResourceFactory#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 ResourceFactory#registerResourceFactory(String, ResourceFactory).

Supporting more Schemes

You can register a new URI scheme to a ResourceFactory implementation using the ResourceFactory#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://eclipse.dev/jetty/");
    Resource resource = ResourceFactory.root().newResource(web);

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static interface
ResourceFactory.Closeable

public static interface
ResourceFactory.LifeCycle

Field Summary

Modifier and TypeField and Description
public static final Logger
LOG

Method Summary

Modifier and TypeMethod and Description
public static ResourceFactory.Closeable

Returns:

a ResourceFactory that can be closed in a try-with-resources code block
closeable()

A ResourceFactory that can close it's opened resources using the Java standard AutoCloseable techniques.

public static Resource

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()
combine(List<Resource>
multiple directory Resources to combine as a single resource. Order is significant.
resources)

Make a directory Resource containing a collection of other directory Resources

public static Resource

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()
combine(Resource...
multiple directory Resources to combine as a single resource. Order is significant.
resources)

Make a directory Resource containing a collection of directory Resources

public static boolean

Returns:

true if it is supported
isSupported(String
the string to test
str)

Test to see if provided string is supported.

public static boolean

Returns:

true if it is supported
isSupported(URI
the uri to test
uri)

Test to see if provided uri is supported.

public static ResourceFactory.LifeCycle

Returns:

the ResourceFactory that implements org.eclipse.jetty.util.component.LifeCycle
lifecycle()

A ResourceFactory that implements the Jetty LifeCycle.

public default Resource

Returns:

The new Resource, or null if string points to a location that does not exist
newClassLoaderResource(String
the resource name to find in a classloader
resource, boolean
true to search ClassLoader#getSystemResource(String), false to skip
searchSystemClassLoader)

Construct a Resource from a search of ClassLoaders.

public default Resource

Returns:

The new Resource, or null if string points to a location that does not exist
newClassLoaderResource(String
string representation of resource to find in a classloader
resource)

Construct a Resource from a search of ClassLoaders.

public default Resource

Returns:

Resource, or null if string points to a location that does not exist
newClassPathResource(String
the relative name of the resource
resource)

Deprecated for removal since 12.0.2. use newClassLoaderResource(String, boolean) instead, will be removed in Jetty 12.1.0

Construct a Resource from a search of ClassLoaders.

public default Resource

Returns:

the Resource, mounted as a java.nio.file.FileSystem, or null if the uri points to a location that does not exist.
newJarFileResource(URI
the URI
uri)

Construct a Resource from a file: based URI that is mountable (eg: a jar file).

public default Resource

Returns:

Resource, or null if url points to a location that does not exist
newMemoryResource(URL
the URL to load into memory
url)

Load a URL into a memory resource.

public Resource

Returns:

A Resource object, or null if uri points to a location that does not exist.
newResource(URI
A URI.
uri)

Construct a resource from a uri.

public default Resource

Returns:

A Resource object, or null if the string points to a location that does not exist
newResource(String
A URL or filename.
resource)

Construct a resource from a string.

public default Resource

Returns:

the Resource for the provided path, or null if the path does not exist
newResource(Path
the path
path)

Construct a Resource from provided path.

public default Resource

Returns:

the Resource for the provided URIs, or null if all of the provided URIs do not exist
newResource(List<URI>
the URIs
uris)

Construct a possible combined Resource from a list of URIs.

public default Resource

Returns:

the Resource for the provided URL, or null if the url points to a location that does not exist
newResource(URL
the URL
url)

Construct a Resource from a provided URL.

public default Resource

Returns:

The new Resource, or null if string points to a location that does not exist
newSystemResource(String
Resource as string representation
resource)

Deprecated for removal since 12.0.2. 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.

public static ResourceFactory

Returns:

the ResourceFactory that builds from the Resource
of(Resource
the resource to base this ResourceFactory from
baseResource)

A new ResourceFactory from a provided Resource, to base newResource(URI) and newResource(String) calls against.

public static ResourceFactory

Returns:

the ResourceFactory that belongs to this container
of(Container
the container this ResourceFactory belongs to
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.

public static void
registerResourceFactory(String
the scheme to support (eg: `ftp`, `http`, `resource`, etc)
scheme, ResourceFactory
the ResourceFactory to be responsible for the registered scheme.
resourceFactory)

Register a new ResourceFactory that can handle the specific scheme for the Resource API.

public static ResourceFactory

Returns:

the JVM wide ResourceFactory.
root()

The JVM wide (root) ResourceFactory.

public static ResourceFactory

Returns:

the existing ResourceFactory that was registered to that scheme.
unregisterResourceFactory(String
the scheme to unregister
scheme)

Unregister a scheme that is supported by the Resource API.

Field Detail

LOGback to summary
public static final Logger LOG

Method Detail

closeableback to summary
public static ResourceFactory.Closeable closeable()

A ResourceFactory that can close it's opened resources using the Java standard AutoCloseable techniques.

Returns:ResourceFactory.Closeable

a ResourceFactory that can be closed in a try-with-resources code block

combineback to summary
public static Resource combine(List<Resource> resources)

Make a directory Resource containing a collection of other directory Resources

Parameters
resources:List<Resource>

multiple directory Resources to combine as a single resource. Order is significant.

Returns:Resource

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()

Exceptions
IllegalArgumentException:
if a non-directory resource is passed.
combineback to summary
public static Resource combine(Resource... resources)

Make a directory Resource containing a collection of directory Resources

Parameters
resources:Resource[]

multiple directory Resources to combine as a single resource. Order is significant.

Returns:Resource

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()

Exceptions
IllegalArgumentException:
if a non-directory resource is passed.
isSupportedback to summary
public static boolean isSupported(String str)

Test to see if provided string is supported.

Parameters
str:String

the string to test

Returns:boolean

true if it is supported

isSupportedback to summary
public static boolean isSupported(URI uri)

Test to see if provided uri is supported.

Parameters
uri:URI

the uri to test

Returns:boolean

true if it is supported

lifecycleback to summary
public 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:ResourceFactory.LifeCycle

the ResourceFactory that implements org.eclipse.jetty.util.component.LifeCycle

newClassLoaderResourceback to summary
public 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:String

the resource name to find in a classloader

searchSystemClassLoader:boolean

true to search ClassLoader#getSystemResource(String), false to skip

Returns:Resource

The new Resource, or null if string points to a location that does not exist

Exceptions
IllegalArgumentException:
if resource name or resulting URL from ClassLoader is invalid.
newClassLoaderResourceback to summary
public default Resource newClassLoaderResource(String resource)

Construct a Resource from a search of ClassLoaders.

Convenience method .newClassLoaderResource(resource, true)

Parameters
resource:String

string representation of resource to find in a classloader

Returns:Resource

The new Resource, or null if string points to a location that does not exist

Exceptions
IllegalArgumentException:
if string is blank
See Also
newClassLoaderResource(String, boolean)
newClassPathResourceback to summary
public default Resource newClassPathResource(String resource)

Deprecated

for removal since 12.0.2.

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:String

the relative name of the resource

Returns:Resource

Resource, or null if string points to a location that does not exist

Annotations
@Deprecated
since:12.0.2
forRemoval:true
Exceptions
IllegalArgumentException:
if string is blank
See Also
newClassLoaderResource(String, boolean)
newJarFileResourceback to summary
public default Resource newJarFileResource(URI uri)

Construct a Resource from a file: based URI that is mountable (eg: a jar file).

Parameters
uri:URI

the URI

Returns:Resource

the Resource, mounted as a java.nio.file.FileSystem, or null if the uri points to a location that does not exist.

Exceptions
IllegalArgumentException:
if provided URI is not "file" scheme.
newMemoryResourceback to summary
public 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:URL

the URL to load into memory

Returns:Resource

Resource, or null if url points to a location that does not exist

Exceptions
IllegalArgumentException:
if URL is null
See Also
newClassLoaderResource(String, boolean)
newResourceback to summary
public Resource newResource(URI uri)

Construct a resource from a uri.

Parameters
uri:URI

A URI.

Returns:Resource

A Resource object, or null if uri points to a location that does not exist.

newResourceback to summary
public default Resource newResource(String resource)

Construct a resource from a string.

Parameters
resource:String

A URL or filename.

Returns:Resource

A Resource object, or null if the string points to a location that does not exist

Exceptions
IllegalArgumentException:
if resource is invalid
newResourceback to summary
public default Resource newResource(Path path)

Construct a Resource from provided path.

Parameters
path:Path

the path

Returns:Resource

the Resource for the provided path, or null if the path does not exist

Exceptions
IllegalArgumentException:
if path is null
newResourceback to summary
public default Resource newResource(List<URI> uris)

Construct a possible combined Resource from a list of URIs.

Parameters
uris:List<URI>

the URIs

Returns:Resource

the Resource for the provided URIs, or null if all of the provided URIs do not exist

Exceptions
IllegalArgumentException:
if list of URIs is empty or null
newResourceback to summary
public default Resource newResource(URL url)

Construct a Resource from a provided URL.

Parameters
url:URL

the URL

Returns:Resource

the Resource for the provided URL, or null if the url points to a location that does not exist

Exceptions
IllegalArgumentException:
if url is null
newSystemResourceback to summary
public default Resource newSystemResource(String resource)

Deprecated

for removal since 12.0.2.

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:String

Resource as string representation

Returns:Resource

The new Resource, or null if string points to a location that does not exist

Annotations
@Deprecated
since:12.0.2
forRemoval:true
Exceptions
IllegalArgumentException:
if string is blank
See Also
newClassLoaderResource(String, boolean)
ofback to summary
public static ResourceFactory of(Resource baseResource)

A new ResourceFactory from a provided Resource, to base newResource(URI) and newResource(String) calls against.

Parameters
baseResource:Resource

the resource to base this ResourceFactory from

Returns:ResourceFactory

the ResourceFactory that builds from the Resource

ofback to summary
public 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:Container

the container this ResourceFactory belongs to

Returns:ResourceFactory

the ResourceFactory that belongs to this container

registerResourceFactoryback to summary
public 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:String

the scheme to support (eg: `ftp`, `http`, `resource`, etc)

resourceFactory:ResourceFactory

the ResourceFactory to be responsible for the registered scheme.

Exceptions
IllegalArgumentException:
if scheme is blank
See Also
unregisterResourceFactory(String)
rootback to summary
public 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:ResourceFactory

the JVM wide ResourceFactory.

See Also
closeable(), lifecycle()
unregisterResourceFactoryback to summary
public static ResourceFactory unregisterResourceFactory(String scheme)

Unregister a scheme that is supported by the Resource API.

Parameters
scheme:String

the scheme to unregister

Returns:ResourceFactory

the existing ResourceFactory that was registered to that scheme.

Exceptions
IllegalArgumentException:
if scheme is blank
See Also
registerResourceFactory(String, ResourceFactory)
org.eclipse.jetty.util.resource back to summary

public Interface ResourceFactory.Closeable

extends ResourceFactory, Closeable
Known Direct Implementers
org.eclipse.jetty.util.resource.ResourceFactoryInternals.Closeable

Field Summary

Inherited from org.eclipse.jetty.util.resource.ResourceFactory:
LOG

Method Summary

Modifier and TypeMethod and Description
public void
close()

Redeclares java.io.Closeable.close.

Closes this stream and releases any system resources associated with it.
Inherited from org.eclipse.jetty.util.resource.ResourceFactory:
closeablecombinecombineisSupportedisSupportedlifecyclenewClassLoaderResourcenewClassLoaderResourcenewClassPathResourcenewJarFileResourcenewMemoryResourcenewResourcenewResourcenewResourcenewResourcenewResourcenewSystemResourceofofregisterResourceFactoryrootunregisterResourceFactory

Method Detail

closeback to summary
public void close()

Redeclares java.io.Closeable.close.

Doc from java.io.Closeable.close.

Closes this stream and releases any system resources associated with it. If the stream is already closed then invoking this method has no effect.

As noted in AutoCloseable#close(), cases where the close may fail require careful attention. It is strongly advised to relinquish the underlying resources and to internally mark the Closeable as closed, prior to throwing the IOException.

Annotations
@Override
org.eclipse.jetty.util.resource back to summary

public Interface ResourceFactory.LifeCycle

extends LifeCycle, ResourceFactory, Dumpable
Known Direct Implementers
org.eclipse.jetty.util.resource.ResourceFactoryInternals.LifeCycle

Field Summary

Inherited from org.eclipse.jetty.util.component.Dumpable:
KEY
Inherited from org.eclipse.jetty.util.resource.ResourceFactory:
LOG

Method Summary

Inherited from org.eclipse.jetty.util.component.Dumpable:
dumpdumpdumpdumpContainerdumpIterabledumpMapEntriesdumpObjectdumpObjectsdumpSelfnamed
Inherited from org.eclipse.jetty.util.component.LifeCycle:
addEventListenerisFailedisRunningisStartedisStartingisStoppedisStoppingremoveEventListenerstartstartstopstop
Inherited from org.eclipse.jetty.util.resource.ResourceFactory:
closeablecombinecombineisSupportedisSupportedlifecyclenewClassLoaderResourcenewClassLoaderResourcenewClassPathResourcenewJarFileResourcenewMemoryResourcenewResourcenewResourcenewResourcenewResourcenewResourcenewSystemResourceofofregisterResourceFactoryrootunregisterResourceFactory