You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Stephen Colebourne <sc...@btopenworld.com> on 2003/08/23 14:24:28 UTC
Re: [collections] Code generation was: Re: [collections]contribute?
I've sent the author a mail to see what his views are. If he is favourable,
it will require primitive-collections to split from [collections], as the
code balance would be wrong. In fact I think I'm +1 to doing that anyway.
The name - [primcoll], [pcollections], [primitive-collections],
[primitives] ?
Stephen
----- Original Message -----
From: "__matthewHawthorne" <mh...@alumni.pitt.edu>
> I took a look around the web for primitive collection implementations,
> http://pcj.sourceforge.net looked interesting, and had some links at the
> bottom to similar projects.
>
>
>
>
> On Thu, 2003-08-21 at 16:24, Stephen Colebourne wrote:
> > At work I use Velocity to generate the java classes which then get
checked
> > into the CVS. The main trick in my case was to allow the generated java
> > files to be read in again by the generator next time around, so manually
> > added methods weren't lost.
> >
> > Code generation will work well for generating primitive Maps as there
are so
> > many possible combinations. However, before anyone starts, it would be
good
> > to search the web as I'm sure someone has probably already done this.
They
> > may be persuedable to donate the code/generator to Apache.
> >
> > Stephen
> >
> > ----- Original Message -----
> > From: "J.Pietschmann" <j3...@yahoo.de>
> > > __matthewHawthorne wrote:
> > > > There are many times that I've wished I had found a nice way to
> > > > autogenerate things while creating a bunch of redundant primitive
> > > > methods.
> > >
> > > There are half a zillion methods for generating code, starting
> > > with Bash/Sed/Perl hacks, leading to dedicated macro languages
> > > like the C preprocessor and m4, continuing with a variety of web
> > > templating languages like PHP, there's XSLT and finally high
> > > level stuff like lex/yacc, ANTLR and all the other grammar
> > > generators.
> > >
> > > The recurrent problems:
> > > - Need dedicated Ant tasks (Make was a bit easier here)
> > > - IDEs rarely handle them well
> > > - Tracking compile and runtime errors caused by generated code
> > > to the ultimate source isn't well supported and often painful
> > >
> > > I personally use ad-hoc generators mainly to bootstrap code, once
> > > the bulk of the code is stable, I abandon them.
> > >
> > > J.Pietschmann
> > >
> > >
> > > ---------------------------------------------------------------------
> > > 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: [collections] Code generation was: Re: [collections]contribute?
Posted by __matthewHawthorne <mh...@alumni.pitt.edu>.
The name [primitives] suggests that there are other classes involved
which deal only with primitives, not just primitive collections.
If that's the case, then I like [primitives].
If not, I like [pcollections].
On Sat, 2003-08-23 at 05:24, Stephen Colebourne wrote:
> I've sent the author a mail to see what his views are. If he is favourable,
> it will require primitive-collections to split from [collections], as the
> code balance would be wrong. In fact I think I'm +1 to doing that anyway.
>
> The name - [primcoll], [pcollections], [primitive-collections],
> [primitives] ?
>
> Stephen
>
> ----- Original Message -----
> From: "__matthewHawthorne" <mh...@alumni.pitt.edu>
> > I took a look around the web for primitive collection implementations,
> > http://pcj.sourceforge.net looked interesting, and had some links at the
> > bottom to similar projects.
> >
> >
> >
> >
> > On Thu, 2003-08-21 at 16:24, Stephen Colebourne wrote:
> > > At work I use Velocity to generate the java classes which then get
> checked
> > > into the CVS. The main trick in my case was to allow the generated java
> > > files to be read in again by the generator next time around, so manually
> > > added methods weren't lost.
> > >
> > > Code generation will work well for generating primitive Maps as there
> are so
> > > many possible combinations. However, before anyone starts, it would be
> good
> > > to search the web as I'm sure someone has probably already done this.
> They
> > > may be persuedable to donate the code/generator to Apache.
> > >
> > > Stephen
> > >
> > > ----- Original Message -----
> > > From: "J.Pietschmann" <j3...@yahoo.de>
> > > > __matthewHawthorne wrote:
> > > > > There are many times that I've wished I had found a nice way to
> > > > > autogenerate things while creating a bunch of redundant primitive
> > > > > methods.
> > > >
> > > > There are half a zillion methods for generating code, starting
> > > > with Bash/Sed/Perl hacks, leading to dedicated macro languages
> > > > like the C preprocessor and m4, continuing with a variety of web
> > > > templating languages like PHP, there's XSLT and finally high
> > > > level stuff like lex/yacc, ANTLR and all the other grammar
> > > > generators.
> > > >
> > > > The recurrent problems:
> > > > - Need dedicated Ant tasks (Make was a bit easier here)
> > > > - IDEs rarely handle them well
> > > > - Tracking compile and runtime errors caused by generated code
> > > > to the ultimate source isn't well supported and often painful
> > > >
> > > > I personally use ad-hoc generators mainly to bootstrap code, once
> > > > the bulk of the code is stable, I abandon them.
> > > >
> > > > J.Pietschmann
> > > >
> > > >
> > > > ---------------------------------------------------------------------
> > > > 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
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
Re: Subject: [collections][lang] question on javadoc guidelines wrt subclass behaviour
Posted by robert burrell donkin <ro...@blueyonder.co.uk>.
IMHO
1. if these changes are implementation details then it's reasonable not to
document them. rationale: if the contract for the subclass method says
that the collection will return a set (even though the return type is
collection) then users may reasonably cast the result to a set. if this is
an implementation detail then changing this will break a lot of code that
depends on it.
2. if these changes are not implementation detail but are core features of
the subclasses then it's reasonable to include these comments in the class
level documentation of each sub class.
- robert
On Sunday, August 24, 2003, at 09:23 AM, Stephen Colebourne wrote:
> I don't know of any way other than you suggest:
> 1) Polute the superclass javadoc
> 2) Add unrequired method to subclass
>
> We need a third option, but that involves javadoc changes.
>
> Stephen
>
> ----- Original Message -----
> From: "Neil O'Toole" <ne...@users.sourceforge.net>
>> this question might belong on a more general java list, but since i
>> came across the issue while doing stuff for collections, you guys are
>> going to have to suffer ;)
>>
>> In brief, how should one javadoc when method behaviour differs (or is
>> more specific) in a subclass, even though that method is not overridden
>> by the subclass? Or more concretely, if a method which returns a
>> Collection in a superclass always returns, say, a List in one subclass
>> and a Set in another subclass, can one cleanly document this fact using
>> javadoc without overriding the method just to add doc? For example:
>>
>> public class CollectionOfStuff
>> {
>> Collection things;
>>
>> Stuff( Collection c)
>> {
>> this.things = c;
>> }
>>
>> /**
>> * Return a Collection of objects.
>> */
>> public Collection getThings()
>> {
>> return things;
>> }
>>
>> }
>>
>>
>> public class SetOfStuff extends CollectionOfStuff
>> {
>> SetOfStuff( Set s)
>> {
>> super(s);
>> }
>>
>> /**
>> * This method will in fact always return a <b>Set</b> of objects.
>> */
>> public Collection getThings()
>> {
>> return (Set) super.getThings();
>> // typecast for emphasis only
>> }
>> }
>>
>> public class ListOfStuff extends CollectionOfStuff
>> {
>> ListOfStuff( List list)
>> {
>> super(list);
>> }
>>
>> /**
>> * This method will in fact always return a <b>List</b> of objects.
>> */
>> public Collection getThings()
>> {
>> return (List) super.getThings();
>> // typecast for emphasis only
>> }
>> }
>>
>> Obviously the #getThings implementations in the subclasses do nothing
>> useful, except generate javadoc. Being that we would really like to
>> document the behaviour of the subclass, how should we do this? Perhaps
>> put a note into the class-level doc stating that 'methods x, y, and z
>> from the superclass will always return this subtype of the method's
>> stated return type'? Can we do better than this?
>>
>> - Neil
>>
>>
>>
>> --- Stephen Colebourne <sc...@btopenworld.com> wrote:
>>> I've sent the author a mail to see what his views are. If he is
>>> favourable,
>>> it will require primitive-collections to split from [collections], as
>>> the
>>> code balance would be wrong. In fact I think I'm +1 to doing that
>>> anyway.
>>>
>>> The name - [primcoll], [pcollections], [primitive-collections],
>>> [primitives] ?
>>>
>>> Stephen
>>>
>>> ----- Original Message -----
>>> From: "__matthewHawthorne" <mh...@alumni.pitt.edu>
>>>> I took a look around the web for primitive collection
>>> implementations,
>>>> http://pcj.sourceforge.net looked interesting, and had some links
>>> at the
>>>> bottom to similar projects.
>>>>
>>>>
>>>>
>>>>
>>>> On Thu, 2003-08-21 at 16:24, Stephen Colebourne wrote:
>>>>> At work I use Velocity to generate the java classes which then
>>> get
>>> checked
>>>>> into the CVS. The main trick in my case was to allow the
>>> generated java
>>>>> files to be read in again by the generator next time around, so
>>> manually
>>>>> added methods weren't lost.
>>>>>
>>>>> Code generation will work well for generating primitive Maps as
>>> there
>>> are so
>>>>> many possible combinations. However, before anyone starts, it
>>> would be
>>> good
>>>>> to search the web as I'm sure someone has probably already done
>>> this.
>>> They
>>>>> may be persuedable to donate the code/generator to Apache.
>>>>>
>>>>> Stephen
>>>>>
>>>>> ----- Original Message -----
>>>>> From: "J.Pietschmann" <j3...@yahoo.de>
>>>>>> __matthewHawthorne wrote:
>>>>>>> There are many times that I've wished I had found a nice way
>>> to
>>>>>>> autogenerate things while creating a bunch of redundant
>>> primitive
>>>>>>> methods.
>>>>>>
>>>>>> There are half a zillion methods for generating code, starting
>>>>>> with Bash/Sed/Perl hacks, leading to dedicated macro languages
>>>>>> like the C preprocessor and m4, continuing with a variety of
>>> web
>>>>>> templating languages like PHP, there's XSLT and finally high
>>>>>> level stuff like lex/yacc, ANTLR and all the other grammar
>>>>>> generators.
>>>>>>
>>>>>> The recurrent problems:
>>>>>> - Need dedicated Ant tasks (Make was a bit easier here)
>>>>>> - IDEs rarely handle them well
>>>>>> - Tracking compile and runtime errors caused by generated code
>>>>>> to the ultimate source isn't well supported and often
>>> painful
>>>>>>
>>>>>> I personally use ad-hoc generators mainly to bootstrap code,
>>> once
>>>>>> the bulk of the code is stable, I abandon them.
>>>>>>
>>>>>> J.Pietschmann
>>>>>>
>>>>>>
>>>>>>
>>> ---------------------------------------------------------------------
>>>>>> 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
>>>>
>>>
>>>
>>> ---------------------------------------------------------------------
>>> 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: Subject: [collections][lang] question on javadoc guidelines wrt subclass behaviour
Posted by Stephen Colebourne <sc...@btopenworld.com>.
I don't know of any way other than you suggest:
1) Polute the superclass javadoc
2) Add unrequired method to subclass
We need a third option, but that involves javadoc changes.
Stephen
----- Original Message -----
From: "Neil O'Toole" <ne...@users.sourceforge.net>
> this question might belong on a more general java list, but since i
> came across the issue while doing stuff for collections, you guys are
> going to have to suffer ;)
>
> In brief, how should one javadoc when method behaviour differs (or is
> more specific) in a subclass, even though that method is not overridden
> by the subclass? Or more concretely, if a method which returns a
> Collection in a superclass always returns, say, a List in one subclass
> and a Set in another subclass, can one cleanly document this fact using
> javadoc without overriding the method just to add doc? For example:
>
> public class CollectionOfStuff
> {
> Collection things;
>
> Stuff( Collection c)
> {
> this.things = c;
> }
>
> /**
> * Return a Collection of objects.
> */
> public Collection getThings()
> {
> return things;
> }
>
> }
>
>
> public class SetOfStuff extends CollectionOfStuff
> {
> SetOfStuff( Set s)
> {
> super(s);
> }
>
> /**
> * This method will in fact always return a <b>Set</b> of objects.
> */
> public Collection getThings()
> {
> return (Set) super.getThings();
> // typecast for emphasis only
> }
> }
>
> public class ListOfStuff extends CollectionOfStuff
> {
> ListOfStuff( List list)
> {
> super(list);
> }
>
> /**
> * This method will in fact always return a <b>List</b> of objects.
> */
> public Collection getThings()
> {
> return (List) super.getThings();
> // typecast for emphasis only
> }
> }
>
> Obviously the #getThings implementations in the subclasses do nothing
> useful, except generate javadoc. Being that we would really like to
> document the behaviour of the subclass, how should we do this? Perhaps
> put a note into the class-level doc stating that 'methods x, y, and z
> from the superclass will always return this subtype of the method's
> stated return type'? Can we do better than this?
>
> - Neil
>
>
>
> --- Stephen Colebourne <sc...@btopenworld.com> wrote:
> > I've sent the author a mail to see what his views are. If he is
> > favourable,
> > it will require primitive-collections to split from [collections], as
> > the
> > code balance would be wrong. In fact I think I'm +1 to doing that
> > anyway.
> >
> > The name - [primcoll], [pcollections], [primitive-collections],
> > [primitives] ?
> >
> > Stephen
> >
> > ----- Original Message -----
> > From: "__matthewHawthorne" <mh...@alumni.pitt.edu>
> > > I took a look around the web for primitive collection
> > implementations,
> > > http://pcj.sourceforge.net looked interesting, and had some links
> > at the
> > > bottom to similar projects.
> > >
> > >
> > >
> > >
> > > On Thu, 2003-08-21 at 16:24, Stephen Colebourne wrote:
> > > > At work I use Velocity to generate the java classes which then
> > get
> > checked
> > > > into the CVS. The main trick in my case was to allow the
> > generated java
> > > > files to be read in again by the generator next time around, so
> > manually
> > > > added methods weren't lost.
> > > >
> > > > Code generation will work well for generating primitive Maps as
> > there
> > are so
> > > > many possible combinations. However, before anyone starts, it
> > would be
> > good
> > > > to search the web as I'm sure someone has probably already done
> > this.
> > They
> > > > may be persuedable to donate the code/generator to Apache.
> > > >
> > > > Stephen
> > > >
> > > > ----- Original Message -----
> > > > From: "J.Pietschmann" <j3...@yahoo.de>
> > > > > __matthewHawthorne wrote:
> > > > > > There are many times that I've wished I had found a nice way
> > to
> > > > > > autogenerate things while creating a bunch of redundant
> > primitive
> > > > > > methods.
> > > > >
> > > > > There are half a zillion methods for generating code, starting
> > > > > with Bash/Sed/Perl hacks, leading to dedicated macro languages
> > > > > like the C preprocessor and m4, continuing with a variety of
> > web
> > > > > templating languages like PHP, there's XSLT and finally high
> > > > > level stuff like lex/yacc, ANTLR and all the other grammar
> > > > > generators.
> > > > >
> > > > > The recurrent problems:
> > > > > - Need dedicated Ant tasks (Make was a bit easier here)
> > > > > - IDEs rarely handle them well
> > > > > - Tracking compile and runtime errors caused by generated code
> > > > > to the ultimate source isn't well supported and often
> > painful
> > > > >
> > > > > I personally use ad-hoc generators mainly to bootstrap code,
> > once
> > > > > the bulk of the code is stable, I abandon them.
> > > > >
> > > > > J.Pietschmann
> > > > >
> > > > >
> > > > >
> > ---------------------------------------------------------------------
> > > > > 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
> > >
> >
> >
> > ---------------------------------------------------------------------
> > 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
>
Subject: [collections][lang] question on javadoc guidelines wrt subclass behaviour
Posted by Neil O'Toole <ne...@users.sourceforge.net>.
this question might belong on a more general java list, but since i
came across the issue while doing stuff for collections, you guys are
going to have to suffer ;)
In brief, how should one javadoc when method behaviour differs (or is
more specific) in a subclass, even though that method is not overridden
by the subclass? Or more concretely, if a method which returns a
Collection in a superclass always returns, say, a List in one subclass
and a Set in another subclass, can one cleanly document this fact using
javadoc without overriding the method just to add doc? For example:
public class CollectionOfStuff
{
Collection things;
Stuff( Collection c)
{
this.things = c;
}
/**
* Return a Collection of objects.
*/
public Collection getThings()
{
return things;
}
}
public class SetOfStuff extends CollectionOfStuff
{
SetOfStuff( Set s)
{
super(s);
}
/**
* This method will in fact always return a <b>Set</b> of objects.
*/
public Collection getThings()
{
return (Set) super.getThings();
// typecast for emphasis only
}
}
public class ListOfStuff extends CollectionOfStuff
{
ListOfStuff( List list)
{
super(list);
}
/**
* This method will in fact always return a <b>List</b> of objects.
*/
public Collection getThings()
{
return (List) super.getThings();
// typecast for emphasis only
}
}
Obviously the #getThings implementations in the subclasses do nothing
useful, except generate javadoc. Being that we would really like to
document the behaviour of the subclass, how should we do this? Perhaps
put a note into the class-level doc stating that 'methods x, y, and z
from the superclass will always return this subtype of the method's
stated return type'? Can we do better than this?
- Neil
--- Stephen Colebourne <sc...@btopenworld.com> wrote:
> I've sent the author a mail to see what his views are. If he is
> favourable,
> it will require primitive-collections to split from [collections], as
> the
> code balance would be wrong. In fact I think I'm +1 to doing that
> anyway.
>
> The name - [primcoll], [pcollections], [primitive-collections],
> [primitives] ?
>
> Stephen
>
> ----- Original Message -----
> From: "__matthewHawthorne" <mh...@alumni.pitt.edu>
> > I took a look around the web for primitive collection
> implementations,
> > http://pcj.sourceforge.net looked interesting, and had some links
> at the
> > bottom to similar projects.
> >
> >
> >
> >
> > On Thu, 2003-08-21 at 16:24, Stephen Colebourne wrote:
> > > At work I use Velocity to generate the java classes which then
> get
> checked
> > > into the CVS. The main trick in my case was to allow the
> generated java
> > > files to be read in again by the generator next time around, so
> manually
> > > added methods weren't lost.
> > >
> > > Code generation will work well for generating primitive Maps as
> there
> are so
> > > many possible combinations. However, before anyone starts, it
> would be
> good
> > > to search the web as I'm sure someone has probably already done
> this.
> They
> > > may be persuedable to donate the code/generator to Apache.
> > >
> > > Stephen
> > >
> > > ----- Original Message -----
> > > From: "J.Pietschmann" <j3...@yahoo.de>
> > > > __matthewHawthorne wrote:
> > > > > There are many times that I've wished I had found a nice way
> to
> > > > > autogenerate things while creating a bunch of redundant
> primitive
> > > > > methods.
> > > >
> > > > There are half a zillion methods for generating code, starting
> > > > with Bash/Sed/Perl hacks, leading to dedicated macro languages
> > > > like the C preprocessor and m4, continuing with a variety of
> web
> > > > templating languages like PHP, there's XSLT and finally high
> > > > level stuff like lex/yacc, ANTLR and all the other grammar
> > > > generators.
> > > >
> > > > The recurrent problems:
> > > > - Need dedicated Ant tasks (Make was a bit easier here)
> > > > - IDEs rarely handle them well
> > > > - Tracking compile and runtime errors caused by generated code
> > > > to the ultimate source isn't well supported and often
> painful
> > > >
> > > > I personally use ad-hoc generators mainly to bootstrap code,
> once
> > > > the bulk of the code is stable, I abandon them.
> > > >
> > > > J.Pietschmann
> > > >
> > > >
> > > >
> ---------------------------------------------------------------------
> > > > 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
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>