Package io.github.classgraph
Class Resource
- java.lang.Object
-
- io.github.classgraph.Resource
-
- All Implemented Interfaces:
java.io.Closeable
,java.lang.AutoCloseable
,java.lang.Comparable<Resource>
public abstract class Resource extends java.lang.Object implements java.io.Closeable, java.lang.Comparable<Resource>
A classpath or module path resource (i.e. file) that was found in an accepted/non-rejected package inside a classpath element or module.
-
-
Field Summary
Fields Modifier and Type Field Description protected java.nio.ByteBuffer
byteBuffer
The byte buffer, or null.private ClasspathElement
classpathElement
The classpath element this resource was obtained from.protected java.io.InputStream
inputStream
The input stream, or null.protected long
length
The length, or -1L for unknown.(package private) LogNode
scanLog
TheLogNode
used to log that the resource was found when classpath element paths are scanned.private java.lang.String
toString
The cached result of toString().
-
Constructor Summary
Constructors Constructor Description Resource(ClasspathElement classpathElement, long length)
Constructor.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description void
close()
Close the underlying InputStream, or release/unmap the underlying ByteBuffer.int
compareTo(Resource o)
Compare to.boolean
equals(java.lang.Object obj)
Equals.java.io.File
getClasspathElementFile()
Get the classpath elementFile
.java.net.URI
getClasspathElementURI()
Get theURI
of the classpath element or module that this resource was obtained from.java.net.URL
getClasspathElementURL()
Get theURL
of the classpath element or module that this resource was obtained from.java.lang.String
getContentAsString()
Convenience method to get the content of thisResource
as a String.abstract long
getLastModified()
Get the last modified time for the resource, in milliseconds since the epoch.long
getLength()
Get the length of the resource.ModuleRef
getModuleRef()
abstract java.lang.String
getPath()
Get the path of this classpath resource relative to the package root.java.lang.String
getPathRelativeToClasspathElement()
Get the full path of this classpath resource relative to the root of the classpath element.abstract java.util.Set<java.nio.file.attribute.PosixFilePermission>
getPosixFilePermissions()
Get the POSIX file permissions for the resource.java.net.URI
getURI()
Get theURI
representing the resource's location.java.net.URL
getURL()
Get theURL
representing the resource's location.int
hashCode()
Hash code.abstract byte[]
load()
Load a classpath resource and return its content as a byte array.abstract java.io.InputStream
open()
Open anInputStream
for a classpath resource.(package private) abstract ClassfileReader
openClassfile()
Open aClassfileReader
on the resource (for reading classfiles).abstract java.nio.ByteBuffer
read()
Open aByteBuffer
for a classpath resource.CloseableByteBuffer
readCloseable()
Open aByteBuffer
for a classpath resource, and wrap it in aCloseableByteBuffer
instance, which implements theCloseable.close()
method to free the underlyingByteBuffer
whenCloseableByteBuffer.close()
is called, by automatically callingclose()
.java.lang.String
toString()
Get a string representation of the resource's location (as a URL string).private static java.net.URL
uriToURL(java.net.URI uri)
Convert a URI to URL, catching "jrt:" URIs as invalid.
-
-
-
Field Detail
-
classpathElement
private final ClasspathElement classpathElement
The classpath element this resource was obtained from.
-
inputStream
protected java.io.InputStream inputStream
The input stream, or null.
-
byteBuffer
protected java.nio.ByteBuffer byteBuffer
The byte buffer, or null.
-
length
protected long length
The length, or -1L for unknown.
-
toString
private java.lang.String toString
The cached result of toString().
-
-
Constructor Detail
-
Resource
public Resource(ClasspathElement classpathElement, long length)
Constructor.- Parameters:
classpathElement
- the classpath element this resource was obtained from.length
- the length the length of the resource.
-
-
Method Detail
-
uriToURL
private static java.net.URL uriToURL(java.net.URI uri)
Convert a URI to URL, catching "jrt:" URIs as invalid.- Parameters:
uri
- the uri- Returns:
- the URL.
- Throws:
java.lang.IllegalArgumentException
- if the URI could not be converted to a URL, or the URI had "jrt:" scheme.
-
getURI
public java.net.URI getURI()
Get theURI
representing the resource's location.- Returns:
- A
URI
representing the resource's location. - Throws:
java.lang.IllegalArgumentException
- the resource was obtained from a module and the module's location URI is null.
-
getURL
public java.net.URL getURL()
Get theURL
representing the resource's location. UsegetURI()
instead if the resource may have come from a system module, or if this is a jlink'd runtime image, since "jrt:" URI schemes used by system modules and jlink'd runtime images are not supported byURL
, and this will causeIllegalArgumentException
to be thrown.- Returns:
- A
URL
representing the resource's location. - Throws:
java.lang.IllegalArgumentException
- if the resource was obtained from a system module or jlink'd runtime image with a "jrt:" location URI, or the resource was obtained from a module and the module's location URI is null
-
getClasspathElementURI
public java.net.URI getClasspathElementURI()
Get theURI
of the classpath element or module that this resource was obtained from.- Returns:
- The
URL
of the classpath element or module that this resource was found within. - Throws:
java.lang.IllegalArgumentException
- if the classpath element does not have a valid URI (e.g. for modules whose location URI is null).
-
getClasspathElementURL
public java.net.URL getClasspathElementURL()
Get theURL
of the classpath element or module that this resource was obtained from. UsegetClasspathElementURI()
instead if the resource may have come from a system module, or if this is a jlink'd runtime image, since "jrt:" URI schemes used by system modules and jlink'd runtime images are not supported byURL
, and this will causeIllegalArgumentException
to be thrown.- Returns:
- The
URL
of the classpath element or module that this resource was found within. - Throws:
java.lang.IllegalArgumentException
- if the resource was obtained from a system module or jlink'd runtime image with a "jrt:" location URI, or the resource was obtained from a module and the module's location URI is null.
-
getClasspathElementFile
public java.io.File getClasspathElementFile()
Get the classpath elementFile
.- Returns:
- The
File
for the classpath element package root dir or jar that thisResource
was found within, or null if thisResource
was found in a module backed by a "jrt:" URI, or a module with an unknown location. May also return null if the classpath element was an http/https URL, and the jar was downloaded directly to RAM, rather than to a temp file on disk (e.g. if the temp dir is not writeable).
-
getModuleRef
public ModuleRef getModuleRef()
-
getContentAsString
public java.lang.String getContentAsString() throws java.io.IOException
Convenience method to get the content of thisResource
as a String. Assumes UTF8 encoding. (Callsclose()
after completion.)- Returns:
- the content of this
Resource
as a String. - Throws:
java.io.IOException
- If an I/O exception occurred.
-
getPath
public abstract java.lang.String getPath()
Get the path of this classpath resource relative to the package root.- Returns:
- the path of this classpath resource relative to the package root. For example, for a resource path of
"BOOT-INF/classes/com/xyz/resource.xml"
and a package root of"BOOT-INF/classes/"
, returns"com/xyz/resource.xml"
. Also drops version prefixes for multi-version jars, for example for a resource path of"META-INF/versions/11/com/xyz/resource.xml"
while running on JDK 9+, returns"com/xyz/resource.xml"
.
-
getPathRelativeToClasspathElement
public java.lang.String getPathRelativeToClasspathElement()
Get the full path of this classpath resource relative to the root of the classpath element.- Returns:
- the full path of this classpath resource within the classpath element. For example, will return the
full path of
"BOOT-INF/classes/com/xyz/resource.xml"
or"META-INF/versions/11/com/xyz/resource.xml"
, not"com/xyz/resource.xml"
.
-
open
public abstract java.io.InputStream open() throws java.io.IOException
Open anInputStream
for a classpath resource. Make sure you callclose()
when you are finished with theInputStream
, so that theInputStream
is closed.- Returns:
- The opened
InputStream
. - Throws:
java.io.IOException
- If theInputStream
could not be opened.
-
read
public abstract java.nio.ByteBuffer read() throws java.io.IOException
Open aByteBuffer
for a classpath resource. Make sure you callclose()
when you are finished with theByteBuffer
, so that theByteBuffer
is released or unmapped. See alsoreadCloseable()
.- Returns:
- The allocated or mapped
ByteBuffer
for the resource file content. - Throws:
java.io.IOException
- If the resource could not be read.
-
readCloseable
public CloseableByteBuffer readCloseable() throws java.io.IOException
Open aByteBuffer
for a classpath resource, and wrap it in aCloseableByteBuffer
instance, which implements theCloseable.close()
method to free the underlyingByteBuffer
whenCloseableByteBuffer.close()
is called, by automatically callingclose()
.Call
CloseableByteBuffer.getByteBuffer()
on the returned instance to access the underlyingByteBuffer
.- Returns:
- The allocated or mapped
ByteBuffer
for the resource file content. - Throws:
java.io.IOException
- If the resource could not be read.
-
load
public abstract byte[] load() throws java.io.IOException
Load a classpath resource and return its content as a byte array. Automatically callsclose()
after loading the byte array and before returning it, so that the underlying InputStream is closed or the underlying ByteBuffer is released or unmapped.- Returns:
- The contents of the resource file.
- Throws:
java.io.IOException
- If the file contents could not be loaded in their entirety.
-
openClassfile
abstract ClassfileReader openClassfile() throws java.io.IOException
Open aClassfileReader
on the resource (for reading classfiles).- Returns:
- the
ClassfileReader
. - Throws:
java.io.IOException
- if an I/O exception occurs.
-
getLength
public long getLength()
Get the length of the resource.- Returns:
- The length of the resource. This only reliably returns a valid value after calling
open()
,read()
, orload()
(and foropen()
, only if the underlying jarfile has length information for correspondingZipEntry
-- some jarfiles may not have length information in their zip entries). Returns -1L if the length is unknown.
-
getLastModified
public abstract long getLastModified()
Get the last modified time for the resource, in milliseconds since the epoch. This time is obtained from the directory entry, if this resource is a file on disk, or from the zipfile central directory, if this resource is a zipfile entry. Timestamps are not available for resources obtained from system modules or jlink'd modules.Note: The ZIP format has no notion of timezone, so timestamps are only meaningful if it is known what timezone they were created in. We arbitrarily assume that zipfile timestamps are in the UTC timezone. This may be a wrong assumption, so you may need to apply a timezone correction if you know the timezone used by the zipfile creator.
- Returns:
- The millis since the epoch indicating the date / time that this file resource was last modified. Returns 0L if the last modified date is unknown.
-
getPosixFilePermissions
public abstract java.util.Set<java.nio.file.attribute.PosixFilePermission> getPosixFilePermissions()
Get the POSIX file permissions for the resource. POSIX file permissions are obtained from the directory entry, if this resource is a file on disk, or from the zipfile central directory, if this resource is a zipfile entry. POSIX file permissions are not available for resources obtained from system modules or jlink'd modules, and may not be available on non-POSIX-compliant operating systems or non-POSIX filesystems.- Returns:
- The set of
PosixFilePermission
permission flags for the resource, or null if unknown.
-
toString
public java.lang.String toString()
Get a string representation of the resource's location (as a URL string).- Overrides:
toString
in classjava.lang.Object
- Returns:
- the resource location as a URL String.
-
hashCode
public int hashCode()
Hash code.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- the int
-
equals
public boolean equals(java.lang.Object obj)
Equals.- Overrides:
equals
in classjava.lang.Object
- Parameters:
obj
- the obj- Returns:
- true, if successful
-
compareTo
public int compareTo(Resource o)
Compare to.- Specified by:
compareTo
in interfacejava.lang.Comparable<Resource>
- Parameters:
o
- the o- Returns:
- the int
-
close
public void close()
Close the underlying InputStream, or release/unmap the underlying ByteBuffer.- Specified by:
close
in interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
-
-