'public' API stability when embedded in JBossAS

[jhalliday]

The long term support commitments for JBossTS CP maintenance involve not making public API changes, the intention being that users can be confident that moving between CP releases won't cause linker type errors. Unfortunately this is at odds with the need to fix bugs, which can sometimes require API changes. As we prepare to fork another long term maintenance branch I think we should spend some time considering this dilemma.

What is the API we wish to support? We have got ahead of the game with XTS, explicitly packaging (i.e. different .jar) the API distinct from the implementation. For the rest of JBossTS it's all bundled up together, so we have to consider any 'public' class to be part of our published API. For a long time the codebase has used .internal. packages to denote implementation, but users are not necessarily aware of this distinction.

A lot of code which end users need to access directly when running standalone, is abstracted by the app server when running embedded. Arguably the only public API for JBossTS when embedded in JBossAS, is the TransactionManagerService mbean, CORBA interceptors, ObjectStore and possibly a recovery class or two. The rest is all abstracted via javax.transaction. But this is at odds with the 'if we ship it we support it' model, since the binaries still include e.g. TxOJ and TransactionalDriver, neither of which JBossAS uses.

My personal preference would be to publish the list of interfaces/classes we consider stable and make clear that everything else is subject to change in CPs, regardless of .internal. or 'public' modifiers.

[marklittle]

Anything that is within the internal package should not be covered by deprecation. It's in the docs and the support guys are aware of it. Anything public can change through normal deprecation rules.

This works for other projects, so I'm not sure why we need to make special rules. XTS is different in that there is no standard API for it to conform to, but I assume it's still using the internal/mwlabs approach so the above still applies.

The trouble with listing interfaces/classes is that it's fairly arbitrary. Do we take only what we use in the AS? What about when running stand-alone? What about JTS or any of the extensions we have to the various standards?

So I'd prefer that we stick with the .internal. and use the deprecation rules (which don't prevent changes that are incompatible with previous releases, but in a controlled manner.)

[adinn]

This works for other projects, so I'm not sure why we need to make special rules. XTS is different in that there is no standard API for it to conform to, but I assume it's still using the internal/mwlabs approach so the above still applies.

Err, well, not exactly -- we currently "expose" just the tip of the iceberg. i.e. we have split the deployed code into an "api" jar plus a set of "interna"l jars culled from the sar, WSAS, WSCF, WS-C, WS-T and WSTX components (ok, it's a little more messy but . . .). This split is only conventional -- all the jars are present in the deployed service archive but only one of them has 'api' in the name. The intention is that we install a copy of this jar in the AS client directory for users to compile against.

The API jar only contains the (very) small number of classes required for AT and BA client code to compile correctly,-- not just the UserTX//BA and TX/BAManager classes but also ancillary classes like Vote, SystemException etc. This also happens to be the exact same set of classes which comprise the API documented in the User Guide. There is no reason why a straight AT/BA client should ever need to look under the hood at what is contained in the internal jars.

Of course this does not mean that someone cannot actually look under the hood. But there is very little incentive to do this with XTS. It does not provide any extensibility mechanisms for the benefit of XTS clients on a par with, for example, the LockManager or StateManager classes implemented by ArjunaCore. I agree we should proceed by deprecating public classes/methods in these internal jars but I'd be surprised if anyone who was not implementing an extension to the XTS package ever needed to build on this code (e.g.perhaps the SOA platform guys might need to open them up).

[marklittle]

"adinn" wrote:

This works for other projects, so I'm not sure why we need to make special rules. XTS is different in that there is no standard API for it to conform to, but I assume it's still using the internal/mwlabs approach so the above still applies.

Err, well, not exactly -- we currently "expose" just the tip of the iceberg. i.e. we have split the deployed code into an "api" jar plus a set of "interna"l jars culled from the sar, WSAS, WSCF, WS-C, WS-T and WSTX components (ok, it's a little more messy but . . .). This split is only conventional -- all the jars are present in the deployed service archive but only one of them has 'api' in the name. The intention is that we install a copy of this jar in the AS client directory for users to compile against.

OK. A little strange, since I'm pretty sure we didn't have an api package in the past or have an equivalent elsewhere. But hey ho ;-)

The API jar only contains the (very) small number of classes required for AT and BA client code to compile correctly,-- not just the UserTX//BA and TX/BAManager classes but also ancillary classes like Vote, SystemException etc.

Wouldn't it be so much better if there was a JSR 156 jar to target ;-) ?

This also happens to be the exact same set of classes which comprise the API documented in the User Guide. There is no reason why a straight AT/BA client should ever need to look under the hood at what is contained in the internal jars.

Sure, I get that.

Of course this does not mean that someone cannot actually look under the hood. But there is very little incentive to do this with XTS.

There should be very little reason to do so with any project using internal structuring. In fact we typically don't even generate javadocs for those classes/interfaces which further discourages such deviant behaviour.

It does not provide any extensibility mechanisms for the benefit of XTS clients on a par with, for example, the LockManager or StateManager classes implemented by ArjunaCore. I agree we should proceed by deprecating public classes/methods in these internal jars

No, you misunderstand. Anything in the internal package structure (or mwlabs from legacy) can change without being deprecated. Of course you COULD deprecate it, but it's not necessary and the docs make that clear. Only public things (in api for the case of XTS) MUST be covered by the deprecation rules.

but I'd be surprised if anyone who was not implementing an extension to the XTS package ever needed to build on this code (e.g.perhaps the SOA platform guys might need to open them up).

Maybe, but in that case we could open them up either through moving them to public (the public interfaces can grow and shrink) or add new public wrappers to expose them.

[marklittle]

BTW in terms of XTS, mwlabs == internal

[jhalliday]

OK, this seems to be missing the point at bit. I'm not concerned with the deprecation rules that exist between project point releases. I'm concerned with CP maintenance i.e. the product branch. The rules there are different. No deprecation. And no additions either if they may break clients e.g. adding a new method to an interface. Even changing the behaviour of an existing public method is dodgy. That's why I want to minimise what we support as our API on the CP line.

[marklittle]

Where does it say 'no deprecation' in the CP rules? Certainly no breaking backward compatibility if it can be avoided, but there are times when changes need to be made to fix bugs and they do break backwards compatibility. But then backwards compatibility with a bug is something we don't want.