Please let us know what you think about these potential incompatible API changes

[Sean Mullan <Se...@Sun.COM>]

Hi,

Raul and I have discussed this a bit offline, but we decided to take the
discussion to the list to hear from others about the effect of some
potentially incompatible changes that were made to the TransformSpi class.

In 1.4, a new abstract protected
enginePerformTransform(XMLSignatureInput, Transform) method was added to 
the TransformSpi class and the existing 
enginePerformTransform(XMLSignatureInput) method was
removed. The new method was designed to replace the old method and was
done to improve performance, which is all very good.

Unfortunately, it means that existing TransformSpi implementations when
compiled against 1.4 will not compile until the new method is
implemented. This is not a problem for the built-in implementations with
XMLSec (since they have been adjusted) but it is a problem for any
TransformSpi implementations developed by users out there. In any case,
this particular compilation failure is not such a big deal since you
will want to implement the better method anyway.

The more serious problem (IMO) is that you will get a runtime error
(NoSuchMethodError) if the current TransformSpi implementations are run
with 1.4 without updating and recompiling to support the new method
(because the new methods don't exist). So this means you cannot
seamlessly upgrade existing TransformSpi implementations to 1.4 without
reimplementing the new methods.

A similar type of API change was made to the KeyResolverSpi class.

Do you think this level of API compatibility is important to preserve
from one release to another? I think it is in most cases. I believe
there are several transform implementations out there (at least one or
two in WSS4J) so it would be useful to hear from those folks and anyone
else who has implemented their own transform (or keyresolver)
implementations. If so, I would recommend the following:

- we try to avoid removing any public/protected (abstract or not)
methods unless there is a really good reason (security hole or something
like that)
- we avoid adding new public/protected abstract methods. Instead add a
concrete method that either throws UnsupportedOperationException or has
a reasonable default implementation. In either case the subclass can
override it with a more efficient/appropriate implementation.

Comments? Does anyone know what other Apache projects do?

Thanks,
Sean

Re: Please let us know what you think about these potential incompatible API changes

[Sean Mullan <Se...@Sun.COM>]

Ok, for now I'll open a bug to restore the old methods. Raul, do you see 
any problems with that?

--Sean

Davanum Srinivas wrote:
> Folks,
> 
> Yes, i think it affects WSS4J. Ruchith may confirm that. But, yes,
> it's a good idea to make backward compatible changes. We do need to
> highlight the API changes in release notes either way whether we
> change signatures or we throw UnsupportedOperationException.
> 
> thanks,
> dims
> 
> On 9/11/06, Sean Mullan <Se...@sun.com> wrote:
>> Hi,
>>
>> Raul and I have discussed this a bit offline, but we decided to take the
>> discussion to the list to hear from others about the effect of some
>> potentially incompatible changes that were made to the TransformSpi 
>> class.
>>
>> In 1.4, a new abstract protected
>> enginePerformTransform(XMLSignatureInput, Transform) method was added to
>> the TransformSpi class and the existing
>> enginePerformTransform(XMLSignatureInput) method was
>> removed. The new method was designed to replace the old method and was
>> done to improve performance, which is all very good.
>>
>> Unfortunately, it means that existing TransformSpi implementations when
>> compiled against 1.4 will not compile until the new method is
>> implemented. This is not a problem for the built-in implementations with
>> XMLSec (since they have been adjusted) but it is a problem for any
>> TransformSpi implementations developed by users out there. In any case,
>> this particular compilation failure is not such a big deal since you
>> will want to implement the better method anyway.
>>
>> The more serious problem (IMO) is that you will get a runtime error
>> (NoSuchMethodError) if the current TransformSpi implementations are run
>> with 1.4 without updating and recompiling to support the new method
>> (because the new methods don't exist). So this means you cannot
>> seamlessly upgrade existing TransformSpi implementations to 1.4 without
>> reimplementing the new methods.
>>
>> A similar type of API change was made to the KeyResolverSpi class.
>>
>> Do you think this level of API compatibility is important to preserve
>> from one release to another? I think it is in most cases. I believe
>> there are several transform implementations out there (at least one or
>> two in WSS4J) so it would be useful to hear from those folks and anyone
>> else who has implemented their own transform (or keyresolver)
>> implementations. If so, I would recommend the following:
>>
>> - we try to avoid removing any public/protected (abstract or not)
>> methods unless there is a really good reason (security hole or something
>> like that)
>> - we avoid adding new public/protected abstract methods. Instead add a
>> concrete method that either throws UnsupportedOperationException or has
>> a reasonable default implementation. In either case the subclass can
>> override it with a more efficient/appropriate implementation.
>>
>> Comments? Does anyone know what other Apache projects do?
>>
>> Thanks,
>> Sean
>>
>>
> 
> 

Re: Please let us know what you think about these potential incompatible API changes

[Davanum Srinivas <da...@gmail.com>]

Folks,

Yes, i think it affects WSS4J. Ruchith may confirm that. But, yes,
it's a good idea to make backward compatible changes. We do need to
highlight the API changes in release notes either way whether we
change signatures or we throw UnsupportedOperationException.

thanks,
dims

On 9/11/06, Sean Mullan <Se...@sun.com> wrote:
> Hi,
>
> Raul and I have discussed this a bit offline, but we decided to take the
> discussion to the list to hear from others about the effect of some
> potentially incompatible changes that were made to the TransformSpi class.
>
> In 1.4, a new abstract protected
> enginePerformTransform(XMLSignatureInput, Transform) method was added to
> the TransformSpi class and the existing
> enginePerformTransform(XMLSignatureInput) method was
> removed. The new method was designed to replace the old method and was
> done to improve performance, which is all very good.
>
> Unfortunately, it means that existing TransformSpi implementations when
> compiled against 1.4 will not compile until the new method is
> implemented. This is not a problem for the built-in implementations with
> XMLSec (since they have been adjusted) but it is a problem for any
> TransformSpi implementations developed by users out there. In any case,
> this particular compilation failure is not such a big deal since you
> will want to implement the better method anyway.
>
> The more serious problem (IMO) is that you will get a runtime error
> (NoSuchMethodError) if the current TransformSpi implementations are run
> with 1.4 without updating and recompiling to support the new method
> (because the new methods don't exist). So this means you cannot
> seamlessly upgrade existing TransformSpi implementations to 1.4 without
> reimplementing the new methods.
>
> A similar type of API change was made to the KeyResolverSpi class.
>
> Do you think this level of API compatibility is important to preserve
> from one release to another? I think it is in most cases. I believe
> there are several transform implementations out there (at least one or
> two in WSS4J) so it would be useful to hear from those folks and anyone
> else who has implemented their own transform (or keyresolver)
> implementations. If so, I would recommend the following:
>
> - we try to avoid removing any public/protected (abstract or not)
> methods unless there is a really good reason (security hole or something
> like that)
> - we avoid adding new public/protected abstract methods. Instead add a
> concrete method that either throws UnsupportedOperationException or has
> a reasonable default implementation. In either case the subclass can
> override it with a more efficient/appropriate implementation.
>
> Comments? Does anyone know what other Apache projects do?
>
> Thanks,
> Sean
>
>


-- 
Davanum Srinivas : http://www.wso2.net (Oxygen for Web Service Developers)