0
# Virtual Machine Operations
1

2
Low-level virtual machine interaction interface providing direct access to VM operations including property access, agent loading, and management agent control. Used internally by attachment mechanisms and available for advanced use cases requiring fine-grained VM control.
3

4
## Capabilities
5

6
### Virtual Machine Interface
7

8
The VirtualMachine interface provides a platform-independent abstraction for interacting with JVM processes. Implementations handle platform-specific communication protocols while providing a consistent API.
9

10
```java { .api }
11
/**
12
 * An implementation for attachment on a virtual machine. This interface mimics the tooling API's virtual
13
 * machine interface to allow for similar usage by ByteBuddyAgent where all calls are made via
14
 * reflection such that this structural typing suffices for interoperability.
15
 * 
16
 * Note: Implementations are required to declare a static method attach(String) returning an
17
 * instance of a class that declares the methods defined by VirtualMachine.
18
 */
19
public interface VirtualMachine {
20
    // Core interface methods defined below
21
}
22
```
23

24
### Property Access Operations
25

26
Retrieve system and agent properties from the target virtual machine for inspection and configuration purposes.
27

28
```java { .api }
29
/**
30
 * Loads the target VMs system properties.
31
 * @return The target VM properties
32
 * @throws IOException If an I/O exception occurs
33
 */
34
Properties getSystemProperties() throws IOException;
35

36
/**
37
 * Loads the target VMs agent properties.
38
 * @return The target VM properties  
39
 * @throws IOException If an I/O exception occurs
40
 */
41
Properties getAgentProperties() throws IOException;
42
```
43

44
### Agent Loading Operations
45

46
Load Java agents and native libraries into the target virtual machine with optional arguments.
47

48
```java { .api }
49
/**
50
 * Loads an agent into the represented virtual machine.
51
 * @param jarFile The jar file to attach
52
 * @throws IOException If an I/O exception occurs
53
 */
54
void loadAgent(String jarFile) throws IOException;
55

56
/**
57
 * Loads an agent into the represented virtual machine.
58
 * @param jarFile The jar file to attach
59
 * @param argument The argument to provide or null if no argument should be provided
60
 * @throws IOException If an I/O exception occurs
61
 */
62
void loadAgent(String jarFile, @MaybeNull String argument) throws IOException;
63

64
/**
65
 * Loads a native agent into the represented virtual machine.
66
 * @param path The agent path
67
 * @throws IOException If an I/O exception occurs
68
 */
69
void loadAgentPath(String path) throws IOException;
70

71
/**
72
 * Loads a native agent into the represented virtual machine.
73
 * @param path The agent path
74
 * @param argument The argument to provide or null if no argument should be provided
75
 * @throws IOException If an I/O exception occurs
76
 */
77
void loadAgentPath(String path, @MaybeNull String argument) throws IOException;
78

79
/**
80
 * Loads a native agent library into the represented virtual machine.
81
 * @param library The agent library
82
 * @throws IOException If an I/O exception occurs
83
 */
84
void loadAgentLibrary(String library) throws IOException;
85

86
/**
87
 * Loads a native agent library into the represented virtual machine.
88
 * @param library The agent library
89
 * @param argument The argument to provide or null if no argument should be provided
90
 * @throws IOException If an I/O exception occurs
91
 */
92
void loadAgentLibrary(String library, @MaybeNull String argument) throws IOException;
93
```
94

95
### Management Agent Operations
96

97
Control JMX management agents on the target virtual machine for monitoring and management capabilities.
98

99
```java { .api }
100
/**
101
 * Starts a JMX management agent.
102
 * @param properties The properties to transfer to the JMX agent
103
 * @throws IOException If an I/O error occurs
104
 */
105
void startManagementAgent(Properties properties) throws IOException;
106

107
/**
108
 * Starts a local management agent.
109
 * @return The local connector address
110
 * @throws IOException If an I/O error occurs
111
 */
112
String startLocalManagementAgent() throws IOException;
113
```
114

115
### Connection Management
116

117
Manage the virtual machine connection lifecycle.
118

119
```java { .api }
120
/**
121
 * Detaches this virtual machine representation.
122
 * @throws IOException If an I/O exception occurs
123
 */
124
void detach() throws IOException;
125
```
126

127
### VM Implementation Resolution  
128

129
Resolve the appropriate virtual machine implementation for the current platform and JVM type.
130

131
```java { .api }
132
/**
133
 * A resolver for the current VM's virtual machine attachment emulation.
134
 */
135
enum Resolver implements PrivilegedAction<Class<? extends VirtualMachine>> {
136
    INSTANCE;
137
    
138
    public Class<? extends VirtualMachine> run();
139
}
140
```
141

142
## Platform-Specific Implementations
143

144
### HotSpot Virtual Machine
145

146
Implementation for HotSpot JVM and compatible virtual machines (Oracle JDK, OpenJDK) using various connection mechanisms.
147

148
```java { .api }
149
/**
150
 * A virtual machine attachment implementation for a HotSpot VM or any compatible JVM.
151
 */
152
class ForHotSpot extends AbstractBase {
153
    /**
154
     * Attaches to the supplied process id using the default JNA implementation.
155
     */
156
    public static VirtualMachine attach(String processId) throws IOException;
157
    
158
    /**
159
     * Attaches to the supplied process id using the supplied connection factory.
160
     */
161
    public static VirtualMachine attach(String processId, Connection.Factory connectionFactory) throws IOException;
162
}
163
```
164

165
### OpenJ9 Virtual Machine
166

167
Implementation for IBM J9/OpenJ9 virtual machines using socket-based communication protocols.
168

169
```java { .api }
170
/**
171
 * A virtual machine attachment implementation for OpenJ9 or any compatible JVM.
172
 */  
173
class ForOpenJ9 extends AbstractBase {
174
    /**
175
     * Attaches to the supplied process id using the default JNA implementation.
176
     */
177
    public static VirtualMachine attach(String processId) throws IOException;
178
    
179
    /**
180
     * Attaches to the supplied process id with timeout and dispatcher.
181
     */
182
    public static VirtualMachine attach(String processId, int timeout, Dispatcher dispatcher) throws IOException;
183
}
184
```
185

186
## Usage Examples
187

188
### Direct VM Attachment
189

190
```java
191
import net.bytebuddy.agent.VirtualMachine;
192
import java.util.Properties;
193

194
// Attach to HotSpot VM
195
VirtualMachine vm = VirtualMachine.ForHotSpot.attach("1234");
196

197
try {
198
    // Inspect VM properties
199
    Properties systemProps = vm.getSystemProperties();
200
    String javaVersion = systemProps.getProperty("java.version");
201
    String vmName = systemProps.getProperty("java.vm.name");
202
    
203
    System.out.println("Target VM Java version: " + javaVersion);
204
    System.out.println("Target VM name: " + vmName);
205
    
206
    // Load agent
207
    vm.loadAgent("/path/to/agent.jar", "debug=true");
208
    
209
} finally {
210
    vm.detach();
211
}
212
```
213

214
### OpenJ9 VM Operations
215

216
```java
217
import net.bytebuddy.agent.VirtualMachine;
218

219
// Attach to OpenJ9 VM with timeout
220
VirtualMachine vm = VirtualMachine.ForOpenJ9.attach("5678", 10000, 
221
    new VirtualMachine.ForOpenJ9.Dispatcher.ForJnaPosixEnvironment(15, 100, TimeUnit.MILLISECONDS));
222

223
try {
224
    // Start local management agent
225
    String connectorAddress = vm.startLocalManagementAgent();
226
    System.out.println("JMX connector: " + connectorAddress);
227
    
228
    // Load native library
229
    vm.loadAgentLibrary("profiler", "output=profile.log");
230
    
231
} finally {
232
    vm.detach();
233
}
234
```
235

236
### Management Agent Control
237

238
```java
239
import net.bytebuddy.agent.VirtualMachine;
240
import java.util.Properties;
241

242
VirtualMachine vm = VirtualMachine.ForHotSpot.attach("9999");
243

244
try {
245
    // Configure and start JMX management agent
246
    Properties jmxProps = new Properties();
247
    jmxProps.setProperty("com.sun.management.jmxremote.port", "9876");
248
    jmxProps.setProperty("com.sun.management.jmxremote.authenticate", "false");
249
    jmxProps.setProperty("com.sun.management.jmxremote.ssl", "false");
250
    
251
    vm.startManagementAgent(jmxProps);
252
    System.out.println("JMX management agent started on port 9876");
253
    
254
    // Verify agent properties
255
    Properties agentProps = vm.getAgentProperties();
256
    String jmxUrl = agentProps.getProperty("com.sun.management.jmxremote.localConnectorAddress");
257
    if (jmxUrl != null) {
258
        System.out.println("Local JMX URL: " + jmxUrl);
259
    }
260
    
261
} finally {
262
    vm.detach();
263
}
264
```
265

266
### Platform-Specific VM Resolution
267

268
```java
269
import net.bytebuddy.agent.VirtualMachine;
270
import java.security.AccessController;
271

272
// Resolve appropriate VM implementation for current platform
273
Class<? extends VirtualMachine> vmClass = AccessController.doPrivileged(
274
    VirtualMachine.Resolver.INSTANCE);
275

276
System.out.println("Using VM implementation: " + vmClass.getName());
277

278
// The resolver returns:
279
// - ForOpenJ9.class for IBM J9 VMs
280
// - ForHotSpot.class for HotSpot and compatible VMs
281
```
282

283
### Advanced Connection Management
284

285
```java
286
import net.bytebuddy.agent.VirtualMachine;
287
import net.bytebuddy.agent.VirtualMachine.ForHotSpot.Connection;
288

289
// Custom connection factory for HotSpot
290
Connection.Factory factory;
291
if (Platform.isWindows()) {
292
    factory = new Connection.ForJnaWindowsNamedPipe.Factory();
293
} else if (Platform.isSolaris()) {
294
    factory = new Connection.ForJnaSolarisDoor.Factory(15, 100, TimeUnit.MILLISECONDS);
295
} else {
296
    factory = Connection.ForJnaPosixSocket.Factory.withDefaultTemporaryFolder(15, 100, TimeUnit.MILLISECONDS);
297
}
298

299
VirtualMachine vm = VirtualMachine.ForHotSpot.attach("1234", factory);
300

301
try {
302
    // Use VM with custom connection
303
    vm.loadAgent("custom-agent.jar");
304
} finally {
305
    vm.detach();
306
}
307
```
308

309
## Error Handling
310

311
Virtual machine operations may throw IOException for various reasons:
312

313
- **Connection failures**: Target process not found or not accessible
314
- **Protocol errors**: Communication protocol mismatch or failure
315
- **Agent loading errors**: Invalid agent JAR or native library
316
- **Permission issues**: Insufficient privileges for VM operations
317
- **VM state issues**: Target VM in incompatible state
318

319
Always use try-finally blocks to ensure proper connection cleanup:
320

321
```java
322
VirtualMachine vm = null;
323
try {
324
    vm = VirtualMachine.ForHotSpot.attach(processId);
325
    // Perform operations
326
} catch (IOException e) {
327
    System.err.println("VM operation failed: " + e.getMessage());
328
} finally {
329
    if (vm != null) {
330
        try {
331
            vm.detach();
332
        } catch (IOException e) {
333
            System.err.println("Failed to detach: " + e.getMessage());
334
        }
335
    }
336
}
337
```
338

339
## Platform Compatibility
340

341
- **Windows**: Named pipe connections, requires JNA
342
- **Linux**: POSIX socket connections via JNA or Unix socket emulation  
343
- **macOS**: POSIX socket connections with macOS-specific temporary directory handling
344
- **Solaris**: Solaris door connections via JNA
345
- **AIX**: Support through POSIX compatibility layer
346

347
The virtual machine abstraction handles platform-specific details automatically, but some features may require specific JNA libraries or native extensions.