////
  Copyright 2009-2023 Roland Huss

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
////

[#exec]
=== Executing JMX operations (exec)

With Jolokia we can also execute exposed JMX
operations with optional arguments. Just as when writing
attributes, Jolokia must be able to serialize the operation arguments. See
xref:jolokia_protocol.adoc#serialization[Object serialization] for details. Execution of
overloaded methods is supported. The JMX specifications recommends
to avoid overloaded methods when exposing them via JMX, though.

[#get-exec]
==== GET exec request

The format of an GET exec request is
----
<base url>/exec/<mbean name>/<operation name>/<arg1>/<arg2>/....
----

.GET Exec Request
[cols="15,~,30"]
|===
|Part|Description|Example

|`<mbean name>`
|MBean's ObjectName
|`java.lang:type=Threading`

|`<operation name>`
|Name of the operation to execute. If this is an overloaded method,
it is mandatory to provide a method signature as
well. A signature consist the fully qualified argument class
names or native types, separated by commas and enclosed with
parentheses. For calling a non-argument overloaded method use `()`
as signature.
|`loadUsers(java.lang.String, int)`

|`<arg1>`, `<arg2>`, `...`
|String representation for the arguments required to execute this
operation. Only certain data types can be used here as
described in xref:jolokia_protocol.adoc#serialization-request[Request parameter serialization].
|`/true/true/`
|===

The following request will trigger a garbage collection:
----
http://localhost:8080/jolokia/exec/java.lang:type=Memory/gc
----

[#post-exec]
==== POST exec request

.POST Exec Request
[cols="15,~,30"]
|===
|Key|Description|Example

|`type`
|*`exec`*
|

|`mbean`
|MBean's ObjectName
|`java.lang:type=Threading`

|`operation`
|The operation to execute, optionally with a signature as
described above.
|`dumpAllThreads`

|`arguments`
|An array of arguments for invoking this operation. The value must be serializable as described in
xref:jolokia_protocol.adoc#serialization-request[Request parameter serialization].
|`[true, true]`
|===

The following request dumps all threads (along with locked
monitors and locked synchronizers, thats what the boolean
arguments are for):

[,json]
----
{
  "type": "exec",
  "mbean": "java.lang:type=Threading",
  "operation": "dumpAllThreads(boolean, boolean)",
  "arguments": [ true, true ]
}
----

[#response-exec]
==== Exec response

For an `exec` operation, the response
contains the return value of the
operation. `null` is returned if either the
operation returns a null value or the operation is declared as
void. A typical response for an URL like (mind that double quote (`"`) has to be encoded with `%22`):
----
http://localhost:8080/jolokia/exec/java.util.logging:type=Logging/setLoggerLevel/%22%22/INFO
----

looks like

[,json]
----
{
  "request": {
    "mbean": "java.util.logging:type=Logging",
    "arguments": [
      "",
      "INFO"
    ],
    "type": "exec",
    "operation": "setLoggerLevel"
  },
  "value": null,
  "status": 200,
  "timestamp": 1702456520
}
----

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

The return value get serialized as described in xref:jolokia_protocol.adoc#serialization-request[Request parameter serialization].
