You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@flink.apache.org by GitBox <gi...@apache.org> on 2018/11/17 19:51:33 UTC
[GitHub] tillrohrmann closed pull request #7132: [BP-1.5][FLINK-10880]
Exclude JobManagerOptions#EXECUTION_FAILOVER_STRATEGY from documentation
tillrohrmann closed pull request #7132: [BP-1.5][FLINK-10880] Exclude JobManagerOptions#EXECUTION_FAILOVER_STRATEGY from documentation
URL: https://github.com/apache/flink/pull/7132
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/docs/_includes/generated/job_manager_configuration.html b/docs/_includes/generated/job_manager_configuration.html
index db0ca53614b..774667407a1 100644
--- a/docs/_includes/generated/job_manager_configuration.html
+++ b/docs/_includes/generated/job_manager_configuration.html
@@ -17,11 +17,6 @@
<td style="word-wrap: break-word;">16</td>
<td>The maximum number of prior execution attempts kept in history.</td>
</tr>
- <tr>
- <td><h5>jobmanager.execution.failover-strategy</h5></td>
- <td style="word-wrap: break-word;">"full"</td>
- <td>The maximum number of prior execution attempts kept in history.</td>
- </tr>
<tr>
<td><h5>jobmanager.heap.mb</h5></td>
<td style="word-wrap: break-word;">1024</td>
diff --git a/docs/release-notes/flink-1.5.md b/docs/release-notes/flink-1.5.md
index ba377dd85b9..666f6538025 100644
--- a/docs/release-notes/flink-1.5.md
+++ b/docs/release-notes/flink-1.5.md
@@ -96,5 +96,13 @@ The Kinesis dependencies of Flink’s Kinesis connector have been updated to the
<aws.kinesis-kpl.version>0.12.9</aws.kinesis-kcl.version>
```
+<!-- Remove once FLINK-10712 has been fixed -->
+### Limitations of failover strategies
+Flink's non-default failover strategies are still a very experimental feature which come with a set of limitations.
+You should only use this feature if you are executing a stateless streaming job.
+In any other cases, it is highly recommended to remove the config option `jobmanager.execution.failover-strategy` from your `flink-conf.yaml` or set it to `"full"`.
+
+In order to avoid future problems, this feature has been removed from the documentation until it will be fixed.
+See [FLINK-10880](https://issues.apache.org/jira/browse/FLINK-10880) for more details.
{% top %}
diff --git a/flink-annotations/src/main/java/org/apache/flink/annotation/docs/Documentation.java b/flink-annotations/src/main/java/org/apache/flink/annotation/docs/Documentation.java
index 4e424c76cf8..d5e12684566 100644
--- a/flink-annotations/src/main/java/org/apache/flink/annotation/docs/Documentation.java
+++ b/flink-annotations/src/main/java/org/apache/flink/annotation/docs/Documentation.java
@@ -40,6 +40,19 @@
String value();
}
+ /**
+ * Annotation used on config option fields to exclude the config option from documentation.
+ */
+ @Target(ElementType.FIELD)
+ @Retention(RetentionPolicy.RUNTIME)
+ @Internal
+ public @interface ExcludeFromDocumentation {
+ /**
+ * The optional reason why the config option is excluded from documentation.
+ */
+ String value() default "";
+ }
+
private Documentation(){
}
}
diff --git a/flink-core/src/main/java/org/apache/flink/configuration/JobManagerOptions.java b/flink-core/src/main/java/org/apache/flink/configuration/JobManagerOptions.java
index add8e68c26d..a0f479f14fb 100644
--- a/flink-core/src/main/java/org/apache/flink/configuration/JobManagerOptions.java
+++ b/flink-core/src/main/java/org/apache/flink/configuration/JobManagerOptions.java
@@ -19,6 +19,7 @@
package org.apache.flink.configuration;
import org.apache.flink.annotation.PublicEvolving;
+import org.apache.flink.annotation.docs.Documentation;
import static org.apache.flink.configuration.ConfigOptions.key;
@@ -92,6 +93,7 @@
/**
* The maximum number of prior execution attempts kept in history.
*/
+ @Documentation.ExcludeFromDocumentation("The failover strategy feature is highly experimental.")
public static final ConfigOption<String> EXECUTION_FAILOVER_STRATEGY =
key("jobmanager.execution.failover-strategy")
.defaultValue("full")
diff --git a/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java b/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java
index b73a40e7c04..a9cebd607de 100644
--- a/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java
+++ b/flink-docs/src/main/java/org/apache/flink/docs/configuration/ConfigOptionsDocGenerator.java
@@ -148,7 +148,7 @@ static void processConfigOptions(String rootDir, String module, String packageNa
List<OptionWithMetaInfo> configOptions = new ArrayList<>(8);
Field[] fields = clazz.getFields();
for (Field field : fields) {
- if (field.getType().equals(ConfigOption.class) && field.getAnnotation(Deprecated.class) == null) {
+ if (isConfigOption(field) && shouldBeDocumented(field)) {
configOptions.add(new OptionWithMetaInfo((ConfigOption<?>) field.get(null), field));
}
}
@@ -159,6 +159,15 @@ static void processConfigOptions(String rootDir, String module, String packageNa
}
}
+ private static boolean isConfigOption(Field field) {
+ return field.getType().equals(ConfigOption.class);
+ }
+
+ private static boolean shouldBeDocumented(Field field) {
+ return field.getAnnotation(Deprecated.class) == null &&
+ field.getAnnotation(Documentation.ExcludeFromDocumentation.class) == null;
+ }
+
/**
* Transforms this configuration group into HTML formatted table.
* Options are sorted alphabetically by key.
diff --git a/flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocGeneratorTest.java b/flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocGeneratorTest.java
index 4176c5d65f6..7306e4d7208 100644
--- a/flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocGeneratorTest.java
+++ b/flink-docs/src/test/java/org/apache/flink/docs/configuration/ConfigOptionsDocGeneratorTest.java
@@ -215,4 +215,44 @@ public void testOverrideDefault() {
assertEquals(expectedTable, htmlTable);
}
+ static class TestConfigGroupWithExclusion {
+ public static ConfigOption<Integer> firstOption = ConfigOptions
+ .key("first.option.a")
+ .defaultValue(2)
+ .withDescription("This is example description for the first option.");
+
+ @Documentation.ExcludeFromDocumentation
+ public static ConfigOption<String> excludedOption = ConfigOptions
+ .key("excluded.option.a")
+ .noDefaultValue()
+ .withDescription("This should not be documented.");
+ }
+
+ /**
+ * Tests that {@link ConfigOption} annotated with {@link Documentation.ExcludeFromDocumentation}
+ * are not documented.
+ */
+ @Test
+ public void testConfigOptionExclusion() {
+ final String expectedTable =
+ "<table class=\"table table-bordered\">\n" +
+ " <thead>\n" +
+ " <tr>\n" +
+ " <th class=\"text-left\" style=\"width: 20%\">Key</th>\n" +
+ " <th class=\"text-left\" style=\"width: 15%\">Default</th>\n" +
+ " <th class=\"text-left\" style=\"width: 65%\">Description</th>\n" +
+ " </tr>\n" +
+ " </thead>\n" +
+ " <tbody>\n" +
+ " <tr>\n" +
+ " <td><h5>first.option.a</h5></td>\n" +
+ " <td style=\"word-wrap: break-word;\">2</td>\n" +
+ " <td>This is example description for the first option.</td>\n" +
+ " </tr>\n" +
+ " </tbody>\n" +
+ "</table>\n";
+ final String htmlTable = ConfigOptionsDocGenerator.generateTablesForClass(TestConfigGroupWithExclusion.class).get(0).f1;
+
+ assertEquals(expectedTable, htmlTable);
+ }
}
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services