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 and Description
protected java.nio.ByteBuffer	byteBuffer The byte buffer, or null.
protected java.io.InputStream	inputStream The input stream, or null.
protected long	length The length, or -1L for unknown.

Constructor Summary

Constructors

Constructor and Description
Resource(io.github.classgraph.ClasspathElement classpathElement, long length) Constructor.

Method Summary

Modifier and Type	Method and 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 element File.
java.net.URI	getClasspathElementURI() Get the URI of the classpath element or module that this resource was obtained from.
java.net.URL	getClasspathElementURL() Get the URL of the classpath element or module that this resource was obtained from.
java.lang.String	getContentAsString() Convenience method to get the content of this Resource 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() Get the The ModuleRef for the module that this Resource was found within.
abstract java.lang.String	getPath() Get the path of this classpath resource relative to the package root.
abstract 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 the URI representing the resource's location.
java.net.URL	getURL() Get the URL 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 an InputStream for a classpath resource.
abstract java.nio.ByteBuffer	read() Open a ByteBuffer for a classpath resource.
CloseableByteBuffer	readCloseable() Open a ByteBuffer for a classpath resource, and wrap it in a CloseableByteBuffer instance, which implements the Closeable.close() method to free the underlying ByteBuffer when CloseableByteBuffer.close() is called, by automatically calling close().
java.lang.String	toString() Get a string representation of the resource's location (as a URL string).

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

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.

Constructor Detail

Resource

public Resource(io.github.classgraph.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

getURI

public java.net.URI getURI()

Get the URI 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 the URL representing the resource's location. Use getURI() 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 by URL, and this will cause IllegalArgumentException 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 the URI 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 the URL of the classpath element or module that this resource was obtained from. Use getClasspathElementURI() 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 by URL, and this will cause IllegalArgumentException 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 element File.

Returns:

The File for the classpath element package root dir or jar that this Resource was found within, or null if this Resource 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()

Get the The ModuleRef for the module that this Resource was found within.

Returns:

The ModuleRef for the module that this Resource was found within, as a ModuleRef, or null if this Resource was found in a directory or jar in the classpath.

getContentAsString

public java.lang.String getContentAsString()
                                    throws java.io.IOException

Convenience method to get the content of this Resource as a String. Assumes UTF8 encoding. (Calls close() 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 abstract 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 an InputStream for a classpath resource. Make sure you call close() when you are finished with the InputStream, so that the InputStream is closed.

Returns:

The opened InputStream.

Throws:

java.io.IOException - If the InputStream could not be opened.

read

public abstract java.nio.ByteBuffer read()
                                  throws java.io.IOException

Open a ByteBuffer for a classpath resource. Make sure you call close() when you are finished with the ByteBuffer, so that the ByteBuffer is released or unmapped. See also readCloseable().

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 a ByteBuffer for a classpath resource, and wrap it in a CloseableByteBuffer instance, which implements the Closeable.close() method to free the underlying ByteBuffer when CloseableByteBuffer.close() is called, by automatically calling close().

Call CloseableByteBuffer.getByteBuffer() on the returned instance to access the underlying ByteBuffer.

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 calls close() 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.

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(), or load() (and for open(), only if the underlying jarfile has length information for corresponding ZipEntry -- 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 class java.lang.Object

Returns:

the resource location as a URL String.

hashCode

public int hashCode()

Hash code.

Overrides:

hashCode in class java.lang.Object

Returns:

the int

equals

public boolean equals(java.lang.Object obj)

Equals.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the obj

Returns:

true, if successful

compareTo

public int compareTo(Resource o)

Compare to.

Specified by:

compareTo in interface java.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 interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable