[CAMEL-7999] Camel Toolbox - Easy information about all Camel components and the release for tooling

• Type: New Feature
• Status: Resolved
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 2.15.0
• Component/s: camel-core, jmx, tooling
• Estimated Complexity: Unknown
• Assignee: Claus Ibsen
• Reporter: Claus Ibsen
• Created: 06/Nov/14 13:40
• Updated: 01/Mar/15 07:44
• Resolved: 01/Mar/15 07:44

Description

A Camel release contains many components, and we have the ability to let components document which options they offer.

Though there is currently a few shortcomings that can be improved

• the component json schema is currently runtime generated, which requires to load the component and create an instance of it. Instead we should build-time generate it, which we do today with the camel apt compiler plugin. DONE

• we should include documentation about the option from the javadoc, that allows end users to fully document a component using plain java getter/settr with javadocs, and add those @UriParam annotations for the apt compiler to detect and leverage DONE

• add a module that embeds all these json schema files in a single module, and also other information, such as the xml schemas, and what else can be handy. Then there is a single module as a one stop shop for tooling and whatnot to gather information about a Camel release. There is a new camel-catalog module that contains this now. DONE

• allow at runtime to explain an endpoint uri what the options in use are, eg as we got the json schema, we can add mbeans that can explain those options, than we can use in tooling, JMX, karaf commands etc. And also IDE editors etc DONE

• add JMX/Java API to explain a EIP and also get a tabular data with a list of all EIPs and their data. DONE

• enrich the dsl xml to inject javadoc for the eips into the xml schema, so we have documented in the xsd directly that any tooling can use. We have a old ticket about this. But the apt compiler plugin can detect the @JAXB annotations in the model and extract the javadoc, and generate a json schema with, and then we can load those and enrich into the generated xsd, or enrich into the jaxb model generator, or something.

• migrate more Camel components to include javadoc as documentation for their options DONE for all camel-core. Other components will be migrated over time.

• figure out how to specify a default value in the json schema. Unfortunately the apt plugin cannot grab that from the source code. So the only solution I can think of now is to add an attribute to the @UriParam where you can specify that, eg this is also what I have seen others do. There is now a defaultValue attribute on UriParam to be used. DONE

• add component summary to component json file so we have a description of what the component does DONE

• add attribute to @UriEndpoint to link it to the component class, so we can include the class name of the component in the json schema, which allows Camel to link from component class -> schema. eg the point is that if people define a component as "activemq" we do not know its the jms schema that has its documentation. Though we can infer this by the component class name. And alternative is for a component to have an api to return its original schema name etc. So activemq can say "jms" etc. We can resolve this by iterating the component data, and find the FQN of the components. DONE

• add @UriComponent annotation to component class which allows end users to provide meta-data about the component. Currently we grab a summary of what the component does from the maven pom.xml. Though this annotation prepares us for being able to scan the component class as well for which option it provides, so we can have out of the box documentation for that also. We detect getter/setter pairs as component options, and the apt plugin generates those in the schema. Use @Metadata to configure the options. DONE

• add JMX/Java API to explain a component and also get a tabular data with a list of all components and that data. DONE

• improve karaf commands to use the component information to show that also DONE

• add name of karaf feature of the component, eg its 99% came-xxx, but there may be some exceptions. We can likely add a property to the maven plugin that generates component.properties to include the karaf feature name as the artifactId by default. But allow to set a property in the pom.xml in case there is another name, or no karaf feature

• add support for @UriPath in apt plugin DONE

• javadoc documentation is not acessible from components which extend other components (eg javadoc from source code of parent components). For example camel-ftp extending file in camel-core etc. Added description to @UriParam to be used for this purpose. DONE

• add support for associating label(s) to a endpoint so we can group the various Camel components. A bit like this page: http://camel.apache.org/component-list-grouped.html DONE

• rename @Label to something more generic like @Metadata or something, so we can introduce new attributes for new stuff. For example a link which refers to the project website, or an icon to refer to an icon that symbol the component, etc. DONE

• we now support components + eip with json schema and documentation and jmx + commands out of the box. We should look into adding the same for languages and data formats. Then we have all of them covered.DONE

Issue Links

• is related to: CAMEL-8361 Camel Components - Generate per component XML schema
• is related to: CAMEL-8362 Camel Components - Generate per component Java fluent builder
• is related to: CAMEL-8211 Camel commands - camel-component-info
• is related to: CAMEL-8260 Camel EIP model - Ensure consistent getter/setter style also for Boolean types
• relates to: CAMEL-8334 EIP documentation maven plugin should aslo inject documentation to abstract/base types