You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by gy...@apache.org on 2022/04/25 15:43:04 UTC
[flink-kubernetes-operator] branch main updated: [FLINK-27397] Improve the CrdReferenceDoclet to handle the abstract class
This is an automated email from the ASF dual-hosted git repository.
gyfora pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/flink-kubernetes-operator.git
The following commit(s) were added to refs/heads/main by this push:
new 247a12f [FLINK-27397] Improve the CrdReferenceDoclet to handle the abstract class
247a12f is described below
commit 247a12f2b5d9c71595cb153606be2551ef79d4a4
Author: Aitozi <yu...@alibaba-inc.com>
AuthorDate: Mon Apr 25 23:18:12 2022 +0800
[FLINK-27397] Improve the CrdReferenceDoclet to handle the abstract class
---
docs/content/docs/custom-resource/reference.md | 45 +++++----------
.../operator/docs/CrdReferenceDoclet.java | 66 +++++++++++++++++-----
2 files changed, 65 insertions(+), 46 deletions(-)
diff --git a/docs/content/docs/custom-resource/reference.md b/docs/content/docs/custom-resource/reference.md
index b56d8f9..b09cf27 100644
--- a/docs/content/docs/custom-resource/reference.md
+++ b/docs/content/docs/custom-resource/reference.md
@@ -38,15 +38,6 @@ This page serves as a full reference for FlinkDeployment custom resource definit
## Spec
-### AbstractFlinkSpec
-**Class**: org.apache.flink.kubernetes.operator.crd.spec.AbstractFlinkSpec
-
-**Description**: The common view of the spec.
-
-| Parameter | Type | Docs |
-| ----------| ---- | ---- |
-| job | org.apache.flink.kubernetes.operator.crd.spec.JobSpec | Job specification for application deployments/session job. Null for session clusters. |
-
### FlinkDeploymentSpec
**Class**: org.apache.flink.kubernetes.operator.crd.spec.FlinkDeploymentSpec
@@ -54,6 +45,7 @@ This page serves as a full reference for FlinkDeployment custom resource definit
| Parameter | Type | Docs |
| ----------| ---- | ---- |
+| job | org.apache.flink.kubernetes.operator.crd.spec.JobSpec | Job specification for application deployments/session job. Null for session clusters. |
| image | java.lang.String | Flink docker image used to start the Job and TaskManager pods. |
| imagePullPolicy | java.lang.String | Image pull policy of the Flink docker image. |
| serviceAccount | java.lang.String | Kubernetes service used by the Flink deployment. |
@@ -73,6 +65,7 @@ This page serves as a full reference for FlinkDeployment custom resource definit
| Parameter | Type | Docs |
| ----------| ---- | ---- |
+| job | org.apache.flink.kubernetes.operator.crd.spec.JobSpec | Job specification for application deployments/session job. Null for session clusters. |
| deploymentName | java.lang.String | The name of the target session cluster deployment. |
### FlinkVersion
@@ -167,16 +160,6 @@ This page serves as a full reference for FlinkDeployment custom resource definit
## Status
-### CommonStatus
-**Class**: org.apache.flink.kubernetes.operator.crd.status.CommonStatus
-
-**Description**: Last observed common status of the Flink deployment/Flink SessionJob.
-
-| Parameter | Type | Docs |
-| ----------| ---- | ---- |
-| jobStatus | org.apache.flink.kubernetes.operator.crd.status.JobStatus | Last observed status of the Flink job on Application/Session cluster. |
-| error | java.lang.String | Error information about the FlinkDeployment/FlinkSessionJob. |
-
### FlinkDeploymentReconciliationStatus
**Class**: org.apache.flink.kubernetes.operator.crd.status.FlinkDeploymentReconciliationStatus
@@ -184,6 +167,10 @@ This page serves as a full reference for FlinkDeployment custom resource definit
| Parameter | Type | Docs |
| ----------| ---- | ---- |
+| reconciliationTimestamp | long | Epoch timestamp of the last successful reconcile operation. |
+| lastReconciledSpec | java.lang.String | Last reconciled deployment spec. Used to decide whether further reconciliation steps are necessary. |
+| lastStableSpec | java.lang.String | Last stable deployment spec according to the specified stability condition. If a rollback strategy is defined this will be the target to roll back to. |
+| state | org.apache.flink.kubernetes.operator.crd.status.ReconciliationState | Deployment state of the last reconciled spec. |
### FlinkDeploymentStatus
**Class**: org.apache.flink.kubernetes.operator.crd.status.FlinkDeploymentStatus
@@ -192,6 +179,8 @@ This page serves as a full reference for FlinkDeployment custom resource definit
| Parameter | Type | Docs |
| ----------| ---- | ---- |
+| jobStatus | org.apache.flink.kubernetes.operator.crd.status.JobStatus | Last observed status of the Flink job on Application/Session cluster. |
+| error | java.lang.String | Error information about the FlinkDeployment/FlinkSessionJob. |
| jobManagerDeploymentStatus | org.apache.flink.kubernetes.operator.crd.status.JobManagerDeploymentStatus | Last observed status of the JobManager deployment. |
| reconciliationStatus | org.apache.flink.kubernetes.operator.crd.status.FlinkDeploymentReconciliationStatus | Status of the last reconcile operation. |
@@ -202,6 +191,10 @@ This page serves as a full reference for FlinkDeployment custom resource definit
| Parameter | Type | Docs |
| ----------| ---- | ---- |
+| reconciliationTimestamp | long | Epoch timestamp of the last successful reconcile operation. |
+| lastReconciledSpec | java.lang.String | Last reconciled deployment spec. Used to decide whether further reconciliation steps are necessary. |
+| lastStableSpec | java.lang.String | Last stable deployment spec according to the specified stability condition. If a rollback strategy is defined this will be the target to roll back to. |
+| state | org.apache.flink.kubernetes.operator.crd.status.ReconciliationState | Deployment state of the last reconciled spec. |
### FlinkSessionJobStatus
**Class**: org.apache.flink.kubernetes.operator.crd.status.FlinkSessionJobStatus
@@ -210,6 +203,8 @@ This page serves as a full reference for FlinkDeployment custom resource definit
| Parameter | Type | Docs |
| ----------| ---- | ---- |
+| jobStatus | org.apache.flink.kubernetes.operator.crd.status.JobStatus | Last observed status of the Flink job on Application/Session cluster. |
+| error | java.lang.String | Error information about the FlinkDeployment/FlinkSessionJob. |
| reconciliationStatus | org.apache.flink.kubernetes.operator.crd.status.FlinkSessionJobReconciliationStatus | Status of the last reconcile operation. |
### JobManagerDeploymentStatus
@@ -250,18 +245,6 @@ This page serves as a full reference for FlinkDeployment custom resource definit
| ROLLING_BACK | In the process of rolling back to the lastStableSpec. |
| ROLLED_BACK | Rolled back to the lastStableSpec. |
-### ReconciliationStatus
-**Class**: org.apache.flink.kubernetes.operator.crd.status.ReconciliationStatus
-
-**Description**: Status of the last reconcile step for the FlinkDeployment/FlinkSessionJob.
-
-| Parameter | Type | Docs |
-| ----------| ---- | ---- |
-| reconciliationTimestamp | long | Epoch timestamp of the last successful reconcile operation. |
-| lastReconciledSpec | java.lang.String | Last reconciled deployment spec. Used to decide whether further reconciliation steps are necessary. |
-| lastStableSpec | java.lang.String | Last stable deployment spec according to the specified stability condition. If a rollback strategy is defined this will be the target to roll back to. |
-| state | org.apache.flink.kubernetes.operator.crd.status.ReconciliationState | Deployment state of the last reconciled spec. |
-
### Savepoint
**Class**: org.apache.flink.kubernetes.operator.crd.status.Savepoint
diff --git a/flink-kubernetes-operator/src/main/java/org/apache/flink/kubernetes/operator/docs/CrdReferenceDoclet.java b/flink-kubernetes-operator/src/main/java/org/apache/flink/kubernetes/operator/docs/CrdReferenceDoclet.java
index f26a9e7..29fe798 100644
--- a/flink-kubernetes-operator/src/main/java/org/apache/flink/kubernetes/operator/docs/CrdReferenceDoclet.java
+++ b/flink-kubernetes-operator/src/main/java/org/apache/flink/kubernetes/operator/docs/CrdReferenceDoclet.java
@@ -27,12 +27,16 @@ import org.apache.commons.io.FileUtils;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.ElementKind;
+import javax.lang.model.element.Modifier;
import javax.lang.model.util.ElementScanner9;
+import javax.lang.model.util.Types;
import java.io.File;
import java.io.PrintStream;
+import java.util.HashMap;
import java.util.List;
import java.util.Locale;
+import java.util.Map;
import java.util.Set;
import java.util.TreeSet;
import java.util.stream.Collectors;
@@ -40,9 +44,14 @@ import java.util.stream.Collectors;
/** Doclet for generating the FlinkDeployment CRD reference. */
public class CrdReferenceDoclet implements Doclet {
+ private static final String SPEC_PACKAGE_PREFIX =
+ "org.apache.flink.kubernetes.operator.crd.spec";
+ private static final String STATUS_PACKAGE_PREFIX =
+ "org.apache.flink.kubernetes.operator.crd.status";
private DocTrees treeUtils;
private String templateFile;
private String outputFile;
+ private Map<Element, Element> child2ParentElements;
@Override
public void init(Locale locale, Reporter reporter) {}
@@ -86,34 +95,56 @@ public class CrdReferenceDoclet implements Doclet {
MdPrinter se = new MdPrinter(printStream);
printStream.println("");
printStream.println("## Spec");
- se.show(
+ var spec =
sortedByName(
environment.getIncludedElements().stream()
- .filter(
- e ->
- e.toString()
- .startsWith(
- "org.apache.flink.kubernetes.operator.crd.spec"))
- .collect(Collectors.toSet())));
+ .filter(e -> e.toString().startsWith(SPEC_PACKAGE_PREFIX))
+ .collect(Collectors.toSet()));
+ handleAbstractClass(spec, environment.getTypeUtils());
+ se.show(spec);
printStream.println("");
printStream.println("## Status");
-
- se.show(
+ var status =
sortedByName(
environment.getIncludedElements().stream()
- .filter(
- e ->
- e.toString()
- .startsWith(
- "org.apache.flink.kubernetes.operator.crd.status"))
- .collect(Collectors.toSet())));
+ .filter(e -> e.toString().startsWith(STATUS_PACKAGE_PREFIX))
+ .collect(Collectors.toSet()));
+ handleAbstractClass(status, environment.getTypeUtils());
+ se.show(status);
return true;
} catch (Exception e) {
throw new RuntimeException(e);
}
}
+ private void handleAbstractClass(Set<? extends Element> elements, Types typeUtils) {
+ this.child2ParentElements = new HashMap<>();
+ var classElements =
+ elements.stream()
+ .filter(element -> element.getKind() == ElementKind.CLASS)
+ .collect(Collectors.toList());
+
+ for (Element element : classElements) {
+ if (element.getModifiers().contains(Modifier.ABSTRACT)) {
+ var enclosedElements = element.getEnclosedElements();
+ // do not print the abstract class's elements
+ enclosedElements.forEach(elements::remove);
+ elements.remove(element);
+ } else {
+ var directSuperTypes = typeUtils.directSupertypes(element.asType());
+ if (directSuperTypes.size() == 1) {
+ var parentElement = typeUtils.asElement(directSuperTypes.get(0));
+ String name = parentElement.toString();
+ if (name.startsWith(SPEC_PACKAGE_PREFIX)
+ || name.startsWith(STATUS_PACKAGE_PREFIX)) {
+ child2ParentElements.put(element, parentElement);
+ }
+ }
+ }
+ }
+ }
+
private String cleanDoc(String doc) {
return doc.replaceAll("[\\t\\n\\r]+", " ");
}
@@ -150,6 +181,11 @@ public class CrdReferenceDoclet implements Doclet {
out.println("");
out.println("| Parameter | Type | Docs |");
out.println("| ----------| ---- | ---- |");
+ // if this is a child class, print it's parent's enclosed elements.
+ if (child2ParentElements.containsKey(e)) {
+ MdPrinter mdPrinter = new MdPrinter(out);
+ mdPrinter.scan(child2ParentElements.get(e).getEnclosedElements(), depth);
+ }
break;
case FIELD:
out.println(