Untitled :: Jolokia

Listing MBeans (list)

The list operation collects information about accessible MBeans. This information includes the MBean names, their attributes, operations and notifications along with type information and description (as far as they are provided by the MBean author which doesn’t seem to be often the case).

GET list request

The GET request format for a Jolokia list request is

<base-url>/list/<inner path>

The <inner path>, as described in Paths specifies a subset of the complete response. You can use this to select a specific domain, MBean or attribute/operation. See the next section for the format of the complete response.

POST list request

A list POST request has the following keys:

Table 1. POST list Request
Key	Description	Example
`type`	`list`
`path`	Inner path for accessing the value of a subset of the complete list Paths).	`java.lang/type=Memory/attr`

The following request fetches the information about the MBean java.lang:type=Memory

{
  "type": "list",
  "path": "java.lang/type=Memory"
}

List response

The value has the following format:

{
  "<domain>": {
    "<prop list>": {
      "attr": {
        "<attr name>": {
          "type": "<attribute type>",
          "desc": "<textual description of attribute>",
          "rw": "true|false"
        },
        ...
      },
      "op": {
        "<operation name>": {
          "args": [
            {
              "type": "<argument type>",
              "name": "<argument name>",
              "desc": "<textual description of argument>"
            },
            ...
          ],
          "ret": "<return type>",
          "desc": "<textual description of operation>"
        },
        ...
      },
      "notif": {
        "<notification type>": {
            "name": "<name>",
            "desc": "<desc>",
            "types": [ "<type1>", "<type2>", ... ]
        },
        ...
      }
    },
    ...
  },
  ...
}

The domain name and the property list together uniquely identify a single MBean. The property list is in the so called canonical order, i.e. in the form "<key1>=<val1>,<key2>=<val2>,.." where the keys are ordered alphabetically. Each MBean has zero or more attributes and operations which can be reached in an MBeans JSON object with the keys attr and op respectively. Within these groups the contained information is explained above in the schema and consist of Java types for attributes, arguments and return values, descriptive information and whether an attribute is writable (rw == true) or read-only.

As for reading attributes you can fetch a subset of this information using an path. E.g a path of domain/prop-list would return the value for a single bean only. For example, a request

http://localhost:8080/jolokia/list/java.lang/type=Memory

results in an answer

{
  "request": {
    "path": "java.lang/type=Memory",
    "type": "list"
  },
  "value": {
    "op": {
      "gc": {
        "args": [],
        "ret": "void",
        "desc": "gc"
      }
    },
    "notif": {
      "javax.management.Notification": {
        "types": [
          "java.management.memory.threshold.exceeded",
          "java.management.memory.collection.threshold.exceeded"
        ],
        "name": "javax.management.Notification",
        "desc": "Memory Notification"
      }
    },
    "attr": {
      "ObjectPendingFinalizationCount": {
        "rw": false,
        "type": "int",
        "desc": "ObjectPendingFinalizationCount"
      },
      "Verbose": {
        "rw": true,
        "type": "boolean",
        "desc": "Verbose"
      },
      "HeapMemoryUsage": {
        "rw": false,
        "type": "javax.management.openmbean.CompositeData",
        "desc": "HeapMemoryUsage"
      },
      "NonHeapMemoryUsage": {
        "rw": false,
        "type": "javax.management.openmbean.CompositeData",
        "desc": "NonHeapMemoryUsage"
      },
      "ObjectName": {
        "rw": false,
        "type": "javax.management.ObjectName",
        "desc": "ObjectName"
      }
    },
    "class": "sun.management.MemoryImpl",
    "desc": "Information on the management interface of the MBean"
  },
  "status": 200,
  "timestamp": 1702463340
}

NOTE: Since Jolokia 2.1.0 we can use includeRequest parameter to tell Jolokia to exclude request field from the response.

Restrict depth of the returned tree

The optional parameter maxDepth can be used to restrict the depth of the return tree. Two value are possible: A maxDepth of 1 restricts the return value to a map with the JMX domains as keys, a maxDepth of 2 truncates the map returned to the domain names (first level) and the MBean’s properties (second level). The final values of the maps don’t have any meaning and are dummy values.

Extension points

When returning list() results, Jolokia translates each MBean’s javax.management.MBeanInfo information into a JSON fragment. Standard fields of this fragment are:

class
desc
attr
op
notif

These fields are added by default, built-in implementations of org.jolokia.service.jmx.handler.list.DataUpdater.

Since Jolokia 2.1.0 we can now discover (using /META-INF/jolokia/services) additional services of org.jolokia.service.jmx.handler.list.DataUpdater class which can be used to construct (or override) additional fields of MBean’s JSON information.
Potential use-case may be information related to RBAC (Role-based Access Control).

One additional built-in data updater is org.jolokia.service.jmx.handler.list.ListKeysDataUpdater which can be enabled using listKeys=true processing parameter. We can use it to get additional "keys" MBeanInfo containing keys obtained from MBean’s ObjectName. For example:

{
  "request": {
    "path": "java.lang",
    "type": "list"
  },
  "value": {
    "name=G1 Survivor Space,type=MemoryPool": {
      "op": {
        "resetPeakUsage": {
          "args": [],
          "ret": "void",
          "desc": "resetPeakUsage"
        }
      },
      "keys": {
        "name": "G1 Survivor Space",
        "type": "MemoryPool"
      },
...

Optimized List response

Since Jolokia 2.1.0 we provide now listCache request processing parameter. When this parameter is set to true (it’s false for backward compatibility), list() response has different format - instead of a structure like:

domain:
  mbean:
    op:
    attr:
    notif:
    class:
    desc:
  ...
...

we now have:

"domains":
  domain:
    mbean: cache-key
    ...
  ...
"cache":
  cache-key:
    op:
    attr:
    notif:
    class:
    desc:
  ...

Effectively:

domain → mbean tree is moved 1 level down under "domains" field of list() response
mbean may contain known op, attr, … fields, but may also be just a cache key pointing to op, attr, … data stored under this key under "cache" field of list() response
the cache keys are generated by org.jolokia.service.jmx.api.CacheKeyProvider services/extensions