Repository: camel Updated Branches: refs/heads/master 92a351e34 -> f2fa80268
CAMEL-7999: apt compiler to generate json schema documentation for the model, whcih we later use to enrich the xml xsd to include documentation. Work in progress. Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/1615993b Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/1615993b Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/1615993b Branch: refs/heads/master Commit: 1615993b7743218e69cc82fb56ffa99227635a9b Parents: 92a351e Author: Claus Ibsen <davscl...@apache.org> Authored: Wed Dec 31 10:03:26 2014 +0100 Committer: Claus Ibsen <davscl...@apache.org> Committed: Wed Dec 31 10:04:49 2014 +0100 ---------------------------------------------------------------------- .../camel/tools/apt/EipAnnotationProcessor.java | 62 ++++++++++++-------- .../tools/apt/EndpointAnnotationProcessor.java | 35 ++++++++--- .../camel/tools/apt/JsonSchemaHelper.java | 10 +++- 3 files changed, 71 insertions(+), 36 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/1615993b/tooling/apt/src/main/java/org/apache/camel/tools/apt/EipAnnotationProcessor.java ---------------------------------------------------------------------- diff --git a/tooling/apt/src/main/java/org/apache/camel/tools/apt/EipAnnotationProcessor.java b/tooling/apt/src/main/java/org/apache/camel/tools/apt/EipAnnotationProcessor.java index a4aa927..eb877c7 100644 --- a/tooling/apt/src/main/java/org/apache/camel/tools/apt/EipAnnotationProcessor.java +++ b/tooling/apt/src/main/java/org/apache/camel/tools/apt/EipAnnotationProcessor.java @@ -49,8 +49,6 @@ import static org.apache.camel.tools.apt.Strings.safeNull; // TODO: figure out a way to specify default value in the model classes which this APT can read -// TODO: add support for @deprecated - /** * Process all camel-core's model classes (EIPs and DSL) and generate json schema documentation */ @@ -173,7 +171,7 @@ public class EipAnnotationProcessor extends AbstractAnnotationProcessor { String doc = entry.getDocumentation(); doc = sanitizeDescription(doc, false); buffer.append(JsonSchemaHelper.toJson(entry.getName(), entry.getKind(), entry.isRequired(), entry.getType(), entry.getDefaultValue(), doc, - entry.isEnumType(), entry.getEnums(), entry.isOneOf(), entry.getOneOfTypes())); + entry.isDeprecated(), entry.isEnumType(), entry.getEnums(), entry.isOneOf(), entry.getOneOfTypes())); } buffer.append("\n }"); @@ -311,7 +309,9 @@ public class EipAnnotationProcessor extends AbstractAnnotationProcessor { } } - EipOption ep = new EipOption(name, "attribute", fieldTypeName, required, "", docComment, isEnum, enums, false, null); + boolean deprecated = fieldElement.getAnnotation(Deprecated.class) != null; + + EipOption ep = new EipOption(name, "attribute", fieldTypeName, required, "", docComment, deprecated, isEnum, enums, false, null); eipOptions.add(ep); return false; @@ -372,7 +372,9 @@ public class EipAnnotationProcessor extends AbstractAnnotationProcessor { } } - EipOption ep = new EipOption(name, kind, fieldTypeName, required, "", docComment, isEnum, enums, isOneOf, oneOfTypes); + boolean deprecated = fieldElement.getAnnotation(Deprecated.class) != null; + + EipOption ep = new EipOption(name, kind, fieldTypeName, required, "", docComment, deprecated, isEnum, enums, isOneOf, oneOfTypes); eipOptions.add(ep); } } @@ -401,7 +403,7 @@ public class EipAnnotationProcessor extends AbstractAnnotationProcessor { oneOfTypes.add(child); } - EipOption ep = new EipOption(name, kind, fieldTypeName, required, "", docComment, false, null, true, oneOfTypes); + EipOption ep = new EipOption(name, kind, fieldTypeName, required, "", docComment, false, false, null, true, oneOfTypes); eipOptions.add(ep); } } @@ -413,52 +415,52 @@ public class EipAnnotationProcessor extends AbstractAnnotationProcessor { // group String docComment = findJavaDoc(elementUtils, null, "group", classElement, true); - EipOption ep = new EipOption("group", "attribute", "java.lang.String", false, "", docComment, false, null, false, null); + EipOption ep = new EipOption("group", "attribute", "java.lang.String", false, "", docComment, false, false, null, false, null); eipOptions.add(ep); // group docComment = findJavaDoc(elementUtils, null, "streamCache", classElement, true); - ep = new EipOption("streamCache", "attribute", "java.lang.String", false, "", docComment, false, null, false, null); + ep = new EipOption("streamCache", "attribute", "java.lang.String", false, "", docComment, false, false, null, false, null); eipOptions.add(ep); // trace docComment = findJavaDoc(elementUtils, null, "trace", classElement, true); - ep = new EipOption("trace", "attribute", "java.lang.String", false, "", docComment, false, null, false, null); + ep = new EipOption("trace", "attribute", "java.lang.String", false, "", docComment, false, false, null, false, null); eipOptions.add(ep); // trace docComment = findJavaDoc(elementUtils, null, "messageHistory", classElement, true); - ep = new EipOption("messageHistory", "attribute", "java.lang.String", false, "", docComment, false, null, false, null); + ep = new EipOption("messageHistory", "attribute", "java.lang.String", false, "", docComment, false, false, null, false, null); eipOptions.add(ep); // trace docComment = findJavaDoc(elementUtils, null, "handleFault", classElement, true); - ep = new EipOption("handleFault", "attribute", "java.lang.String", false, "", docComment, false, null, false, null); + ep = new EipOption("handleFault", "attribute", "java.lang.String", false, "", docComment, false, false, null, false, null); eipOptions.add(ep); // delayer docComment = findJavaDoc(elementUtils, null, "delayer", classElement, true); - ep = new EipOption("delayer", "attribute", "java.lang.String", false, "", docComment, false, null, false, null); + ep = new EipOption("delayer", "attribute", "java.lang.String", false, "", docComment, false, false, null, false, null); eipOptions.add(ep); // autoStartup docComment = findJavaDoc(elementUtils, null, "autoStartup", classElement, true); - ep = new EipOption("autoStartup", "attribute", "java.lang.String", false, "", docComment, false, null, false, null); + ep = new EipOption("autoStartup", "attribute", "java.lang.String", false, "", docComment, false, false, null, false, null); eipOptions.add(ep); // startupOrder docComment = findJavaDoc(elementUtils, null, "startupOrder", classElement, true); - ep = new EipOption("startupOrder", "attribute", "java.lang.Integer", false, "", docComment, false, null, false, null); + ep = new EipOption("startupOrder", "attribute", "java.lang.Integer", false, "", docComment, false, false, null, false, null); eipOptions.add(ep); // errorHandlerRef docComment = findJavaDoc(elementUtils, null, "errorHandlerRef", classElement, true); - ep = new EipOption("errorHandlerRef", "attribute", "java.lang.String", false, "", docComment, false, null, false, null); + ep = new EipOption("errorHandlerRef", "attribute", "java.lang.String", false, "", docComment, false, false, null, false, null); eipOptions.add(ep); // routePolicyRef docComment = findJavaDoc(elementUtils, null, "routePolicyRef", classElement, true); - ep = new EipOption("routePolicyRef", "attribute", "java.lang.String", false, "", docComment, false, null, false, null); + ep = new EipOption("routePolicyRef", "attribute", "java.lang.String", false, "", docComment, false, false, null, false, null); eipOptions.add(ep); // shutdownRoute @@ -466,7 +468,7 @@ public class EipAnnotationProcessor extends AbstractAnnotationProcessor { enums.add("Default"); enums.add("Defer"); docComment = findJavaDoc(elementUtils, null, "shutdownRoute", classElement, true); - ep = new EipOption("shutdownRoute", "attribute", "org.apache.camel.ShutdownRoute", false, "", docComment, true, enums, false, null); + ep = new EipOption("shutdownRoute", "attribute", "org.apache.camel.ShutdownRoute", false, "", docComment, false, true, enums, false, null); eipOptions.add(ep); // shutdownRunningTask @@ -474,14 +476,14 @@ public class EipAnnotationProcessor extends AbstractAnnotationProcessor { enums.add("CompleteCurrentTaskOnly"); enums.add("CompleteAllTasks"); docComment = findJavaDoc(elementUtils, null, "shutdownRunningTask", classElement, true); - ep = new EipOption("shutdownRunningTask", "attribute", "org.apache.camel.ShutdownRunningTask", false, "", docComment, true, enums, false, null); + ep = new EipOption("shutdownRunningTask", "attribute", "org.apache.camel.ShutdownRunningTask", false, "", docComment, false, true, enums, false, null); eipOptions.add(ep); // inputs Set<String> oneOfTypes = new TreeSet<String>(); oneOfTypes.add("from"); docComment = findJavaDoc(elementUtils, null, "inputs", classElement, true); - ep = new EipOption("inputs", "element", "java.util.List<org.apache.camel.model.FromDefinition>", true, "", docComment, false, null, true, oneOfTypes); + ep = new EipOption("inputs", "element", "java.util.List<org.apache.camel.model.FromDefinition>", true, "", docComment, false, false, null, true, oneOfTypes); eipOptions.add(ep); // outputs @@ -506,7 +508,7 @@ public class EipAnnotationProcessor extends AbstractAnnotationProcessor { oneOfTypes.remove("route"); docComment = findJavaDoc(elementUtils, null, "outputs", classElement, true); - ep = new EipOption("outputs", "element", "java.util.List<org.apache.camel.model.ProcessorDefinition<?>>", true, "", docComment, false, null, true, oneOfTypes); + ep = new EipOption("outputs", "element", "java.util.List<org.apache.camel.model.ProcessorDefinition<?>>", true, "", docComment, false, false, null, true, oneOfTypes); eipOptions.add(ep); } @@ -520,19 +522,19 @@ public class EipAnnotationProcessor extends AbstractAnnotationProcessor { // id String docComment = findJavaDoc(elementUtils, null, "id", classElement, true); - EipOption ep = new EipOption("id", "attribute", "java.lang.String", false, "", docComment, false, null, false, null); + EipOption ep = new EipOption("id", "attribute", "java.lang.String", false, "", docComment, false, false, null, false, null); eipOptions.add(ep); // description docComment = findJavaDoc(elementUtils, null, "description", classElement, true); - ep = new EipOption("description", "element", "org.apache.camel.model.DescriptionDefinition", false, "", docComment, false, null, false, null); + ep = new EipOption("description", "element", "org.apache.camel.model.DescriptionDefinition", false, "", docComment, false, false, null, false, null); eipOptions.add(ep); // lets skip custom id as it has no value for end users to configure if (!skipUnwanted) { // custom id docComment = findJavaDoc(elementUtils, null, "customId", classElement, true); - ep = new EipOption("customId", "attribute", "java.lang.String", false, "", docComment, false, null, false, null); + ep = new EipOption("customId", "attribute", "java.lang.String", false, "", docComment, false, false, null, false, null); eipOptions.add(ep); } } @@ -569,7 +571,9 @@ public class EipAnnotationProcessor extends AbstractAnnotationProcessor { } } - EipOption ep = new EipOption(name, kind, fieldTypeName, true, "", "", false, null, true, oneOfTypes); + boolean deprecated = fieldElement.getAnnotation(Deprecated.class) != null; + + EipOption ep = new EipOption(name, kind, fieldTypeName, true, "", "", deprecated, false, null, true, oneOfTypes); eipOptions.add(ep); } } @@ -609,7 +613,7 @@ public class EipAnnotationProcessor extends AbstractAnnotationProcessor { // remove some types which are not intended as an output in eips oneOfTypes.remove("route"); - EipOption ep = new EipOption(name, kind, fieldTypeName, true, "", "", false, null, true, oneOfTypes); + EipOption ep = new EipOption(name, kind, fieldTypeName, true, "", "", false, false, null, true, oneOfTypes); eipOptions.add(ep); } } @@ -672,12 +676,13 @@ public class EipAnnotationProcessor extends AbstractAnnotationProcessor { private boolean required; private String defaultValue; private String documentation; + private boolean deprecated; private boolean enumType; private Set<String> enums; private boolean oneOf; private Set<String> oneOfTypes; - private EipOption(String name, String kind, String type, boolean required, String defaultValue, String documentation, + private EipOption(String name, String kind, String type, boolean required, String defaultValue, String documentation, boolean deprecated, boolean enumType, Set<String> enums, boolean oneOf, Set<String> oneOfTypes) { this.name = name; this.kind = kind; @@ -685,6 +690,7 @@ public class EipAnnotationProcessor extends AbstractAnnotationProcessor { this.required = required; this.defaultValue = defaultValue; this.documentation = documentation; + this.deprecated = deprecated; this.enumType = enumType; this.enums = enums; this.oneOf = oneOf; @@ -715,6 +721,10 @@ public class EipAnnotationProcessor extends AbstractAnnotationProcessor { return documentation; } + public boolean isDeprecated() { + return deprecated; + } + public boolean isEnumType() { return enumType; } http://git-wip-us.apache.org/repos/asf/camel/blob/1615993b/tooling/apt/src/main/java/org/apache/camel/tools/apt/EndpointAnnotationProcessor.java ---------------------------------------------------------------------- diff --git a/tooling/apt/src/main/java/org/apache/camel/tools/apt/EndpointAnnotationProcessor.java b/tooling/apt/src/main/java/org/apache/camel/tools/apt/EndpointAnnotationProcessor.java index a091ab7..592a048 100644 --- a/tooling/apt/src/main/java/org/apache/camel/tools/apt/EndpointAnnotationProcessor.java +++ b/tooling/apt/src/main/java/org/apache/camel/tools/apt/EndpointAnnotationProcessor.java @@ -45,6 +45,8 @@ import static org.apache.camel.tools.apt.Strings.canonicalClassName; import static org.apache.camel.tools.apt.Strings.getOrElse; import static org.apache.camel.tools.apt.Strings.isNullOrEmpty; +// TODO: add support for @Label + /** * Processes all Camel {@link UriEndpoint}s and generate json schema and html documentation for the endpoint/component. */ @@ -190,7 +192,7 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { buffer.append(","); } buffer.append("\n "); - buffer.append(JsonSchemaHelper.toJson(path.getName(), "path", null, path.getType(), "", path.getDocumentation(), + buffer.append(JsonSchemaHelper.toJson(path.getName(), "path", null, path.getType(), "", path.getDocumentation(), path.isDeprecated(), path.isEnumType(), path.getEnums(), false, null)); } @@ -205,7 +207,7 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { // as its json we need to sanitize the docs String doc = entry.getDocumentationWithNotes(); doc = sanitizeDescription(doc, false); - buffer.append(JsonSchemaHelper.toJson(entry.getName(), "parameter", null, entry.getType(), entry.getDefaultValue(), doc, + buffer.append(JsonSchemaHelper.toJson(entry.getName(), "parameter", null, entry.getType(), entry.getDefaultValue(), doc, entry.isDeprecated(), entry.isEnumType(), entry.getEnums(), false, null)); } buffer.append("\n }"); @@ -233,6 +235,7 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { writer.println(" <th>Name</th>"); writer.println(" <th>Kind</th>"); writer.println(" <th>Type</th>"); + writer.println(" <th>Deprecated</th>"); writer.println(" <th>Default Value</th>"); writer.println(" <th>Enum Values</th>"); writer.println(" <th>Description</th>"); @@ -241,8 +244,9 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { for (EndpointPath path : endpointPaths) { writer.println(" <tr>"); writer.println(" <td>" + path.getName() + "</td>"); - writer.println(" <td>" + path.getType() + "</td>"); writer.println(" <td>" + "path" + "</td>"); + writer.println(" <td>" + path.getType() + "</td>"); + writer.println(" <td>" + path.isDeprecated() + "</td>"); writer.println(" <td>" + path.getEnumValuesAsHtml() + "</td>"); writer.println(" <td>" + path.getDocumentation() + "</td>"); writer.println(" </tr>"); @@ -251,8 +255,9 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { for (EndpointOption option : endpointOptions) { writer.println(" <tr>"); writer.println(" <td>" + option.getName() + "</td>"); - writer.println(" <td>" + option.getType() + "</td>"); writer.println(" <td>" + "parameter" + "</td>"); + writer.println(" <td>" + option.getType() + "</td>"); + writer.println(" <td>" + option.isDeprecated() + "</td>"); writer.println(" <td>" + option.getDefaultValue() + "</td>"); writer.println(" <td>" + option.getEnumValuesAsHtml() + "</td>"); writer.println(" <td>" + option.getDocumentationWithNotes() + "</td>"); @@ -326,6 +331,8 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { List<VariableElement> fieldElements = ElementFilter.fieldsIn(classElement.getEnclosedElements()); for (VariableElement fieldElement : fieldElements) { + boolean deprecated = fieldElement.getAnnotation(Deprecated.class) != null; + UriPath path = fieldElement.getAnnotation(UriPath.class); String fieldName = fieldElement.getSimpleName().toString(); if (path != null) { @@ -358,7 +365,7 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { } } - EndpointPath ep = new EndpointPath(name, fieldTypeName, docComment, isEnum, enums); + EndpointPath ep = new EndpointPath(name, fieldTypeName, docComment, deprecated, isEnum, enums); endpointPaths.add(ep); } @@ -410,7 +417,7 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { } } - EndpointOption option = new EndpointOption(name, fieldTypeName, defaultValue, defaultValueNote, docComment.trim(), isEnum, enums); + EndpointOption option = new EndpointOption(name, fieldTypeName, defaultValue, defaultValueNote, docComment.trim(), deprecated, isEnum, enums); endpointOptions.add(option); } } @@ -519,16 +526,18 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { private String defaultValue; private String defaultValueNote; private String documentation; + private boolean deprecated; private boolean enumType; private Set<String> enums; private EndpointOption(String name, String type, String defaultValue, String defaultValueNote, - String documentation, boolean enumType, Set<String> enums) { + String documentation, boolean deprecated, boolean enumType, Set<String> enums) { this.name = name; this.type = type; this.defaultValue = defaultValue; this.defaultValueNote = defaultValueNote; this.documentation = documentation; + this.deprecated = deprecated; this.enumType = enumType; this.enums = enums; } @@ -549,6 +558,10 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { return documentation; } + public boolean isDeprecated() { + return deprecated; + } + public String getEnumValuesAsHtml() { CollectionStringBuffer csb = new CollectionStringBuffer("<br/>"); if (enums != null && enums.size() > 0) { @@ -607,14 +620,16 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { private String name; private String type; private String documentation; + private boolean deprecated; private boolean enumType; private Set<String> enums; - private EndpointPath(String name, String type, String documentation, + private EndpointPath(String name, String type, String documentation, boolean deprecated, boolean enumType, Set<String> enums) { this.name = name; this.type = type; this.documentation = documentation; + this.deprecated = deprecated; this.enumType = enumType; this.enums = enums; } @@ -631,6 +646,10 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { return documentation; } + public boolean isDeprecated() { + return deprecated; + } + public String getEnumValuesAsHtml() { CollectionStringBuffer csb = new CollectionStringBuffer("<br/>"); if (enums != null && enums.size() > 0) { http://git-wip-us.apache.org/repos/asf/camel/blob/1615993b/tooling/apt/src/main/java/org/apache/camel/tools/apt/JsonSchemaHelper.java ---------------------------------------------------------------------- diff --git a/tooling/apt/src/main/java/org/apache/camel/tools/apt/JsonSchemaHelper.java b/tooling/apt/src/main/java/org/apache/camel/tools/apt/JsonSchemaHelper.java index ae0178e..303cf2d 100644 --- a/tooling/apt/src/main/java/org/apache/camel/tools/apt/JsonSchemaHelper.java +++ b/tooling/apt/src/main/java/org/apache/camel/tools/apt/JsonSchemaHelper.java @@ -31,15 +31,16 @@ final class JsonSchemaHelper { } public static String toJson(String name, String kind, Boolean required, String type, String defaultValue, String description, - boolean enumType, Set<String> enums, boolean oneOfType, Set<String> oneOffTypes) { + Boolean deprecated, boolean enumType, Set<String> enums, boolean oneOfType, Set<String> oneOffTypes) { String typeName = JsonSchemaHelper.getType(type, enumType); StringBuilder sb = new StringBuilder(); sb.append(Strings.doubleQuote(name)); sb.append(": { \"kind\": "); sb.append(Strings.doubleQuote(kind)); + if (required != null) { - sb.append(": \"required\": "); + sb.append(", \"required\": "); sb.append(Strings.doubleQuote(required.toString())); } @@ -72,6 +73,11 @@ final class JsonSchemaHelper { sb.append(", \"javaType\": \"" + type + "\""); } + if (deprecated != null) { + sb.append(", \"deprecated\": "); + sb.append(Strings.doubleQuote(deprecated.toString())); + } + if (!Strings.isNullOrEmpty(defaultValue)) { sb.append(", \"defaultValue\": "); sb.append(Strings.doubleQuote(defaultValue));
