Polish "Add Quartz actuator endpoint"

See spring-projectsgh-10364

Author: snicoll

spring-boot-project/spring-boot-actuator-autoconfigure/src/docs/asciidoc/endpoints/quartz.adoc

@@ -0,0 +1,42 @@
+[[quartz]]
+= Quartz (`quartz`)
+
+The `quartz` endpoint provides information about scheduled jobs that are managed by the Quartz Scheduler.
+
+
+
+[[quartz-retrieving]]
+== Retrieving Quartz Jobs
+
+To retrieve the registered jobs, make a `GET` request to `/actuator/quartz`, as shown in the following curl-based example:
+
+include::{snippets}/quartz/report/curl-request.adoc[]
+
+The resulting response is similar to the following:
+
+include::{snippets}/quartz/report/http-response.adoc[]
+
+
+
+[[quartz-job]]
+== Retrieving the Quartz job details
+
+To retrieve the details about a particular job, make a `GET` request to `/actuator/quartz/\{group}/\{name}`, as shown in the following curl-based example:
+
+include::{snippets}/quartz/job/curl-request.adoc[]
+
+The preceding example retrieves the job with the `group` of `groupOne` and `name` of `jobOne`.
+The resulting response is similar to the following:
+
+include::{snippets}/quartz/job/http-response.adoc[]
+
+
+
+[[quartz-job-response-structure]]
+=== Response Structure
+
+The response contains details of the scheduled job.
+The following table describes the structure of the response:
+
+[cols="2,1,3"]
+include::{snippets}/quartz/job/response-fields.adoc[]

spring-boot-project/spring-boot-actuator-autoconfigure/src/main/asciidoc/endpoints/quartz.adoc

@@ -1,11 +1,11 @@
 /*
- * Copyright 2012-2017 the original author or authors.
+ * Copyright 2012-2021 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
  *
- *      http://www.apache.org/licenses/LICENSE-2.0
+ *      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,
@@ -20,6 +20,7 @@
 
 import org.springframework.boot.actuate.autoconfigure.endpoint.condition.ConditionalOnAvailableEndpoint;
 import org.springframework.boot.actuate.quartz.QuartzEndpoint;
+import org.springframework.boot.actuate.quartz.QuartzEndpointWebExtension;
 import org.springframework.boot.autoconfigure.AutoConfigureAfter;
 import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
@@ -35,7 +36,7 @@
  * @author Vedran Pavic
  * @since 2.0.0
  */
-@Configuration
+@Configuration(proxyBeanMethods = false)
 @ConditionalOnClass(Scheduler.class)
 @AutoConfigureAfter(QuartzAutoConfiguration.class)
 @ConditionalOnAvailableEndpoint(endpoint = QuartzEndpoint.class)
@@ -48,4 +49,11 @@ public QuartzEndpoint quartzEndpoint(Scheduler scheduler) {
 		return new QuartzEndpoint(scheduler);
 	}
 
+	@Bean
+	@ConditionalOnBean(QuartzEndpoint.class)
+	@ConditionalOnMissingBean
+	public QuartzEndpointWebExtension quartzEndpointWebExtension(QuartzEndpoint endpoint) {
+		return new QuartzEndpointWebExtension(endpoint);
+	}
+
 }

spring-boot-project/spring-boot-actuator-autoconfigure/src/main/java/org/springframework/boot/actuate/autoconfigure/quartz/QuartzEndpointAutoConfiguration.java

@@ -1,11 +1,11 @@
 /*
- * Copyright 2012-2017 the original author or authors.
+ * Copyright 2012-2021 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
  *
- *      http://www.apache.org/licenses/LICENSE-2.0
+ *      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,

spring-boot-project/spring-boot-actuator-autoconfigure/src/main/java/org/springframework/boot/actuate/autoconfigure/quartz/package-info.java

@@ -1,11 +1,11 @@
 /*
- * Copyright 2012-2017 the original author or authors.
+ * Copyright 2012-2021 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
  *
- *      http://www.apache.org/licenses/LICENSE-2.0
+ *      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,
@@ -23,7 +23,7 @@
 import java.util.HashSet;
 import java.util.regex.Pattern;
 
-import org.junit.Test;
+import org.junit.jupiter.api.Test;
 import org.quartz.Job;
 import org.quartz.JobBuilder;
 import org.quartz.JobDetail;
@@ -35,6 +35,7 @@
 import org.quartz.impl.matchers.GroupMatcher;
 
 import org.springframework.boot.actuate.quartz.QuartzEndpoint;
+import org.springframework.boot.actuate.quartz.QuartzEndpointWebExtension;
 import org.springframework.boot.test.mock.mockito.MockBean;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
@@ -54,7 +55,7 @@
  *
  * @author Vedran Pavic
  */
-public class QuartzEndpointDocumentationTests extends MockMvcEndpointDocumentationTests {
+class QuartzEndpointDocumentationTests extends MockMvcEndpointDocumentationTests {
 
 	private static final JobDetail jobOne = JobBuilder.newJob(Job.class).withIdentity("jobOne", "groupOne")
 			.withDescription("My first job").build();
@@ -79,50 +80,59 @@ public class QuartzEndpointDocumentationTests extends MockMvcEndpointDocumentati
 	private Scheduler scheduler;
 
 	@Test
-	public void quartzReport() throws Exception {
+	void quartzReport() throws Exception {
 		String groupOne = jobOne.getKey().getGroup();
 		String groupTwo = jobThree.getKey().getGroup();
 		given(this.scheduler.getJobGroupNames()).willReturn(Arrays.asList(groupOne, groupTwo));
 		given(this.scheduler.getJobKeys(GroupMatcher.jobGroupEquals(groupOne)))
 				.willReturn(new HashSet<>(Arrays.asList(jobOne.getKey(), jobTwo.getKey())));
 		given(this.scheduler.getJobKeys(GroupMatcher.jobGroupEquals(groupTwo)))
 				.willReturn(Collections.singleton(jobThree.getKey()));
-		this.mockMvc.perform(get("/application/quartz")).andExpect(status().isOk()).andDo(document("quartz/report"));
+		this.mockMvc.perform(get("/actuator/quartz")).andExpect(status().isOk()).andDo(document("quartz/report"));
 	}
 
 	@Test
-	public void quartzJob() throws Exception {
+	void quartzJob() throws Exception {
 		JobKey jobKey = jobOne.getKey();
 		given(this.scheduler.getJobDetail(jobKey)).willReturn(jobOne);
-		given(this.scheduler.getTriggersOfJob(jobKey)).willAnswer(invocation -> Arrays.asList(triggerOne, triggerTwo));
-		this.mockMvc.perform(get("/application/quartz/groupOne/jobOne")).andExpect(status().isOk()).andDo(document(
+		given(this.scheduler.getTriggersOfJob(jobKey))
+				.willAnswer((invocation) -> Arrays.asList(triggerOne, triggerTwo));
+		this.mockMvc.perform(get("/actuator/quartz/jobs/groupOne/jobOne")).andExpect(status().isOk()).andDo(document(
 				"quartz/job",
 				preprocessResponse(replacePattern(Pattern.compile("org.quartz.Job"), "com.example.MyJob")),
-				responseFields(fieldWithPath("jobGroup").description("Job group."),
-						fieldWithPath("jobName").description("Job name."),
-						fieldWithPath("description").description("Job description, if any."),
+				responseFields(fieldWithPath("group").description("Job group."),
+						fieldWithPath("name").description("Job name."),
+						fieldWithPath("description").description("Job description, if any.").optional(),
 						fieldWithPath("className").description("Job class."),
-						fieldWithPath("triggers.[].triggerGroup").description("Trigger group."),
-						fieldWithPath("triggers.[].triggerName").description("Trigger name."),
-						fieldWithPath("triggers.[].description").description("Trigger description, if any."),
-						fieldWithPath("triggers.[].calendarName").description("Trigger's calendar name, if any."),
+						fieldWithPath("triggers.[].group").description("Trigger group."),
+						fieldWithPath("triggers.[].name").description("Trigger name."),
+						fieldWithPath("triggers.[].description").description("Trigger description, if any.").optional(),
+						fieldWithPath("triggers.[].calendarName").description("Trigger's calendar name, if any.")
+								.optional(),
 						fieldWithPath("triggers.[].startTime").description("Trigger's start time."),
 						fieldWithPath("triggers.[].endTime").description("Trigger's end time."),
-						fieldWithPath("triggers.[].nextFireTime").description("Trigger's next fire time."),
-						fieldWithPath("triggers.[].previousFireTime")
-								.description("Trigger's previous fire time, if any."),
-						fieldWithPath("triggers.[].finalFireTime").description("Trigger's final fire time, if any."))));
+						fieldWithPath("triggers.[].nextFireTime").type(Date.class)
+								.description("Trigger's next fire time, if any.").optional(),
+						fieldWithPath("triggers.[].previousFireTime").type(Date.class)
+								.description("Trigger's previous fire time, if any.").optional(),
+						fieldWithPath("triggers.[].finalFireTime").type(Date.class)
+								.description("Trigger's final fire time, if any.").optional())));
 	}
 
-	@Configuration
+	@Configuration(proxyBeanMethods = false)
 	@Import(BaseDocumentationConfiguration.class)
 	static class TestConfiguration {
 
 		@Bean
-		public QuartzEndpoint endpoint(Scheduler scheduler) {
+		QuartzEndpoint endpoint(Scheduler scheduler) {
 			return new QuartzEndpoint(scheduler);
 		}
 
+		@Bean
+		QuartzEndpointWebExtension endpointWebExtension(QuartzEndpoint endpoint) {
+			return new QuartzEndpointWebExtension(endpoint);
+		}
+
 	}
 
 }

spring-boot-project/spring-boot-actuator-autoconfigure/src/test/java/org/springframework/boot/actuate/autoconfigure/endpoint/web/documentation/QuartzEndpointDocumentationTests.java

@@ -1,11 +1,11 @@
 /*
- * Copyright 2012-2017 the original author or authors.
+ * Copyright 2012-2021 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
  *
- *      http://www.apache.org/licenses/LICENSE-2.0
+ *      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,
@@ -16,7 +16,7 @@
 
 package org.springframework.boot.actuate.autoconfigure.quartz;
 
-import org.junit.Test;
+import org.junit.jupiter.api.Test;
 import org.quartz.Scheduler;
 
 import org.springframework.boot.actuate.quartz.QuartzEndpoint;
@@ -32,30 +32,59 @@
  * Tests for {@link QuartzEndpointAutoConfiguration}.
  *
  * @author Vedran Pavic
+ * @author Stephane Nicoll
  */
-public class QuartzEndpointAutoConfigurationTests {
+class QuartzEndpointAutoConfigurationTests {
 
 	private final ApplicationContextRunner contextRunner = new ApplicationContextRunner()
-			.withConfiguration(AutoConfigurations.of(QuartzEndpointAutoConfiguration.class))
-			.withUserConfiguration(QuartzConfiguration.class);
+			.withConfiguration(AutoConfigurations.of(QuartzEndpointAutoConfiguration.class));
 
 	@Test
-	public void runShouldHaveEndpointBean() {
-		this.contextRunner.run((context) -> assertThat(context).hasSingleBean(QuartzEndpoint.class));
+	void endpointIsAutoConfigured() {
+		this.contextRunner.withBean(Scheduler.class, () -> mock(Scheduler.class))
+				.withPropertyValues("management.endpoints.web.exposure.include=quartz")
+				.run((context) -> assertThat(context).hasSingleBean(QuartzEndpoint.class));
 	}
 
 	@Test
-	public void runWhenEnabledPropertyIsFalseShouldNotHaveEndpointBean() throws Exception {
-		this.contextRunner.withPropertyValues("management.endpoint.quartz.enabled:false")
+	void endpointIsNotAutoConfiguredIfSchedulerIsNotAvailable() {
+		this.contextRunner.withPropertyValues("management.endpoints.web.exposure.include=quartz")
 				.run((context) -> assertThat(context).doesNotHaveBean(QuartzEndpoint.class));
 	}
 
-	@Configuration
-	static class QuartzConfiguration {
+	@Test
+	void endpointNotAutoConfiguredWhenNotExposed() {
+		this.contextRunner.withBean(Scheduler.class, () -> mock(Scheduler.class))
+				.run((context) -> assertThat(context).doesNotHaveBean(QuartzEndpoint.class));
+	}
+
+	@Test
+	void endpointCanBeDisabled() {
+		this.contextRunner.withBean(Scheduler.class, () -> mock(Scheduler.class))
+				.withPropertyValues("management.endpoint.quartz.enabled:false")
+				.run((context) -> assertThat(context).doesNotHaveBean(QuartzEndpoint.class));
+	}
+
+	@Test
+	void endpointBacksOffWhenUserProvidedEndpointIsPresent() {
+		this.contextRunner.withUserConfiguration(CustomEndpointConfiguration.class)
+				.run((context) -> assertThat(context).hasSingleBean(QuartzEndpoint.class).hasBean("customEndpoint"));
+	}
+
+	@Configuration(proxyBeanMethods = false)
+	static class CustomEndpointConfiguration {
 
 		@Bean
-		public Scheduler scheduler() {
-			return mock(Scheduler.class);
+		CustomEndpoint customEndpoint() {
+			return new CustomEndpoint();
+		}
+
+	}
+
+	private static final class CustomEndpoint extends QuartzEndpoint {
+
+		private CustomEndpoint() {
+			super(mock(Scheduler.class));
 		}
 
 	}