0
# Jetty JMX
1

2
JMX (Java Management Extensions) integration library for Eclipse Jetty web server providing comprehensive monitoring, management, and administration capabilities. This package enables system administrators and developers to track server performance metrics, configure runtime parameters, and manage server lifecycle operations through standard JMX interfaces.
3

4
## Package Information
5

6
- **Package Name**: jetty-jmx
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
      <groupId>org.eclipse.jetty</groupId>
13
      <artifactId>jetty-jmx</artifactId>
14
      <version>12.0.21</version>
15
  </dependency>
16
  ```
17
- **Module**: `org.eclipse.jetty.jmx`
18

19
## Core Imports
20

21
```java
22
import org.eclipse.jetty.jmx.MBeanContainer;
23
import org.eclipse.jetty.jmx.ConnectorServer;
24
import org.eclipse.jetty.jmx.ObjectMBean;
25
```
26

27
Module imports:
28

29
```java
30
module org.eclipse.jetty.jmx {
31
    requires org.slf4j;
32
    requires transitive java.management;
33
    requires transitive org.eclipse.jetty.util;
34
    requires static java.management.rmi;
35
    requires static java.rmi;
36
    
37
    exports org.eclipse.jetty.jmx;
38
}
39
```
40

41
## Basic Usage
42

43
```java
44
import org.eclipse.jetty.jmx.MBeanContainer;
45
import org.eclipse.jetty.jmx.ConnectorServer;
46
import org.eclipse.jetty.server.Server;
47
import java.lang.management.ManagementFactory;
48
import javax.management.MBeanServer;
49
import javax.management.remote.JMXServiceURL;
50

51
// Create Jetty server
52
Server server = new Server(8080);
53

54
// Create MBean container for registering Jetty components
55
MBeanServer mbeanServer = ManagementFactory.getPlatformMBeanServer();
56
MBeanContainer mbeanContainer = new MBeanContainer(mbeanServer);
57
mbeanContainer.setDomain("org.eclipse.jetty");
58

59
// Register MBean container with server to automatically register components
60
server.addBean(mbeanContainer);
61

62
// Set up JMX remote connector for external access
63
JMXServiceURL serviceURL = new JMXServiceURL("rmi", null, 1099, "/jndi/rmi://localhost:1099/jmxrmi");
64
ConnectorServer connectorServer = new ConnectorServer(serviceURL, "org.eclipse.jetty:name=rmiconnectorserver");
65
server.addBean(connectorServer);
66

67
// Start server (this will automatically register MBeans and start JMX connector)
68
server.start();
69

70
// JMX is now available at: service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi
71
```
72

73
## Architecture
74

75
The jetty-jmx module provides three key components that work together:
76

77
- **MBeanContainer**: Core component that automatically discovers and registers Jetty components as MBeans, implementing Container.InheritedListener for automatic component lifecycle tracking
78
- **ConnectorServer**: Lifecycle wrapper for JMXConnectorServer providing remote JMX access with SSL support and RMI registry management
79
- **ObjectMBean**: Dynamic MBean wrapper that exposes arbitrary Java objects through JMX using reflection and annotation-based metadata discovery
80

81
This architecture enables seamless integration with existing JMX monitoring tools and provides enterprise-grade management capabilities with minimal configuration overhead.
82

83
## Capabilities
84

85
### MBean Container Management
86

87
Core container for managing MBean registration and lifecycle, providing automatic discovery and registration of Jetty components through Container.InheritedListener interface.
88

89
```java { .api }
90
@ManagedObject("The component that registers beans as MBeans")
91
public class MBeanContainer implements Container.InheritedListener, Dumpable, Destroyable {
92
    // Constructors
93
    public MBeanContainer(MBeanServer server);
94
    public MBeanContainer(MBeanServer server, boolean cacheOtherClassLoaders);
95
    
96
    // Core MBean server access
97
    public MBeanServer getMBeanServer();
98
    
99
    // Configuration methods
100
    @ManagedAttribute(value = "Whether to use the cache for MBeans loaded by other ClassLoaders", readonly = true)
101
    public boolean isUseCacheForOtherClassLoaders();
102
    public void setDomain(String domain);
103
    @ManagedAttribute("The default ObjectName domain")
104
    public String getDomain();
105
    
106
    // MBean creation and lookup
107
    public Object mbeanFor(Object o);
108
    public ObjectName findMBean(Object object);
109
    public Object findBean(ObjectName objectName);
110
    public String makeName(String basis);
111
    
112
    // Container.InheritedListener implementation
113
    @Override
114
    public void beanAdded(Container parent, Object obj);
115
    @Override
116
    public void beanRemoved(Container parent, Object obj);
117
    
118
    // Dumpable implementation
119
    @Override
120
    public void dump(Appendable out, String indent) throws IOException;
121
    @Override
122
    public String dump();
123
    
124
    // Destroyable implementation
125
    @Override
126
    public void destroy();
127
}
128
```
129

130
### JMX Connector Server
131

132
LifeCycle wrapper for JMXConnectorServer providing remote JMX connectivity with SSL/TLS support and automatic RMI registry management.
133

134
```java { .api }
135
public class ConnectorServer extends AbstractLifeCycle {
136
    // Constants
137
    public static final String RMI_REGISTRY_CLIENT_SOCKET_FACTORY_ATTRIBUTE = "com.sun.jndi.rmi.factory.socket";
138
    
139
    // Constructors
140
    public ConnectorServer(JMXServiceURL serviceURL, String objectName);
141
    public ConnectorServer(JMXServiceURL serviceURL, Map<String, ?> environment, String objectName);
142
    public ConnectorServer(JMXServiceURL serviceURL, Map<String, ?> environment, String objectName, SslContextFactory.Server sslContextFactory);
143
    
144
    // Configuration and access methods
145
    public JMXServiceURL getAddress();
146
    public void putAttribute(String name, Object value);
147
    public String getObjectName();
148
    public void setObjectName(String objectName);
149
    public SslContextFactory.Server getSslContextFactory();
150
    public void setSslContextFactory(SslContextFactory.Server sslContextFactory);
151
    
152
    // AbstractLifeCycle overrides
153
    @Override
154
    protected void doStart() throws Exception;
155
    @Override
156
    protected void doStop() throws Exception;
157
}
158
```
159

160
### Dynamic MBean Wrapper
161

162
Dynamic MBean implementation that wraps arbitrary Java objects, exposing their methods and properties through JMX using reflection and JMX annotations.
163

164
```java { .api }
165
public class ObjectMBean implements DynamicMBean {
166
    // Constructor
167
    public ObjectMBean(Object managedObject);
168
    
169
    // Managed object access
170
    public Object getManagedObject();
171
    
172
    // ObjectName customization hooks
173
    public ObjectName getObjectName();
174
    public String getObjectContextBasis();
175
    public String getObjectNameBasis();
176
    
177
    // Container access
178
    public MBeanContainer getMBeanContainer();
179
    protected void setMBeanContainer(MBeanContainer container);
180
    
181
    // DynamicMBean interface implementation
182
    @Override
183
    public MBeanInfo getMBeanInfo();
184
    @Override
185
    public Object getAttribute(String name) throws AttributeNotFoundException, ReflectionException, MBeanException;
186
    @Override
187
    public AttributeList getAttributes(String[] names);
188
    @Override
189
    public void setAttribute(Attribute attribute) throws AttributeNotFoundException, ReflectionException, MBeanException;
190
    @Override
191
    public AttributeList setAttributes(AttributeList attributes);
192
    @Override
193
    public Object invoke(String name, Object[] params, String[] signature) throws ReflectionException, MBeanException;
194
}
195
```
196

197
## Types
198

199
```java { .api }
200
// Standard JMX types from java.management
201
interface MBeanServer extends javax.management.MBeanServerConnection;
202
interface DynamicMBean;
203
class ObjectName implements java.io.Serializable;
204
class MBeanInfo implements java.io.Serializable;
205
class AttributeList extends java.util.ArrayList<Object>;
206
class Attribute implements java.io.Serializable;
207
class AttributeNotFoundException extends OperationsException;
208
class ReflectionException extends JMException;
209
class MBeanException extends JMException;
210

211
// Jetty component framework types from org.eclipse.jetty.util.component
212
interface Container;
213
interface Container.InheritedListener {
214
    void beanAdded(Container parent, Object child);
215
    void beanRemoved(Container parent, Object child);
216
}
217
abstract class AbstractLifeCycle implements LifeCycle;
218
interface Dumpable {
219
    void dump(Appendable out, String indent) throws java.io.IOException;
220
    String dump();
221
}
222
interface Destroyable {
223
    void destroy();
224
}
225

226
// JMX connectivity types from java.management.remote
227
class JMXServiceURL implements java.io.Serializable;
228
class JMXConnectorServer implements JMXConnector;
229

230
// SSL support from org.eclipse.jetty.util.ssl  
231
class SslContextFactory.Server extends SslContextFactory;
232

233
// Jetty annotation types from org.eclipse.jetty.util.annotation
234
@interface ManagedObject {
235
    String value() default "";
236
}
237
@interface ManagedAttribute {
238
    String value() default "";
239
    String name() default "";
240
    boolean readonly() default false;
241
    boolean proxied() default false;
242
    String setter() default "";
243
}
244
```
245

246
## Usage Examples
247

248
### Setting up MBean Container with Custom Domain
249

250
```java
251
MBeanServer mbeanServer = ManagementFactory.getPlatformMBeanServer();
252
MBeanContainer mbeanContainer = new MBeanContainer(mbeanServer);
253
mbeanContainer.setDomain("com.example.jetty");
254

255
// Add to server - this automatically registers all Jetty components
256
server.addBean(mbeanContainer);
257
```
258

259
### Creating Custom MBeans
260

261
```java
262
// Wrap any object as an MBean
263
MyCustomComponent component = new MyCustomComponent();
264
Object mbean = mbeanContainer.mbeanFor(component);
265

266
// Find registered MBeans
267
ObjectName objectName = mbeanContainer.findMBean(component);
268
Object retrievedBean = mbeanContainer.findBean(objectName);
269
```
270

271
### Setting up Remote JMX Access with SSL
272

273
```java
274
// Create SSL context factory
275
SslContextFactory.Server sslContextFactory = new SslContextFactory.Server();
276
sslContextFactory.setKeyStorePath("/path/to/keystore.jks");
277
sslContextFactory.setKeyStorePassword("password");
278

279
// Create secure JMX connector
280
JMXServiceURL serviceURL = new JMXServiceURL("rmi", null, 1099, "/jndi/rmi://localhost:1099/jmxrmi");
281
Map<String, Object> environment = new HashMap<>();
282
ConnectorServer connectorServer = new ConnectorServer(serviceURL, environment, "org.eclipse.jetty:name=rmiconnectorserver", sslContextFactory);
283

284
server.addBean(connectorServer);
285
```
286

287
### Working with Dynamic MBeans
288

289
```java
290
// Create ObjectMBean for any object
291
MyComponent component = new MyComponent();
292
ObjectMBean objectMBean = new ObjectMBean(component);
293

294
// Access MBean metadata
295
MBeanInfo mbeanInfo = objectMBean.getMBeanInfo();
296
Object attributeValue = objectMBean.getAttribute("someProperty");
297

298
// Invoke operations
299
Object result = objectMBean.invoke("someMethod", new Object[]{"param"}, new String[]{"java.lang.String"});
300
```
301

302
## Error Handling
303

304
The jetty-jmx module provides comprehensive error handling:
305

306
- **Registration Failures**: Graceful degradation when MBean registration fails, with detailed logging
307
- **Connector Issues**: Proper exception handling for RMI registry and JMX connector setup
308
- **Resource Cleanup**: Automatic cleanup of registered MBeans and resources during component destruction
309
- **Thread Safety**: Thread-safe operations with proper synchronization for concurrent access
310

311
## Integration Notes
312

313
### Jetty Container Integration
314

315
The MBeanContainer implements Container.InheritedListener, automatically registering and unregistering MBeans as Jetty components are added or removed from the container hierarchy.
316

317
### JMX Annotations Support
318

319
ObjectMBean supports standard JMX annotations:
320
- `@ManagedObject` - Marks classes for JMX exposure
321
- `@ManagedAttribute` - Exposes getter/setter methods as MBean attributes
322
- `@ManagedOperation` - Exposes methods as MBean operations
323

324
### ClassLoader Handling
325

326
The module properly handles different ClassLoader contexts, with optional caching for improved performance when working with multiple ClassLoaders.