commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Niall Pemberton" <>
Subject Re: [io] 2.0 Moving to minimum of JDK 1.5
Date Thu, 07 Feb 2008 16:05:25 GMT
On Feb 7, 2008 8:10 AM, Stephen Colebourne <> wrote:
> Niall Pemberton wrote:
> >>> [Note CharSequence replaces String and/or StringBuffer flavours]
> >
> > OK for the above I added new methods, rather than changing the method
> > signature - so still compatbile atm:
> >
> Although, the API is now bigger. If we decide to break binary
> compatibility later, we need to remember to delete duplicates like this.
> >> All the other changes are binary compatible. Except for the problem that
> >> the bytecode format for Java 5 is different as well, so you'd need
> >> retrotranslator to help you out as well.
> >
> > Anything that depends on a JDK 1.5 IO version will have to also be
> > minimum JDK 1.5  and therefore direct or indirect users must be
> > running on JDK 1.5 - so I don't see any need for retrotranslator or
> > issues for users. Have I missed something?
> Hmm, yes we should be OK.
> >> In addition to the changes above, you will probably want to change most
> >> APIs that take in a Collection to take an Iterable instead.
> > OK I just had a quick scan and it looks we have the following methods
> > where we could do this:
> >     FilenameUtils.isExtension()
> >     FileUtils.convertFileCollectionToFileArray()
> >     FileUtils.writeLines()
> >     IOUtils.writeLines()
> > but this could also be done by just adding new flavours with an
> > Iterable, rather than changing the existing methods.
> Agreed, additional method can be added. Its certainly not as neat as
> just one method, and deprecation won't help (as any code linking to [io]
> will always pick the method taking a Collection, until the method is
> removed - hence removing the deprecation will never really be possible).
> >> We should probably remove all references to arrays in the public API, as
> >> generics and arrays work badly together, and I would strongly recommend
> >> treating arrays as a type not to be exposed on any public API post-Java5.
> >
> > Perhaps you could expand more on this because I don't see a big issue
> > for IO. - are you thinking along the following lines:
> >
> Kind of. Arrays and Generics do not work well together. One example is
> passing a generified list to a vararge method:
>   public void process(List<String>... values)
> This will always generate a warning, as the list gets converted to an array.

OK I'm not convinced by this. "Arrays and Generics do not work well
together" is a big generalization and your example doesn't relate to
arrays - from this you could say "varargs and Generics don't work well
together" so lets not use varargs in IO, but I don't see how it
relates to arrays.

How about Commons IO examples:

1) NameFileFilter has both String[] and List constructors:
  public NameFileFilter(List<String>)
  public NameFileFilter(String[])

IMO this provides choice for the user - how would removing the
String[] constructor benefit the user in any way?

2) I guess the other side of the equation is where we return an array,
there doesn't seem many cases of this, a quick scan showed these:
    - FileUtils.convertFileCollectionToFileArray()
    - FileUtils.readFileToByteArray()
    - FileUtils.toFiles()
    - FileUtils.toURLs()
    - IOUtils.toByteArray()
    - IOUtils.toCharArray()

Most seem appropriate, but perhaps toFiles() / toURLs() could return
an Iterable - but I could just as well envisage unhappy users who
prefer getting an array - better in that use case to provide two
flavours of methods so that the user can choose.

> In general, arrays work poorly with generics, to the point that you
> can't avoid the warnings. My recommendation would be to replace arrays
> in the API with Collection/Iterable/List as appropriate. Existing API
> users can easily adapt, and they will thank us for the lack of warnings.

I think you need to make a better case for this kind of policy.


> Stephen

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message