Mailing-List: contact commons-user-help@jakarta.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Jakarta Commons Users List" <commons-user@jakarta.apache.org>
Received-SPF: pass (hermes.apache.org: local policy)
Message-ID: <20040920234422.25057.qmail@web50403.mail.yahoo.com>
Date: Mon, 20 Sep 2004 16:44:22 -0700 (PDT)
From: David Graham <grahamdavid1980@yahoo.com>
Subject: Re: [Validator] Some thoughts about Commons Validator
To: Jakarta Commons Users List <commons-user@jakarta.apache.org>
In-Reply-To: <0E071FA35418D811970500508BBB98195F19@ganymed.allocation.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii

It took me a while to learn the Validator API.  If you think it's bad now
you should check out the very earliest incarnations.  We've put in a lot
of work to make it simpler, cleaner, and easier to use; however, nobody
ever claimed it was perfect.  

In this community, cvs diff -u formatted patches have a way of affecting
change while angry rants without any contribution make their way into
trash bins.  If you provide patches I will do my best to comment on them
and/or apply them.  Even simple javadoc improvements or updated site links
are welcome!

Thanks,
David


--- 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
> 
> 


_______________________________
Do you Yahoo!?
Declare Yourself - Register online to vote today!
http://vote.yahoo.com

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