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)
From: "Ricardo Trindade" <ricardo.trindade@emation.pt>
To: "Jakarta Commons Users List" <commons-user@jakarta.apache.org>
Subject: RE: [Validator] Some thoughts about Commons Validator
Date: Mon, 20 Sep 2004 16:48:16 +0100
Message-ID: <PPEJJDOIBFJHGGGEELNNCEMIGIAA.ricardo.trindade@emation.pt>
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
Importance: Normal
In-Reply-To: <0E071FA35418D811970500508BBB98195F19@ganymed.allocation.net>

Hi,

	After also spending two days with validator, trying to integrate it in a
project, I feel the same way. I posted several questions to the list, none
answered. Is validator alive ? I know that lots of people use it with
struts, but it would be very usefull if using it outside struts wouldn't be
such a nightmare.

thanks
Ricardo

-----Mensagem original-----
De: Andreas Prohaska [mailto:ap@apeiron.de]
Enviada: segunda-feira, 20 de Setembro de 2004 16:13
Para: 'commons-user@jakarta.apache.org'
Assunto: [Validator] Some thoughts about Commons Validator


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