Package com.globalmentor.io

Class ClassResources

java.lang.Object

com.globalmentor.io.ClassResources

public final class ClassResources
extends Object

Utilities for accessing Java class resources loaded from the classpath.

Author:

Garret Wilson

Field Summary

Fields

Modifier and Type	Field	Description
static final char	PATH_SEPARATOR	The slash character ('/') which separates components in a resource path.

Method Summary

Modifier and Type	Method	Description
static String	checkArgumentPathAbsolute(String resourcePath)	Checks to see if a resource path path is absolute.
static String	checkArgumentPathRelative(String resourcePath)	Checks to see if a resource path is relative.
static long	copy(Class<?> contextClass, String resourcePath, Path targetFile, CopyOption... options)	Copies all the bytes of a class resource to a file in a file system.
static long	copy(Class<?> contextClass, Path targetBaseDirectory, Iterable<String> resourcePaths, CopyOption... options)	Copies several class resources to a base directory in a file system, maintaining the relative directory hierarchy.
static long	copy(Class<?> contextClass, Path targetBaseDirectory, String... resourcePaths)	Copies several class resource to a base directory in a file system, maintaining the relative directory hierarchy.
static long	copy(ClassLoader classLoader, String resourcePath, Path targetFile, CopyOption... options)	Copies all the bytes of a class resource to a file in a file system.
static Optional<String>	findResourceName(String resourcePath)	Retrieves the filename for a resource given its path.
static String	getClassLoaderResourceBasePath(Class<?> contextClass)	Determines the base path necessary to access a named resource using the class loader of the given context class.
static String	getClassLoaderResourcePath(Class<?> contextClass, String resourcePath)	Determines the path necessary to access a named resource using the class loader of the given context class.
static List<String>	getPathSegments(String resourcePath)	Returns the segments (the characters appearing between '/' characters) in the given resource path.
static boolean	isPathAbsolute(String resourcePath)	Determines whether a resource path is absolute.
static boolean	isPathRelative(String resourcePath)	Determines whether a resource path is relative.
static <T> T	read(Class<?> objectClass, String name, IO<T> io)	Reads a class resource using the given class' class loader and the given I/O support.
static byte[]	readBytes(Class<?> contextClass, String resourcePath)	Reads all the bytes of a class resource.
static byte[]	readBytes(ClassLoader classLoader, String resourcePath)	Reads all the bytes of a class resource.

Methods inherited from class java.lang.Object

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

Field Details

PATH_SEPARATOR

public static final char PATH_SEPARATOR

The slash character ('/') which separates components in a resource path.

See Also:

• Constant Field Values

Method Details

isPathAbsolute

public static boolean isPathAbsolute(@Nonnull
 String resourcePath)

Determines whether a resource path is absolute.

Parameters:

resourcePath - The path to the class resource.

Returns:

true if the resource path begins with '/'.

See Also:

• isPathRelative(String)

checkArgumentPathAbsolute

public static String checkArgumentPathAbsolute(@Nonnull
 String resourcePath)
                                        throws IllegalArgumentException

Checks to see if a resource path path is absolute. If the resource path is not absolute, an exception is thrown.

Parameters:

resourcePath - The path to the class resource.

Returns:

The given resource path.

Throws:

IllegalArgumentException - if the resource path is not absolute.

See Also:

• isPathAbsolute(String)

isPathRelative

public static boolean isPathRelative(@Nonnull
 String resourcePath)

Determines whether a resource path is relative.

Parameters:

resourcePath - The path to the class resource.

Returns:

true if the resource path does not begin with '/'.

See Also:

• isPathAbsolute(String)

checkArgumentPathRelative

public static String checkArgumentPathRelative(@Nonnull
 String resourcePath)
                                        throws IllegalArgumentException

Checks to see if a resource path is relative. If the path is not relative, an exception is thrown.

Parameters:

resourcePath - The path to the class resource.

Returns:

The given resource path.

Throws:

IllegalArgumentException - if the resource path is absolute.

See Also:

• isPathRelative(String)

getPathSegments

public static List<String> getPathSegments(@Nonnull
 String resourcePath)

Returns the segments (the characters appearing between '/' characters) in the given resource path. This method does not take into consideration whether the resource path is relative or absolute; or whether it ends with a path separator. Thus com/example/foo/bar, /com/example/foo/bar, com/example/foo/bar/, and com/example/foo/bar/ will all return the segments "com", "example", "foo", and "bar". An empty string will result in an empty list.

API Note:

Because this method for the most part does not consider whether the path is relative or absolute, if this is relevant it must be checked by the caller.

Parameters:

resourcePath - The resource path to divide into segments.

Returns:

The segments of the given resource path.

Throws:

IllegalArgumentException - if there are more than one segment and a segment is empty, indicating subsequent path separators.

See Also:

• PATH_SEPARATOR

getClassLoaderResourceBasePath

public static String getClassLoaderResourceBasePath(@Nonnull
 Class<?> contextClass)

Determines the base path necessary to access a named resource using the class loader of the given context class.

Parameters:

contextClass - The class in relation to which the resource name should be resolved.

Returns:

The full relative base path, ending with a path separator, necessary to access resources using the resource loader of the given class.

See Also:

• getClassLoaderResourcePath(Class, String)
• ClassLoader.getResource(String)
• ClassLoader.getResourceAsStream(String)

getClassLoaderResourcePath

public static String getClassLoaderResourcePath(@Nonnull
 Class<?> contextClass,
 @Nonnull
 String resourcePath)

Determines the path necessary to access a named resource using the class loader of the given context class.

Accessing a resource via e.g. Class.getResource(String) for the class com.example.Foo may be accomplished using a resource name such as "bar", relative to the class package directory structure; but loading the same resource via ClassLoader.getResource(String) using the class loader for the same class requires the full path to the resource, such as com/example/bar. This method determines the full path that would need to be used to access a resource using a class loader for a class. Thus given class com.example.Foo and resource name bar, this method will return "com/example/bar". But if the absolute path /bar is passed, bar will be returned.

This method performs functionality equivalent to that performed internally to methods such as Class.getResource(String) before they delegate to the class loader.

Parameters:

contextClass - The class in relation to which the resource name should be resolved

resourcePath - The path of the resource to access, relative to the context class; or an absolute path that will be made relative to the class loader.

Returns:

The full relative path of the resource necessary to access it using the resource loader of the given class.

Throws:

IllegalArgumentException - if the given resource path begins with two path separators (i.e. two forward slashes).

See Also:

• ClassLoader.getResource(String)
• ClassLoader.getResourceAsStream(String)

findResourceName

public static Optional<String> findResourceName(@Nonnull
 String resourcePath)

Retrieves the filename for a resource given its path. The filename is guaranteed never to be the empty string.

Parameters:

resourcePath - The path to the resource.

Returns:

The filename of the resource, or Optional.empty() if the path ends with a separator.

Throws:

IllegalArgumentException - if the given resource path is empty.

copy

public static long copy(@Nonnull
 Class<?> contextClass,
 @Nonnull
 Path targetBaseDirectory,
 @Nonnull
 String... resourcePaths)
                 throws IOException

Copies several class resource to a base directory in a file system, maintaining the relative directory hierarchy.

API Note:

This is a convenience method for passing multiple resource paths as varargs. It provides no facility to indicate copy options, so if the operation needs to specify an option, to replace existing target files using StandardCopyOption.REPLACE_EXISTING for example, copy(Class, Path, Iterable, CopyOption...) should be used instead.

Implementation Specification:

This method delegates to copy(Class, Path, Iterable, CopyOption...).

Parameters:

contextClass - The class the class loader of which to use for retrieving the resources.

targetBaseDirectory - The base directory of the destination to where the resources should be copied. Any target parent directories will be created as needed.

resourcePaths - The paths of the resources, each relative to the context class; or each an absolute path that will be made relative to the class loader. The paths must not end in '/', and an empty path is not allowed.

Returns:

The total number of bytes copied.

Throws:

IOException - if an I/O error occurs when reading or writing. The exception may be a subclass of FileSystemException as per Files.copy(InputStream, Path, CopyOption...).

SecurityException - If the security manager does not permit the operation.

copy

public static long copy(@Nonnull
 Class<?> contextClass,
 @Nonnull
 Path targetBaseDirectory,
 @Nonnull
 Iterable<String> resourcePaths,
 CopyOption... options)
                 throws IOException

Copies several class resources to a base directory in a file system, maintaining the relative directory hierarchy.

For example copying the files example.txt and foo/bar.txt in the context of class com.example.Test to the target base directory /path/to/dest would copy the files to /path/to/dest/example.txt and /path/to/dest/foo/bar.txt.

API Note:

This operation is not atomic; it may fail having copied only some of the resources.

Implementation Specification:

This method delegates to copy(Class, String, Path, CopyOption...) for each resource to copy.

Parameters:

contextClass - The class the class loader of which to use for retrieving the resources.

targetBaseDirectory - The base directory of the destination to where the resources should be copied. Any target parent directories will be created as needed.

resourcePaths - The paths of the resources, each relative to the context class; or each an absolute path that will be made relative to the class loader. The paths must not end in '/', and an empty path is not allowed.

options - Options specifying how the copy should be performed.

Returns:

The total number of bytes copied.

Throws:

FileNotFoundException - if the indicated resource cannot be found.

IOException - if an I/O error occurs when reading or writing. The exception may be a subclass of FileSystemException as per Files.copy(InputStream, Path, CopyOption...).

UnsupportedOperationException - if options contains a copy option that is not supported.

SecurityException - If the security manager does not permit the operation.

copy

public static long copy(@Nonnull
 Class<?> contextClass,
 @Nonnull
 String resourcePath,
 @Nonnull
 Path targetFile,
 CopyOption... options)
                 throws IOException

Copies all the bytes of a class resource to a file in a file system.

Implementation Specification:

This method delegates to copy(ClassLoader, String, Path, CopyOption...).

Parameters:

contextClass - The class the class loader of which to use for retrieving the resource.

resourcePath - The path of the resource to access, relative to the context class; or an absolute path that will be made relative to the class loader.

targetFile - The path to the destination to where the resource should be copied. Any target parent directories will be created as needed.

options - Options specifying how the copy should be performed.

Returns:

The number of bytes copied.

Throws:

FileNotFoundException - if the indicated resource cannot be found.

IOException - if an I/O error occurs when reading or writing. The exception may be a subclass of FileSystemException as per Files.copy(InputStream, Path, CopyOption...).

UnsupportedOperationException - if options contains a copy option that is not supported.

SecurityException - If the security manager does not permit the operation.

copy

public static long copy(@Nonnull
 ClassLoader classLoader,
 @Nonnull
 String resourcePath,
 @Nonnull
 Path targetFile,
 CopyOption... options)
                 throws IOException

Copies all the bytes of a class resource to a file in a file system.

API Note:

This method requires the full classpath-relative path to the resource, unlike copy(Class, String, Path, CopyOption...), which requires a path relative to a class.

Implementation Specification:

This method delegates to Files.copy(InputStream, Path, CopyOption...).

Parameters:

classLoader - The class loader to use for retrieving the resource.

resourcePath - The full relative path of the resource in relation to the class loader.

targetFile - The path to the destination to where the resource should be copied. Any target parent directories will be created as needed.

options - Options specifying how the copy should be performed.

Returns:

The number of bytes copied.

Throws:

FileNotFoundException - if the indicated resource cannot be found.

IOException - if an I/O error occurs when reading or writing. The exception may be a subclass of FileSystemException as per Files.copy(InputStream, Path, CopyOption...).

UnsupportedOperationException - if options contains a copy option that is not supported.

SecurityException - If the security manager does not permit the operation.

readBytes

public static byte[] readBytes(@Nonnull
 Class<?> contextClass,
 @Nonnull
 String resourcePath)
                        throws IOException

Reads all the bytes of a class resource.

API Note:

This method is analogous to the Files.readAllBytes(Path) utility for paths.

Implementation Specification:

This method delegates to readBytes(ClassLoader, String).

Parameters:

contextClass - The class the class loader of which to use for retrieving the resource.

resourcePath - The path of the resource to access, relative to the context class; or an absolute path that will be made relative to the class loader.

Returns:

An array of all the bytes read from the resource.

Throws:

FileNotFoundException - if the indicated resource cannot be found.

IOException - if there is an error reading the bytes.

See Also:

• InputStreams.readBytes(InputStream)

readBytes

public static byte[] readBytes(@Nonnull
 ClassLoader classLoader,
 @Nonnull
 String resourcePath)
                        throws IOException

Reads all the bytes of a class resource.

API Note:

This method requires the full classpath-relative path to the resource, unlike readBytes(Class, String), which requires a path relative to a class., This method is analogous to the Files.readAllBytes(Path) utility for paths.

Parameters:

classLoader - The class loader to use for retrieving the resource.

resourcePath - The full relative path of the resource in relation to the class loader.

Returns:

An array of all the bytes read from the resource.

Throws:

FileNotFoundException - if the indicated resource cannot be found.

IOException - if there is an error reading the bytes.

See Also:

• InputStreams.readBytes(InputStream)

read

public static <T> T read(Class<?> objectClass,
 String name,
 IO<T> io)
                  throws IOException

Reads a class resource using the given class' class loader and the given I/O support.

Type Parameters:

T - The type of the resource.

Parameters:

objectClass - The class relative to which the given resource will be located.

name - The name of the resource to read.

io - The I/O support for reading the object.

Returns:

The object read from the resource.

Throws:

NullPointerException - if the given class, name, and/or I/O support is null.

IOException - if there is an error reading the data.

FileNotFoundException - if the indicated resource does not exist.