commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: [VFS] Next release should be 3.0 or 2.1?
Date Wed, 18 Jul 2012 01:10:41 GMT
On 17 July 2012 19:03, Gary Gregory <garydgregory@gmail.com> wrote:
> On Tue, Jul 17, 2012 at 11:08 AM, sebb <sebbaz@gmail.com> wrote:
>
>> On 17 July 2012 15:15, Gary Gregory <garydgregory@gmail.com> wrote:
>> > On Tue, Jul 17, 2012 at 5:47 AM, sebb <sebbaz@gmail.com> wrote:
>> >
>> >> On 16 July 2012 22:58, sebb <sebbaz@gmail.com> wrote:
>> >> > On 16 July 2012 21:31, Gary Gregory <garydgregory@gmail.com>
wrote:
>> >> >> Hi All:
>> >> >>
>> >> >> With the addition of many new methods to the FileObject interface
and
>> >> other
>> >> >> TAR changes reported by Clirr [1], the next release will break
BC for
>> >> VFS
>> >> >> providers (those not provided by VFS itself.)
>> >> >>
>> >> >> For normal call sites of the interfaces, nothing should change.
For
>> call
>> >> >> sites that use the TAR provider classe, some VFS TAR changes might
>> need
>> >> >> call site changes.
>> >> >>
>> >> >> Therefore, strictly speaking, the next release should be 3.0 with
a
>> >> package
>> >> >> rename.
>> >> >>
>> >> >> Thoughts?
>> >> >
>> >> > If it is only the TAR classes that break BC, could these alone be
>> >> renamed?
>> >> > If so, the original classes could be kept and deprecated.
>> >> >
>> >> > As a separate issue, if BC does have to be broken in some or all of
>> >> > the code, then please consider privatising all mutable variables (use
>> >> > setters/getters) and reducing visibility of classes and methods that
>> >> > are not intended to be part of the public API.
>>
>
> Right, I can buy that.
>
>
>> >> >
>> >> > I've not looked at the code, but it also strikes me that it might be
>> >> > possible to maintain BC by keeping and deprecating the methods that
>> >> > have changed parameter types; introducing a new interface for the new
>> >> > methods, and creating new methods for createTarFile and getTarFile
>> >> > which have changed return types.
>> >>
>> >> Just remembered that adding a method to an interface is binary
>> >> compatible [2], however it can affect source compatibility.
>> >>
>> >> Allowing these changes would much reduce the work needed to maintain BC.
>> >>
>> >> [2] http://docs.oracle.com/javase/specs/jls/se5.0/html/binaryComp.html
>> >>
>> >
>> > Ok, that that takes care of all the methods added to interfaces, which is
>> > in 2.1 territory
>> >
>> > I'm not sure if the other changes are easily changeable. I (or someone)
>> > will have to see if this can be hacked back.
>> >
>> > For the curious:
>> >
>> > Changed type of field entry from
>> > org.apache.commons.vfs2.provider.tar.TarEntry to
>> > org.apache.commons.compress.archivers.tar.TarArchiveEntry
>> > org.apache.commons.vfs2.provider.tar.TarFileObject    entry
>> >
>> > Parameter 2 of 'protected
>> > TarFileObject(org.apache.commons.vfs2.provider.AbstractFileName,
>> > org.apache.commons.vfs2.provider.tar.TarEntry,
>> > org.apache.commons.vfs2.provider.tar.TarFileSystem, boolean)' has changed
>> > its type to org.apache.commons.compress.archivers.tar.TarArchiveEntry
>> > org.apache.commons.vfs2.provider.tar.TarFileObject    protected
>> > TarFileObject(org.apache.commons.vfs2.provider.AbstractFileName,
>> > org.apache.commons.vfs2.provider.tar.TarEntry,
>> > org.apache.commons.vfs2.provider.tar.TarFileSystem, boolean)
>> >
>> > Parameter 1 of 'protected void
>> > setTarEntry(org.apache.commons.vfs2.provider.tar.TarEntry)' has changed
>> its
>> > type to org.apache.commons.compress.archivers.tar.TarArchiveEntry
>> > org.apache.commons.vfs2.provider.tar.TarFileObject    protected void
>> > setTarEntry(org.apache.commons.vfs2.provider.tar.TarEntry)
>> >
>> > Return type of method 'protected
>> > org.apache.commons.vfs2.provider.tar.TarInputStream
>> > createTarFile(java.io.File)' has been changed to
>> > org.apache.commons.compress.archivers.tar.TarArchiveInputStream
>> > org.apache.commons.vfs2.provider.tar.TarFileSystem    protected
>> > org.apache.commons.vfs2.provider.tar.TarInputStream
>> > createTarFile(java.io.File)
>> >
>> > Parameter 2 of 'protected
>> > org.apache.commons.vfs2.provider.tar.TarFileObject
>> > createTarFileObject(org.apache.commons.vfs2.provider.AbstractFileName,
>> > org.apache.commons.vfs2.provider.tar.TarEntry)' has changed its type to
>> > org.apache.commons.compress.archivers.tar.TarArchiveEntry
>> > org.apache.commons.vfs2.provider.tar.TarFileSystem    protected
>> > org.apache.commons.vfs2.provider.tar.TarFileObject
>> > createTarFileObject(org.apache.commons.vfs2.provider.AbstractFileName,
>> > org.apache.commons.vfs2.provider.tar.TarEntry)
>> >
>> > Parameter 1 of 'public java.io.InputStream
>> > getInputStream(org.apache.commons.vfs2.provider.tar.TarEntry)' has
>> changed
>> > its type to org.apache.commons.compress.archivers.tar.TarArchiveEntry
>> > org.apache.commons.vfs2.provider.tar.TarFileSystem    public
>> > java.io.InputStream
>> > getInputStream(org.apache.commons.vfs2.provider.tar.TarEntry)
>> >
>> > Return type of method 'protected
>> > org.apache.commons.vfs2.provider.tar.TarInputStream getTarFile()' has
>> been
>> > changed to
>> org.apache.commons.compress.archivers.tar.TarArchiveInputStream
>>
>> The main issue is that the TarEntry class has been removed; this was
>> used in various protected method signatures.
>> Given that the TarEntry class was package-protected, I'm not sure how
>> subclassing was supposed to work.
>>
>> Was it possible to subclass TarFileObject in the previous VFS releases?
>> AFAICT, that would require creating the subclass in the package
>> org.apache.commons.vfs2.provider.tar.
>>
>
> Yeah, hooking in that deep is a receipe for brittle code.
>
>
>> If so, then I think we can be fairly sure that there are no external
>> subclasses.
>> If there are, then the authors must realise that their code is
>> fragile, as it is based on the private API.
>> As such, IMO breaking BC is not really an issue.
>>
>> Note: the entry field really needs to be made private or package
>> protected; add a protected getter.
>> This can be done now.
>>
>
> org.apache.commons.vfs2.provider.tar.TarFileObject.entry is now private.
> org.apache.commons.vfs2.provider.tar.TarFileObject.setTarEntry(TarArchiveEntry)
> is now package private.
> See revision 1362586.
>
> What other changes like this do you think we should do for the next release?

I've not checked.
But the general rule is to minimise visibility as much as possible for
new methods etc.
It's always possible to relax restrictions; tightening them is much
more difficult.
Mutable fields should be avoided if possible and mutable fields should
always be private, as that allows methods to synchronise if necessary.

> Gary
>
>
>>
>> > Gary
>> >
>> >
>> >>
>> >> >> [1] http://oi46.tinypic.com/2ef46qr.jpg
>> >> >>
>> >> >> Thank you,
>> >> >> Gary
>> >> >>
>> >> >> --
>> >> >> E-Mail: garydgregory@gmail.com | ggregory@apache.org
>> >> >> JUnit in Action, 2nd Ed: <http://goog_1249600977>http://bit.ly/ECvg0
>> >> >> Spring Batch in Action: <http://s.apache.org/HOq>
>> http://bit.ly/bqpbCK
>> >> >> Blog: http://garygregory.wordpress.com
>> >> >> Home: http://garygregory.com/
>> >> >> Tweet! http://twitter.com/GaryGregory
>> >>
>> >> ---------------------------------------------------------------------
>> >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> >> For additional commands, e-mail: dev-help@commons.apache.org
>> >>
>> >>
>> >
>> >
>> > --
>> > E-Mail: garydgregory@gmail.com | ggregory@apache.org
>> > JUnit in Action, 2nd Ed: <http://goog_1249600977>http://bit.ly/ECvg0
>> > Spring Batch in Action: <http://s.apache.org/HOq>http://bit.ly/bqpbCK
>> > Blog: http://garygregory.wordpress.com
>> > Home: http://garygregory.com/
>> > Tweet! http://twitter.com/GaryGregory
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
>
>
> --
> E-Mail: garydgregory@gmail.com | ggregory@apache.org
> JUnit in Action, 2nd Ed: <http://goog_1249600977>http://bit.ly/ECvg0
> Spring Batch in Action: <http://s.apache.org/HOq>http://bit.ly/bqpbCK
> Blog: http://garygregory.wordpress.com
> Home: http://garygregory.com/
> Tweet! http://twitter.com/GaryGregory

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message