[jboss-dev-forums] [Design of JBoss Transaction Services] - Re: 'public' API stability when embedded in JBossAS

[mark.little@jboss.com]

"adinn" wrote : anonymous 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 ;-)

anonymous wrote : 
  | 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 ;-) ?

anonymous wrote : 
  | 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.

anonymous wrote : 
  | 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.

anonymous wrote : 
  | 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.

anonymous wrote : 
  | 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.

View the original post : http://www.jboss.org/index.html?module=bb&op=viewtopic&p=4209090#4209090

Reply to the post : http://www.jboss.org/index.html?module=bb&op=posting&mode=reply&p=4209090