From e8de069e00b2d887bdd5d28e21b3fe1d6ece1798 Mon Sep 17 00:00:00 2001 From: Ivo Smid Date: Thu, 20 Aug 2020 20:18:53 +0200 Subject: [PATCH 1/2] Add example of custom Actuator operations See gh-23028 --- .../src/main/asciidoc/production-ready-features.adoc | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc index d838974353..86166dc432 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc @@ -475,7 +475,15 @@ Consider the following JSON request body: } ---- -This can be used to invoke a write operation that takes `String name` and `int counter` parameters. +This can be used to invoke a write operation that takes `String name` and `int counter` parameters (name of Java parameter have to match name of JSON property). + +[source,java,indent=0] +---- + @WriteOperation + public void writeMethod(String name, int counter) { + // do the stuff + } +---- TIP: Because endpoints are technology agnostic, only simple types can be specified in the method signature. In particular declaring a single parameter with a custom type defining a `name` and `counter` properties is not supported. From f1455b156a2d84dcfaae14289f9c56cef4f85fb8 Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Mon, 24 Aug 2020 11:56:31 +0200 Subject: [PATCH 2/2] Polish "Add example of custom Actuator operations" See gh-23028 --- .../asciidoc/production-ready-features.adoc | 16 +++-- .../endpoint/CustomEndpointExample.java | 58 +++++++++++++++++++ 2 files changed, 68 insertions(+), 6 deletions(-) create mode 100644 spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuate/endpoint/CustomEndpointExample.java diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc index 86166dc432..ad014ab9e5 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc @@ -445,6 +445,13 @@ If you add a `@Bean` annotated with `@Endpoint`, any methods annotated with `@Re Endpoints can be exposed over HTTP using Jersey, Spring MVC, or Spring WebFlux. If both Jersey and Spring MVC are available, Spring MVC will be used. +The following example exposes a read operation that returns a custom object: + +[source,java,indent=0] +---- +include::{code-examples}/actuate/endpoint/CustomEndpointExample.java[tag=read] +---- + You can also write technology-specific endpoints by using `@JmxEndpoint` or `@WebEndpoint`. These endpoints are restricted to their respective technologies. For example, `@WebEndpoint` is exposed only over HTTP and not over JMX. @@ -475,18 +482,15 @@ Consider the following JSON request body: } ---- -This can be used to invoke a write operation that takes `String name` and `int counter` parameters (name of Java parameter have to match name of JSON property). +This can be used to invoke a write operation that takes `String name` and `int counter` parameters, as shown in the following example: [source,java,indent=0] ---- - @WriteOperation - public void writeMethod(String name, int counter) { - // do the stuff - } +include::{code-examples}/actuate/endpoint/CustomEndpointExample.java[tag=write] ---- TIP: Because endpoints are technology agnostic, only simple types can be specified in the method signature. -In particular declaring a single parameter with a custom type defining a `name` and `counter` properties is not supported. +In particular declaring a single parameter with a `CustomData` type defining a `name` and `counter` properties is not supported. NOTE: To allow the input to be mapped to the operation method's parameters, Java code implementing an endpoint should be compiled with `-parameters`, and Kotlin code implementing an endpoint should be compiled with `-java-parameters`. This will happen automatically if you are using Spring Boot's Gradle plugin or if you are using Maven and `spring-boot-starter-parent`. diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuate/endpoint/CustomEndpointExample.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuate/endpoint/CustomEndpointExample.java new file mode 100644 index 0000000000..78674d700c --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuate/endpoint/CustomEndpointExample.java @@ -0,0 +1,58 @@ +/* + * Copyright 2012-2020 the original author or authors. + * + * 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 + * + * https://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. + */ + +package org.springframework.boot.docs.actuate.endpoint; + +import org.springframework.boot.actuate.endpoint.annotation.Endpoint; +import org.springframework.boot.actuate.endpoint.annotation.ReadOperation; +import org.springframework.boot.actuate.endpoint.annotation.WriteOperation; + +/** + * An example of a custom actuator endpoint. + * + * @author Stephane Nicoll + */ +@Endpoint(id = "custom") +public class CustomEndpointExample { + + // tag::read[] + @ReadOperation + public CustomData getCustomData() { + return new CustomData("test", 5); + } + // end::read[] + + // tag::write[] + @WriteOperation + public void updateCustomData(String name, int counter) { + // injects "test" and 42 + } + // end::write[] + + public static class CustomData { + + private final String name; + + private final int counter; + + public CustomData(String name, int counter) { + this.name = name; + this.counter = counter; + } + + } + +}