Skip to content
This repository was archived by the owner on May 14, 2025. It is now read-only.

Commit 64f098a

Browse files
ghillertcppwfs
ghillert
authored and
cppwfs
committed
gh-3321 Document Task Execution deletes
- Add Rest API Documentation Polishing on merge
1 parent 1ec1ff3 commit 64f098a

File tree

2 files changed

+116
-53
lines changed

2 files changed

+116
-53
lines changed

‎spring-cloud-dataflow-classic-docs/src/test/java/org/springframework/cloud/dataflow/server/rest/documentation/TaskExecutionsDocumentation.java‎

Lines changed: 73 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@
4242
* @author Eric Bottard
4343
* @author Glenn Renfro
4444
* @author David Turanski
45+
* @author Gunnar Hillert
4546
*/
4647
@FixMethodOrder(MethodSorters.NAME_ASCENDING)
4748
public class TaskExecutionsDocumentation extends BaseDocumentation {
@@ -79,21 +80,48 @@ public void launchTask() throws Exception {
7980
}
8081

8182
@Test
82-
public void stopTask() throws Exception {
83+
public void launchTaskCurrentCount() throws Exception {
8384
this.mockMvc.perform(
84-
post("/tasks/executions")
85-
.param("name", "taskA")
86-
.param("properties", "app.my-task.foo=bar,deployer.my-task.something-else=3")
87-
.param("arguments", "--server.port=8080 --foo=bar"))
88-
.andExpect(status().isCreated());
85+
get("/tasks/executions/current"))
86+
.andDo(print())
87+
.andExpect(status().isOk())
88+
.andDo(this.documentationHandler.document(
89+
responseFields(
90+
fieldWithPath("[].name").description("The name of the platform instance (account)"),
91+
fieldWithPath("[].type").description("The platform type"),
92+
fieldWithPath("[].maximumTaskExecutions").description("The number of maximum task execution"),
93+
fieldWithPath("[].runningExecutionCount").description("The number of running executions")
94+
)
95+
));
96+
}
97+
98+
@Test
99+
public void launchTaskDisplayDetail() throws Exception {
89100
this.mockMvc.perform(
90-
post("/tasks/executions/{id}", 1))
101+
get("/tasks/executions/{id}", "1"))
91102
.andDo(print())
92103
.andExpect(status().isOk())
93104
.andDo(this.documentationHandler.document(
94105
pathParameters(
95106
parameterWithName("id").description("The id of an existing task execution (required)")
96-
)));
107+
),
108+
responseFields(
109+
fieldWithPath("executionId").description("The id of the task execution"),
110+
fieldWithPath("exitCode").description("The exit code of the task execution"),
111+
fieldWithPath("taskName").description("The task name related to the task execution"),
112+
fieldWithPath("startTime").description("The start time of the task execution"),
113+
fieldWithPath("endTime").description("The end time of the task execution"),
114+
fieldWithPath("exitMessage").description("The exit message of the task execution"),
115+
fieldWithPath("arguments").description("The arguments of the task execution"),
116+
fieldWithPath("jobExecutionIds").description("The job executions ids of the task executions"),
117+
fieldWithPath("errorMessage").description("The error message of the task execution"),
118+
fieldWithPath("externalExecutionId").description("The external id of the task execution"),
119+
fieldWithPath("taskExecutionStatus").description("The status of the task execution"),
120+
fieldWithPath("parentExecutionId").description("The id of parent task execution, " +
121+
"null if task execution does not have parent"),
122+
subsectionWithPath("_links.self").description("Link to the task execution resource")
123+
)
124+
));
97125
}
98126

99127
@Test
@@ -147,52 +175,46 @@ public void listTaskExecutionsByName() throws Exception {
147175
}
148176

149177
@Test
150-
public void launchTaskDisplayDetail() throws Exception {
178+
public void stopTask() throws Exception {
151179
this.mockMvc.perform(
152-
get("/tasks/executions/{id}", "1"))
180+
post("/tasks/executions")
181+
.param("name", "taskA")
182+
.param("properties", "app.my-task.foo=bar,deployer.my-task.something-else=3")
183+
.param("arguments", "--server.port=8080 --foo=bar"))
184+
.andExpect(status().isCreated());
185+
this.mockMvc.perform(
186+
post("/tasks/executions/{id}", 1))
153187
.andDo(print())
154188
.andExpect(status().isOk())
155189
.andDo(this.documentationHandler.document(
156190
pathParameters(
157-
parameterWithName("id").description("The id of an existing task execution (required)")
158-
),
159-
responseFields(
160-
fieldWithPath("executionId").description("The id of the task execution"),
161-
fieldWithPath("exitCode").description("The exit code of the task execution"),
162-
fieldWithPath("taskName").description("The task name related to the task execution"),
163-
fieldWithPath("startTime").description("The start time of the task execution"),
164-
fieldWithPath("endTime").description("The end time of the task execution"),
165-
fieldWithPath("exitMessage").description("The exit message of the task execution"),
166-
fieldWithPath("arguments").description("The arguments of the task execution"),
167-
fieldWithPath("jobExecutionIds").description("The job executions ids of the task execution"),
168-
fieldWithPath("errorMessage").description("The error message of the task execution"),
169-
fieldWithPath("externalExecutionId").description("The external id of the task execution"),
170-
fieldWithPath("taskExecutionStatus").description("The status of the task execution"),
171-
fieldWithPath("parentExecutionId").description("The id of parent task execution, " +
172-
"null if task execution does not have parent"),
173-
subsectionWithPath("_links.self").description("Link to the task execution resource")
174-
)
175-
));
191+
parameterWithName("id").description("The ids of an existing task execution (required)")
192+
)));
176193
}
177194

178195
@Test
179-
public void launchTaskCurrentCount() throws Exception {
196+
public void taskExecutionRemove() throws Exception {
197+
198+
documentation.dontDocument( () -> this.mockMvc.perform(
199+
post("/tasks/executions")
200+
.param("name", "taskB")
201+
.param("properties", "app.my-task.foo=bar,deployer.my-task.something-else=3")
202+
.param("arguments", "--server.port=8080 --foo=bar"))
203+
.andExpect(status().isCreated()));
204+
180205
this.mockMvc.perform(
181-
get("/tasks/executions/current"))
206+
delete("/tasks/executions/{ids}?action=CLEANUP", "1"))
182207
.andDo(print())
183208
.andExpect(status().isOk())
184209
.andDo(this.documentationHandler.document(
185-
responseFields(
186-
fieldWithPath("[].name").description("The name of the platform instance (account)"),
187-
fieldWithPath("[].type").description("The platform type"),
188-
fieldWithPath("[].maximumTaskExecutions").description("The number of maximum task execution"),
189-
fieldWithPath("[].runningExecutionCount").description("The number of number execution")
190-
)
191-
));
210+
requestParameters(parameterWithName("action").description("Optional. Defaults to: CLEANUP.")),
211+
pathParameters(parameterWithName("ids")
212+
.description("The id of an existing task execution (required). Multiple comma separated values are accepted."))
213+
));
192214
}
193215

194216
@Test
195-
public void removeTaskExecution() throws Exception {
217+
public void taskExecutionRemoveAndTaskDataRemove() throws Exception {
196218

197219
documentation.dontDocument( () -> this.mockMvc.perform(
198220
post("/tasks/executions")
@@ -201,14 +223,23 @@ public void removeTaskExecution() throws Exception {
201223
.param("arguments", "--server.port=8080 --foo=bar"))
202224
.andExpect(status().isCreated()));
203225

226+
documentation.dontDocument( () -> this.mockMvc.perform(
227+
post("/tasks/executions")
228+
.param("name", "taskB")
229+
.param("properties", "app.my-task.foo=bar2,deployer.my-task.something-else=3")
230+
.param("arguments", "--server.port=8082 --foo=bar2"))
231+
.andExpect(status().isCreated()));
232+
204233
this.mockMvc.perform(
205-
delete("/tasks/executions/{id}", "1"))
234+
delete("/tasks/executions/{ids}?action=CLEANUP,REMOVE_DATA", "1,2"))
206235
.andDo(print())
207236
.andExpect(status().isOk())
208237
.andDo(this.documentationHandler.document(
209-
pathParameters(parameterWithName("id")
210-
.description("The id of an existing task execution (required)"))
238+
requestParameters(parameterWithName("action").description("Using both actions CLEANUP and REMOVE_DATA simultaneously.")),
239+
pathParameters(parameterWithName("ids")
240+
.description("Providing 2 comma separated task execution id values."))
211241
));
242+
212243
}
213244

214245
private void createTaskDefinition(String taskName) throws Exception{

‎spring-cloud-dataflow-docs/src/main/asciidoc/api-guide.adoc‎

Lines changed: 43 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1927,9 +1927,13 @@ include::{snippets}/task-executions-documentation/launch-task-display-detail/htt
19271927
[[api-guide-resources-task-executions-delete]]
19281928
==== Delete Task Execution
19291929

1930-
The task executions endpoint lets you clean up resources used to deploy the task.
1930+
The task executions endpoint lets you:
19311931

1932-
NOTE: The cleanup implementation is platform specific.
1932+
- Clean up resources used to deploy the task
1933+
- Remove relevant task data as well as possibly associated Spring Batch job data from the persistence store
1934+
1935+
NOTE: The cleanup implementation (first option) is platform specific. Both operations can be triggered
1936+
at once or separately.
19331937

19341938
The following topics provide more details:
19351939

@@ -1938,36 +1942,64 @@ The following topics provide more details:
19381942
* <<api-guide-resources-task-executions-delete-example-request>>
19391943
* <<api-guide-resources-task-executions-delete-response-structure>>
19401944

1941-
1945+
Please refer to the following section in regards to <<api-guide-resources-task-executions-delete-multiple-and-task-data>>.
19421946

19431947
[[api-guide-resources-task-executions-delete-request-structure]]
19441948
===== Request Structure
19451949

1946-
include::{snippets}/task-executions-documentation/remove-task-execution/http-request.adoc[]
1947-
1948-
include::{snippets}/task-executions-documentation/remove-task-execution/path-parameters.adoc[]
1950+
include::{snippets}/task-executions-documentation/task-execution-remove-and-task-data-remove/http-request.adoc[]
19491951

1952+
include::{snippets}/task-executions-documentation/task-execution-remove-and-task-data-remove/path-parameters.adoc[]
19501953

1954+
[IMPORTANT]
1955+
====
1956+
You must ensure to only provide task execution ids that actually exist. Otherwise a `404` (Not Found) HTTP status is returned.
1957+
In case of submitting multiple task execution ids, the invalidity of a single task execution id will cause the entire request to fail,
1958+
without performing any operation.
1959+
====
19511960

19521961
[[api-guide-resources-task-executions-delete-request-parameters]]
19531962
===== Request Parameters
19541963

1955-
There are no request parameters for this endpoint.
1964+
This endpoint supports 1 optional request parameter named **action**. It is an enumeration and supports the following
1965+
2 values:
19561966

1967+
- CLEANUP
1968+
- REMOVE_DATA
19571969

1970+
include::{snippets}/task-executions-documentation/task-execution-remove-and-task-data-remove/request-parameters.adoc[]
19581971

19591972
[[api-guide-resources-task-executions-delete-example-request]]
19601973
===== Example Request
19611974

1962-
include::{snippets}/task-executions-documentation/remove-task-execution/curl-request.adoc[]
1963-
1964-
1975+
include::{snippets}/task-executions-documentation/task-execution-remove-and-task-data-remove/curl-request.adoc[]
19651976

19661977
[[api-guide-resources-task-executions-delete-response-structure]]
19671978
===== Response Structure
19681979

1969-
include::{snippets}/task-executions-documentation/remove-task-execution/http-response.adoc[]
1980+
include::{snippets}/task-executions-documentation/task-execution-remove-and-task-data-remove/http-response.adoc[]
1981+
1982+
[[api-guide-resources-task-executions-delete-multiple-and-task-data]]
1983+
==== Deleting Task Execution Data
1984+
1985+
Not only can you clean up resources that were used to deploy tasks but you can also delete the data associated with
1986+
task executions from the underlying persistence store. Also, if a task execution is associated with one or
1987+
more batch job executions, these will be removed as well.
1988+
1989+
The following example illustrates how a request can be made using multiple task execution ids and multiple actions:
1990+
1991+
include::{snippets}/task-executions-documentation/task-execution-remove-and-task-data-remove/curl-request.adoc[]
1992+
1993+
include::{snippets}/task-executions-documentation/task-execution-remove-and-task-data-remove/path-parameters.adoc[]
1994+
1995+
include::{snippets}/task-executions-documentation/task-execution-remove-and-task-data-remove/request-parameters.adoc[]
19701996

1997+
[IMPORTANT]
1998+
====
1999+
When deleting data from the persistence store using the `REMOVE_DATA` action parameter, you must ensure to provide
2000+
only task execution ids that represent parent task executions. When providing child task executions (Executed as part of a composed task),
2001+
then a `400` (Bad Request) HTTP status is returned.
2002+
====
19712003

19722004
[[api-guide-resources-task-executions-current-count]]
19732005
==== Task Execution Current Count

0 commit comments

Comments
 (0)