Improve @FrankDocGroup annotation (#175)

Author: mhdirkse

frank-doc-doclet/README.md

@@ -26,7 +26,7 @@ The XML schema helps Frank developers when they are writing their configs, but t
 
 ![webapp-intro](./picturesForReadme/webapp-intro.jpg)
 
-To the top-left, you see a list of groups (number 1). These groups are controlled by Java annotation [@FrankDocGroup](https://github.com/ibissource/iaf/blob/master/iaf-commons/src/main/java/nl/nn/adapterframework/doc/FrankDocGroup.java). To the bottom-left, you see the Java class names that are members of the chosen group (number 2). When you select a class name, you get information about it (number 3). More explanation of this text follows later.
+To the top-left, you see a list of groups (number 1). These groups are controlled by Java annotation [@FrankDocGroup](https://github.com/frankframework/frankframework/blob/master/commons/src/main/java/org/frankframework/doc/FrankDocGroup.java). To the bottom-left, you see the Java class names that are members of the chosen group (number 2). When you select a class name, you get information about it (number 3). More explanation of this text follows later.
 
 ## Descriptions of classes, child elements and attributes
 
@@ -100,33 +100,15 @@ Frank configs that violate the preferred order can still be parsed by the Frank!
 
 ## Groups in the web application
 
-This section is about the groups shown in the top-left of the Frank!Doc web application:
+This section is about the groups shown in the top-left of the Frank!Doc web application. These groups are managed through Java annotation [@FrankDocGroup](https://github.com/frankframework/frankframework/blob/master/commons/src/main/java/org/frankframework/doc/FrankDocGroup.java). This annotation has a value field that is of an enum type. Each value of the enum should be annotated with [@EnumLabel](https://github.com/frankframework/frankframework/blob/master/commons/src/main/java/org/frankframework/doc/EnumLabel.java) to provide the group name to be shown. The order of the enum constants determines the order of the shown groups.
 
-![webapp-groups-batch](./picturesForReadme/webapp-groups-batch.jpg)
+When [@FrankDocGroup](https://github.com/frankframework/frankframework/blob/master/commons/src/main/java/org/frankframework/doc/FrankDocGroup.java) is placed on a Java class or interface, then all Java classes that implement the interface (or only the class itself in case of a class) are added to the group. 
 
-The overview of all groups is shown as number 1. We have selected group `Batch` (number 2). How does the Frank!Doc know the order of the groups and the elements they contain? First, see the following snippet of [IRecordHandlerManager](https://github.com/ibissource/iaf/blob/master/core/src/main/java/nl/nn/adapterframework/batch/IRecordHandlerManager.java)
+Java classes that do not have or inherit a [@FrankDocGroup](https://github.com/frankframework/frankframework/blob/master/commons/src/main/java/org/frankframework/doc/FrankDocGroup.java) annotation are put in group `Other`.
 
-![eclipseIRecordHandlerManager](./picturesForReadme/eclipseIRecordHandlerManager.jpg)
+A [@FrankDocGroup](https://github.com/frankframework/frankframework/blob/master/commons/src/main/java/org/frankframework/doc/FrankDocGroup.java) annotation is only processed when it appears on a class or interface that appears as the argument of a config child setter. This means: when it gives rise to an [ElementType](src/main/java/org/frankframework/frankdoc/model/ElementType.java).
 
-The interface has a Java annotation [@FrankDocGroup](https://github.com/ibissource/iaf/blob/master/iaf-commons/src/main/java/nl/nn/adapterframework/doc/FrankDocGroup.java). The annotation has fields `name` and `order`. The `order` is an integer that is used to sort the groups in the shown order.
-
-When [@FrankDocGroup](https://github.com/ibissource/iaf/blob/master/iaf-commons/src/main/java/nl/nn/adapterframework/doc/FrankDocGroup.java) is placed on a Java class or interface, then all Java classes that implement the interface (or only the class itself in case of a class) are added to the group. Here is the type hierarchy of [IRecordHandlerManager](https://github.com/ibissource/iaf/blob/master/core/src/main/java/nl/nn/adapterframework/batch/IRecordHandlerManager.java):
-
-![eclipseTypeHierarchyIRecordHandlerManager](./picturesForReadme/eclipseTypeHierarchyIRecordHandlerManager.jpg)
-
-The Java classes that implement [IRecordHandlerManager](https://github.com/ibissource/iaf/blob/master/core/src/main/java/nl/nn/adapterframework/batch/IRecordHandlerManager.java) are highlighted. They are annotated in the first figure of this section as number 3.
-
-The annotation on [IRecordHandlerManager](https://github.com/ibissource/iaf/blob/master/core/src/main/java/nl/nn/adapterframework/batch/IRecordHandlerManager.java) only adds three classes to group `Batch`. The other elements are added by other [@FrankDocGroup](https://github.com/ibissource/iaf/blob/master/iaf-commons/src/main/java/nl/nn/adapterframework/doc/FrankDocGroup.java) annotations. These do not have their `order` field set, see for example [RecordHandlingFlow](https://github.com/ibissource/iaf/blob/master/core/src/main/java/nl/nn/adapterframework/batch/RecordHandlingFlow.java)
-
-![eclipseRecordHandlingFlow](./picturesForReadme/eclipseRecordHandlingFlow.jpg)
-
-The annotation is placed on a class here. Then that class is added to the group in the Frank!Doc web application.
-
-Java classes that do not have or inherit a [@FrankDocGroup](https://github.com/ibissource/iaf/blob/master/iaf-commons/src/main/java/nl/nn/adapterframework/doc/FrankDocGroup.java) annotation are put in group `Other`.
-
-A [@FrankDocGroup](https://github.com/ibissource/iaf/blob/master/iaf-commons/src/main/java/nl/nn/adapterframework/doc/FrankDocGroup.java) annotation is only processed when it appears on a class or interface that appears as the argument of a config child setter. This means: when it gives rise to an [ElementType](src/main/java/org/frankframework/frankdoc/model/ElementType.java).
-
-A Java class can extend a Java class or inherit an interface without a functional meaning. For example, class [MessageStoreSender](https://github.com/ibissource/iaf/blob/master/core/src/main/java/nl/nn/adapterframework/jdbc/MessageStoreSender.java) inherits `ITransactionalStorage`, but that has no functional meaning. Frank configs should not contain elements `MessageStoreSenderMessageLog` or `MessageStoreSenderErrorStorage`. This can be achieved by setting Java annotation `@ExcludeFromType` or JavaDoc tag `@ff.excludeFromType`. Both can take a list of classes as the argument. In case of the JavaDoc tag, do not add `.class` to a class name and separate the classes by a `,`. This annotation is inherited.
+A Java class can extend a Java class or inherit an interface without a functional meaning. For example, class [MessageStoreSender](https://github.com/frankframework/frankframework/blob/master/core/src/main/java/org/frankframework/jdbc/MessageStoreSender.java) inherits `ITransactionalStorage`, but that has no functional meaning. Frank configs should not contain elements `MessageStoreSenderMessageLog` or `MessageStoreSenderErrorStorage`. This can be achieved by setting Java annotation `@ExcludeFromType` or JavaDoc tag `@ff.excludeFromType`. Both can take a list of classes as the argument. In case of the JavaDoc tag, do not add `.class` to a class name and separate the classes by a `,`. This annotation is inherited.
 
 ## Attribute types
 
@@ -282,4 +264,4 @@ The default value is `org.frankframework.pipes.SenderPipe` in this example. The
 
 **@ff.reintroduce:** JavaDoc tag that does the same as Java annotation `@Reintroduce`.
 
-**@Label:** Java annotation that appears on other Java annotations, e.g <code>@Category</code>. A target annotation that is itself annotated with meta-annotation `@Label` produces a label in the Frank!Doc webapp when it is applied above a class of the Frank!Framework sources. The value of the label comes from the `value()` field of the target annotation. The name of the label comes from the `@Label` meta-annotation within the definition of the target annotation; attribute `name`. Labels only apply to classes, not child elements and not attributes. You can have enum-valued label values. In this case, the @EnumLabel annotation is supported. The JSON file that feeds the Frank!Doc webapp provides for each label an overview of all possible values. The label values are sorted alphabetically for non-enum values. Enum values are sorted by the order in the enum type.
+**@Label:** Java annotation that appears on other Java annotations, e.g <code>@Category</code>. A target annotation that is itself annotated with meta-annotation `@Label` produces a label in the Frank!Doc webapp when it is applied above a class of the Frank!Framework sources. The value of the label comes from the `value()` field of the target annotation. The name of the label comes from the `@Label` meta-annotation within the definition of the target annotation; attribute `name`. Labels only apply to classes, not child elements and not attributes. You can have enum-valued label values. In this case, the @EnumLabel annotation is supported. The JSON file that feeds the Frank!Doc webapp provides for each label an overview of all possible values. The label values are sorted alphabetically. If values are of an enum type, the order of the enum constants is NOT used.

frank-doc-doclet/picturesForReadme/eclipseIRecordHandlerManager.jpg

@@ -1,22 +1,23 @@
-/* 
-Copyright 2021, 2022 WeAreFrank! 
+/*
+Copyright 2021, 2022, 2024 WeAreFrank!
 
-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 
+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 
+    http://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, 
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
-See the License for the specific language governing permissions and 
-limitations under the License. 
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
 */
 
 package org.frankframework.frankdoc;
 
 public class Constants {
 	static final String MODULE_ELEMENT_NAME = "Module";
 	static final String MODULE_ELEMENT_DESCRIPTION = "Wrapper element to help split up large configuration files into smaller valid XML files. It may be used as root tag when an XML file contains multiple adapters and/or jobs. The Module element itself does not influence the behavior of Frank configurations.";
+	public static final String FRANK_DOC_GROUP_VALUES_PACKAGE = "org.frankframework.doc.";
 }

frank-doc-doclet/picturesForReadme/eclipseRecordHandlingFlow.jpg

@@ -1,5 +1,5 @@
 /*
-Copyright 2021 WeAreFrank!
+Copyright 2021, 2024 WeAreFrank!
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -16,71 +16,78 @@
 
 package org.frankframework.frankdoc.model;
 
+import lombok.NonNull;
 import org.apache.logging.log4j.Logger;
 import org.frankframework.frankdoc.util.LogUtil;
 import org.frankframework.frankdoc.wrapper.FrankAnnotation;
 import org.frankframework.frankdoc.wrapper.FrankClass;
+import org.frankframework.frankdoc.wrapper.FrankClassRepository;
 import org.frankframework.frankdoc.wrapper.FrankDocException;
+import org.frankframework.frankdoc.wrapper.FrankEnumConstant;
 
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
+
+import static org.frankframework.frankdoc.Constants.FRANK_DOC_GROUP_VALUES_PACKAGE;
 
 class FrankDocGroupFactory {
 	static final String JAVADOC_GROUP_ANNOTATION = "org.frankframework.doc.FrankDocGroup";
+	static final String FRANK_DOC_GROUP_VALUES_CLASS = FRANK_DOC_GROUP_VALUES_PACKAGE + "FrankDocGroupValue";
+	private static final Logger log = LogUtil.getLogger(FrankDocGroupFactory.class);
 
-	private static Logger log = LogUtil.getLogger(FrankDocGroupFactory.class);
-
+	private final Map<String, Integer> valuePositions = new HashMap<>();
 	private final Map<String, FrankDocGroup> allGroups = new HashMap<>();
 
 	// This constructor ensures that group Other is always created, also if there
 	// is no ElementType without a FrankDocGroup annotation. We always need group
 	// Other because it will contain Configuration and Module.
-	FrankDocGroupFactory() {
+	FrankDocGroupFactory(@NonNull FrankClassRepository classes) {
+		try {
+			FrankClass valuesEnum = classes.findClass(FRANK_DOC_GROUP_VALUES_CLASS);
+			if(valuesEnum == null) {
+				log.error("Class [{}] has not been loaded", FRANK_DOC_GROUP_VALUES_CLASS);
+			}
+			int position = 0;
+			for(FrankEnumConstant enumConstant: valuesEnum.getEnumConstants()) {
+				valuePositions.put(enumConstant.getName(), position++);
+			}
+		} catch(FrankDocException e) {
+			log.error("Cannot find value class {} for @FrankDocGroup", FRANK_DOC_GROUP_VALUES_CLASS);
+		}
 		FrankDocGroup groupOther = new FrankDocGroup(FrankDocGroup.GROUP_NAME_OTHER);
 		allGroups.put(groupOther.getName(), groupOther);
 	}
 
 	FrankDocGroup getGroup(FrankClass clazz) {
-		FrankDocGroup result;
 		try {
 			FrankAnnotation annotation = clazz.getAnnotationIncludingInherited(JAVADOC_GROUP_ANNOTATION);
 			if(annotation == null) {
-				result = getGroup(FrankDocGroup.GROUP_NAME_OTHER);
+				log.trace("Class [{}] belongs to group [{}]", () -> clazz.getName(), () -> FrankDocGroup.GROUP_NAME_OTHER);
+				return allGroups.get(FrankDocGroup.GROUP_NAME_OTHER);
 			} else {
-				String groupName = (String) annotation.getValueOf("name");
-				Integer groupOrder = (Integer) annotation.getValueOf("order");
-				log.trace("FrankDocGroup requested for group name {} with new order {}", () -> groupName, () -> groupOrder);
-				result = getGroup(groupName, groupOrder);
+				FrankEnumConstant enumConstant = (FrankEnumConstant) annotation.getValue();
+				String groupName = new EnumValue(enumConstant).getLabel();
+				if(allGroups.containsKey(groupName)) {
+					FrankDocGroup group = allGroups.get(groupName);
+					log.trace("Class [{}] belongs to found group [{}]", () -> clazz.getName(), () -> group.getName());
+					return group;
+				} else {
+					int groupOrder = Optional.of(valuePositions.get(enumConstant.getName())).orElseThrow(
+						() -> new FrankDocException("Programming error: Could not get position of enum constant " + enumConstant.getName(), null));
+					FrankDocGroup group = new FrankDocGroup(groupName);
+					group.setOrder(groupOrder);
+					log.trace("Class [{}] belongs to new group [{}], order is [{}]", () -> clazz.getName(), () -> group.getName(), () -> group.getOrder());
+					allGroups.put(groupName, group);
+					return group;
+				}
 			}
 		} catch(FrankDocException e) {
 			log.error("Class [{}] has invalid @FrankDocGroup: {}", clazz.getName(), e.getMessage());
-			return getGroup(FrankDocGroup.GROUP_NAME_OTHER);
-		}
-		return result;
-	}
-
-	FrankDocGroup getGroup(String groupName, Integer groupOrder) {
-		FrankDocGroup result;
-		result = getGroup(groupName);
-		if(groupOrder == null) {
-			// The Doclet API does not provide the default value of the @FrankDocGroup annotation.
-			// We need to repeat it here.
-			groupOrder = Integer.MAX_VALUE;
-		}
-		result.setOrder(groupOrder);
-		return result;
-	}
-
-	private FrankDocGroup getGroup(String name) {
-		if(allGroups.containsKey(name)) {
-			return allGroups.get(name);
-		} else {
-			FrankDocGroup group = new FrankDocGroup(name);
-			allGroups.put(name, group);
-			return group;
+			return allGroups.get(FrankDocGroup.GROUP_NAME_OTHER);
 		}
 	}
 

frank-doc-doclet/picturesForReadme/eclipseTypeHierarchyIRecordHandlerManager.jpg

@@ -1,5 +1,5 @@
 /*
-Copyright 2020 - 2023 WeAreFrank!
+Copyright 2020 - 2024 WeAreFrank!
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -64,7 +64,7 @@ public class FrankDocModel {
 
 	private final @Getter Map<String, List<ConfigChildSetterDescriptor>> configChildDescriptors = new HashMap<>();
 
-	private final FrankDocGroupFactory groupFactory = new FrankDocGroupFactory();
+	private final FrankDocGroupFactory groupFactory;
 	private @Getter List<FrankDocGroup> groups;
 
 	// We want to iterate FrankElement in the order they are created, to be able
@@ -86,6 +86,7 @@ public class FrankDocModel {
 
 	FrankDocModel(FrankClassRepository classRepository, String rootClassName) {
 		this.classRepository = classRepository;
+		this.groupFactory = new FrankDocGroupFactory(classRepository);
 		this.rootClassName = rootClassName;
 	}
 

frank-doc-doclet/picturesForReadme/webapp-groups-batch.jpg

@@ -1,5 +1,5 @@
 /*
-Copyright 2020 - 2023 WeAreFrank!
+Copyright 2020 - 2024 WeAreFrank!
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -254,7 +254,7 @@ void handleSpecificLabel(FrankAnnotation labelAddingAnnotation, LabelValues labe
 			// This considers annotation @EnumLabel
 			EnumValue value = new EnumValue(enumConstant);
 			labels.add(new FrankLabel(label, value.getLabel()));
-			labelValues.addEnumValue(label, value.getLabel(), enumConstant.getPosition());
+			labelValues.addValue(label, value.getLabel());
 		} else {
 			labels.add(new FrankLabel(label, rawValue.toString()));
 			labelValues.addValue(label, rawValue.toString());

frank-doc-doclet/src/main/java/org/frankframework/frankdoc/Constants.java

@@ -1,5 +1,5 @@
 /*
-Copyright 2022 WeAreFrank!
+Copyright 2022, 2024 WeAreFrank!
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -30,62 +30,11 @@
 public class LabelValues {
 	private static final Logger log = LogUtil.getLogger(LabelValues.class);
 
-	private abstract static class SortableValue implements Comparable<SortableValue> {
-		private @Getter final String value;
-
-		SortableValue(String value) {
-			this.value = value;
-		}
-
-		@Override
-		public String toString() {
-			return value;
-		}
-	}
-
-	private static final class EnumValue extends SortableValue {
-		private final int order;
-
-		EnumValue(String value, int order) {
-			super(value);
-			this.order = order;
-		}
-
-		@Override
-		public int compareTo(SortableValue other) {
-			// It is a programming error if a label has both enum values and
-			// non-enum values. If this happens, a ClassCastException will occur.
-			return Integer.compare(order, ((EnumValue) other).order);
-		}
-	}
-
-	private static final class SimpleValue extends SortableValue {
-		SimpleValue(String value) {
-			super(value);
-		}
-
-		@Override
-		public int compareTo(SortableValue other) {
-			// It is a programming error if a label has both enum values and
-			// non-enum values. If this happens, a ClassCastException will occur.
-			return getValue().compareTo(((SimpleValue) other).getValue());
-		}
-	}
-
 	private boolean isInitialized = false;
-	private final Map<String, List<SortableValue>> data = new HashMap<>();
+	private final Map<String, List<String>> data = new HashMap<>();
 
 	void addValue(String label, String value) {
-		log.trace("Label [{}] can have non-enum value [{}]", label, value);
-		add(label, new SimpleValue(value));
-	}
-
-	void addEnumValue(String label, String value, int order) {
-		log.trace("Label [{}] can have enum value [{}], position is [{}]", label, value, order);
-		add(label, new EnumValue(value, order));
-	}
-
-	private void add(String label, SortableValue value) {
+		log.trace("Label [{}] can have value [{}]", label, value);
 		data.putIfAbsent(label, new ArrayList<>());
 		data.get(label).add(value);
 	}
@@ -114,7 +63,6 @@ private void checkInitialized() {
 	List<String> getAllValuesOfLabel(String label) {
 		checkInitialized();
 		return data.get(label).stream()
-				.map(SortableValue::getValue)
 				.distinct()
 				.collect(Collectors.toList());
 	}