Mailing-List: contact dev-help@camel.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@camel.apache.org
MIME-Version: 1.0
In-Reply-To: 
 <CAMpNYoYGeUXm8q=75dn1Y5Yp+u=0sktAXtUVDh9JVUTJGJgFQg@mail.gmail.com>
References: 
 <CAMpNYoYzwFhyfUE0TRHHL3ppjew29CsDTfezesb3A2EK8PdsKQ@mail.gmail.com>
 <CAGB5yNkLpk7Q2BcckUVDB6aopg1msWuyeV5XHYtNMAfRJu7GHg@mail.gmail.com>
 <CAMpNYoYGeUXm8q=75dn1Y5Yp+u=0sktAXtUVDh9JVUTJGJgFQg@mail.gmail.com>
From: Claus Ibsen <claus.ibsen@gmail.com>
Date: Fri, 25 Mar 2016 07:25:06 +0100
Message-ID: 
 <CAGB5yNn7eiyTBkXqfExfUt2uudrs8wJB4x_VDYBXaV6m=DqVGA@mail.gmail.com>
Subject: Re: Improve endpoint configuration
To: dev <dev@camel.apache.org>
Content-Type: text/plain; charset=UTF-8

Hi

I do think there is some very good ideas in here.

If we for Camel 3.0 can make those annotations mandatory and part of
the auto configuration and validation of components.

Today the annotations only play as a role of component documentation.
You can remove the annotations and Camel at runtime will still run.

And with the annotations as part of auto configuration we also close
the circle and make configuration and the documented options aligned.

For example you can try run the mvn plugin that validates the endpoint
uris from source code
http://www.davsclaus.com/2016/01/cheers-fabric8-camel-maven-plugin-to.html

And see that you can find "mistakes" between the documented options vs
what you can actual configure. Ideally that validation should always
pass and be part of the endpoint auto configure.

The validation uses the camel-catalog today for that, but part of that
logic can be in camel-core. That can also help make better validation
exceptions, such as the mvn plugin does. It even has that "did you
mean" logic to suggest options you may have mistyped. Its currently
using lucence for that, but we could have a simpler logic that can
make suggestion in the camel-core so there is no runtime dependency on
lucene.


On Thu, Mar 24, 2016 at 2:05 PM, lb <lburgazzoli@gmail.com> wrote:
> On Thu, Mar 24, 2016 at 1:34 PM, Claus Ibsen <claus.ibsen@gmail.com> wrote:
>> On Wed, Mar 23, 2016 at 3:55 PM, lb <lburgazzoli@gmail.com> wrote:
>>> Hi,
>>>
>>> I've been working on a number of components in the lates months and what I found
>>> a little bit repetitive is to handle endpoints configuration so I would like to
>>> know if there is any interest about improving such area by adding
>>> support as example
>>> for:
>>>
>>> - collections
>>> - nested objects
>>> - validation
>>> - default values
>>>
>>> As today a common pattern to configure an endpoint is:
>>>
>>>     @Override
>>>     protected Endpoint createEndpoint(
>>>         String uri, String remaining, Map<String, Object> parameters)
>>> throws Exception {
>>>
>>>         MyConfiguration configuration = new MyConfiguration();
>>>         setProperties(configuration, parameters);
>>>
>>>         return new MyEndpoint(uri, this, configuration);
>>>     }
>>>
>>> As far as I know, setProperties does not take into account field annotations so
>>> handling i.e. multi value objects (lists, maps) has to be manually
>>> done or default
>>> values have to be defined on both the annotations and the fields.
>>>
>>> So let's suppose to have a configuration bean like:
>>>
>>>
>>>     @UriParams
>>>     class MyConfiguration {
>>>         @UriPath
>>>         @Metadata(required = "true")
>>>         private String key;
>>>
>>>         @UriPath( defaultValue = "localhost" )
>>>         private String host;
>>>
>>>         @UriPath( elementType = User.class)
>>>         private List<User> users;
>>>
>>>         @UriPath( elementType = User.class )
>>>         private Map<String, User> aliases;
>>>
>>>         @UriPath( elementType = User.class )
>>>         private Proxy proxy;
>>>
>>>         @UriPath( elementType = String.class, enum = "NEW, UPDATE, DELETE")
>>>         private List<String> events;
>>>
>>>         // getter/setters as usual
>>>     }
>>>
>>>
>>> I'd like to be able to write an endpint uri like:
>>>
>>>     "users=#usr1,#usr2&aliases.alias1=#usr1&proxy.userName=myUsr,proxy.password=myPwd&events=NEW,CANCEL"
>>>
>>
>> We should avoid the proxy.xxx notation when possible and only use it
>> for more advanced use cases. There is no type safety and the end user
>> and tooling do not know what setters are possible to use.
>>
>> So its better to have a proxyUserName / proxyPassword as options in
>> the configuration class so its nicely exposed as options.
>>
>
> I forgot to mention that also Proxy need to be annotated :-)
>
>> Also its not so common to have Map types with nested type objects. eg
>> going down that path makes configuring harder. Instead the endpoint
>> should provide a easier to use configuration.
>>
>
> Yep I agree that maps and beans are advanced configuration options and
> should be avoided but there are cases where they make sense so I think
> it is worth having native support in camel at least to make it a
> common path so tooling & co may try to handle them properly.
>
>> And for enums, then if the type is an enum, then its out of the box.
>> In your use case the type is String. So it can be any kind of string.
>> Having enums in the annotation makes the component doc / schema aware
>> of those and can make it easier for tooling where you can have a
>> dropdown to chose among the enum values.
>>
>
> Here the goal was to provide a option validation and yes an enum would
> be better but sometimes not possible or not making much sense so imho
> having a way to validate the options is valuable.
>
>>
>>
>>
>>> And having camel to automatically bind/validate my options using annotations so:
>>>
>>> - set defaults, in this case set host to "localhost" as indicated by
>>> the annotation
>>> - split users, lookup values in the registry and fill users
>>> - set key/vaue for aliases
>>> - set bean properties to proxy (of course proxy need to be instantiable)
>>> - warn about unknown value (CACNEL) for events
>>> - warn/fail as required field key is not provided
>>>
>>
>> Yes all good suggestions but I think its more a goal for Camel 3.0
>> than for 2.x. See further below.
>>
>>
>>> This enhancement is definitively not intended to replace any of the methods
>>> available as now bur to leverage them and make configurations simpler
>>> and a little
>>> more annotation oriented.
>>>
>>> If there is any interest I'd more than happy to work on it.
>>>
>>
>> The @UriParam et all was added much after how components is done
>> today. They are a means for component documentation and tooling. Only
>> recently we have @UriParams on all the options.
>>
>> And in the future we can make that mandatory so components and
>> endpoints are always documented and we know what options there are and
>> what they do etc.
>>
>> So in the future it may make feasible to use the @UriParam annotations
>> as a means for validation and configuring as well.
>>
>> However I think we need to get the component docs and the other parts
>> done before we go down this road. I suggest to take a look at after
>> Camel 2.18, eg for Camel 3.0. There we can move to make using
>> @UriParam mandatory. And figure out in camel-core how component and
>> endpoint creation logic can tap into those annotations and do
>> accordingly to your ideas.
>>
>> But I think its worth creating a JIRA and refer to this @dev and mark
>> it for 3.0.
>>
>
> I will


-- 
Claus Ibsen
-----------------
http://davsclaus.com @davsclaus
Camel in Action 2: https://www.manning.com/ibsen2