0
# jMock Legacy
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: jmock-legacy
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.jmock</groupId>
13
    <artifactId>jmock-legacy</artifactId>
14
    <version>2.13.1</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.jmock.lib.legacy.ClassImposteriser;
22
import org.jmock.api.Imposteriser;
23
```
24

25
## Basic Usage
26

27
```java
28
import org.jmock.lib.legacy.ClassImposteriser;
29
import org.jmock.api.Imposteriser;
30
import org.jmock.api.Invokable;
31

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

35
// Check if a class can be mocked
36
if (imposteriser.canImposterise(MyConcreteClass.class)) {
37
    // Create a mock instance
38
    MyConcreteClass mock = imposteriser.imposterise(
39
        mockInvokable, 
40
        MyConcreteClass.class
41
    );
42
}
43

44
// Mock with additional interfaces
45
MyConcreteClass mock = imposteriser.imposterise(
46
    mockInvokable,
47
    MyConcreteClass.class,
48
    AdditionalInterface.class,
49
    AnotherInterface.class
50
);
51
```
52

53
## Architecture
54

55
ClassImposteriser uses CGLib proxies and Objenesis for runtime class enhancement:
56

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

63
## Capabilities
64

65
### Class Imposterization Check
66

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

69
```java { .api }
70
boolean canImposterise(Class<?> type);
71
```
72

73
**Parameters:**
74
- `type` (Class<?>): The class type to check for imposterisation capability
75

76
**Returns:**
77
- `boolean`: `true` if the type can be imposterised, `false` otherwise
78

79
**Constraints:**
80
- Cannot imposterise primitive types
81
- Cannot imposterise final classes
82
- Cannot imposterise classes with final toString methods (for concrete classes)
83
- Interfaces can always be imposterised if not final
84

85
### Mock Object Creation
86

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

89
```java { .api }
90
<T> T imposterise(Invokable mockObject, Class<T> mockedType, Class<?>... ancilliaryTypes);
91
```
92
93
**Parameters:**
94
- `mockObject` (Invokable): The handler that will receive forwarded method invocations
95
- `mockedType` (Class<T>): The primary class or interface to mock
96
- `ancilliaryTypes` (Class<?>...): Additional interfaces the mock should implement (varargs)
97

98
**Returns:**
99
- `T`: Mock instance that can be cast to `mockedType` and implements all `ancilliaryTypes`
100

101
**Throws:**
102
- `IllegalArgumentException`: If `mockedType` has a final toString method or cannot be imposterised
103
- `IllegalArgumentException`: If CGLib proxy creation fails
104

105
**Notes:**
106
- For concrete classes, constructors are temporarily made accessible during proxy creation
107
- Uses Objenesis to create instances without calling constructors
108
- Automatically handles method filtering (ignores bridge methods and finalize)
109

110
### Singleton Instance Access
111

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

114
```java { .api }
115
public static final Imposteriser INSTANCE;
116
```
117

118
**Description:**
119
- Pre-initialized singleton instance of ClassImposteriser
120
- Thread-safe access point for all imposterisation operations
121
- Implements the Imposteriser interface from jMock core
122

123
## Types
124

125
### Core Interface
126

127
```java { .api }
128
/**
129
 * Interface for creating proxy objects that capture method invocations
130
 * and forward them to Invokable handlers for mocking or stubbing
131
 */
132
public interface Imposteriser {
133
    boolean canImposterise(Class<?> type);
134
    <T> T imposterise(Invokable mockObject, Class<T> mockedType, Class<?>... ancilliaryTypes);
135
}
136
```
137

138
### Supporting Types
139

140
```java { .api }
141
/**
142
 * Handler interface for receiving method invocations from mock objects
143
 */
144
public interface Invokable {
145
    Object invoke(Invocation invocation) throws Throwable;
146
}
147

148
/**
149
 * Interface for building textual descriptions of objects
150
 */
151
public interface Description {
152
    Description appendText(String text);
153
    Description appendValueList(String start, String separator, String end, Object... values);
154
}
155

156
/**
157
 * Interface for objects that can describe themselves to a Description
158
 */
159
public interface SelfDescribing {
160
    void describeTo(Description description);
161
}
162

163
/**
164
 * Represents a method invocation on a mock object
165
 */
166
public class Invocation implements SelfDescribing {
167
    public static final Object[] NO_PARAMETERS = null;
168
    
169
    public enum ExpectationMode {
170
        BUILDING, // We're building the expectations so invocations can return null
171
        ASSERTING, // Return the default or specified reply
172
        LEGACY // Legacy mode old imposters
173
    }
174
    
175
    public Invocation(ExpectationMode mode, Object invoked, Method method, Object... parameterValues);
176
    public Invocation(ExpectationMode mode, Invocation other);
177
    public Invocation(Object invoked, Method method, Object... parameterValues);
178
    
179
    public Object getInvokedObject();
180
    public Method getInvokedMethod();
181
    public int getParameterCount();
182
    public Object getParameter(int i);
183
    public Object[] getParametersAsArray();
184
    public Object applyTo(Object target) throws Throwable;
185
    public void checkReturnTypeCompatibility(Object value);
186
    public boolean isBuildingExpectation();
187
    
188
    // SelfDescribing interface
189
    public void describeTo(Description description);
190
}
191
```
192

193
### Internal Classes
194

195
```java { .api }
196
/**
197
 * Utility class used internally to work around CGLib limitations
198
 * when mocking Object.class
199
 */
200
public static class ClassWithSuperclassToWorkAroundCglibBug {
201
    // Empty class used as CGLib proxy superclass
202
}
203
```
204

205
## Error Handling
206

207
### Common Exceptions
208

209
- **IllegalArgumentException**: Thrown when attempting to imposterise unsupported types
210
  - Classes with final toString methods
211
  - Types that cannot be enhanced by CGLib
212
  - Proxy creation failures in complex class loading scenarios
213

214
- **IllegalStateException**: Thrown for reflection security issues
215
  - When access to toString method is denied
216
  - When finalize method cannot be found on Object
217

218
### Best Practices
219

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

225
## Migration Notes
226

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

229
```java
230
// Recommended alternative
231
import org.jmock.lib.imposters.ByteBuddyClassImposteriser;
232

233
Imposteriser imposteriser = ByteBuddyClassImposteriser.INSTANCE;
234
```