Class Resource

java.lang.Object
org.eclipse.jetty.util.resource.Resource
All Implemented Interfaces:
Closeable, AutoCloseable, ResourceFactory
Direct Known Subclasses:
EmptyResource, FileResource, PathResource, ResourceCollection, URLResource

public abstract class Resource extends Object implements ResourceFactory, 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 Details

    • LOG

      private static final Logger LOG
    • __defaultUseCaches

      public static boolean __defaultUseCaches
    • _associate

      volatile Object _associate
  • Constructor Details

    • Resource

      public Resource()
  • Method Details

    • 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(URI uri) throws MalformedURLException
      Construct a resource from a uri.
      Parameters:
      uri - A URI.
      Returns:
      A Resource object.
      Throws:
      MalformedURLException - Problem accessing URI
    • newResource

      public static Resource newResource(URL url)
      Construct a resource from a url.
      Parameters:
      url - A URL.
      Returns:
      A Resource object.
    • newResource

      static Resource newResource(URL url, boolean useCaches)
      Construct a resource from a url.
      Parameters:
      url - the url for which to make the resource
      useCaches - true enables URLConnection caching if applicable to the type of resource
    • newResource

      public static Resource newResource(String resource) throws IOException
      Construct a resource from a string.
      Parameters:
      resource - A URL or filename.
      Returns:
      A Resource object.
      Throws:
      MalformedURLException - Problem accessing URI
      IOException
    • newResource

      public static Resource newResource(String resource, boolean useCaches) throws IOException
      Construct a resource from a string.
      Parameters:
      resource - A URL or filename.
      useCaches - controls URLConnection caching
      Returns:
      A Resource object.
      Throws:
      MalformedURLException - Problem accessing URI
      IOException
    • newResource

      public static Resource newResource(File file)
    • newResource

      public static Resource newResource(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(String resource) throws 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:
      IOException - Problem accessing resource.
    • newClassPathResource

      public static Resource newClassPathResource(String resource)
      Find a classpath resource.
      Parameters:
      resource - the relative name of the resource
      Returns:
      Resource or null
    • newClassPathResource

      public static Resource newClassPathResource(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 MalformedURLException
      Throws:
      MalformedURLException
    • finalize

      protected void finalize()
      Overrides:
      finalize in class Object
    • isContainedIn

      public abstract boolean isContainedIn(Resource r) throws MalformedURLException
      Throws:
      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.
    • release

      public final void release()
      Deprecated.
      Release any temporary resources held by the resource.
    • close

      public abstract void close()
      Release any temporary resources held by the resource.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface 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. if the resource is not a file, resources ending with "/" are considered directories.
    • 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
    • getURL

      @Deprecated public abstract URL getURL()
      Deprecated.
      use {getURI().toURL() instead.
      URL representing the resource.
      Returns:
      a URL representing the given resource
    • getURI

      public URI getURI()
      URI representing the resource.
      Returns:
      an URI representing the given resource
    • getFile

      public abstract File getFile() throws IOException
      File representing the given resource.
      Returns:
      an File representing the given resource or NULL if this is not possible.
      Throws:
      IOException - if unable to get the resource due to permissions
    • getName

      public abstract String getName()
      The name of the resource.
      Returns:
      the name of the resource
    • getInputStream

      public abstract InputStream getInputStream() throws IOException
      Input stream to the resource
      Returns:
      an input stream to the resource
      Throws:
      IOException - if unable to open the input stream
    • getReadableByteChannel

      public abstract ReadableByteChannel getReadableByteChannel() throws IOException
      Readable ByteChannel for the resource.
      Returns:
      an readable bytechannel to the resource or null if one is not available.
      Throws:
      IOException - if unable to open the readable bytechannel for the resource.
    • delete

      public abstract boolean delete() throws 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:
      SecurityException - if unable to delete due to permissions
    • renameTo

      public abstract boolean renameTo(Resource dest) throws 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:
      SecurityException - if unable to rename due to permissions
    • list

      public abstract 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(String path) throws IOException, MalformedURLException
      Returns the resource contained inside the current resource with the given name.
      Parameters:
      path - The path segment to add, which is not encoded
      Returns:
      the Resource for the resolved path within this Resource.
      Throws:
      IOException - if unable to resolve the path
      MalformedURLException - if the resolution of the path fails because the input path parameter is malformed.
    • getResource

      public Resource getResource(String path)
      Get a resource from within this resource.

      This method is essentially an alias for addPath(String), but without checked exceptions. This method satisfied the ResourceFactory interface.

      Specified by:
      getResource in interface ResourceFactory
      Parameters:
      path - The path to the resource
      Returns:
      The resource or null
      See Also:
    • encode

      @Deprecated public String encode(String uri)
      Deprecated.
      use URIUtil or UrlEncoded instead
      Parameters:
      uri - the uri to encode
      Returns:
      null (this is deprecated)
    • getAssociate

      public Object getAssociate()
    • setAssociate

      public void setAssociate(Object o)
    • isAlias

      public boolean isAlias()
      Returns:
      true if this Resource is an alias to another real Resource
    • getAlias

      public URI getAlias()
      Returns:
      The canonical Alias of this resource or null if none.
    • getListHTML

      @Deprecated public String getListHTML(String base, boolean parent) throws IOException
      Deprecated.
      use getListHTML(String, boolean, String) instead and supply raw query string.
      Get the resource list as a HTML directory listing.
      Parameters:
      base - The base URL
      parent - True if the parent directory should be included
      Returns:
      String of HTML
      Throws:
      IOException - if unable to get the list of resources as HTML
    • getListHTML

      public String getListHTML(String base, boolean parent, String query) throws 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:
      IOException
    • getFileName

      private String getFileName()
      Get the raw (decoded if possible) Filename for this Resource. This is the last segment of the path.
      Returns:
      the raw / decoded filename for this resource
    • hrefEncodeURI

      private static String hrefEncodeURI(String raw)
      Encode any characters that could break the URI string in an HREF. The above example would parse incorrectly on various browsers as the "invalid input: '<'" or '"' characters would end the href attribute value string prematurely.
      Parameters:
      raw - the raw text to encode.
      Returns:
      the defanged text.
    • deTag

      private static String deTag(String raw)
    • writeTo

      public void writeTo(OutputStream out, long start, long count) throws IOException
      Parameters:
      out - the output stream to write to
      start - First byte to write
      count - Bytes to write or -1 for all of them.
      Throws:
      IOException - if unable to copy the Resource to the output
    • copyTo

      public void copyTo(File destination) throws IOException
      Copy the Resource to the new destination file.

      Will not replace existing destination file.

      Parameters:
      destination - the destination file to create
      Throws:
      IOException - if unable to copy the resource
    • getWeakETag

      public String getWeakETag()
      Generate a weak ETag reference for this Resource.
      Returns:
      the weak ETag reference for this resource.
    • getWeakETag

      public String getWeakETag(String suffix)
    • longToBytes

      private static byte[] longToBytes(long value)
    • getAllResources

      public Collection<Resource> getAllResources()
    • toURL

      public static URL toURL(File file) throws MalformedURLException
      Generate a properly encoded URL from a File instance.
      Parameters:
      file - Target file.
      Returns:
      URL of the target file.
      Throws:
      MalformedURLException - if unable to convert File to URL