[VFS] Analysis of binary compatibility breaks between 1.0 and 2.0; release strategy

[sebb <se...@gmail.com>]

Clirr reports the following problems when comparing the codebases
(prior to the vfs2 package rename)

1) Selectors: Changed from interface to class
This contains only constants. The interface was not actually
implemented by any VFS classes; the constants were referenced using
the class name
If any user classes were lazy and implemented the interface rather
than using the qualified name, then they would break.
But this seems rather unlikely.

2) util.UserAuthenticatorUtils: Added final modifier to class
- class has static methods only, so no point in sub-classing it

3) FileSystemOptions: Added final modifier to class
- this class appears to be internal use only

4)
provider.HostFileNameParser$Authority: Accessibility of field hostName
has been weakened from public to private
provider.HostFileNameParser$Authority: Accessibility of field password
has been weakened from public to private
provider.HostFileNameParser$Authority: Accessibility of field port has
been weakened from public to private
provider.HostFileNameParser$Authority: Accessibility of field scheme
has been weakened from public to private
provider.HostFileNameParser$Authority: Accessibility of field userName
has been weakened from public to private
- These are all changes to a protected nested class; seems to be
internal use only

5) FileSystemConfigBuilder: Accessibility of method 'public
FileSystemConfigBuilder()' has been decreased from public to protected
This is the default ctor of an abstract class. The other ctor was
already protected. User code should not be instantiating this class
directly.

6) util.UserAuthenticatorUtils: Accessibility of method 'public
UserAuthenticatorUtils()' has been decreased from public to private
This is a class with static methods only; it should never be instantiated

7) FileContent: Method 'public boolean hasAttribute(java.lang.String)'
has been added to an interface
   FileContent: Method 'public void removeAttribute(java.lang.String)'
has been added to an interface
There is a single implementation: DefaultFileContent

8) FileSystem: Method 'public java.lang.String getRootURI()' has been
added to an interface
There is an AbstractFileSystem class which all other VFS
implementations subclass.

9) FileSystemManager: Method 'public boolean
hasProvider(java.lang.String)' has been added to an interface
There is a DefaultFileSystemManager which is the most likely route for
any 3rd party implementations.

These 3 interfaces are part of the public API as far as I can tell.
However, would user code ever directly implement the interfaces?

==

It looks to me as though user code is very unlikely to be affected by
any of the binary changes.
The only changes that might perhaps affect user code are 1), 7), 9)
and possibly 8)

Also, the latest Gump run of vfs 1.x (which is actually using the SVN
code commons/proper/vfs/tags/preVFS2package temporarily) does not have
any dependee failures (apart from Doxia which fails for an unrelated
reason).

I think it would be safe to release 2.0 using the package o.a.c.vfs
(rather than vfs2).
[It needs to be 2.0 because of the API changes and there are a lot of
new providers etc.]
However this would mean reverting to the old groupId (unless we can be
sure that relocation POMs work).

[Note: The recent StringBuilder changes can be made
backwards-compatible by adding back the old API methods].

As I see it, there are the following options:

1) Release 2.0 as described above.
Upside: no need for downstream users to update their code.
Downside is the change to o.a.c groupId may not be possible. Slight
risk of user API break.

2) Release 2.0 using vfs2 and groupId o.a.c
Upside: Can fix groupId. No need to maintain any API compatibility;
can drop all deprecated code.
Downside: All downstream users need to recode their applications.

If the consensus is to stick with VFS2 and option 2, then I think we
need to look very carefully at the code to ensure that there aren't
any areas of the code that would benefit from an API change.  In
particular, we should delete all deprecated code.

Otherwise there might have to be VFS3 which would force all downstream
users to recode their applications yet again.

Or perhaps we could release an ALPHA or BETA version, with the proviso
that the API might change when the final version is released?
At least then downstream users would be warned.

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

Re: [VFS] Analysis of binary compatibility breaks between 1.0 and 2.0; release strategy

[Jörg Schaible <jo...@scalaris.com>]

James Carman wrote:

> On Wed, Nov 17, 2010 at 12:25 PM, Gary Gregory
> <GG...@seagullsoftware.com> wrote:
>>> My feeling is that if we are upgrading to Java 5 then we should do it
>>> correctly. Go ahead and break compatibility where required. In that view
>>> the changes done to the Comparables were done correctly.  I suspect they
>>> will cause very few problems in any case.  Since we have changed the
>>> package name and artifactId I just wouldn't worry about it.
>>>
>>> I agree we should remove the deprecated APIs - there don't appear to be
>>> many of them - although I do find myself wondering why in
>>> AbstractFileObject doSetLastModifiedTime was deprecated in favor of
>>> doSetLastModTime. I actually prefer the former name.
>>
>> +1
>>
> 
> +1.  I say keep things the way they are now.  It's not just about
> client libraries having to fix themselves.  It's mostly about client
> libraries using other libraries that could rely on a binary
> incompatible version of VFS.  Of course it's no trouble (or at least
> not much) to fix my code to use the new API.  However, suppose I rely
> on Library X which uses an older, incompatible version of VFS?  What
> do I do then if the package names haven't changed?  Bottom line, if
> you're breaking compatibility in any way, you need to bump the major
> version number.  With that comes the package and artifactId change, as
> suggested.

+1 :)


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

Re: [VFS] Analysis of binary compatibility breaks between 1.0 and 2.0; release strategy

[James Carman <ja...@carmanconsulting.com>]

On Wed, Nov 17, 2010 at 12:25 PM, Gary Gregory
<GG...@seagullsoftware.com> wrote:
>> My feeling is that if we are upgrading to Java 5 then we should do it
>> correctly. Go ahead and break compatibility where required. In that view the
>> changes done to the Comparables were done correctly.  I suspect they will
>> cause very few problems in any case.  Since we have changed the package name
>> and artifactId I just wouldn't worry about it.
>>
>> I agree we should remove the deprecated APIs - there don't appear to be many
>> of them - although I do find myself wondering why in AbstractFileObject
>> doSetLastModifiedTime was deprecated in favor of doSetLastModTime. I actually
>> prefer the former name.
>
> +1
>

+1.  I say keep things the way they are now.  It's not just about
client libraries having to fix themselves.  It's mostly about client
libraries using other libraries that could rely on a binary
incompatible version of VFS.  Of course it's no trouble (or at least
not much) to fix my code to use the new API.  However, suppose I rely
on Library X which uses an older, incompatible version of VFS?  What
do I do then if the package names haven't changed?  Bottom line, if
you're breaking compatibility in any way, you need to bump the major
version number.  With that comes the package and artifactId change, as
suggested.

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

RE: [VFS] Analysis of binary compatibility breaks between 1.0 and 2.0; release strategy

[Gary Gregory <GG...@seagullsoftware.com>]

> -----Original Message-----
> From: Ralph Goers [mailto:ralph.goers@dslextreme.com]
> Sent: Wednesday, November 17, 2010 06:35
> To: Commons Developers List
> Subject: Re: [VFS] Analysis of binary compatibility breaks between 1.0 and
> 2.0; release strategy
> 
> 
> On Nov 17, 2010, at 2:54 AM, sebb wrote:
> 
> > On 17 November 2010 07:17, Ralph Goers <ra...@dslextreme.com> wrote:
> >>
> >
> >> I'm not suggesting we change these. Since we are adopting Java 5 I would
> prefer to change these now and move forward.
> >
> > To change or not to change? Sorry, cannot understand the last paragraph.
> >
> 
> Sorry I wasn't clear.
> 
> My feeling is that if we are upgrading to Java 5 then we should do it
> correctly. Go ahead and break compatibility where required. In that view the
> changes done to the Comparables were done correctly.  I suspect they will
> cause very few problems in any case.  Since we have changed the package name
> and artifactId I just wouldn't worry about it.
> 
> I agree we should remove the deprecated APIs - there don't appear to be many
> of them - although I do find myself wondering why in AbstractFileObject
> doSetLastModifiedTime was deprecated in favor of doSetLastModTime. I actually
> prefer the former name.

+1

> 
> Ralph


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

Re: [VFS] Analysis of binary compatibility breaks between 1.0 and 2.0; release strategy

[Ralph Goers <ra...@dslextreme.com>]

On Nov 17, 2010, at 2:54 AM, sebb wrote:

> On 17 November 2010 07:17, Ralph Goers <ra...@dslextreme.com> wrote:
>> 
> 
>> I'm not suggesting we change these. Since we are adopting Java 5 I would prefer to change these now and move forward.
> 
> To change or not to change? Sorry, cannot understand the last paragraph.
> 

Sorry I wasn't clear.  

My feeling is that if we are upgrading to Java 5 then we should do it correctly. Go ahead and break compatibility where required. In that view the changes done to the Comparables were done correctly.  I suspect they will cause very few problems in any case.  Since we have changed the package name and artifactId I just wouldn't worry about it.   

I agree we should remove the deprecated APIs - there don't appear to be many of them - although I do find myself wondering why in AbstractFileObject doSetLastModifiedTime was deprecated in favor of doSetLastModTime. I actually prefer the former name.

Ralph

Re: [VFS] Analysis of binary compatibility breaks between 1.0 and 2.0; release strategy

[sebb <se...@gmail.com>]

On 17 November 2010 07:17, Ralph Goers <ra...@dslextreme.com> wrote:
>
> On Nov 16, 2010, at 4:19 PM, sebb wrote:
>
>> On 17 November 2010 00:06, ralph.goers @dslextreme.com
>> <ra...@dslextreme.com> wrote:
>>> I'm not sure why the tool didn't catch it, but a few methods now return
>>> Map<String, Object> where they previously returned Map. I didn't check for
>>> generics other than "Map<".
>>
>> Surely these are equivalent at run-time?
>>
>> Generics are a compile-time feature.
>>
>
> See http://www.jroller.com/scolebourne/entry/java_generics_migration_compatibility and then take a look at the several changes made to add generics to Comparable.  These changes don't seem to be binary compatible. I'm surprised they didn't show up in the report you ran.

Maybe Clirr does not check fully - after all it was written before Java 5.

But I agreed that once generics are introduced, one needs to be
careful to ensure that source compatibility is also maintained.

Prior to Java 5, I think source compatibility was probably guaranteed
if the code was binary compatible. I don't think it is now.
[The reverse has never been the case - e.g. changing a void method to
return boolean won't affect recompilation, but will affect run-time as
the signature changes - so the method can no longer be found.]

There probably needs to be a tool to check source compatibility.

> I've found several other articles that describe how, under certain circumstances, type erasure can result in a different type being used than existed in a prior, non-generified version of the code. I've not fully inspected all teh changes to determine if any of those cases are present.

Perhaps add the links to a Wiki page where we can collect any such info?

> I'm not suggesting we change these. Since we are adopting Java 5 I would prefer to change these now and move forward.

To change or not to change? Sorry, cannot understand the last paragraph.

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

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

Re: [VFS] Analysis of binary compatibility breaks between 1.0 and 2.0; release strategy

[Ralph Goers <ra...@dslextreme.com>]

On Nov 16, 2010, at 4:19 PM, sebb wrote:

> On 17 November 2010 00:06, ralph.goers @dslextreme.com
> <ra...@dslextreme.com> wrote:
>> I'm not sure why the tool didn't catch it, but a few methods now return
>> Map<String, Object> where they previously returned Map. I didn't check for
>> generics other than "Map<".
> 
> Surely these are equivalent at run-time?
> 
> Generics are a compile-time feature.
> 

See http://www.jroller.com/scolebourne/entry/java_generics_migration_compatibility and then take a look at the several changes made to add generics to Comparable.  These changes don't seem to be binary compatible. I'm surprised they didn't show up in the report you ran.

I've found several other articles that describe how, under certain circumstances, type erasure can result in a different type being used than existed in a prior, non-generified version of the code. I've not fully inspected all teh changes to determine if any of those cases are present.

I'm not suggesting we change these. Since we are adopting Java 5 I would prefer to change these now and move forward.

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

Re: [VFS] Analysis of binary compatibility breaks between 1.0 and 2.0; release strategy

[sebb <se...@gmail.com>]

On 17 November 2010 00:06, ralph.goers @dslextreme.com
<ra...@dslextreme.com> wrote:
> I'm not sure why the tool didn't catch it, but a few methods now return
> Map<String, Object> where they previously returned Map. I didn't check for
> generics other than "Map<".

Surely these are equivalent at run-time?

Generics are a compile-time feature.

> Ralph
>
> On Tue, Nov 16, 2010 at 1:21 PM, sebb <se...@gmail.com> wrote:
>
>> Clirr reports the following problems when comparing the codebases
>> (prior to the vfs2 package rename)
>>
>> 1) Selectors: Changed from interface to class
>> This contains only constants. The interface was not actually
>> implemented by any VFS classes; the constants were referenced using
>> the class name
>> If any user classes were lazy and implemented the interface rather
>> than using the qualified name, then they would break.
>> But this seems rather unlikely.
>>
>> 2) util.UserAuthenticatorUtils: Added final modifier to class
>> - class has static methods only, so no point in sub-classing it
>>
>> 3) FileSystemOptions: Added final modifier to class
>> - this class appears to be internal use only
>>
>> 4)
>> provider.HostFileNameParser$Authority: Accessibility of field hostName
>> has been weakened from public to private
>> provider.HostFileNameParser$Authority: Accessibility of field password
>> has been weakened from public to private
>> provider.HostFileNameParser$Authority: Accessibility of field port has
>> been weakened from public to private
>> provider.HostFileNameParser$Authority: Accessibility of field scheme
>> has been weakened from public to private
>> provider.HostFileNameParser$Authority: Accessibility of field userName
>> has been weakened from public to private
>> - These are all changes to a protected nested class; seems to be
>> internal use only
>>
>> 5) FileSystemConfigBuilder: Accessibility of method 'public
>> FileSystemConfigBuilder()' has been decreased from public to protected
>> This is the default ctor of an abstract class. The other ctor was
>> already protected. User code should not be instantiating this class
>> directly.
>>
>> 6) util.UserAuthenticatorUtils: Accessibility of method 'public
>> UserAuthenticatorUtils()' has been decreased from public to private
>> This is a class with static methods only; it should never be instantiated
>>
>> 7) FileContent: Method 'public boolean hasAttribute(java.lang.String)'
>> has been added to an interface
>>   FileContent: Method 'public void removeAttribute(java.lang.String)'
>> has been added to an interface
>> There is a single implementation: DefaultFileContent
>>
>> 8) FileSystem: Method 'public java.lang.String getRootURI()' has been
>> added to an interface
>> There is an AbstractFileSystem class which all other VFS
>> implementations subclass.
>>
>> 9) FileSystemManager: Method 'public boolean
>> hasProvider(java.lang.String)' has been added to an interface
>> There is a DefaultFileSystemManager which is the most likely route for
>> any 3rd party implementations.
>>
>> These 3 interfaces are part of the public API as far as I can tell.
>> However, would user code ever directly implement the interfaces?
>>
>> ==
>>
>> It looks to me as though user code is very unlikely to be affected by
>> any of the binary changes.
>> The only changes that might perhaps affect user code are 1), 7), 9)
>> and possibly 8)
>>
>> Also, the latest Gump run of vfs 1.x (which is actually using the SVN
>> code commons/proper/vfs/tags/preVFS2package temporarily) does not have
>> any dependee failures (apart from Doxia which fails for an unrelated
>> reason).
>>
>> I think it would be safe to release 2.0 using the package o.a.c.vfs
>> (rather than vfs2).
>> [It needs to be 2.0 because of the API changes and there are a lot of
>> new providers etc.]
>> However this would mean reverting to the old groupId (unless we can be
>> sure that relocation POMs work).
>>
>> [Note: The recent StringBuilder changes can be made
>> backwards-compatible by adding back the old API methods].
>>
>> As I see it, there are the following options:
>>
>> 1) Release 2.0 as described above.
>> Upside: no need for downstream users to update their code.
>> Downside is the change to o.a.c groupId may not be possible. Slight
>> risk of user API break.
>>
>> 2) Release 2.0 using vfs2 and groupId o.a.c
>> Upside: Can fix groupId. No need to maintain any API compatibility;
>> can drop all deprecated code.
>> Downside: All downstream users need to recode their applications.
>>
>> If the consensus is to stick with VFS2 and option 2, then I think we
>> need to look very carefully at the code to ensure that there aren't
>> any areas of the code that would benefit from an API change.  In
>> particular, we should delete all deprecated code.
>>
>> Otherwise there might have to be VFS3 which would force all downstream
>> users to recode their applications yet again.
>>
>> Or perhaps we could release an ALPHA or BETA version, with the proviso
>> that the API might change when the final version is released?
>> At least then downstream users would be warned.
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
>

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

Re: [VFS] Analysis of binary compatibility breaks between 1.0 and 2.0; release strategy

["ralph.goers @dslextreme.com" <ra...@dslextreme.com>]

I'm not sure why the tool didn't catch it, but a few methods now return
Map<String, Object> where they previously returned Map. I didn't check for
generics other than "Map<".

Ralph

On Tue, Nov 16, 2010 at 1:21 PM, sebb <se...@gmail.com> wrote:

> Clirr reports the following problems when comparing the codebases
> (prior to the vfs2 package rename)
>
> 1) Selectors: Changed from interface to class
> This contains only constants. The interface was not actually
> implemented by any VFS classes; the constants were referenced using
> the class name
> If any user classes were lazy and implemented the interface rather
> than using the qualified name, then they would break.
> But this seems rather unlikely.
>
> 2) util.UserAuthenticatorUtils: Added final modifier to class
> - class has static methods only, so no point in sub-classing it
>
> 3) FileSystemOptions: Added final modifier to class
> - this class appears to be internal use only
>
> 4)
> provider.HostFileNameParser$Authority: Accessibility of field hostName
> has been weakened from public to private
> provider.HostFileNameParser$Authority: Accessibility of field password
> has been weakened from public to private
> provider.HostFileNameParser$Authority: Accessibility of field port has
> been weakened from public to private
> provider.HostFileNameParser$Authority: Accessibility of field scheme
> has been weakened from public to private
> provider.HostFileNameParser$Authority: Accessibility of field userName
> has been weakened from public to private
> - These are all changes to a protected nested class; seems to be
> internal use only
>
> 5) FileSystemConfigBuilder: Accessibility of method 'public
> FileSystemConfigBuilder()' has been decreased from public to protected
> This is the default ctor of an abstract class. The other ctor was
> already protected. User code should not be instantiating this class
> directly.
>
> 6) util.UserAuthenticatorUtils: Accessibility of method 'public
> UserAuthenticatorUtils()' has been decreased from public to private
> This is a class with static methods only; it should never be instantiated
>
> 7) FileContent: Method 'public boolean hasAttribute(java.lang.String)'
> has been added to an interface
>   FileContent: Method 'public void removeAttribute(java.lang.String)'
> has been added to an interface
> There is a single implementation: DefaultFileContent
>
> 8) FileSystem: Method 'public java.lang.String getRootURI()' has been
> added to an interface
> There is an AbstractFileSystem class which all other VFS
> implementations subclass.
>
> 9) FileSystemManager: Method 'public boolean
> hasProvider(java.lang.String)' has been added to an interface
> There is a DefaultFileSystemManager which is the most likely route for
> any 3rd party implementations.
>
> These 3 interfaces are part of the public API as far as I can tell.
> However, would user code ever directly implement the interfaces?
>
> ==
>
> It looks to me as though user code is very unlikely to be affected by
> any of the binary changes.
> The only changes that might perhaps affect user code are 1), 7), 9)
> and possibly 8)
>
> Also, the latest Gump run of vfs 1.x (which is actually using the SVN
> code commons/proper/vfs/tags/preVFS2package temporarily) does not have
> any dependee failures (apart from Doxia which fails for an unrelated
> reason).
>
> I think it would be safe to release 2.0 using the package o.a.c.vfs
> (rather than vfs2).
> [It needs to be 2.0 because of the API changes and there are a lot of
> new providers etc.]
> However this would mean reverting to the old groupId (unless we can be
> sure that relocation POMs work).
>
> [Note: The recent StringBuilder changes can be made
> backwards-compatible by adding back the old API methods].
>
> As I see it, there are the following options:
>
> 1) Release 2.0 as described above.
> Upside: no need for downstream users to update their code.
> Downside is the change to o.a.c groupId may not be possible. Slight
> risk of user API break.
>
> 2) Release 2.0 using vfs2 and groupId o.a.c
> Upside: Can fix groupId. No need to maintain any API compatibility;
> can drop all deprecated code.
> Downside: All downstream users need to recode their applications.
>
> If the consensus is to stick with VFS2 and option 2, then I think we
> need to look very carefully at the code to ensure that there aren't
> any areas of the code that would benefit from an API change.  In
> particular, we should delete all deprecated code.
>
> Otherwise there might have to be VFS3 which would force all downstream
> users to recode their applications yet again.
>
> Or perhaps we could release an ALPHA or BETA version, with the proviso
> that the API might change when the final version is released?
> At least then downstream users would be warned.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>