js.util

Class Classes

java.lang.Object

js.util.Classes

public class Classes
extends Object

Handy methods, mostly reflexive, related to class and class loader. This utility class allows for sub-classing. See js.util for utility sub-classing description.

Version:

final

Author:

Iulian Rotaru

Field Summary

Fields

Modifier and Type	Field and Description
private static Map<Class<?>,Class<?>>	COLLECTIONS Default implementations for collection interfaces.
private static Map<Class<?>,Class<?>>	LISTS Default implementations for list interfaces.
private static Log	log Class logger.
private static Map<Class<?>,Class<?>>	MAPS Default implementations for maps interfaces.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Classes() Prevent default constructor synthesis but allow sub-classing.

Method Summary

Modifier and Type	Method and Description
static Method	findMethod(Class<?> clazz, String methodName) Find method with given name and unknown parameter types.
static <T> Class<T>	forName(String className) Load named class using current thread context class loader.
static <T> Class<T>	forNameEx(String className) Get class by name with checked exception.
static <T> Class<T>	forOptionalName(String className) Get optional class by name or null if class not found.
static Class<?>	forType(Type type) Get the underlying class for a type, or null if the type is a variable type.
static String	getCallerMethod() Get source line for the caller method.
static Field	getField(Class<?> clazz, String fieldName) Get class field with unchecked runtime exception.
static Field	getFieldEx(Class<?> clazz, String fieldName) Get named field of requested class class or its super-classes package hierarchy, with checked exception.
static <T> T	getFieldValue(Object object, Class<?> clazz, String fieldName) Get instance field value declared into superclass.
private static <T> T	getFieldValue(Object object, Class<?> clazz, String fieldName, Class<T> fieldType, boolean optional) Helper method for field value retrieval.
static <T> T	getFieldValue(Object object, Field field) Get object instance field value.
static <T> T	getFieldValue(Object object, String fieldName) Get instance or class field value.
static Class<?>	getImplementation(Map<Class<?>,Class<?>> implementationsRegistry, Type interfaceType) Lookup implementation into given registry, throwing exception if not found.
static <T extends List<?>> Class<T>	getListDefaultImplementation(Type listType) Get default implementation for requested list type.
static Method	getMethod(Class<?> clazz, String methodName, Class<?>... parameterTypes) Get class method with runtime exception.
static Field	getOptionalField(Class<?> clazz, String fieldName) Get class field or null if not found.
static <T> T	getOptionalFieldValue(Object object, String fieldName, Class<T>... fieldType) Get optional field value from instance or class.
static String	getPackageResource(Class<?> type, String resourceName) Get resource name qualified with the package of a given class.
static Class<?>[]	getParameterTypes(Object... arguments) Get method formal parameter types inferred from actual invocation arguments.
static URL	getResource(String name) Retrieve URL of the named resource or null if not found.
private static URL	getResource(String name, ClassLoader[] classLoaders) Get named resource URL from a list of class loaders.
static byte[]	getResourceAsBytes(String name) Retrieve binary resource as array of bytes.
static File	getResourceAsFile(String name) Get file resource, that is, resource with file protocol.
static Reader	getResourceAsReader(String name) Convenient method to retrieve named resource as reader.
static InputStream	getResourceAsStream(String name) Retrieve resource, identified by qualified name, as input stream.
private static InputStream	getResourceAsStream(String name, ClassLoader[] classLoaders) Get named resource input stream from a list of class loaders.
static String	getResourceAsString(String name) Retrieve text resource content as a string.
static boolean	hasMethod(Class<?> clazz, String methodName, Class<?>... parameterTypes) Predicate to test if a class do possess a given method.
static <T> T	invoke(Object object, Class<?> clazz, String methodName, Object... arguments) Reflexively executes a method on an object.
private static Object	invoke(Object object, Method method, Object... arguments) Do the actual reflexive method invocation.
static <T> T	invoke(Object object, String methodName, Object... arguments) Invoke instance or class method with arguments.
static void	invokeOptionalSetter(Object object, String name, String value) Variant for invokeSetter(Object, String, String) but no exception if setter not found.
static void	invokeSetter(Object object, String name, String value) Invoke setter method on given object instance.
static boolean	isInstantiable(Class<?> clazz) Test if class is not an interface or abstract and have default constructor.
static Collection<String>	listPackageResources(String packageName, String fileNamesPattern) List package resources from local classes or from archives.
private static Collection<String>	listPackageResources(URL packageURL, String packagePath, String fileNamesPattern) Get package resources that match file name pattern.
static <S> S	loadOptionalService(Class<S> serviceInterface) Load service of requested interface returning null if service provider not found.
static <S> S	loadService(Class<S> serviceInterface) Load service of requested interface throwing exception if provider not found.
static <S> S	loadService(Class<S> serviceInterface, ClassLoader classLoader) Load service of requested interface using given class loader.
private static NoSuchBeingException	missingConstructorException(Class<?> clazz, Object... arguments) Helper for missing constructor exception.
static <T extends Collection<?>> T	newCollection(Type type) Create new collection of given type.
static <T> T	newInstance(Class<T> clazz, Object... arguments) Create a new object instance of specified class.
static <T> T	newInstance(String className, Object... arguments) Create a new instance.
static <T> T	newInstance(Type type, Object... arguments) Create instance of requested type - objects, collections or maps, using a constructor with given arguments.
static <T extends List<?>> T	newList(Type type) Create new list of given raw type.
static <T extends Map<?,?>> T	newMap(Type type) Create new map of given type.
private static <T> T	newRegisteredInstance(Map<Class<?>,Class<?>> implementationsRegistry, Type interfaceType) Lookup implementation for requested interface into given registry and return a new instance of it.
static void	setFieldValue(Object object, Class<?> clazz, String fieldName, Object value) Set instance field declared into superclass.
static void	setFieldValue(Object object, Field field, Object value) Set field value for object instance, or class if given object instance is null.
static void	setFieldValue(Object object, String fieldName, Object value) Set instance or class field value.
static void	setFieldValues(Object object, String fieldName, String valuesString) Set values to a field of array or collection type.
static <T> T	unproxy(T instance) Return wrapped instance of a Java Proxy implemented on a InstanceInvocationHandler handler.

Methods inherited from class java.lang.Object

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

Field Detail

log

private static Log log

Class logger.

COLLECTIONS

private static Map<Class<?>,Class<?>> COLLECTIONS

Default implementations for collection interfaces.

LISTS

private static Map<Class<?>,Class<?>> LISTS

Default implementations for list interfaces.

MAPS

private static Map<Class<?>,Class<?>> MAPS

Default implementations for maps interfaces.

Constructor Detail

Classes

protected Classes()

Prevent default constructor synthesis but allow sub-classing.

Method Detail

forName

public static <T> Class<T> forName(String className)
                            throws NoSuchBeingException,
                                   ClassCastException,
                                   NullPointerException

Load named class using current thread context class loader. Uses current thread context class loader to locate and load requested class. If current thread context class loader is null or fails to find requested class try with this utility class class loader.

This logic is designed for Tomcat class loading algorithm. Libraries are loaded using a separated class loader and every application has its own class loader. This method algorithm allows for a class used by an application to be found either by current thread or by library class loader.

Considering above, note that there is a subtle difference compared with standard Class.forName(String) counterpart: this method uses current thread context loader whereas Java standard uses current loader. Maybe not obvious, this 'semantic' difference could lead to class not found on Java standard while this utility method find the class. For example, a class defined by an web application could not be found by Java Class.forName method running inside a class defined by library.

Type Parameters:

T - class to auto-cast named class.

Parameters:

className - qualified class name, not null.

Returns:

class identified by name.

Throws:

NoSuchBeingException - if class not found.

ClassCastException - if found class cannot cast to requested auto-cast type.

NullPointerException - if className argument is null.

forOptionalName

public static <T> Class<T> forOptionalName(String className)

Get optional class by name or null if class not found. Tries to load the class with given class name returning null if not found. This method does not throw exceptions nor log missing class exception. It is supposed caller will test for null returned value and take appropriate action.

Uses current thread context class loader to locate and load requested class. If current thread context class loader is null or fails to find requested class try with this utility class class loader.

This logic is designed for Tomcat class loading algorithm. Libraries are loaded using a separated class loader and every application has its own class loader. This method algorithm allows for a class used by an application to be found either by current thread or by library class loader.

Considering above, note that there is a subtle difference compared with standard Class.forName(String) counterpart: this method uses current thread context loader whereas Java standard uses current loader. Maybe not obvious, this 'semantic' difference could lead to class not found on Java standard while this utility method find the class. For example, a class defined by an web application could not be found by Java Class.forName method running inside a class defined by library.

Type Parameters:

T - class to auto-cast named class.

Parameters:

className - requested class name, null tolerated.

Returns:

class identified by name or null if not found or given class name argument is null.

Throws:

ClassCastException - if found class cannot cast to requested auto-cast type.

forNameEx

public static <T> Class<T> forNameEx(String className)
                              throws ClassNotFoundException,
                                     ClassCastException,
                                     NullPointerException

Get class by name with checked exception. The same as forName(String) but throws checked exception in the event requested class is not found.

Type Parameters:

T - class to auto-cast named class.

Parameters:

className - requested class name, not null.

Returns:

class identified by name.

Throws:

ClassNotFoundException - if class not found.

ClassCastException - if found class cannot cast to requested auto-cast type.

NullPointerException - if className argument is null.

loadService

public static <S> S loadService(Class<S> serviceInterface)

Load service of requested interface throwing exception if provider not found. It is a convenient variant of loadService(Class) usable when a missing service implementation is a run-time stopper.

Type Parameters:

S - service type

Parameters:

serviceInterface - service interface.

Returns:

service instance.

Throws:

NoProviderException - if service provider not found on run-time.

loadService

public static <S> S loadService(Class<S> serviceInterface,
                                ClassLoader classLoader)

Load service of requested interface using given class loader. Throws exception if service implementation not found on run-time.

Type Parameters:

S - service type.

Parameters:

serviceInterface - service interface,

classLoader - class loader.

Returns:

service instance.

Throws:

NoProviderException - if service provider not found on run-time.

loadOptionalService

public static <S> S loadOptionalService(Class<S> serviceInterface)

Load service of requested interface returning null if service provider not found. Caller should test returned value and take appropriate actions.

Type Parameters:

S - service type.

Parameters:

serviceInterface - service interface.

Returns:

service instance or null.

isInstantiable

public static boolean isInstantiable(Class<?> clazz)

Test if class is not an interface or abstract and have default constructor. If this method returns true Class.newInstance() has no reason to fail.

Parameters:

clazz - class to test if instantiable.

Returns:

true if requested class is instantiable.

getParameterTypes

public static Class<?>[] getParameterTypes(Object... arguments)

Get method formal parameter types inferred from actual invocation arguments. This utility is a helper for method discovery when have access to the actual invocation argument, but not the formal parameter types list declared by method signature.

Parameters:

arguments - variable number of method arguments.

Returns:

parameter types.

invoke

public static <T> T invoke(Object object,
                           String methodName,
                           Object... arguments)
                    throws Exception

Invoke instance or class method with arguments. If this method object argument is a Class delegate invoke(Object, Class, String, Object...) with first argument set to null; otherwise object is passed as first argument and its class the second.

Type Parameters:

T - returned value type.

Parameters:

object - object instance or class,

methodName - method name,

arguments - variable number of arguments.

Returns:

value returned by method or null.

Throws:

NoSuchBeingException - if method is not found.

Exception - if invocation fail for whatever reason including method internals.

invoke

public static <T> T invoke(Object object,
                           Class<?> clazz,
                           String methodName,
                           Object... arguments)
                    throws Exception

Reflexively executes a method on an object. Locate the method on given class, that is not necessarily object class, e.g. it can be a superclass, and execute it. Given arguments are used for both method discovery and invocation.

Implementation note: this method is a convenient way to invoke a method when one knows actual parameters but not strictly formal parameters types. When formal parameters include interfaces or abstract classes or an actual parameter is null there is no way to infer formal parameter type from actual parameter instance. The only option left is to locate method by name and if overloads found uses best effort to determine the right parameter list. For this reason, on limit is possible to invoke the wrong method. Anyway, this method is designed for tests logic and best effort is good enough. The same is true for invoke(Object, String, Object...).

Type Parameters:

T - returned value type.

Parameters:

object - object instance,

clazz - object class one of its superclass,

methodName - method name,

arguments - variable number of arguments.

Returns:

value returned by method or null.

Throws:

NoSuchBeingException - if method is not found.

Exception - if invocation fail for whatever reason including method internals.

invokeSetter

public static void invokeSetter(Object object,
                                String name,
                                String value)
                         throws NoSuchMethodException,
                                Exception

Invoke setter method on given object instance. Setter name has format as accepted by Strings.getMethodAccessor(String, String) and value string is converted to method parameter type using Converter facility. For this reason set parameter type should have a converter registered.

This method has no means to determine method using Class.getMethod(String, Class...) because parameter value is always string and setter parameter type is unknown. For this reason this method uses findMethod(Class, String). Note that find method searches for named method on object super hierarchy too.

Parameters:

object - object instance,

name - setter name, method name only without set prefix, dashed case accepted,

value - value to set, string value that is converted to setter method parameter type.

Throws:

NoSuchMethodException - if setter not found.

Exception - if invocation fail for whatever reason including method logic.

invokeOptionalSetter

public static void invokeOptionalSetter(Object object,
                                        String name,
                                        String value)
                                 throws Exception

Variant for invokeSetter(Object, String, String) but no exception if setter not found.

Parameters:

object - object instance,

name - setter name,

value - value to set.

Throws:

Exception - if invocation fail for whatever reason including method logic.

invoke

private static Object invoke(Object object,
                             Method method,
                             Object... arguments)
                      throws Exception

Do the actual reflexive method invocation.

Parameters:

object - object instance,

method - reflexive method,

arguments - variable number of arguments.

Returns:

value returned by method execution.

Throws:

Exception - if invocation fail for whatever reason including method internals.

hasMethod

public static boolean hasMethod(Class<?> clazz,
                                String methodName,
                                Class<?>... parameterTypes)

Predicate to test if a class do possess a given method. Java language support for method discovery throws NoSuchMethodException if method not found. This method does not throws exception but returns a boolean.

Parameters:

clazz - reflexive class,

methodName - method name,

parameterTypes - formal parameters list.

Returns:

true if class has requested method.

getMethod

public static Method getMethod(Class<?> clazz,
                               String methodName,
                               Class<?>... parameterTypes)

Get class method with runtime exception. JRE throws checked NoSuchMethodException if method is missing, behavior that is not desirable for this library. This method uses runtime, unchecked NoSuchBeingException instead. Returned method has accessibility set to true.

Parameters:

clazz - Java class to return method from,

methodName - method name,

parameterTypes - method formal parameters.

Returns:

class reflective method.

Throws:

NoSuchBeingException - if does not found the method.

findMethod

public static Method findMethod(Class<?> clazz,
                                String methodName)
                         throws NoSuchMethodException

Find method with given name and unknown parameter types. Traverses all declared methods from given class and returns the one with specified name; if none found throws NoSuchMethodException. If there are overloaded methods returns one of them but there is no guarantee which one. Returned method has accessibility enabled.

Implementation note: this method is inherently costly since at worst case needs to traverse all class methods. It is recommended to be used with external method cache.

Parameters:

clazz - Java class to return method from,

methodName - method name.

Returns:

class reflective method.

Throws:

NoSuchMethodException - if there is no method with requested name.

getCallerMethod

public static String getCallerMethod()

Get source line for the caller method.

Returns:

caller method.

getField

public static Field getField(Class<?> clazz,
                             String fieldName)

Get class field with unchecked runtime exception. JRE throws checked NoSuchFieldException if field is missing, behavior that is not desirable for this library. This method uses runtime, unchecked NoSuchBeingException instead. Returned field has accessibility set to true.

Parameters:

clazz - Java class to return field from,

fieldName - field name.

Returns:

class reflective field.

Throws:

NoSuchBeingException - if field not found.

getOptionalField

public static Field getOptionalField(Class<?> clazz,
                                     String fieldName)

Get class field or null if not found. Try to get named class field and returns null if not found; this method does not throw any exception.

Parameters:

clazz - Java class to return field from,

fieldName - field name.

Returns:

class reflective field or null.

getFieldEx

public static Field getFieldEx(Class<?> clazz,
                               String fieldName)
                        throws NoSuchFieldException

Get named field of requested class class or its super-classes package hierarchy, with checked exception. Tries to get requested field from given class; if not found try with super-classes hierarchy but limited to requested class package. If field still not found throw NoSuchFieldException.

Implementation note: if field not found on requested class this method is executed recursively as long as superclass is in the same package as requested base class. Is not possible to retrieve inherited fields if superclass descendant is in different package.

Parameters:

clazz - class to search for named field,

fieldName - the name of field to retrieve.

Returns:

requested field.

Throws:

NoSuchFieldException - if class or super-class package hierarchy has no field with requested name.

getFieldValue

public static <T> T getFieldValue(Object object,
                                  Field field)

Get object instance field value. Reflective field argument should have accessibility set to true and this condition is fulfilled if field is obtained via getField(Class, String).

Type Parameters:

T - field type.

Parameters:

object - instance to retrieve field value from,

field - object reflective field.

Returns:

field value, possible null.

getFieldValue

public static <T> T getFieldValue(Object object,
                                  String fieldName)

Get instance or class field value. Retrieve named field value from given instance; if object argument is a Class retrieve class static field.

Type Parameters:

T - field value type.

Parameters:

object - instance or class to retrieve field value from,

fieldName - field name.

Returns:

instance or class field value.

Throws:

NullPointerException - if object argument is null.

NoSuchBeingException - if field is missing.

BugError - if object is a class and field is not static or if object is an instance and field is static.

getOptionalFieldValue

@SafeVarargs
public static <T> T getOptionalFieldValue(Object object,
                                                        String fieldName,
                                                        Class<T>... fieldType)

Get optional field value from instance or class. Retrieve named field value from given instance or class; if field is missing return null. Note that this method does not throw exceptions. Also, if optional desired field type is present and named field is of different type returns null.

Type Parameters:

T - field value type.

Parameters:

object - instance or class to retrieve field value from,

fieldName - field name,

fieldType - optional desired field type.

Returns:

instance or class field value or null if field not found.

getFieldValue

public static <T> T getFieldValue(Object object,
                                  Class<?> clazz,
                                  String fieldName)

Get instance field value declared into superclass. Retrieve inherited field value from given instance throwing exception if field is not declared into superclass.

Type Parameters:

T - field value type.

Parameters:

object - instance to retrieve field value from,

clazz - instance superclass,

fieldName - field name.

Returns:

instance field value.

Throws:

NoSuchBeingException - if field is missing.

getFieldValue

private static <T> T getFieldValue(Object object,
                                   Class<?> clazz,
                                   String fieldName,
                                   Class<T> fieldType,
                                   boolean optional)

Helper method for field value retrieval. Get object field value, declared into specified class which can be object class or superclass. If desired field type is not null retrieved field should have the type; otherwise returns null. If field not found this method behavior depends on optional argument: if true returns null, otherwise throws exception.

Type Parameters:

T - field value type.

Parameters:

object - instance to retrieve field value from or null if static field,

clazz - class or superclass where field is actually declared,

fieldName - field name,

fieldType - desired field type or null,

optional - if true, return null if field is missing.

Returns:

field value or null.

Throws:

NoSuchBeingException - if optional flag is false and field is missing.

BugError - if object is null and field is not static or if object is not null and field is static.

setFieldValue

public static void setFieldValue(Object object,
                                 Field field,
                                 Object value)
                          throws IllegalArgumentException,
                                 BugError

Set field value for object instance, or class if given object instance is null. This setter takes care to enable accessibility for private fields. Also it tries to adapt value to field type: if value is a string and field type is not, delegates Converter.asObject(String, Class). Anyway, if value is not a string it should be assignable to field type otherwise bug error is thrown.

Parameters:

object - instance to set field value to or null,

field - reflective field,

value - field value, possible null.

Throws:

IllegalArgumentException - if field parameter is null.

ConverterException - if attempt to convert string value to field type but there is no registered converted for that type.

BugError - if value is not assignable to field type.

setFieldValue

public static void setFieldValue(Object object,
                                 String fieldName,
                                 Object value)

Set instance or class field value. Try to set field value throwing exception if field not found. If object argument is a class, named field should be static; otherwise exception is thrown.

This setter tries to adapt value to field type: if value is a string and field type is not, delegates Converter.asObject(String, Class). Anyway, if value is not a string it should be assignable to field type otherwise bug error is thrown.

Parameters:

object - instance or class to set field value to,

fieldName - field name,

value - field value.

Throws:

IllegalArgumentException - if object or fieldName argument is null.

NoSuchBeingException - if field not found.

BugError - if object is null and field is not static or if object is not null and field is static.

BugError - if value is not assignable to field type.

setFieldValue

public static void setFieldValue(Object object,
                                 Class<?> clazz,
                                 String fieldName,
                                 Object value)

Set instance field declared into superclass. Try to set field value throwing exception if field is not declared into superclass; if field is static object instance should be null.

Parameters:

object - instance to set field value to or null if field is static,

clazz - instance superclass where field is declared,

fieldName - field name,

value - field value.

Throws:

NoSuchBeingException - if field not found.

BugError - if object is null and field is not static or if object is not null and field is static.

setFieldValues

public static void setFieldValues(Object object,
                                  String fieldName,
                                  String valuesString)

Set values to a field of array or collection type. If named field is not of supported types throws bug exception. This method has valuesString parameter that is a list of comma separated value objects. Split values string and converter every resulting item to field component type.

Parameters:

object - instance to set field value to or null if field is static,

fieldName - field name,

valuesString - comma separated values.

Throws:

ConverterException - if there is no converter registered for field component type or parsing fails.

BugError - if named field type is not of supported types.

getPackageResource

public static String getPackageResource(Class<?> type,
                                        String resourceName)

Get resource name qualified with the package of a given class. Given a resource with simple name pdf-view-fop.xconf and class js.fop.PdfView this method returns js/fop/pdf-view-fop.xconf.

Parameters:

type - class to infer package on which resource reside,

resourceName - simple resource name.

Returns:

qualified resource name.

getResource

public static URL getResource(String name)

Retrieve URL of the named resource or null if not found. A resource can be any file including Java source files or package directory. A special case is resource with empty name that denotes package root.

Resource is searched into next class loaders, in given order:

• current thread context class loader,
• this utility class loader,
• system class loader, as returned by ClassLoader.getSystemClassLoader()

Parameters:

name - resource qualified name, using path separators instead of dots.

Returns:

resource URL or null if not found.

Throws:

IllegalArgumentException - if name argument is null.

getResource

private static URL getResource(String name,
                               ClassLoader[] classLoaders)

Get named resource URL from a list of class loaders. Traverses class loaders in given order searching for requested resource. Return first resource found or null if none found.

Parameters:

name - resource name with syntax as requested by Java ClassLoader,

classLoaders - target class loaders.

Returns:

found resource URL or null.

getResourceAsStream

public static InputStream getResourceAsStream(String name)

Retrieve resource, identified by qualified name, as input stream. This method does its best to load requested resource but throws exception if fail. Resource is loaded using ClassLoader.getResourceAsStream(String) and name argument should follow Java class loader convention: it is always considered as absolute path, that is, should contain package but does not start with leading path separator, e.g. js/fop/config.xml .

Resource is searched into next class loaders, in given order:

• current thread context class loader,
• this utility class loader,
• system class loader, as returned by ClassLoader.getSystemClassLoader()

Parameters:

name - resource qualified name, using path separators instead of dots.

Returns:

resource input stream.

Throws:

IllegalArgumentException - if name argument is null or empty.

NoSuchBeingException - if resource not found.

getResourceAsStream

private static InputStream getResourceAsStream(String name,
                                               ClassLoader[] classLoaders)

Get named resource input stream from a list of class loaders. Traverses class loaders in given order searching for requested resource. Return first resource found or null if none found.

Parameters:

name - resource name with syntax as required by Java ClassLoader,

classLoaders - target class loaders.

Returns:

found resource as input stream or null.

getResourceAsFile

public static File getResourceAsFile(String name)

Get file resource, that is, resource with file protocol. Try to load resource throwing exception if not found. If resource protocol is file returns it as File otherwise throws unsupported operation.

Parameters:

name - resource name.

Returns:

resource file.

Throws:

NoSuchBeingException - if named resource can't be loaded.

UnsupportedOperationException - if named resource protocol is not file.

getResourceAsReader

public static Reader getResourceAsReader(String name)
                                  throws UnsupportedEncodingException

Convenient method to retrieve named resource as reader. Uses getResourceAsStream(String) and return the stream wrapped into a reader.

Parameters:

name - resource name.

Returns:

reader for named resource.

Throws:

UnsupportedEncodingException - if Java run-time does not support UTF-8 encoding.

NoSuchBeingException - if resource not found.

getResourceAsString

public static String getResourceAsString(String name)
                                  throws IOException

Retrieve text resource content as a string. Uses getResourceAsReader(String) to reader resource content and store it in a String.

Parameters:

name - resource name.

Returns:

resource content as string.

Throws:

NoSuchBeingException - if resource not found.

IOException - if resource reading fails.

getResourceAsBytes

public static byte[] getResourceAsBytes(String name)
                                 throws IOException

Retrieve binary resource as array of bytes. Uses getResourceAsStream(String) to read binary resource and return bytes array.

Parameters:

name - resource name.

Returns:

binary resource content as array of bytes.

Throws:

NoSuchBeingException - if resource not found.

IOException - if resource reading fails.

listPackageResources

public static Collection<String> listPackageResources(String packageName,
                                                      String fileNamesPattern)

List package resources from local classes or from archives. List resource file names that respect a given pattern from local stored package or from Java archive file. This utility method tries to locate the package with given name using ClassLoader.getResources(String). If returned URL starts with jar:file, that is, has JAR protocol the package is contained into a Java archive file and is processed entry by entry. Otherwise protocol should be file and package is located into local classes and is processed as file. If protocol is neither file nor jar:file throws unsupported operation.

Parameters:

packageName - qualified package name, possible empty for package root,

fileNamesPattern - file names pattern as accepted by FilteredStrings.FilteredStrings(String).

Returns:

collection of resources from package matching requested pattern, possible empty.

Throws:

NoSuchBeingException - if package is not found by current application class loader.

UnsupportedOperationException - if found package URL protocol is not file or jar:file.

listPackageResources

private static Collection<String> listPackageResources(URL packageURL,
                                                       String packagePath,
                                                       String fileNamesPattern)

Get package resources that match file name pattern. Returned collection is in no particular order and can be empty if no resource match requested pattern. This helper process both file and jar:file URL protocols meaning it searches on both local classes and .jar files.

Parameters:

packageURL - package URL as returned by ClassLoader.getResources(String),

packagePath - package path for resources lookup, possible empty for package root,

fileNamesPattern - file name pattern.

Returns:

collection of resources with requested file name pattern, possible empty.

Throws:

UnsupportedOperationException - given package URL protocol is not file or jar:file.

newInstance

public static <T> T newInstance(Type type,
                                Object... arguments)

Create instance of requested type - objects, collections or maps, using a constructor with given arguments. This factory method detect if type is object, collection or map and delegates newInstance(Class, Object...), respective newCollection(Type) or newMap(Type).

Type Parameters:

T - instance type.

Parameters:

type - instance type.

arguments - constructor arguments.

Returns:

newly created instance.

Throws:

BugError - if instance cannot be created.

newInstance

public static <T> T newInstance(String className,
                                Object... arguments)

Create a new instance. Handy utility for hidden classes creation. Constructor accepting given arguments, if any, must exists.

Type Parameters:

T - instance type.

Parameters:

className - fully qualified class name,

arguments - variable number of arguments to be passed to constructor.

Returns:

newly created instance.

Throws:

NoSuchBeingException - if class or constructor not found.

newInstance

public static <T> T newInstance(Class<T> clazz,
                                Object... arguments)
                         throws BugError,
                                NoSuchBeingException,
                                BugError

Create a new object instance of specified class. This factory is specialized in objects creation; for collections, lists and maps see newCollection(Type), newList(Type) respective newMap(Type).

If arguments are supplied a constructor with exact formal parameters is located otherwise default constructor is used; if none found throws NoSuchBeingException. This method forces accessibility so is not mandatory for constructor to be public.

Requested class should be instantiable, i.e. should not be interface, abstract or void class. Also arrays are not accepted by this factory method.

Type Parameters:

T - instance type.

Parameters:

clazz - object class to instantiate,

arguments - optional constructor arguments.

Returns:

newly created instance

Throws:

BugError - if attempt to instantiate interface, abstract, array or void class.

NoSuchBeingException - if class or constructor not found.

BugError - for any other failing condition, since there is no particular reason to expect fail.

InvocationException - with target exception if constructor fails on its execution.

missingConstructorException

private static NoSuchBeingException missingConstructorException(Class<?> clazz,
                                                                Object... arguments)

Helper for missing constructor exception.

Parameters:

clazz - constructor class,

arguments - constructor arguments.

Returns:

formatted exception.

newCollection

public static <T extends Collection<?>> T newCollection(Type type)

Create new collection of given type.

Type Parameters:

T - collection type.

Parameters:

type - collection type.

Returns:

newly create collection.

getListDefaultImplementation

public static <T extends List<?>> Class<T> getListDefaultImplementation(Type listType)

Get default implementation for requested list type.

Type Parameters:

T - list type.

Parameters:

listType - raw list type.

Returns:

default implementation for requested list.

newList

public static <T extends List<?>> T newList(Type type)

Create new list of given raw type.

Type Parameters:

T - list type.

Parameters:

type - list raw type.

Returns:

list instance.

getImplementation

public static Class<?> getImplementation(Map<Class<?>,Class<?>> implementationsRegistry,
                                         Type interfaceType)

Lookup implementation into given registry, throwing exception if not found.

Parameters:

implementationsRegistry - implementations registry,

interfaceType - interface to lookup into registry.

Returns:

implementation for requested interface type.

Throws:

BugError - if implementation is not found into registry.

newRegisteredInstance

private static <T> T newRegisteredInstance(Map<Class<?>,Class<?>> implementationsRegistry,
                                           Type interfaceType)
                                    throws BugError

Lookup implementation for requested interface into given registry and return a new instance of it.

Type Parameters:

T - instance type.

Parameters:

implementationsRegistry - implementations registry,

interfaceType - interface to lookup into registry.

Returns:

implementation instance.

Throws:

BugError - if implementation is not found into registry.

newMap

public static <T extends Map<?,?>> T newMap(Type type)

Create new map of given type.

Type Parameters:

T - map type.

Parameters:

type - map type.

Returns:

newly created map.

forType

public static Class<?> forType(Type type)

Get the underlying class for a type, or null if the type is a variable type.

Parameters:

type - the type

Returns:

the underlying class

unproxy

public static <T> T unproxy(T instance)

Return wrapped instance of a Java Proxy implemented on a InstanceInvocationHandler handler. If given instance is not a Java Proxy return it as it is and return null if instance is null. It is considered a bug if instance is a Java Proxy and its handler does not implement InstanceInvocationHandler.

Type Parameters:

T - instance type.

Parameters:

instance - instance to unproxy, null accepted.

Returns:

proxy wrapped instance, possible null.

Throws:

BugError - if Java Proxy handler does not implement InstanceInvocationHandler.