Package com.blackrook.small.struct

Class Utils

java.lang.Object

com.blackrook.small.struct.Utils

public final class Utils
extends Object

Utility methods.

Author:

Matthew Tropiano

Method Summary

Modifier and Type	Method	Description
static void	close(AutoCloseable c)	Attempts to close an AutoCloseable object.
static <T> T	construct(Constructor<T> constructor, Object... params)	Creates a new instance of a class from a class type.
static <T> T	create(Class<T> clazz)	Creates a new instance of a class from a class type.
static <T> T	createForType(Object object, Class<T> targetType)	Reflect.creates a new instance of an object for placement in a POJO or elsewhere.
static <T> T	createForType(String memberName, Object object, Class<T> targetType)	Reflect.creates a new instance of an object for placement in a POJO or elsewhere.
static boolean	createPath(String path)	Creates the necessary directories for a file path.
static int	getArrayDimensions(Class<?> arrayType)	Gets how many dimensions that this array, represented by the provided type, has.
static int	getArrayDimensions(Object array)	Gets how many array dimensions that an object (presumably an array) has.
static Class<?>	getArrayType(Class<?> arrayType)	Gets the class type of this array type, if this is an array type.
static Class<?>	getArrayType(Object object)	Gets the class type of this array, if this is an array.
static String[]	getClasses(String prefix, ClassLoader classLoader)	Returns the fully-qualified names of all classes beginning with a certain string.
static String[]	getClassesFromClasspath(String prefix)	Returns the fully-qualified names of all classes beginning with a certain string.
static Object	getFieldValue(Object instance, Field field)	Gets the value of a field on an object.
static String	getFileExtension(File file)	Returns the extension of a file's name.
static String	getFileExtension(File file, String extensionSeparator)	Returns the extension of a file's name.
static String	getFileExtension(String filename)	Returns the extension of a filename.
static String	getFileExtension(String filename, String extensionSeparator)	Returns the extension of a filename.
static <T> TypeProfileFactory.Profile<T>	getProfile(Class<T> clazz)	Creates a new profile for a provided type.
static Object	invoke(Method method, Object instance, Object... params)	Invokes a method, only throwing a RuntimeException if something goes wrong (except for an actual exception thrown during execution).
static Object	invokeBlind(Method method, Object instance, Object... params)	Invokes a method, only throwing a RuntimeException if something goes wrong.
static boolean	isArray(Class<?> clazz)	Tests if a class is actually an array type.
static boolean	isArray(Object object)	Tests if an object is actually an array type.
static boolean	isEmpty(Object obj)	Checks if a value is "empty." The following is considered "empty": Null references.
static String	join(String joiner, String... values)	Joins a list of values into one string, placing a joiner between all of them.
static <T> T[]	joinArrays(T[]... arrays)	Concatenates a set of arrays together, such that the contents of each array are joined into one array.
static int	relay(InputStream in, OutputStream out, int bufferSize, int maxLength)	Reads from an input stream, reading in a consistent set of data and writing it to the output stream.
static void	setFieldValue(Object instance, Field field, Object value)	Sets the value of a field on an object.
static String	urlUnescape(String inString)	Decodes a URL-encoded string.

Methods inherited from class java.lang.Object

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

Method Details

isEmpty

public static boolean isEmpty(Object obj)

Checks if a value is "empty." The following is considered "empty":

• Null references.
• Array objects that have a length of 0.
• Boolean objects that are false.
• Character objects that are the null character ('\0', '').
• Number objects that are zero.
• String objects that are the empty string, or are String.trim()'ed down to the empty string.
• Collection objects where Collection.isEmpty() returns true.

Parameters:

obj - the object to check.

Returns:

true if the provided object is considered "empty", false otherwise.

createPath

public static boolean createPath(String path)

Creates the necessary directories for a file path.

Parameters:

path - the abstract path.

Returns:

true if the paths were made (or exists), false otherwise.

getClasses

public static String[] getClasses(String prefix,
 ClassLoader classLoader)

Returns the fully-qualified names of all classes beginning with a certain string. None of the classes are "forName"-ed into PermGen/Metaspace.

This scan can be expensive, as this searches the contents of the entire ClassLoader.

Parameters:

prefix - the String to use for lookup. Can be null.

classLoader - the ClassLoader to look into.

Returns:

the list of class names.

Throws:

RuntimeException - if a JAR file could not be read for some reason.

getClassesFromClasspath

public static String[] getClassesFromClasspath(String prefix)

Returns the fully-qualified names of all classes beginning with a certain string. None of the classes are "forName"-ed into PermGen/Metaspace.

This scan can be expensive, as this searches the contents of the entire ClassLoader.

Parameters:

prefix - the String to use for lookup. Can be null.

Returns:

the list of class names.

Throws:

RuntimeException - if a JAR file could not be read for some reason.

urlUnescape

public static String urlUnescape(String inString)

Decodes a URL-encoded string.

Parameters:

inString - the input string.

Returns:

the unescaped string.

relay

public static int relay(InputStream in,
 OutputStream out,
 int bufferSize,
 int maxLength)
                 throws IOException

Reads from an input stream, reading in a consistent set of data and writing it to the output stream. The read/write is buffered so that it does not bog down the OS's other I/O requests. This method finishes when the end of the source stream is reached. Note that this may block if the input stream is a type of stream that will block if the input stream blocks for additional input. This method is thread-safe.

Parameters:

in - the input stream to grab data from.

out - the output stream to write the data to.

bufferSize - the buffer size for the I/O. Must be > 0.

maxLength - the maximum amount of bytes to relay, or a value < 0 for no max.

Returns:

the total amount of bytes relayed.

Throws:

IOException - if a read or write error occurs.

close

public static void close(AutoCloseable c)

Attempts to close an AutoCloseable object. If the object is null, this does nothing.

Parameters:

c - the reference to the AutoCloseable object.

getFileExtension

public static String getFileExtension(String filename,
 String extensionSeparator)

Returns the extension of a filename.

Parameters:

filename - the file name.

extensionSeparator - the text or characters that separates file name from extension.

Returns:

the file's extension, or an empty string for no extension.

getFileExtension

public static String getFileExtension(File file,
 String extensionSeparator)

Returns the extension of a file's name.

Parameters:

file - the file.

extensionSeparator - the text or characters that separates file name from extension.

Returns:

the file's extension, or an empty string for no extension.

getFileExtension

public static String getFileExtension(String filename)

Returns the extension of a filename. Assumes the separator to be ".".

Parameters:

filename - the file name.

Returns:

the file's extension, or an empty string for no extension.

getFileExtension

public static String getFileExtension(File file)

Returns the extension of a file's name. Assumes the separator to be ".".

Parameters:

file - the file.

Returns:

the file's extension, or an empty string for no extension.

create

public static <T> T create(Class<T> clazz)

Creates a new instance of a class from a class type. This essentially calls Class.newInstance(), but wraps the call in a try/catch block that only throws an exception if something goes wrong.

Type Parameters:

T - the return object type.

Parameters:

clazz - the class type to instantiate.

Returns:

a new instance of an object.

Throws:

RuntimeException - if instantiation cannot happen, either due to a non-existent constructor or a non-visible constructor.

construct

public static <T> T construct(Constructor<T> constructor,
 Object... params)

Creates a new instance of a class from a class type. This essentially calls Class.newInstance(), but wraps the call in a try/catch block that only throws an exception if something goes wrong.

Type Parameters:

T - the return object type.

Parameters:

constructor - the constructor to call.

params - the constructor parameters.

Returns:

a new instance of an object created via the provided constructor.

Throws:

RuntimeException - if instantiation cannot happen, either due to a non-existent constructor or a non-visible constructor.

createForType

public static <T> T createForType(Object object,
 Class<T> targetType)

Reflect.creates a new instance of an object for placement in a POJO or elsewhere.

Type Parameters:

T - the return object type.

Parameters:

object - the object to convert to another object

targetType - the target class type to convert to, if the types differ.

Returns:

a suitable object of type targetType.

Throws:

ClassCastException - if the incoming type cannot be converted.

createForType

public static <T> T createForType(String memberName,
 Object object,
 Class<T> targetType)

Reflect.creates a new instance of an object for placement in a POJO or elsewhere.

Type Parameters:

T - the return object type.

Parameters:

memberName - the name of the member that is being converted (for reporting).

object - the object to convert to another object

targetType - the target class type to convert to, if the types differ.

Returns:

a suitable object of type targetType.

Throws:

ClassCastException - if the incoming type cannot be converted.

getProfile

public static <T> TypeProfileFactory.Profile<T> getProfile(Class<T> clazz)

Creates a new profile for a provided type. Generated profiles are stored in memory, and retrieved again by class type.

This method is thread-safe.

Type Parameters:

T - the class type.

Parameters:

clazz - the class.

Returns:

a new profile.

isArray

public static boolean isArray(Class<?> clazz)

Tests if a class is actually an array type.

Parameters:

clazz - the class to test.

Returns:

true if so, false if not.

isArray

public static boolean isArray(Object object)

Tests if an object is actually an array type.

Parameters:

object - the object to test.

Returns:

true if so, false if not.

getArrayDimensions

public static int getArrayDimensions(Class<?> arrayType)

Gets how many dimensions that this array, represented by the provided type, has.

Parameters:

arrayType - the type to inspect.

Returns:

the number of array dimensions, or 0 if not an array.

getArrayDimensions

public static int getArrayDimensions(Object array)

Gets how many array dimensions that an object (presumably an array) has.

Parameters:

array - the object to inspect.

Returns:

the number of array dimensions, or 0 if not an array.

getArrayType

public static Class<?> getArrayType(Class<?> arrayType)

Gets the class type of this array type, if this is an array type.

Parameters:

arrayType - the type to inspect.

Returns:

this array's type, or null if the provided type is not an array, or if the found class is not on the classpath.

getArrayType

public static Class<?> getArrayType(Object object)

Gets the class type of this array, if this is an array.

Parameters:

object - the object to inspect.

Returns:

this array's type, or null if the provided object is not an array, or if the found class is not on the classpath.

setFieldValue

public static void setFieldValue(Object instance,
 Field field,
 Object value)

Sets the value of a field on an object.

Parameters:

instance - the object instance to set the field on.

field - the field to set.

value - the value to set.

Throws:

NullPointerException - if the field or object provided is null.

ClassCastException - if the value could not be cast to the proper type.

RuntimeException - if anything goes wrong (bad field name, bad target, bad argument, or can't access the field).

See Also:

• Field.set(Object, Object)

getFieldValue

public static Object getFieldValue(Object instance,
 Field field)

Gets the value of a field on an object.

Parameters:

instance - the object instance to get the field value of.

field - the field to get the value of.

Returns:

the current value of the field.

Throws:

NullPointerException - if the field or object provided is null.

RuntimeException - if anything goes wrong (bad target, bad argument, or can't access the field).

See Also:

• Field.set(Object, Object)

invokeBlind

public static Object invokeBlind(Method method,
 Object instance,
 Object... params)

Invokes a method, only throwing a RuntimeException if something goes wrong. Here for the convenience of not making a billion try/catch clauses for a method invocation.

Parameters:

method - the method to invoke.

instance - the object instance that is the method target.

params - the parameters to pass to the method.

Returns:

the return value from the method invocation. If void, this is null.

Throws:

ClassCastException - if one of the parameters could not be cast to the proper type.

RuntimeException - if anything goes wrong (bad target, bad argument, exception thrown, or can't access the method).

See Also:

• Method.invoke(Object, Object...)

invoke

public static Object invoke(Method method,
 Object instance,
 Object... params)
                     throws InvocationTargetException

Invokes a method, only throwing a RuntimeException if something goes wrong (except for an actual exception thrown during execution). Here for the convenience of not making a billion try/catch clauses for a method invocation.

Parameters:

method - the method to invoke.

instance - the object instance that is the method target.

params - the parameters to pass to the method.

Returns:

the return value from the method invocation. If void, this is null.

Throws:

InvocationTargetException - if an exception happens during invocation.

ClassCastException - if one of the parameters could not be cast to the proper type.

RuntimeException - if anything goes wrong (can't access the method).

See Also:

• Method.invoke(Object, Object...)

joinArrays

public static <T> T[] joinArrays(T[]... arrays)

Concatenates a set of arrays together, such that the contents of each array are joined into one array. Null arrays are skipped.

Type Parameters:

T - the object type stored in the arrays.

Parameters:

arrays - the list of arrays.

Returns:

a new array with all objects in each provided array added to the resultant one in the order in which they appear.

join

public static String join(String joiner,
 String... values)

Joins a list of values into one string, placing a joiner between all of them.

Parameters:

joiner - the joining string.

values - the values to join together.

Returns:

the resultant string.