You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Simon Kitching <si...@ecnetwork.co.nz> on 2003/08/02 08:15:45 UTC
[digester] patch: usage examples
Hi,
Recently there was a suggestion on the users email group that some
digester examples would be helpful.
I felt this myself when starting to use digester.
So attached is a tar file containing a (proposed) initial example.
The tar file contains the tree:
examples
api
example1
**files here
xmlrules
I suggest that this could all go under "src", so that there would be
"src/java", "src/test" and "src/examples".
This would be consistent with the "httpclient" projects' directory
structure.
I think that additional examples could usefully be added in future,
hence the name "example1" for the dir containing the provided code.
Stuff that could be covered in later examples include:
* FactoryCreateRule
* NodeCreateRule
* mapping of attribute names to bean properties
(eg some-attr --> someAttr) when using setProperties et al.
This contribution is not entirely selfless :-). The existence of this
examples directory also gives me somewhere to put "plugins" module
examples if the "plugins" module is accepted [patch coming soon....]
NOTE: I haven't made any changes to the existing digester "build.xml" to
either build or not build these new files. This would have to be done
sometime I think.
Regards,
Simon
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [digester] patch: usage examples
Posted by Simon Kitching <si...@ecnetwork.co.nz>.
Oh bugger :- here's the attachment.
On Sat, 2003-08-02 at 18:15, Simon Kitching wrote:
> Hi,
>
> Recently there was a suggestion on the users email group that some
> digester examples would be helpful.
>
> I felt this myself when starting to use digester.
>
> So attached is a tar file containing a (proposed) initial example.
>
> The tar file contains the tree:
>
> examples
> api
> example1
> **files here
> xmlrules
>
> I suggest that this could all go under "src", so that there would be
> "src/java", "src/test" and "src/examples".
>
> This would be consistent with the "httpclient" projects' directory
> structure.
>
> I think that additional examples could usefully be added in future,
> hence the name "example1" for the dir containing the provided code.
>
> Stuff that could be covered in later examples include:
> * FactoryCreateRule
> * NodeCreateRule
> * mapping of attribute names to bean properties
> (eg some-attr --> someAttr) when using setProperties et al.
>
> This contribution is not entirely selfless :-). The existence of this
> examples directory also gives me somewhere to put "plugins" module
> examples if the "plugins" module is accepted [patch coming soon....]
>
>
> NOTE: I haven't made any changes to the existing digester "build.xml" to
> either build or not build these new files. This would have to be done
> sometime I think.
>
> Regards,
>
> Simon
Re: [digester] patch: usage examples
Posted by robert burrell donkin <ro...@blueyonder.co.uk>.
On Friday, August 15, 2003, at 03:38 AM, Simon Kitching wrote:
> On Fri, 2003-08-15 at 06:32, robert burrell donkin wrote:
>> committed. many thanks.
>>
>> it all looks fine. i've managed to resist the temptation to tinker too
>> much (just yet ;) but i have renamed the directory from example1 to
>> addressbook since i prefer descriptive names where possible. (i think
>> that
>> it makes it easier for users.)
>
> Tweak away :-) Any improvements to the examples are welcome; I would be
> keen to see better ways of implementing the "addressbook" example.
>
> I should have explained why I picked the name "example1"; it was chosen
> so that we could also have example2, example3, etc.
>
> Example 1 is the "start here" point, showing the simplest features of
> Digester.
>
> I had intended to add an Example 2 with more complex things like:
> * passing Digester as a SAXContentHandler to an existing SAXParser
> instead of calling parse(File), as done in example 1
> * demonstrating ObjectFactoryRule
> * wildcards in patterns
>
> And maybe example 3 getting on to really tricky stuff like:
> * extended rules matching
> * NodeCreateRule (if I can figure it out myself :-)
> * subclassing the Digester
> * handling namespaces
that sounds great.
> If you want to name the examples by the example filetype they happen to
> process, then I suggest the readme file be modified to indicate which
> order a newbie to Digester should read the examples in.
what i'd really like to do is to integrate the examples into a set of html
documents which can be posted on the site and browsed. i know that this is
quite a long way off at the moment but it's nive to dream :)
i prefer examples with names since it's easier to remember which is which
when answering user questions. we should certainly make sure that the
(maybe something like the descriptions you've given about would be cool in
the readme).
>> don't worry too much about the build script, it not a priority. maybe it'
>> d
>> be a good idea to have a separate build.xml script in the examples
>> directory.
>
> I just want to make sure that changes in Digester itself don't break the
> examples. It would be rather embarrassing to ship a digester release
> where the examples don't compile. To avoid this, I suggest that the
> examples be *compiled* as part of the "dist" target, though of course
> the resulting class files shouldn't be included in the distribution jar!
+1
> That way, any time someone runs "ant dist", they immediately see if the
> examples are broken or not. Agreed, they don't know if the examples
> still *work*; that would require them to be written as "unit tests",
> which unfortunately then makes them less useful as tutorials (too much
> unit-test-related clutter).
it might be nice to have a few example unit tests as part of the examples.
there are some tricks such as using a StringReader (rather than reading
the xml from a file) which people might find useful.
> Or we could build them whenever the unit tests are built? I don't think
> that the Digester unit tests are in a very good state though (I was
> going to look into this soon, as I also need to build unit tests for the
> Plugins module).
the digester unit tests may not look pretty but they have provided pretty
effective. i'm particularly guilty since i tend to leave a lot of
commented out logging in there.
- robert
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [digester] patch: usage examples
Posted by robert burrell donkin <ro...@blueyonder.co.uk>.
On Friday, August 15, 2003, at 03:38 AM, Simon Kitching wrote:
> On Fri, 2003-08-15 at 06:32, robert burrell donkin wrote:
>> committed. many thanks.
>>
>> it all looks fine. i've managed to resist the temptation to tinker too
>> much (just yet ;) but i have renamed the directory from example1 to
>> addressbook since i prefer descriptive names where possible. (i think
>> that
>> it makes it easier for users.)
>
> Tweak away :-) Any improvements to the examples are welcome; I would be
> keen to see better ways of implementing the "addressbook" example.
>
> I should have explained why I picked the name "example1"; it was chosen
> so that we could also have example2, example3, etc.
>
> Example 1 is the "start here" point, showing the simplest features of
> Digester.
>
> I had intended to add an Example 2 with more complex things like:
> * passing Digester as a SAXContentHandler to an existing SAXParser
> instead of calling parse(File), as done in example 1
> * demonstrating ObjectFactoryRule
> * wildcards in patterns
>
> And maybe example 3 getting on to really tricky stuff like:
> * extended rules matching
> * NodeCreateRule (if I can figure it out myself :-)
> * subclassing the Digester
> * handling namespaces
that sounds great.
> If you want to name the examples by the example filetype they happen to
> process, then I suggest the readme file be modified to indicate which
> order a newbie to Digester should read the examples in.
what i'd really like to do is to integrate the examples into a set of html
documents which can be posted on the site and browsed. i know that this is
quite a long way off at the moment but it's nive to dream :)
i prefer examples with names since it's easier to remember which is which
when answering user questions. we should certainly make sure that the
(maybe something like the descriptions you've given about would be cool in
the readme).
>> don't worry too much about the build script, it not a priority. maybe it'
>> d
>> be a good idea to have a separate build.xml script in the examples
>> directory.
>
> I just want to make sure that changes in Digester itself don't break the
> examples. It would be rather embarrassing to ship a digester release
> where the examples don't compile. To avoid this, I suggest that the
> examples be *compiled* as part of the "dist" target, though of course
> the resulting class files shouldn't be included in the distribution jar!
+1
> That way, any time someone runs "ant dist", they immediately see if the
> examples are broken or not. Agreed, they don't know if the examples
> still *work*; that would require them to be written as "unit tests",
> which unfortunately then makes them less useful as tutorials (too much
> unit-test-related clutter).
it might be nice to have a few example unit tests as part of the examples.
there are some tricks such as using a StringReader (rather than reading
the xml from a file) which people might find useful.
> Or we could build them whenever the unit tests are built? I don't think
> that the Digester unit tests are in a very good state though (I was
> going to look into this soon, as I also need to build unit tests for the
> Plugins module).
the digester unit tests may not look pretty but they have provided pretty
effective. i'm particularly guilty since i tend to leave a lot of
commented out logging in there.
- robert
Re: [digester] patch: usage examples
Posted by Simon Kitching <si...@ecnetwork.co.nz>.
On Fri, 2003-08-15 at 06:32, robert burrell donkin wrote:
> committed. many thanks.
>
> it all looks fine. i've managed to resist the temptation to tinker too
> much (just yet ;) but i have renamed the directory from example1 to
> addressbook since i prefer descriptive names where possible. (i think that
> it makes it easier for users.)
Tweak away :-) Any improvements to the examples are welcome; I would be
keen to see better ways of implementing the "addressbook" example.
I should have explained why I picked the name "example1"; it was chosen
so that we could also have example2, example3, etc.
Example 1 is the "start here" point, showing the simplest features of
Digester.
I had intended to add an Example 2 with more complex things like:
* passing Digester as a SAXContentHandler to an existing SAXParser
instead of calling parse(File), as done in example 1
* demonstrating ObjectFactoryRule
* wildcards in patterns
And maybe example 3 getting on to really tricky stuff like:
* extended rules matching
* NodeCreateRule (if I can figure it out myself :-)
* subclassing the Digester
* handling namespaces
If you want to name the examples by the example filetype they happen to
process, then I suggest the readme file be modified to indicate which
order a newbie to Digester should read the examples in.
> don't worry too much about the build script, it not a priority. maybe it'd
> be a good idea to have a separate build.xml script in the examples
> directory.
I just want to make sure that changes in Digester itself don't break the
examples. It would be rather embarrassing to ship a digester release
where the examples don't compile. To avoid this, I suggest that the
examples be *compiled* as part of the "dist" target, though of course
the resulting class files shouldn't be included in the distribution jar!
That way, any time someone runs "ant dist", they immediately see if the
examples are broken or not. Agreed, they don't know if the examples
still *work*; that would require them to be written as "unit tests",
which unfortunately then makes them less useful as tutorials (too much
unit-test-related clutter).
Or we could build them whenever the unit tests are built? I don't think
that the Digester unit tests are in a very good state though (I was
going to look into this soon, as I also need to build unit tests for the
Plugins module).
>
> i've been toying with the idea of using maven to create some kind of
> documentation based on the source plus html contained in the files but i
> don't have the time to do this right now.
>
> - robert
>
> On Saturday, August 2, 2003, at 07:15 AM, Simon Kitching wrote:
>
> > Hi,
> >
> > Recently there was a suggestion on the users email group that some
> > digester examples would be helpful.
> >
> > I felt this myself when starting to use digester.
> >
> > So attached is a tar file containing a (proposed) initial example.
> >
> > The tar file contains the tree:
> >
> > examples
> > api
> > example1
> > **files here
> > xmlrules
> >
> > I suggest that this could all go under "src", so that there would be
> > "src/java", "src/test" and "src/examples".
> >
> > This would be consistent with the "httpclient" projects' directory
> > structure.
> >
> > I think that additional examples could usefully be added in future,
> > hence the name "example1" for the dir containing the provided code.
> >
> > Stuff that could be covered in later examples include:
> > * FactoryCreateRule
> > * NodeCreateRule
> > * mapping of attribute names to bean properties
> > (eg some-attr --> someAttr) when using setProperties et al.
> >
> > This contribution is not entirely selfless :-). The existence of this
> > examples directory also gives me somewhere to put "plugins" module
> > examples if the "plugins" module is accepted [patch coming soon....]
> >
> >
> > NOTE: I haven't made any changes to the existing digester "build.xml" to
> > either build or not build these new files. This would have to be done
> > sometime I think.
> >
> > Regards,
> >
> > Simon
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> > For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>
Re: [digester] patch: usage examples
Posted by Simon Kitching <si...@ecnetwork.co.nz>.
On Fri, 2003-08-15 at 06:32, robert burrell donkin wrote:
> committed. many thanks.
>
> it all looks fine. i've managed to resist the temptation to tinker too
> much (just yet ;) but i have renamed the directory from example1 to
> addressbook since i prefer descriptive names where possible. (i think that
> it makes it easier for users.)
Tweak away :-) Any improvements to the examples are welcome; I would be
keen to see better ways of implementing the "addressbook" example.
I should have explained why I picked the name "example1"; it was chosen
so that we could also have example2, example3, etc.
Example 1 is the "start here" point, showing the simplest features of
Digester.
I had intended to add an Example 2 with more complex things like:
* passing Digester as a SAXContentHandler to an existing SAXParser
instead of calling parse(File), as done in example 1
* demonstrating ObjectFactoryRule
* wildcards in patterns
And maybe example 3 getting on to really tricky stuff like:
* extended rules matching
* NodeCreateRule (if I can figure it out myself :-)
* subclassing the Digester
* handling namespaces
If you want to name the examples by the example filetype they happen to
process, then I suggest the readme file be modified to indicate which
order a newbie to Digester should read the examples in.
> don't worry too much about the build script, it not a priority. maybe it'd
> be a good idea to have a separate build.xml script in the examples
> directory.
I just want to make sure that changes in Digester itself don't break the
examples. It would be rather embarrassing to ship a digester release
where the examples don't compile. To avoid this, I suggest that the
examples be *compiled* as part of the "dist" target, though of course
the resulting class files shouldn't be included in the distribution jar!
That way, any time someone runs "ant dist", they immediately see if the
examples are broken or not. Agreed, they don't know if the examples
still *work*; that would require them to be written as "unit tests",
which unfortunately then makes them less useful as tutorials (too much
unit-test-related clutter).
Or we could build them whenever the unit tests are built? I don't think
that the Digester unit tests are in a very good state though (I was
going to look into this soon, as I also need to build unit tests for the
Plugins module).
>
> i've been toying with the idea of using maven to create some kind of
> documentation based on the source plus html contained in the files but i
> don't have the time to do this right now.
>
> - robert
>
> On Saturday, August 2, 2003, at 07:15 AM, Simon Kitching wrote:
>
> > Hi,
> >
> > Recently there was a suggestion on the users email group that some
> > digester examples would be helpful.
> >
> > I felt this myself when starting to use digester.
> >
> > So attached is a tar file containing a (proposed) initial example.
> >
> > The tar file contains the tree:
> >
> > examples
> > api
> > example1
> > **files here
> > xmlrules
> >
> > I suggest that this could all go under "src", so that there would be
> > "src/java", "src/test" and "src/examples".
> >
> > This would be consistent with the "httpclient" projects' directory
> > structure.
> >
> > I think that additional examples could usefully be added in future,
> > hence the name "example1" for the dir containing the provided code.
> >
> > Stuff that could be covered in later examples include:
> > * FactoryCreateRule
> > * NodeCreateRule
> > * mapping of attribute names to bean properties
> > (eg some-attr --> someAttr) when using setProperties et al.
> >
> > This contribution is not entirely selfless :-). The existence of this
> > examples directory also gives me somewhere to put "plugins" module
> > examples if the "plugins" module is accepted [patch coming soon....]
> >
> >
> > NOTE: I haven't made any changes to the existing digester "build.xml" to
> > either build or not build these new files. This would have to be done
> > sometime I think.
> >
> > Regards,
> >
> > Simon
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> > For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [digester] patch: usage examples
Posted by robert burrell donkin <ro...@blueyonder.co.uk>.
committed. many thanks.
it all looks fine. i've managed to resist the temptation to tinker too
much (just yet ;) but i have renamed the directory from example1 to
addressbook since i prefer descriptive names where possible. (i think that
it makes it easier for users.)
don't worry too much about the build script, it not a priority. maybe it'd
be a good idea to have a separate build.xml script in the examples
directory.
i've been toying with the idea of using maven to create some kind of
documentation based on the source plus html contained in the files but i
don't have the time to do this right now.
- robert
On Saturday, August 2, 2003, at 07:15 AM, Simon Kitching wrote:
> Hi,
>
> Recently there was a suggestion on the users email group that some
> digester examples would be helpful.
>
> I felt this myself when starting to use digester.
>
> So attached is a tar file containing a (proposed) initial example.
>
> The tar file contains the tree:
>
> examples
> api
> example1
> **files here
> xmlrules
>
> I suggest that this could all go under "src", so that there would be
> "src/java", "src/test" and "src/examples".
>
> This would be consistent with the "httpclient" projects' directory
> structure.
>
> I think that additional examples could usefully be added in future,
> hence the name "example1" for the dir containing the provided code.
>
> Stuff that could be covered in later examples include:
> * FactoryCreateRule
> * NodeCreateRule
> * mapping of attribute names to bean properties
> (eg some-attr --> someAttr) when using setProperties et al.
>
> This contribution is not entirely selfless :-). The existence of this
> examples directory also gives me somewhere to put "plugins" module
> examples if the "plugins" module is accepted [patch coming soon....]
>
>
> NOTE: I haven't made any changes to the existing digester "build.xml" to
> either build or not build these new files. This would have to be done
> sometime I think.
>
> Regards,
>
> Simon
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [digester] patch: usage examples
Posted by robert burrell donkin <ro...@blueyonder.co.uk>.
committed. many thanks.
it all looks fine. i've managed to resist the temptation to tinker too
much (just yet ;) but i have renamed the directory from example1 to
addressbook since i prefer descriptive names where possible. (i think that
it makes it easier for users.)
don't worry too much about the build script, it not a priority. maybe it'd
be a good idea to have a separate build.xml script in the examples
directory.
i've been toying with the idea of using maven to create some kind of
documentation based on the source plus html contained in the files but i
don't have the time to do this right now.
- robert
On Saturday, August 2, 2003, at 07:15 AM, Simon Kitching wrote:
> Hi,
>
> Recently there was a suggestion on the users email group that some
> digester examples would be helpful.
>
> I felt this myself when starting to use digester.
>
> So attached is a tar file containing a (proposed) initial example.
>
> The tar file contains the tree:
>
> examples
> api
> example1
> **files here
> xmlrules
>
> I suggest that this could all go under "src", so that there would be
> "src/java", "src/test" and "src/examples".
>
> This would be consistent with the "httpclient" projects' directory
> structure.
>
> I think that additional examples could usefully be added in future,
> hence the name "example1" for the dir containing the provided code.
>
> Stuff that could be covered in later examples include:
> * FactoryCreateRule
> * NodeCreateRule
> * mapping of attribute names to bean properties
> (eg some-attr --> someAttr) when using setProperties et al.
>
> This contribution is not entirely selfless :-). The existence of this
> examples directory also gives me somewhere to put "plugins" module
> examples if the "plugins" module is accepted [patch coming soon....]
>
>
> NOTE: I haven't made any changes to the existing digester "build.xml" to
> either build or not build these new files. This would have to be done
> sometime I think.
>
> Regards,
>
> Simon
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>