Java™ Management Extensions (JMX™) Specification, version 1.4: Final Release

1.
Introduction to the JMX Specification
21
1.1
Benefits of the JMX Architecture
21
1.2
Scope of this Specification
23
1.2.1
Reference Implementation
23
1.2.2
Compatibility Test Suite
23
1.2.3
JMX APIs as part of the Java Platform
24
1.3
Architectural Overview
24
1.3.1
Instrumentation Level
25
1.3.2
Agent Level
26
1.3.3
Distributed Services Level
27
1.4
Component Overview
28
1.4.1
Components of the Instrumentation Level
28
1.4.1.1
Managed Beans (MBeans)
28
1.4.1.2
Notification Model
29
1.4.1.3
MBean Metadata Classes
30
1.4.2
Components of the Agent Level
30
1.4.2.1
MBean Server
30
1.4.2.2
Agent Services
31
1.5
JMX Remote API
32
1.6
What Has Changed
32
1.6.1
Changes to the JMX Specification (JSR 3)
33
1.6.2
Changes to the JMX Remote Specification (JSR 160)
35
Part I.
JMX Instrumentation Specification
2.
MBean Instrumentation
39
2.1
Definition
39
2.1.1
Public Management Interface
40
6
Java Management Extensions Specification, version 1.4
•  November 9, 2006
2.1.2
MBean Public Constructor
40
2.2
Standard MBeans
41
2.2.1
MBean Interface
42
2.2.1.1
The
MyClass
 Example MBean
43
2.2.2
Lexical Design Patterns
44
2.2.2.1
Attributes
44
2.2.2.2
Operations
45
2.2.2.3
Case Sensitivity
46
2.3
Dynamic MBeans
46
2.3.1
DynamicMBean
 Interface
47
2.3.2
Behavior of Dynamic MBeans
49
2.3.2.1
Coherence
49
2.3.2.2
Dynamics
49
2.4
Inheritance Patterns
50
2.5
JMX Notification Model
54
2.5.0.1
Notification Type
54
2.5.1
Notification Class
55
2.5.2
NotificationBroadcaster
 and NotificationEmitter
Interfaces
56
2.5.3
NotificationListener
 Interface
57
2.5.4
NotificationFilter
 Interface
58
2.6
Attribute Change Notifications
58
2.6.1
AttributeChangeNotification
 Class
59
2.6.2
AttributeChangeNotificationFilter
 Class
59
2.7
MBean Metadata Classes
60
2.7.1
MBeanInfo
 Class
61
2.7.2
MBeanFeatureInfo
 Class
62
2.7.3
MBeanAttributeInfo
 Class
63
2.7.4
MBeanConstructorInfo
 Class
63
2.7.5
MBeanOperationInfo
 Class
64
2.7.6
MBeanParameterInfo
 Class
64
Chapter
Contents
7
2.7.7
MBeanNotificationInfo
 Class
65
3.
Open MBeans
67
3.1
Overview
67
3.2
Basic Data Types
68
3.2.1
Representing Complex Data
70
3.2.1.1
CompositeData
 Interface and Support Class
70
3.2.1.2
TabularData
 Interface and Support Class
71
3.2.2
Open Type Descriptions
71
3.3
Open MBean Metadata Classes
72
3.3.1
OpenMBeanInfo
 Interface and Support Class
73
3.3.2
OpenMBeanOperationInfo
and
OpenMBeanConstructorInfo
Interfaces and Support Classes
74
3.3.3
OpenMBeanParameterInfo
 and
OpenMBeanAttributeInfo
Interfaces and Support Classes
75
3.4
Summary of Open MBean Requirements
76
4.
Model MBeans
77
4.1
Overview
77
4.1.1
Generic Notifications
79
4.1.2
Interaction with Managed Resources
80
4.1.3
Interaction with Management Applications
81
4.2
Model MBean Metadata Classes
81
4.2.1
Descriptor
 Interface
81
4.2.2
DescriptorAccess
 Interface
83
4.2.3
ModelMBeanInfo
 Interface
84
4.2.4
ModelMBeanInfo
 Implementation
85
4.2.5
ModelMBeanAttributeInfo
 Implementation
88
4.2.6
ModelMBeanConstructorInfo
 Implementation
89
4.2.7
ModelMBeanOperationInfo
 Implementation
89
4.2.8
ModelMBeanNotificationInfo
 Implementation
90
8
Java Management Extensions Specification, version 1.4
•  November 9, 2006
4.3
Model MBean Specification
90
4.3.1
ModelMBean
 Interface
91
4.3.2
ModelMBean
 Implementation
92
4.3.3
DynamicMBean
 Implementation
93
4.3.4
PersistentMBean
 Interface
95
4.3.5
ModelMBeanNotificationBroadcaster
 Interface
96
4.3.6
ModelMBeanNotificationBroadcaster
 Implementation
97
4.4
Descriptors
97
4.4.1
Attribute Behavior
98
4.4.2
Notification Logging Policy
98
4.4.3
Persistence Policy
99
4.4.4
Behavior of Cached Values
100
4.4.5
Protocol Map Support
100
4.4.6
Export Policy
101
4.4.7
Visibility Policy
101
4.4.8
Presentation Behavior
102
4.5
Predefined Descriptor Fields
102
4.5.1
MBean Descriptor Fields
102
4.5.2
Attribute Descriptor Fields
104
4.5.3
Operation Descriptor Fields
105
4.5.4
Notification Descriptor Fields
106
Part II.
JMX Agent Specification
5.
Agent Architecture
111
5.1
Overview
111
5.2
JMX Compliant Agent
113
5.3
Protocol Adaptors and Connectors
113
6.
Foundation Classes
115
6.1
ObjectName
 Class
115
6.1.1
Domain Name
116
6.1.2
Key Property List
116
6.1.3
String Representation of Names
117
6.1.4
Pattern Matching
117
6.1.4.1
Pattern Matching Examples
118
6.2
ObjectInstance
 Class
119
6.3
Attribute
 and
AttributeList
 Classes
119
6.4
JMX Exceptions
119
6.4.1
JMException
 Class and Subclasses
120
6.4.2
JMRuntimeException
 Class and Subclasses
121
6.4.3
Description of JMX Exceptions
122
6.4.3.1
JMException
 Class
123
6.4.3.2
ReflectionException
 Class
123
6.4.3.3
MBeanException
 Class
123
6.4.3.4
OperationsException
 Class
123
6.4.3.5
InstanceAlreadyExistsException
 Class
123
6.4.3.6
InstanceNotFoundException
 Class
124
6.4.3.7
InvalidAttributeValueException
 Class
124
6.4.3.8
AttributeNotFoundException
 Class
124
6.4.3.9
IntrospectionException
 Class
124
6.4.3.10
MalformedObjectNameException
 Class
124
6.4.3.11
NotCompliantMBeanException
 Class
124
6.4.3.12
ServiceNotFoundException
 Class
124
6.4.3.13
MBeanRegistrationException
 Class
124
6.4.3.14
JMRuntimeException
 Class
125
6.4.3.15
RuntimeOperationsException
 Class
125
6.4.3.16
RuntimeMBeanException
 Class
125
6.4.3.17
RuntimeErrorException
 Class
125
7.
MBean Server
127
7.1
Role of the MBean Server
127
10
Java Management Extensions Specification, version 1.4
•  November 9, 2006
7.1.1
MBean Server Factory
127
7.1.2
MBean Server Permission Checking
128
7.1.3
Registration of MBeans
129
7.1.3.1
MBean Registration Control
129
7.1.4
Operations on MBeans
131
7.1.5
MBean Proxies
132
7.2
MBean Server Delegate MBean
132
7.3
Remote Operations on MBeans
133
7.4
MBean Server Notifications
134
7.5
Queries
135
7.5.1
Scope of a Query
135
7.5.2
Query Expressions
136
7.5.2.1
Methods of the
Query
 Class
137
7.5.2.2
Query Expression Examples
139
7.5.3
Query Exceptions
139
7.5.3.1
BadAttributeValueExpException
 Class
140
7.5.3.2
BadStringOperationException
 Class
140
7.5.3.3
BadBinaryOpValueExpException
 Class
140
7.5.3.4
InvalidApplicationException
 Class
140
7.6
MBeanServerConnection Interface
140
7.7
Changing the MBean Server Implementation
141
8.
Advanced Dynamic Loading
143
8.1
Overview of M-Lets
143
8.2
The MLET Tag
144
8.3
The M-Let Service
146
8.3.1
Loading MBeans From a URL
146
8.3.2
Class Loader Functionality
147
8.3.2.1
Native libraries
147
8.4
The Class Loader Repository
148
8.4.1
How to Add Loaders to the Class Loader Repository
148
Chapter
Contents
11
8.4.2
Order of Loaders in the Class Loader Repository
149
8.4.3
M-Let Delegation to the Class Loader Repository
149
8.4.3.1
New Semantics in the JMX 1.2 Specification
150
8.5
Using the Correct Class Loader for Parameters
152
8.5.1
getClassLoaderFor
153
8.5.2
getClassLoader and getClassLoaderRepository
153
9.
Monitoring
155
9.1
Overview
155
9.1.1
Types of Monitors
155
9.2
MonitorNotification
 Class
156
9.2.1
Common Monitor Notification Types
157
9.3
CounterMonitor
 Class
158
9.3.1
Counter Monitor Notification Types
159
9.4
GaugeMonitor
 Class
160
9.4.1
Gauge Monitor Notification Types
161
9.5
StringMonitor
 Class
162
9.5.1
String Monitor Notification Types
163
9.6
Implementation of the Monitor MBeans
163
10.
Timer Service
165
10.1
Timer Notifications
165
10.1.1
TimerNotification
 Class
166
10.1.2
Adding Notifications to the Timer
166
10.1.3
Receiving Timer Notifications
167
10.1.4
Removing Notifications From the Timer
167
10.2
Starting and Stopping the Timer
168
11.
Relation Service
169
11.1
The Relation Model
169
11.1.1
Terminology
170
12
Java Management Extensions Specification, version 1.4
•  November 9, 2006
11.1.2
Example of a Relation
170
11.1.3
Maintaining Consistency
171
11.1.4
Implementation
172
11.1.4.1
External Relation Types
173
11.1.4.2
External Relations
174
11.2
Relation Service Classes
175
11.2.1
RelationService
 Class
177
11.2.2
RelationNotification
 Class
179
11.2.3
MBeanServerNotificationFilter
 Class
179
11.3
Interfaces and Support Classes
179
11.3.1
RelationType
 Interface
181
11.3.2
RelationTypeSupport
 Class
181
11.3.3
Relation
 Interface
182
11.3.3.1
Specified Methods
182
11.3.3.2
Maintaining Consistency
183
11.3.4
RelationSupport
 Class
184
11.4
Role Description Classes
184
11.4.1
RoleInfo
 Class
185
11.4.2
Role
 Class
186
11.4.3
RoleList
 Class
186
11.4.4
RoleUnresolved
 Class
187
11.4.5
RoleUnresolvedList
 Class
187
11.4.6
RoleResult
 Class
187
11.4.7
RoleStatus
 Class
188
12.
Security
189
12.1
Permissions
189
12.1.1
MBeanServerPermission
190
12.1.2
MBeanPermission
191
12.1.2.1
MBeanPermission Target
191
12.1.2.2
MBeanPermission Actions
193
Chapter
Contents
13
12.1.2.3
Unchecked MBean Server Methods
196
12.1.2.4
Permission Checking for Queries
196
12.1.2.5
Permission Checking for getDomains
197
12.1.2.6
Permission Checking for getAttributes and
setAttributes
198
12.1.3
MBeanTrustPermission
198
12.2
Policy File Examples
199
Part III.
JMX Remote API Specification
13.
Connectors
205
13.1
Sessions and Connections
206
13.2
Connection Establishment
206
13.3
MBean Server Operations Through a Connection
207
13.4
Adding Remote Listeners
208
13.4.1
Filters and Handbacks
208
13.4.2
Removing Listeners
209
13.4.3
Notification Buffer
210
13.4.4
Getting Notifications From the Notification Buffer
211
13.5
Concurrency
212
13.6
Normal Termination
212
13.7
Abnormal Termination
213
13.7.1
Detecting Abnormal Termination
213
13.8
Connector Server Addresses
214
13.9
Creating a Connector Client
214
13.9.1
JMXConnectorFactory
215
13.9.2
Connection Stubs
215
13.9.3
Finding a Server
216
13.10   Creating a Connector Server
216
13.10.1  Publishing a Server
218
13.11   Class Loading
218
14
Java Management Extensions Specification, version 1.4
•  November 9, 2006
13.11.1  Class Loading on the Client End
219
13.11.2  Class Loading on the Server End
219
13.12   Connector Server Security
221
13.12.1  Subject Delegation
222
13.12.2  Access Control Context
222
14.
RMI Connector
225
14.1
RMI Transports
225
14.2
Mechanics of the RMI Connector
225
14.2.1
Wrapping the RMI Objects
228
14.2.2
RMIConnection
228
14.2.3
Notifications
229
14.3
How to Connect to an RMI Connector Server
229
14.4
Basic Security With the RMI Connector
230
14.4.1
How Security Affects the RMI Connector Protocol
230
14.4.2
Achieving Real Security
231
14.5
Protocol Versioning
232
15.
Generic Connector
233
15.1
Pluggable Transport Protocol
233
15.2
Pluggable Object Wrapping
234
15.3
Generic Connector Protocol
235
15.3.1
Handshake and Profile Message Exchanges
236
15.3.2
MBean Server Operation and Connection Message Exchanges
239
15.3.3
Security Features in the JMXMP Connector
241
15.3.3.1
TLS Profile
242
15.3.3.2
SASL Profile
242
15.3.4
Protocol Violations
242
15.3.5
Protocol Versioning
243
15.3.6
Properties Controlling Client and Server
244
15.3.6.1
Global Properties of the Generic Connector
244
Chapter
Contents
15
15.3.6.2
TLS Properties
244
15.3.6.3
SASL Properties
245
16.
Defining a New Transport
247
17.
Bindings to Lookup Services
249
17.1
Terminology
249
17.2
General Principles
250
17.2.1
JMXServiceURL Versus JMXConnector Stubs
250
17.2.2
Lookup Attributes
251
17.3
Using the Service Location Protocol
254
17.3.1
SLP Implementation
254
17.3.2
SLP Service URL
254
17.3.3
SLP Lookup Attributes
254
17.3.4
Code Templates
254
17.3.4.1
Discovering the SLP Service
255
17.3.4.2
Registering a JMX Service URL With SLP
256
17.3.4.3
Looking up a JMX Service URL With SLP
257
17.4
Using the Jini Network Technology
258
17.4.1
Jini Networking Technology Implementation
258
17.4.2
Service Registration
258
17.4.3
Using JMX Remote API Connector Stubs
259
17.4.4
Jini Lookup Service Attributes
260
17.4.5
Code Templates
260
17.4.5.1
Discovering the Jini Lookup Service
261
17.4.5.2
Registering a JMX Remote API Connector Stub With the
Jini Lookup Service
262
17.4.5.3
Looking up a JMX Connector Stub From the Jini Lookup
Service
263
17.5
Using the Java Naming and Directory Interface (LDAP Backend)
264
17.5.1
LDAP Schema for Registration of JMX Connectors
265
17.5.2
Mapping to Java Objects
267
16
Java Management Extensions Specification, version 1.4
•  November 9, 2006
17.5.3
Structure of the JMX Remote API Registration Tree
267
17.5.4
Leasing
268
17.5.5
Code Templates
268
17.5.5.1
Discovering the LDAP Server
268
17.5.5.2
Registering a JMXServiceURL in the LDAP server
269
17.5.5.3
Looking up a JMX Service URL From the LDAP Server
271
17.6
Registration With Standards Bodies
272
18.
Summary of Environment Parameters
273
A.  Service Templates
277
A.1
Service Template for the service:jmx Abstract Service Type
277
A.2
Service Template for the service:jmx:jmxmp Concrete Service Type
279
A.3
Service Template for the service:jmx:rmi Concrete Service Type
280
A.4
Service Template for the service:jmx:iiop Concrete Service Type
282
B.  Non-standard environment parameters 285