commons-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Martin Cooper <mfncoo...@gmail.com>
Subject Re: [Validator] Some thoughts about Commons Validator
Date Mon, 20 Sep 2004 20:13:35 GMT
You are always welcome to contribute back to the project with
improvements to the documentation or the implementation. Simply
complaining that the developers didn't spend their own free time
making it more usable for you is not a good way to go about things.
We're all volunteers here, and in general we work on what we want to
work on. If nobody has the itch to write documentation, then it won't
happen. But if you'd like to volunteer, I'm sure we'd be glad to
review your patches and apply them as appropriate.

--
Martin Cooper


On Mon, 20 Sep 2004 17:12:58 +0200, Andreas Prohaska <ap@apeiron.de> wrote:
> Hi!
> 
> I've spent quite some time on deciding whether I should write this email
> or not, and I finally came to the conclusion that I have to do it, even
> if it's just to vent my anger about the Validator project. To be honest,
> I'm quite pissed off at the moment, but I'll try to share my thoughts in
> a kindly way, hopefully with rational arguments in order to give you a
> user's view on the whole project. For all of you that are not interested
> in feedback, skip this posting.
> 
> I've been trying to use the framework in one of our projects. After
> working on the integration for about two days, I'm finally giving up.
> It's not, because I couldn't figure out how the validation works. It's
> because I HAVE figured it out, and I'm not really convinced about
> the quality of the implementation. Here's the story:
> 
> Let's start at the beginning, the download of the binary distribution
> together with the source code. You start at the Jakarta site, go through
> the Commons project and finally end at the Validator homepage. After
> realizing that "About us" doesn't tell you anything about Validator and
> is only related to Commons, you navigate back and go to "Downloads". So
> far, so good. There you see two sections:
> 
>        Latest stable release
>                1.1.3 Binary
>                1.1.3 Source
> 
>        Latest development release
>                1.1.2 Binary
>                1.1.2 Source
> 
> This is the point when you start asking yourself why the development
> release is older than the stable release. That's the wrong order, isn't it?
> OK, I decided to get the 1.1.3 release, unzipped it and copied the
> commons-validator.jar into my project classpath.
> 
> That's when the nightmare really begins. I started looking for the
> documentation... Well, .... Besides the "Source Code metrics" that
> give you information about the abstractness of a class (which I, as a
> user, find rather useless) there isn't any. It's unbelievable that there
> seems to be no time to document 20+x classes and how they are intended to
> be used. While most of the Jakarta projects lack a good documentation,
> this is the worst. After browsing through the Wiki, and the other Wiki,
> and Google, I ended debugging the source code together with an example
> source code.
> 
> Source code of example (from the Wiki) is here:
> http://cvs.apache.org/viewcvs.cgi/jakarta-commons/validator/src/example/org/
> apache/commons/validator/example/ValidateExample.java?rev=1.17&view=auto
> 
> Everything starts the way, you would expect it to: the ValidatorResources
> are
> loaded, the Validator instantiated. But then, the bean to validate is set
> with:
> 
>        validator.setParameter(Validator.BEAN_PARAM, bean);
> 
> Now, please look at the the JavaDoc of the method:
> 
>        setParameter(java.lang.String parameterClassName, java.lang.Object
> parameterValue)
>          Set a parameter of a pluggable validation method.
> 
> Don't you agree, that the documentation is completely misleading?
> Passing the instance of the bean to validate is not what I think of, when
> I read "Sets the parameter of a pluggable validation method". Why isn't
> there a
> 
>        validator.setBeanToValidate(Object obj)
> 
> method? The parameter "parameterClassName" does in no way specify a class
> name. It's the name of the parameter.
> 
> Let's go on. After validating the bean, the ValidatorResults have to be
> processed. You start with getPropertyNames() that returns the names of
> all properties that had a validation applied to them. Now you have to
> get a ValidatorResult for each property from the
> ValidatorResults.getValidatorResult() method. Note that the parameter of the
> method is named "key". Why not
> "property"? Or "propertyName"? Only from the name of the method someone
> can guess the intention of the parameter.
> 
> From the undocumented (!) method getActionMap() you will finally get all
> validations that had been applied to the property. First of all, how
> should someone know that "getActionMap()" and "get applied validations"
> means the same thing? The other question is: What kind of Map does this
> method return? Action instances with property names as keys? Error
> messages with Actions as keys? Actually, I still don't know what the
> values of this Map are.
> 
> Learning from the example, you only take the String keys (ahh .. the
> keys are String instances), ignoring the values. This gives you the
> name of the Action. For some reason, you cannot get the result from
> the map, but you have to get it from the ValidatorResult. Please have
> a look at the JavaDoc, again:
> 
>        ValidatorResult.isValid(java.lang.String validatorName)
> 
> Aha! Now "action name" means "validatorName" again. But "validatorName" is
> actually "propertyName", isn't it? Nothing gives you a hint about the
> differences between property, action and validator. Is there any?
> Is there any consistent nomenclature for classes, methods and parameters?
> 
> You're finally glad, that validation seems to work and that you get the
> results and can show error messages to your users...
> 
> Until you try to add your first validation. If you have a look at the
> JavaDoc again, the only thing that comes close to a class that offers
> validation is "GenericValidator". Ahhh, you think and put it into your
> validation.xml file. Nothing works. Perhaps you mistyped the parameters.
> No, still nothing works. You finally launch the debugger again and start
> to realize, that all the GenericValidator's methods mismatch with the
> MethodInvocation call deep down in the source code.
> 
> Back in the example again, you see that a "TestValidator" is used.
> Hmm. It's not in the commons-validator.jar. It's in the jUnit test
> package, but not in the distribution. Is it only for test purposes?
> Where's the production implementation of a validator. Do I have to
> write them on my own? What benefit would I then have from using the
> Commons Validator package?
> 
> To put it straight:
> Why is the actual implementation provided in a class that is intended
> for unit testing and not even contained in the .jar archive of the
> distribution? Can anyone explain this to me?
> 
> I hope you see, that there are a lot of hurdles that make it hard
> (if not impossible) to use the Validator framework. Writing a good
> documentation would be a great benefit. A tutorial would be wonderful.
> There are open source projects with good documentation. Have a look
> at the Spring framework for reference.
> 
> Flames welcome...
> 
>        Andreas
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-user-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-user-help@jakarta.apache.org
> 
>

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-user-help@jakarta.apache.org


Mime
View raw message