Mailing-List: contact camel-dev-help@activemq.apache.org; run by ezmlm
Precedence: bulk
Reply-To: camel-dev@activemq.apache.org
Received-SPF: pass (athena.apache.org: local policy)
Content-class: urn:content-classes:message
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
Subject: Camel 1.4 - Improved URI validation - (Component Writers pay
 attention) - Feedback please
Date: Mon, 12 May 2008 09:30:29 +0200
Message-ID: <4C1FB9C00D24A140906239533638C4D2042844BE@EXVS04.exserver.dk>
Thread-Topic: Camel 1.4 - Improved URI validation - (Component Writers pay
 attention) - Feedback please
Thread-Index: Aci0Ag3IHuXC7KX2SZqxLX20fzU/8Q==
From: "Claus Ibsen" <ci@silverbullet.dk>
To: <camel-dev@activemq.apache.org>
Cc: <camel-user@activemq.apache.org>

Hi

In Camel 1.4 we are improving the validation when Camel creates =
endpoints (CAMEL-433) regarding the given URI string.

Use-case
=3D=3D=3D=3D=3D=3D=3D=3D

As of now Camel will throw a ResolveEndpointFailedException if the =
validation failed with a message what is the problem.
Camel will now validate out-of-the-box:
1) Simple URI syntax
2) No more lost parameters


Ad 1)
The simple syntax validation is eg. If the end-user has forgotten that =
the parameters separator is a ? marker and to use & for further =
parameters.

So this invalid URI: timer://foo&fixedRate=3Dtrue&delay=3D0&period=3D500
Will fail since there are no ? marker.

Failed to resolve endpoint: =
timer://foo&fixedRate=3Dtrue&delay=3D0&period=3D500 due to: =
org.apache.camel.ResolveEndpointFailedException: Failed to resolve =
endpoint: timer://foo&fixedRate=3Dtrue&delay=3D0&period=3D500 due to: =
Invalid uri syntax: no ? marker however the uri has & parameter =
separators. Check the uri if its missing a ? marker.


Ad 2)
This is the most serious problem that bites most people. If they have =
mistyped an optional parameter Camel will ignore it and go on. This can =
lead to users thinking that Camel runs with that parameter but it does =
not.

Now Camel barfs and throws a ResolveEndpointFailedException with the =
list of unknown parameters.=20

The example from above but with a mistype in the parameter: =
"timer://foo?delay=3D250&perid=3D500"


Failed to resolve endpoint: timer://foo?delay=3D250&perid=3D500 due to: =
org.apache.camel.ResolveEndpointFailedException: Failed to resolve =
endpoint: timer://foo?delay=3D250&perid=3D500 due to: There are 1 =
parameters that couldn't be set on the endpoint. Check the uri if the =
parameters are spelt correctly and that they are properties of the =
endpoint. Unknown parameters=3D[{perid=3D500}]


Component Writers
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

Only in rare cases your component will not work out-of-the-box with =
Camel 1.4. In these conditions you need to make sure that you handle the =
parameters your component support.

=CFf you have code that handles parameters manually by such as: =
parameters.get("size");

You should get and remove the parameter such as:
parameters.get("size");
parameters.remove("size");

or in one-line
Object size =3D parameters.remove("size");


In Camel 1.4 we have added convenient methods to do this trick; one with =
a fallback to a default value if the parameter does not exists. This =
method does also the converTo to the requested type. These methods are =
added on the DefaultComponent, that most components extend:

    public <T> T getAndRemoveParameter(Map parameters, String key, =
Class<T> type)

    public <T> T getAndRemoveParameter(Map parameters, String key, =
Class<T> type, T defaultValue)


Feedback
=3D=3D=3D=3D=3D=3D=3D=3D
Feedback is most welcome. Any native English speakers could proof read =
the exception message as I am sure it "smells".

Also I considered naming the methods getAndRemoveParameter just =
getParameter

And do you some ideas for even better URI validation that Camel should =
do out-of-the-box please feel free to comment here or on the CAMEL-433.


Med venlig hilsen

Claus Ibsen
......................................
Silverbullet
Skovsg=E5rdsv=E6nget 21
8362 H=F8rning
Tlf. +45 2962 7576
Web: www.silverbullet.dk