org.apache.flink.annotation.docs.Documentation Java Examples

@VisibleForTesting
static void generateCommonSection(String rootDir, String outputDirectory, OptionsClassLocation[] locations, String pathPrefix) throws IOException, ClassNotFoundException {
	List<OptionWithMetaInfo> commonOptions = new ArrayList<>(32);
	for (OptionsClassLocation location : locations) {
		commonOptions.addAll(findCommonOptions(rootDir, location.getModule(), location.getPackage(), pathPrefix));
	}
	commonOptions.sort((o1, o2) -> {
		int position1 = o1.field.getAnnotation(Documentation.CommonOption.class).position();
		int position2 = o2.field.getAnnotation(Documentation.CommonOption.class).position();
		if (position1 == position2) {
			return o1.option.key().compareTo(o2.option.key());
		} else {
			return Integer.compare(position1, position2);
		}
	});

	String commonHtmlTable = toHtmlTable(commonOptions);
	Files.write(Paths.get(outputDirectory, COMMON_SECTION_FILE_NAME), commonHtmlTable.getBytes(StandardCharsets.UTF_8));
}
 

@VisibleForTesting
static void generateCommonSection(String rootDir, String outputDirectory, OptionsClassLocation[] locations, String pathPrefix) throws IOException, ClassNotFoundException {
	List<OptionWithMetaInfo> commonOptions = new ArrayList<>(32);
	for (OptionsClassLocation location : locations) {
		commonOptions.addAll(findCommonOptions(rootDir, location.getModule(), location.getPackage(), pathPrefix));
	}
	commonOptions.sort((o1, o2) -> {
		int position1 = o1.field.getAnnotation(Documentation.CommonOption.class).position();
		int position2 = o2.field.getAnnotation(Documentation.CommonOption.class).position();
		if (position1 == position2) {
			return o1.option.key().compareTo(o2.option.key());
		} else {
			return Integer.compare(position1, position2);
		}
	});

	String commonHtmlTable = toHtmlTable(commonOptions);
	Files.write(Paths.get(outputDirectory, COMMON_SECTION_FILE_NAME), commonHtmlTable.getBytes(StandardCharsets.UTF_8));
}
 

private static Collection<OptionWithMetaInfo> findCommonOptions(String rootDir, String module, String packageName, String pathPrefix) throws IOException, ClassNotFoundException {
	Collection<OptionWithMetaInfo> commonOptions = new ArrayList<>(32);
	processConfigOptions(rootDir, module, packageName, pathPrefix, optionsClass -> extractConfigOptions(optionsClass).stream()
		.filter(optionWithMetaInfo -> optionWithMetaInfo.field.getAnnotation(Documentation.CommonOption.class) != null)
		.forEachOrdered(commonOptions::add));
	return commonOptions;
}
 

@Test
public void testCommonSectionCompleteness() throws IOException, ClassNotFoundException {
	Map<String, DocumentedOption> documentedOptions = parseDocumentedCommonOptions();
	Map<String, ExistingOption> existingOptions = findExistingOptions(
		optionWithMetaInfo -> optionWithMetaInfo.field.getAnnotation(Documentation.CommonOption.class) != null);

	compareDocumentedAndExistingOptions(documentedOptions, existingOptions);
}
 

private static Collection<OptionWithMetaInfo> findCommonOptions(String rootDir, String module, String packageName, String pathPrefix) throws IOException, ClassNotFoundException {
	Collection<OptionWithMetaInfo> commonOptions = new ArrayList<>(32);
	processConfigOptions(rootDir, module, packageName, pathPrefix, optionsClass -> extractConfigOptions(optionsClass).stream()
		.filter(optionWithMetaInfo -> optionWithMetaInfo.field.getAnnotation(Documentation.CommonOption.class) != null)
		.forEachOrdered(commonOptions::add));
	return commonOptions;
}
 

/**
 * Transforms option to table row.
 *
 * @param optionWithMetaInfo option to transform
 * @return row with the option description
 */
private static String toHtmlString(final OptionWithMetaInfo optionWithMetaInfo) {
	ConfigOption<?> option = optionWithMetaInfo.option;
	String defaultValue = stringifyDefault(optionWithMetaInfo);
	Documentation.TableOption tableOption = optionWithMetaInfo.field.getAnnotation(Documentation.TableOption.class);
	StringBuilder execModeStringBuilder = new StringBuilder();
	if (tableOption != null) {
		Documentation.ExecMode execMode = tableOption.execMode();
		if (Documentation.ExecMode.BATCH_STREAMING.equals(execMode)) {
			execModeStringBuilder.append("<br> <span class=\"label label-primary\">")
					.append(Documentation.ExecMode.BATCH.toString())
					.append("</span> <span class=\"label label-primary\">")
					.append(Documentation.ExecMode.STREAMING.toString())
					.append("</span>");
		} else {
			execModeStringBuilder.append("<br> <span class=\"label label-primary\">")
					.append(execMode.toString())
					.append("</span>");
		}
	}

	return "" +
		"        <tr>\n" +
		"            <td><h5>" + escapeCharacters(option.key()) + "</h5>" + execModeStringBuilder.toString() + "</td>\n" +
		"            <td style=\"word-wrap: break-word;\">" + escapeCharacters(addWordBreakOpportunities(defaultValue)) + "</td>\n" +
		"            <td>" + formatter.format(option.description()) + "</td>\n" +
		"        </tr>\n";
}
 

@Test
public void testCommonSectionCompleteness() throws IOException, ClassNotFoundException {
	Map<String, DocumentedOption> documentedOptions = parseDocumentedCommonOptions();
	Map<String, ExistingOption> existingOptions = findExistingOptions(
		optionWithMetaInfo -> optionWithMetaInfo.field.getAnnotation(Documentation.CommonOption.class) != null);

	compareDocumentedAndExistingOptions(documentedOptions, existingOptions);
}
 

private static Collection<OptionWithMetaInfo> findSectionOptions(String rootDir, String module, String packageName, String pathPrefix) throws IOException, ClassNotFoundException {
	Collection<OptionWithMetaInfo> commonOptions = new ArrayList<>(32);
	processConfigOptions(rootDir, module, packageName, pathPrefix, optionsClass -> extractConfigOptions(optionsClass).stream()
		.filter(optionWithMetaInfo -> optionWithMetaInfo.field.getAnnotation(Documentation.Section.class) != null)
		.forEachOrdered(commonOptions::add));
	return commonOptions;
}
 

/**
 * Transforms option to table row.
 *
 * @param optionWithMetaInfo option to transform
 * @return row with the option description
 */
private static String toHtmlString(final OptionWithMetaInfo optionWithMetaInfo) {
	ConfigOption<?> option = optionWithMetaInfo.option;
	String defaultValue = stringifyDefault(optionWithMetaInfo);
	String type = typeToHtml(optionWithMetaInfo);
	Documentation.TableOption tableOption = optionWithMetaInfo.field.getAnnotation(Documentation.TableOption.class);
	StringBuilder execModeStringBuilder = new StringBuilder();
	if (tableOption != null) {
		Documentation.ExecMode execMode = tableOption.execMode();
		if (Documentation.ExecMode.BATCH_STREAMING.equals(execMode)) {
			execModeStringBuilder.append("<br> <span class=\"label label-primary\">")
					.append(Documentation.ExecMode.BATCH.toString())
					.append("</span> <span class=\"label label-primary\">")
					.append(Documentation.ExecMode.STREAMING.toString())
					.append("</span>");
		} else {
			execModeStringBuilder.append("<br> <span class=\"label label-primary\">")
					.append(execMode.toString())
					.append("</span>");
		}
	}

	return "" +
		"        <tr>\n" +
		"            <td><h5>" + escapeCharacters(option.key()) + "</h5>" + execModeStringBuilder.toString() + "</td>\n" +
		"            <td style=\"word-wrap: break-word;\">" + escapeCharacters(addWordBreakOpportunities(defaultValue)) + "</td>\n" +
		"            <td>" + type + "</td>\n" +
		"            <td>" + formatter.format(option.description()) + "</td>\n" +
		"        </tr>\n";
}
 

private static boolean shouldBeDocumented(Field field) {
	return field.getAnnotation(Deprecated.class) == null &&
		field.getAnnotation(Documentation.ExcludeFromDocumentation.class) == null;
}
 

private static boolean shouldBeDocumented(Field field) {
	return field.getAnnotation(Deprecated.class) == null &&
		field.getAnnotation(Documentation.ExcludeFromDocumentation.class) == null;
}
 

private static boolean shouldBeDocumented(MessageHeaders spec) {
	return spec.getClass().getAnnotation(Documentation.ExcludeFromDocumentation.class) == null;
}
 

@VisibleForTesting
static void generateCommonSection(String rootDir, String outputDirectory, OptionsClassLocation[] locations, String pathPrefix) throws IOException, ClassNotFoundException {
	List<OptionWithMetaInfo> allSectionOptions = new ArrayList<>(32);
	for (OptionsClassLocation location : locations) {
		allSectionOptions.addAll(findSectionOptions(rootDir, location.getModule(), location.getPackage(), pathPrefix));
	}

	Map<String, List<OptionWithMetaInfo>> optionsGroupedBySection = allSectionOptions.stream()
		.flatMap(option -> {
			final String[] sections = option.field.getAnnotation(Documentation.Section.class).value();
			if (sections.length == 0) {
				throw new RuntimeException(String.format(
					"Option %s is annotated with %s but the list of sections is empty.",
					option.option.key(),
					Documentation.Section.class.getSimpleName()));
			}

			return Arrays.stream(sections).map(section -> Tuple2.of(section, option));
		})
		.collect(Collectors.groupingBy(option -> option.f0, Collectors.mapping(option -> option.f1, Collectors.toList())));

	optionsGroupedBySection.forEach(
		(section, options) -> {
			options.sort((o1, o2) -> {
				int position1 = o1.field.getAnnotation(Documentation.Section.class).position();
				int position2 = o2.field.getAnnotation(Documentation.Section.class).position();
				if (position1 == position2) {
					return o1.option.key().compareTo(o2.option.key());
				} else {
					return Integer.compare(position1, position2);
				}
			});

			String sectionHtmlTable = toHtmlTable(options);
			try {
				Files.write(Paths.get(outputDirectory, getSectionFileName(section)), sectionHtmlTable.getBytes(StandardCharsets.UTF_8));
			} catch (Exception e) {
				throw new RuntimeException(e);
			}
		}
	);
}
 

private static boolean shouldBeDocumented(Field field) {
	return field.getAnnotation(Deprecated.class) == null &&
		field.getAnnotation(Documentation.ExcludeFromDocumentation.class) == null;
}
 

private static boolean isSuffixOption(Field field) {
	final Class<?> containingOptionsClass = field.getDeclaringClass();

	return field.getAnnotation(Documentation.SuffixOption.class) != null ||
		containingOptionsClass.getAnnotation(Documentation.SuffixOption.class) != null;
}