Claus Ibsen created CAMEL-8197:
----------------------------------
Summary: Create Maven plugin to inject EIP documentation into the
spring and blueprint XML DSL
Key: CAMEL-8197
URL: https://issues.apache.org/jira/browse/CAMEL-8197
Project: Camel
Issue Type: Sub-task
Components: eip, tooling
Reporter: Claus Ibsen
Fix For: 2.15.0
So we can include documentation out of the box in the XSD schema files, which
allows end users to better work with Camel, as their IDE editors can show the
documentation in the IDE.
To do this we need to
1)
Create a new Maven plugin at
https://github.com/apache/camel/tree/master/tooling/maven
which can be inspired by
https://github.com/apache/camel/tree/master/tooling/maven/camel-package-maven-plugin
2)
Run this plugin in camel-spring and camel-blueprint, so it can read the
camel-spring.xsd, camel-blueprint.xsd file, and inject documentation.
3)
Parse the XSD maybe using SAX, and inject the documentation.
For each xs:element in the top of the schema file
http://camel.apache.org/schema/spring/camel-spring.xsd
Then use the name, eg (name=split)
{code}
<xs:element name="split" type="tns:splitDefinition"/>
{code}
To find the split.json file in camel-core. Then the json file has the
documentation for that type (including inherited types).
So for the split definition
{code}
<xs:complexType name="splitDefinition">
<xs:complexContent>
<xs:extension base="tns:expressionNode">
<xs:sequence/>
<xs:attribute name="parallelProcessing" type="xs:boolean"/>
<xs:attribute name="strategyRef" type="xs:string"/>
<xs:attribute name="strategyMethodName" type="xs:string"/>
<xs:attribute name="strategyMethodAllowNull" type="xs:boolean"/>
<xs:attribute name="executorServiceRef" type="xs:string"/>
<xs:attribute name="streaming" type="xs:boolean"/>
<xs:attribute name="stopOnException" type="xs:boolean"/>
<xs:attribute name="timeout" type="xs:long"/>
<xs:attribute name="onPrepareRef" type="xs:string"/>
<xs:attribute name="shareUnitOfWork" type="xs:boolean"/>
<xs:anyAttribute namespace="##other" processContents="skip"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
{code}
We can find the description of these attributes, and elements from the json
file.
For example for the streaming attribute we have
{code}
"streaming": { "kind": "attribute": "required": "false", "type": "boolean",
"javaType": "java.lang.Boolean", "description": "The splitter should use
streaming -- exchanges are being sent as the data for them becomes available.
This improves throughput and memory usage but it has a drawback: - the sent
exchanges will no longer contain the link org.apache.camel.ExchangeSPLIT_SIZE
header property"
{code}
Then add the needed xs:annotation to document it.
http://www.w3schools.com/schema/el_annotation.asp
Which should be
{code}
<xs:annotation>
<xs:documentation xml:lang="en">
The splitter should use streaming -- exchanges are being sent as the data for
them becomes available. This improves throughput and memory usage but it has a
drawback: - the sent exchanges will no longer contain the link
org.apache.camel.ExchangeSPLIT_SIZE header property
</xs:documentation>
</xs:annotation>
{code}
Notice that the xsd will become bigger due the verbosity of how to annotate xsd
fields.
Mind that sometimes there is not yet documentation, so check for not empty
value.
To parse the json file, then use this class from camel-core
{code}
List<Map<String, String>> rows = JsonSchemaHelper.parseJsonSchema("properties",
json, true);
{code}
Then you have a map with key/value for all those values.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
