[REFACTORING] Self-Describing Driver Parameters

[Julian Feinauer <j....@pragmaticminds.de>]

Hi,

as we plan to do a refactoring for the next release (0.6) I wanted to bring up an “older” Issue PLC4X-138.
My suggestion is to do it somehow similar to what Apache Camel or Apache Maven do.
Basically, they use Annotations in their Configuration POJOs to generate Documentation about all available configuration options, default values, etc.

For Example for Camel, see https://github.com/Talend/apache-camel/blob/master/camel-core/src/main/java/org/apache/camel/component/timer/TimerEndpoint.java

A short Snippet:
```
@UriEndpoint(firstVersion = "1.0.0", scheme = "timer", title = "Timer", syntax = "timer:timerName", consumerOnly = true, consumerClass = TimerConsumer.class, label = "core,scheduling")

public class TimerEndpoint extends DefaultEndpoint implements MultipleConsumersSupport {

@UriPath @Metadata(required = "true")

private String timerName;

@UriParam(defaultValue = "1000", description = "If greater than 0, generate periodic events every period milliseconds."

+ " You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).")

private long period = 1000;

@UriParam(defaultValue = "1000", description = "Miliseconds before first event is triggered."

+ " You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).")

private long delay = 1000;

@UriParam(defaultValue = "0")

private long repeatCount;

@UriParam

private boolean fixedRate;

@UriParam(defaultValue = "true", label = "advanced")

private boolean daemon = true;


```

So this would give us the possibility to generate custom UIs for all drivers and nice visualization (e.g. on the Homepage).
See e.g. the (generated) Camel Homepage (for above Timer): https://camel.apache.org/components/latest/timer-component.html

What are your thoughts?

Julian

Re: [REFACTORING] Self-Describing Driver Parameters

[Niclas Hedhman <he...@gmail.com>]

If I am not mistaken, the annotations in Camel are used in runtime as well,
and the additional description is a "small extra", compared to no
annotations with at the start.

That said; annotations were added with multiple purposes, and one explicit
such purpose was for documentation purposes, I think it is a positive idea,
but it could be a major undertaking in comparison.

Cheers
Niclas

On Wed, Oct 23, 2019, 21:06 Julian Feinauer <j....@pragmaticminds.de>
wrote:

> Hi,
>
> as we plan to do a refactoring for the next release (0.6) I wanted to
> bring up an “older” Issue PLC4X-138.
> My suggestion is to do it somehow similar to what Apache Camel or Apache
> Maven do.
> Basically, they use Annotations in their Configuration POJOs to generate
> Documentation about all available configuration options, default values,
> etc.
>
> For Example for Camel, see
> https://github.com/Talend/apache-camel/blob/master/camel-core/src/main/java/org/apache/camel/component/timer/TimerEndpoint.java
>
> A short Snippet:
> ```
> @UriEndpoint(firstVersion = "1.0.0", scheme = "timer", title = "Timer",
> syntax = "timer:timerName", consumerOnly = true, consumerClass =
> TimerConsumer.class, label = "core,scheduling")
>
> public class TimerEndpoint extends DefaultEndpoint implements
> MultipleConsumersSupport {
>
> @UriPath @Metadata(required = "true")
>
> private String timerName;
>
> @UriParam(defaultValue = "1000", description = "If greater than 0,
> generate periodic events every period milliseconds."
>
> + " You can also specify time values using units, such as 60s (60
> seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).")
>
> private long period = 1000;
>
> @UriParam(defaultValue = "1000", description = "Miliseconds before first
> event is triggered."
>
> + " You can also specify time values using units, such as 60s (60
> seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).")
>
> private long delay = 1000;
>
> @UriParam(defaultValue = "0")
>
> private long repeatCount;
>
> @UriParam
>
> private boolean fixedRate;
>
> @UriParam(defaultValue = "true", label = "advanced")
>
> private boolean daemon = true;
>
>
> ```
>
> So this would give us the possibility to generate custom UIs for all
> drivers and nice visualization (e.g. on the Homepage).
> See e.g. the (generated) Camel Homepage (for above Timer):
> https://camel.apache.org/components/latest/timer-component.html
>
> What are your thoughts?
>
> Julian
>