Agreed, this is getting confusing. Let me reformulate the proposal,
this time for inclusion in the commons directly, and taking feedback
into account. The following section have been updated and need a new
reading: 1.5, 2, 2.1, and 4.
Votes already received for inclusion in commons are:
Ted Husted +1
Jason van Zyl +1
David Winterfeldt +1
Votes already received for inclusion in the sandbox are:
Jeff Turner +1
Scott Sanders +1
The two people above should vote again if they mean inclusion in the
commons directly.
Proposal for a mapper framework in the Jakarta Commons
======================================================
(0) rationale
---------
In many application environments validation is performed on data fields,
data is converted from one form to another, and is being transferred
from one object to another. A typical example is found in graphical user
interfaces that validate user input, convert it to a proper form, and send
it to a server application for processing. In the case of HTML front-ends,
the HTTP protocol forces user input to be sent as text data to the server
where the validation and conversion has to be performed.
Most of the time implementing such validation and conversion requires lots
of custom code: get the data element, validate it, convert it, and put the
result into another object. In a small application, this may not be an
issue. However in medium to large applications with many different data
elements, such coding becomes a tedious and error-prone task.
In such situation developers tend to achieve some form of reuse in order to
reduce the menial work. At the lowest level is the cut'n'paste approach. A
better approach is the definition of some high-level abstraction which
encapsulate reusable logic: validation and conversion classes are typical
abstractions found in most systems.
However, even with validation and conversion logic being reusable, some
custom coding is still required in order to attach those validations and
conversions to the data elements. To avoid completely the custom code, an
even higher level of abstraction is needed in order to model such bindings.
The mapper framework implemented in this package provides such high-level
abstractions, making the validation, conversion, and transfer of data a
process driven by a configuration file.
Although the central concept in this framework is the one of a mapper, the
framework is flexible enough to be used only for validating fields of an
object, or converting an object into another one, or simply copying fields
from one object to another. It is also flexible enough so that validation,
conversion, and transfer can be performed on multiple objects within the
same mapper.
(1) scope of the package
--------------------
The mapper framework provides the necessary classes and abstractions to
perform validation, conversion, and transfer of data fields between any
types of objects. The configuration of all mappers and other abstractions is
done in one or more XML file loaded at startup. The framework does not
depend on any other application framework such as Struts or Turbine, and
integration with such frameworks should be provided separately.
(1.5) interaction with other packages
-------------------------------
The mapper framework makes use of
- the Commons Digester
- the Commons BeanUtils
- JavaCC
- the Commons Pool (work in progress)
The main differences with the validator framework from David Winterfeldt
is in the scope and level of abstractions.
While the validation framework only covers the validation part,
the mapper framework can also convert values, validate converted
values, and copy the converted/validated values to one or more object (e.g.
value objects). The mapper framework provides many abstractions: validators,
converters, getters, setters, error handlers, etc., making it possible, for
example, to define each single validation and conversion in its own class
that can easily be reused. Also, the mapper framework includes a small
language that is used essentially for simple validations and for combining
validators and converters together, making it easier to create smaller
grained and reusable validations/conversions that can be glued together with
this language (e.g. no need to write a third validator in order to combine
two existing ones). Most of the mapper framework classes (mapper, mapping,
mapped-object, etc.) can be extended so that much of the behavior can be
altered either globally or locally. On the other hand, the validator
framework from David provides less levels of abstractions (e.g. each
validation is a method on a class) and extensibility. It does however
perform a very good job at validating forms within a Struts application,
even making it possible to generate client-side validation in JavaScript.
This latter feature is not supported by the mapper framework, but can
easily be implemented with a Visitor pattern and a JavaScript visitor.
Since both the validator and mapper frameworks overlap in the validation
function, it is proposed to have both share a common set of validation
logic. Further discussions may be needed to specify how to do this properly
(see section 2).
The differences with the Intake service found in Turbine are to be
investigated further. From reading the Intake doc, both seems to cover the
same functionality: validate/convert/transfer. Intake is part of the Fulcrum
service framework used by Turbine, so at present using intake means using
the fulcrum framework as well. On the other hand, the mapper framework is
not dependent on any other application or service framework such as Struts
or Turbine/Fulcrum. It has of course dependencies with the packages
mentioned above, but one can use the mapper framework in any context:
Struts, Turbine, etc.
Although independent of Struts, the mapper framework can easily be used
in a Struts application by subclassing the ActionMapping and adding a new
property containing the name of the mapper to use for validating an
ActionForm. That way the mapper can be specified in struts-config.xml.
While it is possible and easy to use the mapper framework just for
validation in Struts, such usage does not differentiate it from David's
validation framework (which is probably a better choice if only
validation is required). The real value of the mapper framework is when
conversion and transfer of data elements are also required.
(2) identify the initial source for the package
-------------------------------------------
The initial codebase is to be contributed by Francois Rey. A version of the
source is already available at <
http://husted.com/struts/resources/mapper.htm >.
Before inclusion into the commons the following will be performed:
- alignment of the build process with the commons build process
- repackaging into Jakarta packages as described in 2.1
- use of the commons digester and BeanUtils instead of the Struts versions
(2.1) identify the base name for the package
--------------------------------------
org.apache.commons.mapper
org.apache.commons.mapper.parser
org.apache.commons.mapper.util
If a set of validation logic is to be shared between the validation and
mapper framework, it is suggested that another separate package is
created for holding the shared logic. This however is not a definite
point of this proposal and can be discussed further. If for example
the shared validation logic is implemented by deriving the Validator
class of the mapper framework, it would make sense to have them under
the existing mapper.util package.
(3) identify any Jakarta-Commons resources to be created
----------------------------------------------------
(3.1) mailing list
Until traffic justifies, the package will use the Jakarta-Commons list for
communications.
(3.2) CVS repositories
For the time being, the package will reside in a sub-project of the
Jakarta-Commons sandbox CVS.
(3.3) Bugzilla
The package should be listed as a component of under the Jakarta-Commons
Bugzilla entry.
(3.4) Jyve FAQ (when available)
commons-mapper
(4) identify the initial set of committers to be listed in the Status File
----------------------------------------------------------------------
Francois Rey
David Winterfeldt
Ted Husted
Craig McClanahan
************************************************************************
The information in this email is confidential and is intended solely
for the addressee(s).
Access to this email by anyone else is unauthorised. If you are not
an intended recipient, please notify the sender of this email
immediately. You should not copy, use or disseminate the
information contained in the email.
Any views expressed in this message are those of the individual
sender, except where the sender specifically states them to be
the views of Capco.
http://www.capco.com
***********************************************************************
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
