Module org.eclipse.jetty.util

Package org.eclipse.jetty.util.resource

Class Resource

java.lang.Object

org.eclipse.jetty.util.resource.Resource

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, ResourceFactory

Direct Known Subclasses:

EmptyResource, PathResource, ResourceCollection, URLResource

public abstract class Resource
extends java.lang.Object
implements ResourceFactory, java.io.Closeable

Abstract resource class.

This class provides a resource abstraction, where a resource may be a file, a URL or an entry in a jar file.

Field Summary

Fields

Modifier and Type	Field	Description
static boolean	__defaultUseCaches

Constructor Summary

Constructors

Constructor	Description
Resource()

Method Summary

Modifier and Type	Method	Description
abstract Resource	addPath(java.lang.String path)	Returns the resource contained inside the current resource with the given name, which may or may not exist.
abstract void	close()	Release any temporary resources held by the resource.
void	copyTo(java.io.File destination)	Copy the Resource to the new destination file.
abstract boolean	delete()	Deletes the given resource
abstract boolean	exists()
static java.util.List<Resource>	fromList(java.lang.String resources, boolean globDirs)	Parse a list of String delimited resources and return the List of Resources instances it represents.
static java.util.List<Resource>	fromList(java.lang.String resources, boolean globDirs, ResourceFactory resourceFactory)	Parse a delimited String of resource references and return the List of Resources instances it represents.
java.net.URI	getAlias()
java.util.Collection<Resource>	getAllResources()
java.lang.Object	getAssociate()
static boolean	getDefaultUseCaches()
abstract java.io.File	getFile()	File representing the given resource.
abstract java.io.InputStream	getInputStream()	Input stream to the resource
java.lang.String	getListHTML(java.lang.String base, boolean parent, java.lang.String query)	Get the resource list as a HTML directory listing.
abstract java.lang.String	getName()	The name of the resource.
abstract java.nio.channels.ReadableByteChannel	getReadableByteChannel()	Readable ByteChannel for the resource.
Resource	getResource(java.lang.String path)	Get a resource from within this resource.
abstract java.net.URI	getURI()	URI representing the resource.
java.lang.String	getWeakETag()	Generate a weak ETag reference for this Resource.
java.lang.String	getWeakETag(java.lang.String suffix)
boolean	isAlias()
abstract boolean	isContainedIn(Resource r)
static boolean	isContainedIn(Resource r, Resource containingResource)
abstract boolean	isDirectory()
boolean	isSame(Resource resource)	Return true if the passed Resource represents the same resource as the Resource.
abstract long	lastModified()	Time resource was last modified.
abstract long	length()	Length of the resource.
abstract java.lang.String[]	list()	list of resource names contained in the given resource.
static Resource	newClassPathResource(java.lang.String resource)	Find a classpath resource.
static Resource	newClassPathResource(java.lang.String name, boolean useCaches, boolean checkParents)	Find a classpath resource.
static Resource	newResource(java.io.File file)
static Resource	newResource(java.lang.String resource)	Construct a resource from a string.
static Resource	newResource(java.lang.String resource, boolean useCaches)	Construct a resource from a string.
static Resource	newResource(java.net.URI uri)	Construct a resource from a uri.
static Resource	newResource(java.net.URL url)	Construct a resource from a url.
static Resource	newResource(java.nio.file.Path path)	Construct a Resource from provided path
static Resource	newSystemResource(java.lang.String resource)	Construct a system resource from a string.
abstract boolean	renameTo(Resource dest)	Rename the given resource
void	setAssociate(java.lang.Object o)
static void	setDefaultUseCaches(boolean useCaches)	Change the default setting for url connection caches.
static java.net.URL	toURL(java.io.File file)	Generate a properly encoded URL from a File instance.

Methods inherited from class java.lang.Object

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

Field Detail

__defaultUseCaches

public static boolean __defaultUseCaches

Constructor Detail

Resource

public Resource()

Method Detail

setDefaultUseCaches

public static void setDefaultUseCaches(boolean useCaches)

Change the default setting for url connection caches. Subsequent URLConnections will use this default.

Parameters:

useCaches - true to enable URL connection caches, false otherwise.

getDefaultUseCaches

public static boolean getDefaultUseCaches()

newResource

public static Resource newResource(java.net.URI uri)
                            throws java.net.MalformedURLException

Construct a resource from a uri.

Parameters:

uri - A URI.

Returns:

A Resource object.

Throws:

java.net.MalformedURLException - Problem accessing URI

newResource

public static Resource newResource(java.net.URL url)

Construct a resource from a url.

Parameters:

url - A URL.

Returns:

A Resource object.

newResource

public static Resource newResource(java.lang.String resource)
                            throws java.io.IOException

Construct a resource from a string.

Parameters:

resource - A URL or filename.

Returns:

A Resource object.

Throws:

java.net.MalformedURLException - Problem accessing URI

java.io.IOException

newResource

public static Resource newResource(java.lang.String resource,
                                   boolean useCaches)
                            throws java.io.IOException

Construct a resource from a string.

Parameters:

resource - A URL or filename.

useCaches - controls URLConnection caching

Returns:

A Resource object.

Throws:

java.net.MalformedURLException - Problem accessing URI

java.io.IOException

newResource

public static Resource newResource(java.io.File file)

newResource

public static Resource newResource(java.nio.file.Path path)

Construct a Resource from provided path

Parameters:

path - the path

Returns:

the Resource for the provided path

Since:

9.4.10

newSystemResource

public static Resource newSystemResource(java.lang.String resource)
                                  throws java.io.IOException

Construct a system resource from a string. The resource is tried as classloader resource before being treated as a normal resource.

Parameters:

resource - Resource as string representation

Returns:

The new Resource

Throws:

java.io.IOException - Problem accessing resource.

newClassPathResource

public static Resource newClassPathResource(java.lang.String resource)

Find a classpath resource.

Parameters:

resource - the relative name of the resource

Returns:

Resource or null

newClassPathResource

public static Resource newClassPathResource(java.lang.String name,
                                            boolean useCaches,
                                            boolean checkParents)

Find a classpath resource. The Class.getResource(String) method is used to lookup the resource. If it is not found, then the Loader.getResource(String) method is used. If it is still not found, then ClassLoader.getSystemResource(String) is used. Unlike ClassLoader.getSystemResource(String) this method does not check for normal resources.

Parameters:

name - The relative name of the resource

useCaches - True if URL caches are to be used.

checkParents - True if forced searching of parent Classloaders is performed to work around loaders with inverted priorities

Returns:

Resource or null

isContainedIn

public static boolean isContainedIn(Resource r,
                                    Resource containingResource)
                             throws java.net.MalformedURLException

Throws:

java.net.MalformedURLException

isContainedIn

public abstract boolean isContainedIn(Resource r)
                               throws java.net.MalformedURLException

Throws:

java.net.MalformedURLException

isSame

public boolean isSame(Resource resource)

Return true if the passed Resource represents the same resource as the Resource. For many resource types, this is equivalent to Object.equals(Object), however for resources types that support aliasing, this maybe some other check (e.g. Files.isSameFile(Path, Path)).

Parameters:

resource - The resource to check

Returns:

true if the passed resource represents the same resource.

close

public abstract void close()

Release any temporary resources held by the resource.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

exists

public abstract boolean exists()

Returns:

true if the represented resource exists.

isDirectory

public abstract boolean isDirectory()

Returns:

true if the represented resource is a container/directory.

lastModified

public abstract long lastModified()

Time resource was last modified.

Returns:

the last modified time as milliseconds since unix epoch

length

public abstract long length()

Length of the resource.

Returns:

the length of the resource

getURI

public abstract java.net.URI getURI()

URI representing the resource.

Returns:

an URI representing the given resource

getFile

public abstract java.io.File getFile()
                              throws java.io.IOException

File representing the given resource.

Returns:

an File representing the given resource or NULL if this is not possible.

Throws:

java.io.IOException - if unable to get the resource due to permissions

getName

public abstract java.lang.String getName()

The name of the resource.

Returns:

the name of the resource

getInputStream

public abstract java.io.InputStream getInputStream()
                                            throws java.io.IOException

Input stream to the resource

Returns:

an input stream to the resource

Throws:

java.io.IOException - if unable to open the input stream

getReadableByteChannel

public abstract java.nio.channels.ReadableByteChannel getReadableByteChannel()
                                                                      throws java.io.IOException

Readable ByteChannel for the resource.

Returns:

an readable bytechannel to the resource or null if one is not available.

Throws:

java.io.IOException - if unable to open the readable bytechannel for the resource.

delete

public abstract boolean delete()
                        throws java.lang.SecurityException

Deletes the given resource

Returns:

true if resource was found and successfully deleted, false if resource didn't exist or was unable to be deleted.

Throws:

java.lang.SecurityException - if unable to delete due to permissions

renameTo

public abstract boolean renameTo(Resource dest)
                          throws java.lang.SecurityException

Rename the given resource

Parameters:

dest - the destination name for the resource

Returns:

true if the resource was renamed, false if the resource didn't exist or was unable to be renamed.

Throws:

java.lang.SecurityException - if unable to rename due to permissions

list

public abstract java.lang.String[] list()

list of resource names contained in the given resource. Ordering is unspecified, so callers may wish to sort the return value to ensure deterministic behavior.

Returns:

a list of resource names contained in the given resource, or null. Note: The resource names are not URL encoded.

addPath

public abstract Resource addPath(java.lang.String path)
                          throws java.io.IOException,
                                 java.net.MalformedURLException

Returns the resource contained inside the current resource with the given name, which may or may not exist.

Parameters:

path - The path segment to add, which is not encoded. The path may be non canonical, but if so then the resulting Resource will return true from isAlias().

Returns:

the Resource for the resolved path within this Resource, never null

Throws:

java.io.IOException - if unable to resolve the path

java.net.MalformedURLException - if the resolution of the path fails because the input path parameter is malformed, or a relative path attempts to access above the root resource.

getResource

public Resource getResource(java.lang.String path)
                     throws java.io.IOException

Get a resource from within this resource.

Specified by:

getResource in interface ResourceFactory

Parameters:

path - The path to the resource

Returns:

The resource, that might not actually exist (yet).

Throws:

java.io.IOException - if unable to create Resource

getAssociate

public java.lang.Object getAssociate()

setAssociate

public void setAssociate(java.lang.Object o)

isAlias

public boolean isAlias()

Returns:

true if this Resource is an alias to another real Resource

getAlias

public java.net.URI getAlias()

Returns:

The canonical Alias of this resource or null if none.

getListHTML

public java.lang.String getListHTML(java.lang.String base,
                                    boolean parent,
                                    java.lang.String query)
                             throws java.io.IOException

Get the resource list as a HTML directory listing.

Parameters:

base - The base URL

parent - True if the parent directory should be included

query - query params

Returns:

String of HTML

Throws:

java.io.IOException - on failure to generate a list.

copyTo

public void copyTo(java.io.File destination)
            throws java.io.IOException

Copy the Resource to the new destination file.

Will not replace existing destination file.

Parameters:

destination - the destination file to create

Throws:

java.io.IOException - if unable to copy the resource

getWeakETag

public java.lang.String getWeakETag()

Generate a weak ETag reference for this Resource.

Returns:

the weak ETag reference for this resource.

getWeakETag

public java.lang.String getWeakETag(java.lang.String suffix)

getAllResources

public java.util.Collection<Resource> getAllResources()

toURL

public static java.net.URL toURL(java.io.File file)
                          throws java.net.MalformedURLException

Generate a properly encoded URL from a File instance.

Parameters:

file - Target file.

Returns:

URL of the target file.

Throws:

java.net.MalformedURLException - if unable to convert File to URL

fromList

public static java.util.List<Resource> fromList(java.lang.String resources,
                                                boolean globDirs)
                                         throws java.io.IOException

Parse a list of String delimited resources and return the List of Resources instances it represents.

Supports glob references that end in /* or \*. Glob references will only iterate through the level specified and will not traverse found directories within the glob reference.

Parameters:

resources - the comma , or semicolon ; delimited String of resource references.

globDirs - true to return directories in addition to files at the level of the glob

Returns:

the list of resources parsed from input string.

Throws:

java.io.IOException

fromList

public static java.util.List<Resource> fromList(java.lang.String resources,
                                                boolean globDirs,
                                                ResourceFactory resourceFactory)
                                         throws java.io.IOException

Parse a delimited String of resource references and return the List of Resources instances it represents.

Supports glob references that end in /* or \*. Glob references will only iterate through the level specified and will not traverse found directories within the glob reference.

Parameters:

resources - the comma , or semicolon ; delimited String of resource references.

globDirs - true to return directories in addition to files at the level of the glob

resourceFactory - the ResourceFactory used to create new Resource references

Returns:

the list of resources parsed from input string.

Throws:

java.io.IOException