jMock Legacy

jMock Legacy provides CGLib-based class imposterization for the jMock 2 mocking framework. It enables mocking of concrete classes without calling their constructors, primarily for backward compatibility with older jMock applications. This component is deprecated in favor of ByteBuddy implementations due to weak Java 11 support.

Package Information

• Package Name: jmock-legacy
• Package Type: maven
• Language: Java
• Installation:

  <dependency>
    <groupId>org.jmock</groupId>
    <artifactId>jmock-legacy</artifactId>
    <version>2.13.1</version>
  </dependency>

Core Imports

import org.jmock.lib.legacy.ClassImposteriser;
import org.jmock.api.Imposteriser;

Basic Usage

import org.jmock.lib.legacy.ClassImposteriser;
import org.jmock.api.Imposteriser;
import org.jmock.api.Invokable;

// Get the singleton instance
Imposteriser imposteriser = ClassImposteriser.INSTANCE;

// Check if a class can be mocked
if (imposteriser.canImposterise(MyConcreteClass.class)) {
    // Create a mock instance
    MyConcreteClass mock = imposteriser.imposterise(
        mockInvokable, 
        MyConcreteClass.class
    );
}

// Mock with additional interfaces
MyConcreteClass mock = imposteriser.imposterise(
    mockInvokable,
    MyConcreteClass.class,
    AdditionalInterface.class,
    AnotherInterface.class
);

Architecture

ClassImposteriser uses CGLib proxies and Objenesis for runtime class enhancement:

• CGLib Integration: Creates runtime subclasses using method interception
• Objenesis: Instantiates objects without calling constructors
• Callback System: Routes method calls through InvocationHandler to mock objects
• Class Loading: Combines class loaders to handle complex deployment scenarios
• Signed Package Support: Special naming policy for classes in signed packages

Capabilities

Class Imposterization Check

Determines whether a given class type can be imposterised by this implementation.

boolean canImposterise(Class<?> type);

Parameters:

• type (Class<?>): The class type to check for imposterisation capability

Returns:

• boolean: true if the type can be imposterised, false otherwise

Constraints:

• Cannot imposterise primitive types
• Cannot imposterise final classes
• Cannot imposterise classes with final toString methods (for concrete classes)
• Interfaces can always be imposterised if not final

Mock Object Creation

Creates a mock object (imposter) that forwards method invocations to the provided Invokable handler.

<T> T imposterise(Invokable mockObject, Class<T> mockedType, Class<?>... ancilliaryTypes);

Parameters:

• mockObject (Invokable): The handler that will receive forwarded method invocations
• mockedType (Class<T>): The primary class or interface to mock
• ancilliaryTypes (Class<?>...): Additional interfaces the mock should implement (varargs)

Returns:

• T: Mock instance that can be cast to mockedType and implements all ancilliaryTypes

Throws:

• IllegalArgumentException: If mockedType has a final toString method or cannot be imposterised
• IllegalArgumentException: If CGLib proxy creation fails

Notes:

• For concrete classes, constructors are temporarily made accessible during proxy creation
• Uses Objenesis to create instances without calling constructors
• Automatically handles method filtering (ignores bridge methods and finalize)

Singleton Instance Access

Static singleton instance providing the primary access point for the imposteriser.

public static final Imposteriser INSTANCE;

Description:

• Pre-initialized singleton instance of ClassImposteriser
• Thread-safe access point for all imposterisation operations
• Implements the Imposteriser interface from jMock core

Types

Core Interface

/**
 * Interface for creating proxy objects that capture method invocations
 * and forward them to Invokable handlers for mocking or stubbing
 */
public interface Imposteriser {
    boolean canImposterise(Class<?> type);
    <T> T imposterise(Invokable mockObject, Class<T> mockedType, Class<?>... ancilliaryTypes);
}

Supporting Types

/**
 * Handler interface for receiving method invocations from mock objects
 */
public interface Invokable {
    Object invoke(Invocation invocation) throws Throwable;
}

/**
 * Interface for building textual descriptions of objects
 */
public interface Description {
    Description appendText(String text);
    Description appendValueList(String start, String separator, String end, Object... values);
}

/**
 * Interface for objects that can describe themselves to a Description
 */
public interface SelfDescribing {
    void describeTo(Description description);
}

/**
 * Represents a method invocation on a mock object
 */
public class Invocation implements SelfDescribing {
    public static final Object[] NO_PARAMETERS = null;
    
    public enum ExpectationMode {
        BUILDING, // We're building the expectations so invocations can return null
        ASSERTING, // Return the default or specified reply
        LEGACY // Legacy mode old imposters
    }
    
    public Invocation(ExpectationMode mode, Object invoked, Method method, Object... parameterValues);
    public Invocation(ExpectationMode mode, Invocation other);
    public Invocation(Object invoked, Method method, Object... parameterValues);
    
    public Object getInvokedObject();
    public Method getInvokedMethod();
    public int getParameterCount();
    public Object getParameter(int i);
    public Object[] getParametersAsArray();
    public Object applyTo(Object target) throws Throwable;
    public void checkReturnTypeCompatibility(Object value);
    public boolean isBuildingExpectation();
    
    // SelfDescribing interface
    public void describeTo(Description description);
}

Internal Classes

/**
 * Utility class used internally to work around CGLib limitations
 * when mocking Object.class
 */
public static class ClassWithSuperclassToWorkAroundCglibBug {
    // Empty class used as CGLib proxy superclass
}

Error Handling

Common Exceptions

• IllegalArgumentException: Thrown when attempting to imposterise unsupported types

  • Classes with final toString methods
  • Types that cannot be enhanced by CGLib
  • Proxy creation failures in complex class loading scenarios

• IllegalStateException: Thrown for reflection security issues

  • When access to toString method is denied
  • When finalize method cannot be found on Object

Best Practices

• Always check canImposterise() before calling imposterise()
• Handle IllegalArgumentException for unsupported class types
• Be aware of Java 11 compatibility limitations (use ByteBuddy alternative for newer Java versions)
• Consider thread safety when sharing mock instances across threads

Migration Notes

This library is marked as deprecated. For new development or Java 11+ compatibility, migrate to:

// Recommended alternative
import org.jmock.lib.imposters.ByteBuddyClassImposteriser;

Imposteriser imposteriser = ByteBuddyClassImposteriser.INSTANCE;