0
# PowerMock Classloading XStream
1

2
PowerMock Classloading XStream provides deep cloning capabilities for Java objects using XStream serialization. It enables objects to be deeply cloned across different classloaders, which is essential for PowerMock's advanced mocking features including static method mocking, final class mocking, and bytecode manipulation.
3

4
## Package Information
5

6
- **Package Name**: org.powermock:powermock-classloading-xstream
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Version**: 2.0.9
10
- **License**: Apache-2.0
11
- **Installation**: Include in Maven dependencies:
12

13
```xml
14
<dependency>
15
    <groupId>org.powermock</groupId>
16
    <artifactId>powermock-classloading-xstream</artifactId>
17
    <version>2.0.9</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
import org.powermock.classloading.DeepCloner;
25
```
26

27
## Basic Usage
28

29
```java
30
import org.powermock.classloading.DeepCloner;
31
import java.net.URLClassLoader;
32

33
// Create a deep cloner with the current context classloader
34
DeepCloner cloner = new DeepCloner();
35

36
// Or specify a specific classloader
37
ClassLoader customClassLoader = new URLClassLoader(urls);
38
DeepCloner customCloner = new DeepCloner(customClassLoader);
39

40
// Clone an object
41
MyObject original = new MyObject("example");
42
MyObject cloned = cloner.clone(original);
43

44
// The cloned object is a deep copy
45
assert original != cloned;
46
assert original.equals(cloned); // Assuming equals() is properly implemented
47
```
48

49
## Capabilities
50

51
### Object Deep Cloning
52

53
Creates complete deep copies of Java objects using XStream serialization, with support for cross-classloader cloning.
54

55
```java { .api }
56
public class DeepCloner implements DeepClonerSPI {
57
    
58
    // Create deep cloner using current context classloader
59
    public DeepCloner();
60
    
61
    // Create deep cloner using specified classloader
62
    public DeepCloner(ClassLoader classLoader);
63
    
64
    // Clone an object with full deep copy semantics
65
    public <T> T clone(T objectToClone);
66
}
67
```
68

69
**Constructor Details:**
70

71
- **`DeepCloner()`**: Creates a deep cloner using the current thread's context ClassLoader (`Thread.currentThread().getContextClassLoader()`)
72
- **`DeepCloner(ClassLoader classLoader)`**: Creates a deep cloner using the specified ClassLoader for loading cloned classes
73

74
**Method Details:**
75

76
- **`clone(T objectToClone)`**: 
77
  - Creates a deep clone of the supplied object using XStream XML serialization
78
  - Returns the same type as the input object
79
  - Supports cross-classloader cloning when a specific ClassLoader was provided
80
  - Handles complex object graphs including collections, arrays, and nested objects
81
  - **Thread Safety**: Not thread-safe (XStream instance is not thread-safe)
82

83
### Usage Examples
84

85
**Basic Cloning:**
86
```java
87
DeepCloner cloner = new DeepCloner();
88
String original = "Hello World";
89
String cloned = cloner.clone(original);
90
```
91

92
**Collection Cloning:**
93
```java
94
import java.util.Arrays;
95
import java.util.List;
96

97
DeepCloner cloner = new DeepCloner();
98
List<String> originalList = Arrays.asList("a", "b", "c");
99
List<String> clonedList = cloner.clone(originalList);
100
```
101

102
**Cross-ClassLoader Cloning:**
103
```java
104
import java.net.URL;
105
import java.net.URLClassLoader;
106

107
URLClassLoader targetClassLoader = new URLClassLoader(new URL[]{jarUrl});
108
DeepCloner cloner = new DeepCloner(targetClassLoader);
109
MyObject cloned = cloner.clone(originalObject);
110
// cloned object's class is loaded by targetClassLoader
111
```
112

113
## Types
114

115
### DeepClonerSPI Interface
116

117
```java { .api }
118
public interface DeepClonerSPI {
119
    <T> T clone(T objectToClone);
120
}
121
```
122

123
The `DeepClonerSPI` interface from the `org.powermock.classloading.spi` package defines the contract that all deep cloners must implement.
124

125
## Dependencies
126

127
This package requires the following dependencies:
128

129
- **XStream 1.4.10**: Core XML serialization engine
130
- **powermock-classloading-base**: Base classloading utilities and SPI interfaces
131

132
## Security Considerations
133

134
The `DeepCloner` disables XStream's security restrictions to allow unrestricted type access, which is intended for testing scenarios where maximum flexibility is required. This configuration allows serialization of any type but should be used carefully in production environments.
135

136
## Error Handling
137

138
The `DeepCloner` relies on XStream's exception handling for serialization errors. Common exceptions that may be thrown include:
139

140
- Serialization errors for non-serializable objects
141
- ClassNotFoundException when target classloader cannot load required classes
142
- XStream configuration errors for complex object graphs
143

144
## Implementation Notes
145

146
- Uses XStream's `toXML()` and `fromXML()` methods for serialization/deserialization
147
- Configured to omit the `classloader` field from `SingleClassloaderExecutor` instances during serialization
148
- Security is disabled with `allowTypesByRegExp(new String[]{".*"})` for maximum compatibility