[jbosscache-dev] Let's make 3.0 backwards compatible

[Jason T. Greene]

Manik Surtani wrote:
> 
> On 18 Aug 2008, at 18:39, Jason T. Greene wrote:
> 
>> One of the headaches we cause our users, include the AS5 clustering 
>> team, is breaking API compatibility on every major release. This is 
>> probably the biggest reason why getting JBC3 into an AS5 release is a 
>> non-option.
> 
> Not just API - with MVCC, it is also the default configs shipped.  
> Although since 3.0 supports legacy locking schemes, it could always be 
> configured with the legacy locking schemes and a README included 
> explaining how to change these configs.

Yeah, I think it's generally ok for defaults to change. It only affects 
people that omitted a setting, and that is easily fixed.

> 
>> See users complaining:
>> http://www.jboss.com/index.html?module=bb&op=viewtopic&p=4171065#4171065
>>
>> I propose that we make 3.0 100% backwards compatible with JBC 2.x. 
>> This will improve adoption, and means we stand a chance at becoming a 
>> part of an AS5 release. IMO, there is little justification for API 
>> changes since our biggest feature / release goal doesn't require it. 
>> Also, since we have some API impacting features (partitioning, etc) 
>> scheduled for the next major release, it is very possible that we 
>> would end up breaking the API twice.
> 
> Agreed about the backward compat.
> 
> I don't foresee Partitioning affecting public API.

I think it has the potential to affect the Region API.

> 
>> The biggest API change is the Fqn changes, which while the overloaded 
>> constructors where broken, we don't have to remove them. We can just 
>> mark them as deprecated. Also, while the generics usage doesn't fit 
>> the type, it doesn't really hurt anything, so I think we can just live 
>> with that past design decision.
> 
> Yes, this is what I have done in 2.2.0 (deprecated the constructors, 
> introduced the factory methods).  I removed the deprecated ctors in 3.0 
> but they could be put back.  Same with the generics.

+1 :)

>> The other API change I noticed was XmlConfigurationParser. The old one 
>> was renamed to XmlConfigurationParser2x and moved to another package. 
>> The new one was named XmlConfigurationParser. Is this considered a 
>> public API?. If it is then we should make XmlConfigurationParser 
>> choose the appropriate implementation based off of the file format.
> 
> No this is not public API.  This is used by the DefaultCacheFactory.

That changed as well, getInstance() disappeared.

> Other public APIs that are potentially broken include the Eviction 
> configuration beans, but again we can provide a translation later and 
> mark old ones as deprecated.  The EvictionAlgorithm interface is harder.
> 
> Region and RegionManager interfaces have changed as well, and it can be 
> tricky to maintain compatibility here.
 >
> InvocationContext has changed (it is now an interface and cannot be 
> constructed with "new", but I don't think anyone ever did or should have 
> used it that way anyway).
> 
> LockManager has changed too, but again this is internal.

Yeah I think external usage is going to be fairly remote, and it was 
never considered a public API anyway. We should make this more explicit 
though, by moving stuff like this to packages like internal, impl, and 
so on.

> Everything else should be good.  At the end of the day, I guess the acid 
> test is to drop it into an AS 5 beta as well as Hibernate.
> 

Yeah if those work then IMO we achieved our goal.

-- 
Jason T. Greene
JBoss, a division of Red Hat