Skip to content

Commit d595005

Browse files
grgrzybekgrgrzybek
committed
[Fixes #916] Update documentation - Jolokia protocol 8.2
1 parent e15861f commit d595005

7 files changed

Lines changed: 492 additions & 496 deletions

File tree

‎pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1171,7 +1171,7 @@
11711171
<!-- A version used in documentation -->
11721172
<currentStableVersion>2.4.2</currentStableVersion>
11731173
<!-- Jolokia protocol version -->
1174-
<protocolVersion>8.1</protocolVersion>
1174+
<protocolVersion>8.2</protocolVersion>
11751175

11761176
<!--
11771177
Versions are specified in one place, so updates can be discovered with single command:

‎src/documentation/manual/modules/ROOT/pages/clients.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Three client implementations exists for Jolokia: Jmx4Perl, the
2020
Perl binding (the grandmother of all clients ;-), a Java library
2121
and a JavaScript library. This reference describes the client
2222
bindings bundled with Jolokia. Information about Jmx4Perl can be found
23-
https://metacpan.org/dist/jmx4perl[elsewhere,role=externalLink,window=_blank,window=_blank].
23+
https://metacpan.org/dist/jmx4perl[elsewhere,role=externalLink,window=_blank].
2424
2525
include::client/javascript.adoc[]
2626
include::client/java.adoc[]

‎src/documentation/manual/modules/ROOT/pages/jolokia_protocol.adoc‎

Lines changed: 280 additions & 454 deletions
Large diffs are not rendered by default.

‎src/documentation/manual/modules/ROOT/pages/protocol/config.adoc‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
////
2+
Copyright 2009-2026 Roland Huss
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
////
16+
17+
[#version]
18+
=== Getting the basic configuration (config)
19+
20+
The Jolokia command `config` is provided to get unauthenticated information about the agent.
21+
It duplicates (a bit) the information from the `version` operation, but is meant to be more universal and generic.
22+
23+
It serves similar purpose as `/.well-known/openid-configuration` endpoint for OpenID Connect providers.
24+
25+
[#get-version]
26+
==== GET version request
27+
28+
The GET URL for a config request has the following format:
29+
30+
----
31+
<base-url>/config
32+
----
33+
34+
[#post-version]
35+
==== POST version request
36+
37+
A version POST request has only a single key
38+
`type` which has to be set to
39+
*`config`*.
40+
41+
However, GET requests are preferred for `config` operation. The reason is that it's easier to configure restricted
42+
access in Servlet applications for GET requests (and remove the constraints for one specific URI). See https://jakarta.ee/specifications/servlet/5.0/jakarta-servlet-spec-5.0#security[Security chapter,role=externalLink,window=_blank]
43+
of Java Servlet API specification.
44+
45+
[#response-version]
46+
==== Config response
47+
48+
The response value for a `config` request looks like this:
49+
50+
[,json,subs="attributes,verbatim"]
51+
----
52+
{
53+
"request": {
54+
"type": "config"
55+
},
56+
"value": {
57+
"agent": "2.5.0-SNAPSHOT",
58+
"protocol": "8.1",
59+
"security": {
60+
"authentication": [
61+
{
62+
"method": "basic",
63+
"realm": "jolokia"
64+
}
65+
]
66+
},
67+
"id": "jolokia-7778"
68+
},
69+
"status": 200,
70+
"timestamp": 1770641830
71+
}
72+
73+
----
74+
75+
Jolokia only returns information for:
76+
77+
* agent version
78+
* protocol version
79+
* security mechanisms used (could be `basic` authentication or `mtls`)

‎src/documentation/manual/modules/ROOT/pages/protocol/list.adoc‎

Lines changed: 110 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
[#list]
1818
=== Listing MBeans (list)
1919
20-
The list operation collects information about accessible
20+
The list operation collects information about available
2121
MBeans. This information includes the MBean names, their
2222
attributes, operations and notifications along with type
2323
information and description (as far as they are provided by the
@@ -109,7 +109,15 @@ The `value` has the following format:
109109
"types": [ "<type1>", "<type2>", ... ]
110110
},
111111
...
112-
}
112+
},
113+
"class": "fully qualified class name",
114+
"desc": "description",
115+
"ctor": {
116+
...
117+
},
118+
"interfaces": [
119+
...
120+
]
113121
},
114122
...
115123
},
@@ -169,27 +177,42 @@ results in an answer
169177
},
170178
"attr": {
171179
"ObjectPendingFinalizationCount": {
180+
"r": true,
172181
"rw": false,
182+
"w": false,
183+
"is": false,
173184
"type": "int",
174185
"desc": "ObjectPendingFinalizationCount"
175186
},
176187
"Verbose": {
188+
"r": true,
177189
"rw": true,
190+
"w": true,
191+
"is": true,
178192
"type": "boolean",
179193
"desc": "Verbose"
180194
},
181195
"HeapMemoryUsage": {
196+
"r": true,
182197
"rw": false,
198+
"w": false,
199+
"is": false,
183200
"type": "javax.management.openmbean.CompositeData",
184201
"desc": "HeapMemoryUsage"
185202
},
186203
"NonHeapMemoryUsage": {
204+
"r": true,
187205
"rw": false,
206+
"w": false,
207+
"is": false,
188208
"type": "javax.management.openmbean.CompositeData",
189209
"desc": "NonHeapMemoryUsage"
190210
},
191211
"ObjectName": {
212+
"r": true,
192213
"rw": false,
214+
"w": false,
215+
"is": false,
193216
"type": "javax.management.ObjectName",
194217
"desc": "ObjectName"
195218
}
@@ -198,13 +221,13 @@ results in an answer
198221
"desc": "Information on the management interface of the MBean"
199222
},
200223
"status": 200,
201-
"timestamp": 1702463340
224+
"timestamp": 1770643662
202225
}
203226
----
204227
205228
NOTE:: Since Jolokia 2.1.0 we can use `includeRequest` parameter to tell Jolokia to exclude `request` field from the response.
206229
207-
==== Restrict depth of the returned tree
230+
==== Restrict the depth of the returned tree
208231
209232
The optional parameter `maxDepth` can be used
210233
to restrict the depth of the return tree. Two value are
@@ -219,11 +242,12 @@ meaning and are dummy values.
219242
220243
When returning `list()` results, Jolokia translates each MBean's `javax.management.MBeanInfo` information into a JSON fragment. Standard fields of this fragment are:
221244
222-
* `class`
223-
* `desc`
224-
* `attr`
225-
* `op`
226-
* `notif`
245+
* `class` - information about the class of an MBean
246+
* `desc` - the description
247+
* `attr` - attributes of an MBean
248+
* `op` - operations of an MBean
249+
* `notif` - notifications supported by an MBean
250+
* `ctor` - constructors of an MBean
227251
228252
These fields are added by default, built-in implementations of `org.jolokia.server.core.service.api.DataUpdater`.
229253
@@ -241,20 +265,90 @@ One additional built-in _data updater_ is `org.jolokia.service.jmx.handler.list.
241265
},
242266
"value": {
243267
"name=G1 Survivor Space,type=MemoryPool": {
244-
"op": {
245-
"resetPeakUsage": {
246-
"args": [],
247-
"ret": "void",
248-
"desc": "resetPeakUsage"
249-
}
250-
},
268+
...
251269
"keys": {
252270
"name": "G1 Survivor Space",
253271
"type": "MemoryPool"
254272
},
255273
...
256274
----
257275
276+
Since Jolokia 2.5.0, we can use `listInterfaces=true` parameter to get information about the interfaces implemented by an MBean:
277+
278+
[,json]
279+
----
280+
{
281+
"request": {
282+
"path": "java.lang/type=Memory",
283+
"type": "list"
284+
},
285+
"value": {
286+
...
287+
"interfaces": [
288+
"javax.management.NotificationEmitter",
289+
"java.lang.management.PlatformManagedObject",
290+
"javax.management.NotificationBroadcaster",
291+
"java.lang.management.MemoryMXBean"
292+
],
293+
...
294+
----
295+
296+
Another big addition to Jolokia 2.5.0 is new processing parameter. When sending `openTypes=true`, we get full information about
297+
the composite/tabular Open Types used by the MBean (attributes or method parameters and return values). For example:
298+
299+
[,json]
300+
----
301+
{
302+
"request": {
303+
"path": "java.lang/type=Memory",
304+
"type": "list"
305+
},
306+
"value": {
307+
...
308+
"attr": {
309+
"ObjectPendingFinalizationCount": {
310+
"r": true,
311+
"rw": false,
312+
"w": false,
313+
"is": false,
314+
"type": "int",
315+
"desc": "ObjectPendingFinalizationCount",
316+
"openType": "java.lang.Integer"
317+
},
318+
"Verbose": {
319+
"r": true,
320+
"rw": true,
321+
"w": true,
322+
"is": true,
323+
"type": "boolean",
324+
"desc": "Verbose",
325+
"openType": "java.lang.Boolean"
326+
},
327+
"HeapMemoryUsage": {
328+
"r": true,
329+
"rw": false,
330+
"w": false,
331+
"is": false,
332+
"type": "javax.management.openmbean.CompositeData",
333+
"desc": "HeapMemoryUsage",
334+
"openType": {
335+
"kind": "composite",
336+
"type": "java.lang.management.MemoryUsage",
337+
"class": "javax.management.openmbean.CompositeData",
338+
"items": {
339+
"init": "java.lang.Long",
340+
"committed": "java.lang.Long",
341+
"max": "java.lang.Long",
342+
"used": "java.lang.Long"
343+
},
344+
"desc": "java.lang.management.MemoryUsage"
345+
}
346+
},
347+
...
348+
----
349+
350+
In the above example, we can see the actual type structure of `HeapMemoryUsage` attribute.
351+
258352
[#optimized-response-list]
259353
==== Optimized List response
260354

‎src/documentation/manual/modules/ROOT/pages/protocol/notification.adoc‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
////
1616
1717
[#notification]
18-
=== Using JMX notifications (notification) #new in Jolokia 2#
18+
=== Using JMX notifications (notification)
1919
2020
A new feature of Jolokia 2 is access to https://docs.oracle.com/en/java/javase/11/docs/api/java.management/javax/management/Notification.html[JMX notifications,role=externalLink,window=_blank].
2121
While reading/writing attributes, executing operations or listing/searching MBeans is implemented as single request-response operation, with notifications the flow of messages is more complex.
@@ -38,7 +38,7 @@ The GET URL for client registration has the following format:
3838
<base-url>/notification/register
3939
----
4040
41-
The equivalend POST JSON payload is:
41+
The equivalent POST JSON payload is:
4242
4343
[,json]
4444
----
@@ -110,7 +110,7 @@ The GET URL for client registration has the following format:
110110
|`d77475dc-c7a7-4f71-b988-52b7f0252ca3`
111111
|===
112112
113-
The equivalend POST JSON payload is:
113+
The equivalent POST JSON payload is:
114114
115115
[,json]
116116
----
@@ -304,7 +304,7 @@ The GET URL for listing client listener registrations has the following format:
304304
|`d77475dc-c7a7-4f71-b988-52b7f0252ca3`
305305
|===
306306
307-
The equivalend POST JSON payload is:
307+
The equivalent POST JSON payload is:
308308
309309
[,json]
310310
----
@@ -387,7 +387,7 @@ The GET URL for removing client listener registrations has the following format:
387387
|`1`
388388
|===
389389
390-
The equivalend POST JSON payload is:
390+
The equivalent POST JSON payload is:
391391
392392
[,json]
393393
----
@@ -526,7 +526,7 @@ Instead of providing us with Mbean name to access when needed (_pull_ the notifi
526526
527527
When calling `open` command for `sse` backed notifications, the request (`HttpServletRequest`) is put into https://jakarta.ee/specifications/servlet/5.0/jakarta-servlet-spec-5.0#asynchronous-processing[asynchronous mode,role=externalLink,window=_blank] and connection is not closed.
528528
529-
The GET URL for openning a backend channel for notification acces is:
529+
The GET URL for opening a backend channel for notification access is:
530530
531531
----
532532
<base-url>/notification/open/<client-id>/<mode>
@@ -546,7 +546,7 @@ The GET URL for openning a backend channel for notification acces is:
546546
|`sse`
547547
|===
548548
549-
The equivalend POST JSON payload is:
549+
The equivalent POST JSON payload is:
550550
551551
[,json]
552552
----

0 commit comments

Comments
 (0)