Package com.cedarsoftware.util

Class ClassUtilities

java.lang.Object
com.cedarsoftware.util.ClassUtilities
public class ClassUtilities extends Object
A utility class providing various methods for working with Java Class objects and related operations.

ClassUtilities includes functionalities such as:

Inheritance Distance

The computeInheritanceDistance(Class, Class) method calculates the number of inheritance steps between two classes or interfaces. If there is no relationship, it returns -1.

Primitive and Wrapper Handling

  • Supports identification of primitive types and their wrappers.
  • Handles conversions between primitive types and their wrapper classes.
  • Considers primitive types and their wrappers interchangeable for certain operations.

Resource Loading

Includes methods for loading resources from the classpath as strings or byte arrays, throwing appropriate exceptions if the resource cannot be found or read.

OSGi and JPMS ClassLoader Support

Detects and supports environments such as OSGi or JPMS for proper class loading. Uses caching for efficient retrieval of class loaders in these environments.

Design Notes

  • This class is designed to be a static utility class and should not be instantiated.
  • It uses internal caching for operations like class aliasing and OSGi class loading to optimize performance.

Usage Example


 // Compute inheritance distance
 int distance = ClassUtilities.computeInheritanceDistance(ArrayList.class, List.class); // Outputs 1

 // Check if a class is primitive
 boolean isPrimitive = ClassUtilities.isPrimitive(int.class); // Outputs true

 // Load a resource as a string
 String resourceContent = ClassUtilities.loadResourceAsString("example.txt");
Author:
John DeRegnaucourt ([email protected])
Copyright (c) Cedar Software LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

License

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
See Also:

  • Method Details

    • getPrimitiveFromWrapper

      public static Class<?> getPrimitiveFromWrapper(Class<?> toType)
      Converts a wrapper class to its corresponding primitive type.
      Parameters:
      toType - The wrapper class to convert to its primitive equivalent. Must be one of the standard Java wrapper classes (e.g., Integer.class, Boolean.class).
      Returns:
      The primitive class corresponding to the provided wrapper class or null if toType is not a primitive wrapper.
      Throws:
      IllegalArgumentException - If toType is null

    • addPermanentClassAlias

      public static void addPermanentClassAlias(Class<?> clazz, String alias)
      Registers a permanent alias name for a class to support Class.forName() lookups.
      Parameters:
      clazz - the class to alias
      alias - the alternative name for the class

    • removePermanentClassAlias

      public static void removePermanentClassAlias(String alias)
      Removes a previously registered class alias.
      Parameters:
      alias - the alias name to remove

    • computeInheritanceDistance

      public static int computeInheritanceDistance(Class<?> source, Class<?> destination)
      Computes the inheritance distance between two classes/interfaces/primitive types. Results are cached for performance.
      Parameters:
      source - The source class, interface, or primitive type.
      destination - The destination class, interface, or primitive type.
      Returns:
      The number of steps from the source to the destination, or -1 if no path exists.

    • isPrimitive

      public static boolean isPrimitive(Class<?> c)
      Parameters:
      c - Class to test
      Returns:
      boolean true if the passed in class is a Java primitive, false otherwise. The Wrapper classes Integer, Long, Boolean, etc. are considered primitives by this method.

    • forName

      public static Class<?> forName(String name, ClassLoader classLoader)
      Given the passed in String class name, return the named JVM class.
      Parameters:
      name - String name of a JVM class.
      classLoader - ClassLoader to use when searching for JVM classes.
      Returns:
      Class instance of the named JVM class or null if not found.

    • isClassFinal

      public static boolean isClassFinal(Class<?> c)
      Determines if a class is declared as final.

      Checks if the class has the final modifier, indicating that it cannot be subclassed.

      Example:

      
 boolean isFinal = ClassUtilities.isClassFinal(String.class);  // Returns true
 boolean notFinal = ClassUtilities.isClassFinal(ArrayList.class);  // Returns false
      Parameters:
      c - the class to check, must not be null
      Returns:
      true if the class is final, false otherwise
      Throws:
      NullPointerException - if the input class is null

    • areAllConstructorsPrivate

      public static boolean areAllConstructorsPrivate(Class<?> c)
      Determines if all constructors in a class are declared as private.

      This method is useful for identifying classes that enforce singleton patterns or utility classes that should not be instantiated.

      Example:

      
 // Utility class with private constructor
 public final class Utils {
     private Utils() {}
 }

 boolean isPrivate = ClassUtilities.areAllConstructorsPrivate(Utils.class);  // Returns true
 boolean notPrivate = ClassUtilities.areAllConstructorsPrivate(String.class);  // Returns false
      Parameters:
      c - the class to check, must not be null
      Returns:
      true if all constructors in the class are private, false if any constructor is non-private
      Throws:
      NullPointerException - if the input class is null

    • toPrimitiveWrapperClass

      public static Class<?> toPrimitiveWrapperClass(Class<?> primitiveClass)
      Converts a primitive class to its corresponding wrapper class.

      If the input class is already a non-primitive type, it is returned unchanged. For primitive types, returns the corresponding wrapper class (e.g., int.class → Integer.class).

      Examples:

      
 Class<?> intWrapper = ClassUtilities.toPrimitiveWrapperClass(int.class);     // Returns Integer.class
 Class<?> boolWrapper = ClassUtilities.toPrimitiveWrapperClass(boolean.class); // Returns Boolean.class
 Class<?> sameClass = ClassUtilities.toPrimitiveWrapperClass(String.class);    // Returns String.class

      Supported Primitive Types:

      • boolean.class → Boolean.class
      • byte.class → Byte.class
      • char.class → Character.class
      • double.class → Double.class
      • float.class → Float.class
      • int.class → Integer.class
      • long.class → Long.class
      • short.class → Short.class
      • void.class → Void.class
      Parameters:
      primitiveClass - the class to convert, must not be null
      Returns:
      the wrapper class if the input is primitive, otherwise the input class itself
      Throws:
      NullPointerException - if the input class is null
      IllegalArgumentException - if the input class is not a recognized primitive type

    • doesOneWrapTheOther

      public static boolean doesOneWrapTheOther(Class<?> x, Class<?> y)
      Determines if one class is the wrapper type of the other.

      This method checks if there is a primitive-wrapper relationship between two classes. For example, Integer.class wraps int.class and vice versa.

      Examples:

      
 boolean wraps = ClassUtilities.doesOneWrapTheOther(Integer.class, int.class);    // Returns true
 boolean wraps2 = ClassUtilities.doesOneWrapTheOther(int.class, Integer.class);   // Returns true
 boolean noWrap = ClassUtilities.doesOneWrapTheOther(Integer.class, long.class);  // Returns false

      Supported Wrapper Pairs:

      • Boolean.class ↔ boolean.class
      • Byte.class ↔ byte.class
      • Character.class ↔ char.class
      • Double.class ↔ double.class
      • Float.class ↔ float.class
      • Integer.class ↔ int.class
      • Long.class ↔ long.class
      • Short.class ↔ short.class
      Parameters:
      x - first class to check
      y - second class to check
      Returns:
      true if one class is the wrapper of the other, false otherwise
      Throws:
      NullPointerException - if either input class is null

    • getClassLoader

      public static ClassLoader getClassLoader()
      Obtains the appropriate ClassLoader depending on whether the environment is OSGi, JPMS, or neither.
      Returns:
      the appropriate ClassLoader

    • getClassLoader

      public static ClassLoader getClassLoader(Class<?> anchorClass)
      Obtains the appropriate ClassLoader depending on whether the environment is OSGi, JPMS, or neither.
      Parameters:
      anchorClass - the class to use as reference for loading
      Returns:
      the appropriate ClassLoader

    • findClosest

      public static <T> T findClosest(Class<?> clazz, Map<Class<?>,T> candidateClasses, T defaultClass)
      Finds the closest matching class in an inheritance hierarchy from a map of candidate classes.

      This method searches through a map of candidate classes to find the one that is most closely related to the input class in terms of inheritance distance. The search prioritizes:

      • Exact class match (returns immediately)
      • Closest superclass/interface in the inheritance hierarchy

      This method is typically used for cache misses when looking up class-specific handlers or processors.

      Type Parameters:
      T - The type of value stored in the candidateClasses map
      Parameters:
      clazz - The class to find a match for (must not be null)
      candidateClasses - Map of candidate classes and their associated values (must not be null)
      defaultClass - Default value to return if no suitable match is found
      Returns:
      The value associated with the closest matching class, or defaultClass if no match found
      Throws:
      NullPointerException - if clazz or candidateClasses is null
      See Also:

    • loadResourceAsString

      public static String loadResourceAsString(String resourceName)
      Loads resource content as a String.
      Parameters:
      resourceName - Name of the resource file.
      Returns:
      Content of the resource file as a String.

    • loadResourceAsBytes

      public static byte[] loadResourceAsBytes(String resourceName)
      Loads resource content as a byte[].
      Parameters:
      resourceName - Name of the resource file.
      Returns:
      Content of the resource file as a byte[].
      Throws:
      IllegalArgumentException - if the resource cannot be found
      UncheckedIOException - if there is an error reading the resource
      NullPointerException - if resourceName is null

    • indexOfSmallestValue

      @Deprecated public static int indexOfSmallestValue(int[] array)
      Deprecated.
      Returns the index of the smallest value in an array.
      Parameters:
      array - The array to search.
      Returns:
      The index of the smallest value, or -1 if the array is empty.

    • getClassIfEnum

      public static Class<?> getClassIfEnum(Class<?> c)
      Returns the related enum class for the provided class, if one exists.
      Parameters:
      c - the class to check; may be null
      Returns:
      the related enum class, or null if none is found

    • newInstance

      public static Object newInstance(Converter converter, Class<?> c, Collection<?> argumentValues)
      Create a new instance of the specified class, optionally using provided constructor arguments.

      This method attempts to instantiate a class using the following strategies in order:

      1. Using cached successful constructor from previous instantiations
      2. Using constructors in optimal order (public, protected, package, private)
      3. Within each accessibility level, trying constructors with more parameters first
      4. For each constructor, trying with exact matches first, then allowing null values
      5. Using unsafe instantiation (if enabled)
      Parameters:
      converter - Converter instance used to convert null values to appropriate defaults for primitive types
      c - Class to instantiate
      argumentValues - Optional collection of values to match to constructor parameters. Can be null or empty.
      Returns:
      A new instance of the specified class
      Throws:
      IllegalArgumentException - if:
      • The class cannot be instantiated
      • The class is a security-sensitive class (Process, ClassLoader, etc.)
      • The class is an unknown interface
      IllegalStateException - if constructor invocation fails

    • setUseUnsafe

      public static void setUseUnsafe(boolean state)
      Globally turn on (or off) the 'unsafe' option of Class construction. The unsafe option is used when all constructors have been tried and the Java class could not be instantiated.
      Parameters:
      state - boolean true = on, false = off.

    • findLowestCommonSupertypesExcluding

      public static Set<Class<?>> findLowestCommonSupertypesExcluding(Class<?> classA, Class<?> classB, Set<Class<?>> excluded)
      Returns all equally "lowest" common supertypes (classes or interfaces) shared by both classA and classB, excluding any types specified in excludeSet.
      Parameters:
      classA - the first class, may be null
      classB - the second class, may be null
      excluded - a set of classes or interfaces to exclude from the final result
      Returns:
      a Set of the most specific common supertypes, excluding any in excluded set

    • findLowestCommonSupertypes

      public static Set<Class<?>> findLowestCommonSupertypes(Class<?> classA, Class<?> classB)
      Returns all equally "lowest" common supertypes (classes or interfaces) that both classA and classB share, automatically excluding Object, Serializable, Externalizable, Cloneable.

      This method is a convenience wrapper around findLowestCommonSupertypesExcluding(Class, Class, Set) using a skip list that includes Object, Serializable, Externalizable, Cloneable. In other words, if the only common ancestor is Object.class, this method returns an empty set.

      Example: 

      
 Set<Class<?>> supertypes = findLowestCommonSupertypes(Integer.class, Double.class);
 // Potentially returns [Number, Comparable] because those are
 // equally specific and not ancestors of one another, ignoring Object.class.
      Parameters:
      classA - the first class, may be null
      classB - the second class, may be null
      Returns:
      a Set of all equally "lowest" common supertypes, excluding Object, Serializable, Externalizable, Cloneable; or an empty set if none are found beyond Object (or if either input is null)
      See Also:

    • findLowestCommonSupertype

      public static Class<?> findLowestCommonSupertype(Class<?> classA, Class<?> classB)
      Returns the *single* most specific type from findLowestCommonSupertypes(...). If there's more than one, returns any one (or null if none).

    • getClassHierarchyInfo

      public static ClassUtilities.ClassHierarchyInfo getClassHierarchyInfo(Class<?> clazz)
      Gets the complete hierarchy information for a class, including all supertypes and their inheritance distances from the source class.
      Parameters:
      clazz - The class to analyze
      Returns:
      ClassHierarchyInfo containing all supertypes and distances

    • haveCommonAncestor

      public static boolean haveCommonAncestor(Class<?> a, Class<?> b)