Re: [transaction] svn commit: r494203 - in /jakarta/commons/proper/transaction/trunk: RELEASE-NOTES.txt src/java/org/apache/commons/transaction/file/ResourceManager.java
Folks! Thanks for caring that much and sorry for me being quiet until now as I am the guilty person. The design we are talking about actually is quite weird as it is a stub of a former implementation. There is this interface and there is *exactly* one implementation for that interface and IMHO there will be no - reasonable - further implementation at any time. Thus it is alright to extend the interface. Even if you do not agree we should at least add the additional methods to the implementation, leaving the interface untouched, breaking nothing! OK? Cheers and have a nice weekend Oliver 2007/1/11, Simon Kitching [EMAIL PROTECTED]: On Wed, 2007-01-10 at 14:12 -0500, Rahul Akolkar wrote: On 1/10/07, Joerg Heinicke [EMAIL PROTECTED] wrote: Rahul Akolkar rahul.akolkar at gmail.com writes: Generally speaking, an interface-compatible change will at most change the private interface of a component, or simply add classes, methods and attributes whose use is optional to both internal and external interface clients. And this is not. In which way is it different from simply add [..] methods [..] whose use is optional to both internal and external interface clients. ?? Even simply replacing the former jar with the next version should work as the client does not know about the new methods. Only recompilation of implementations need adaptions before but that's not what I consider a use or a client. snip/ I suspect that bit is talking about Java classes (rather than interfaces), though I haven't tried to hunt it down in the guide. I flagged what I thought would lead to a versioning discussion at 1.2 voting time. There is a section in the java specification that defines precisely what binary compatibility involves, and adding a method to an interface definitely breaks it. This is an *object oriented* library we are talking about here, so use includes implementing any public interfaces, subclassing any non-final classes and overriding any public or protected methods. Unless explicitly documented, we cannot assume that users of an open-source library restrict themselves to just calling the existing classes. If the interfaces had been explicitly documented as being not intended for user implementation then this might be ok. Or if they had been placed in a special package, as Eclipse does, to explicitly separate internal from external apis. However if neither of these have been done, then I would personally expect these APIs to be binary-compatible, *at least* without a major version number update. In the branch for digester 2.x, I explicitly indicated the binary stability expectations for the Action interface: http://svn.apache.org/repos/asf/jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/Action.java Note that this is still experimental work, and I haven't received feedback from the commons community on whether this sort of comment would be considered adequate to allow an interface change in a minor release, but IMO without an indication of this sort an API really shouldn't change (without a major release at least). Ideally, existing public interfaces should not be changed *at all*, eg by introducing a new interface rather than changing the existing one. In cases where an application uses two different libraries that both depend on a commons lib, the existence of different versions of the commons lib with the same package names but different APIs can cause major headaches. As Rahul says this situation may well draw -1 votes at release time. We all want commons projects to have a good reputation for API stability. There have been mistakes made in the past, causing a lot of negative user feedback. Yes, it can be a hassle for development. However the reason that commons is a good place to host libraries is because commons is trusted, and that's because the software development processes here are reasonably strict. Writing libraries is hard - and quite different from writing full applications (eg tomcat, ant) or frameworks. Regards, Simon - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: [transaction] svn commit: r494203 - in /jakarta/commons/proper/transaction/trunk: RELEASE-NOTES.txt src/java/org/apache/commons/transaction/file/ResourceManager.java
On Wed, 2007-01-10 at 14:12 -0500, Rahul Akolkar wrote: On 1/10/07, Joerg Heinicke [EMAIL PROTECTED] wrote: Rahul Akolkar rahul.akolkar at gmail.com writes: Generally speaking, an interface-compatible change will at most change the private interface of a component, or simply add classes, methods and attributes whose use is optional to both internal and external interface clients. And this is not. In which way is it different from simply add [..] methods [..] whose use is optional to both internal and external interface clients. ?? Even simply replacing the former jar with the next version should work as the client does not know about the new methods. Only recompilation of implementations need adaptions before but that's not what I consider a use or a client. snip/ I suspect that bit is talking about Java classes (rather than interfaces), though I haven't tried to hunt it down in the guide. I flagged what I thought would lead to a versioning discussion at 1.2 voting time. There is a section in the java specification that defines precisely what binary compatibility involves, and adding a method to an interface definitely breaks it. This is an *object oriented* library we are talking about here, so use includes implementing any public interfaces, subclassing any non-final classes and overriding any public or protected methods. Unless explicitly documented, we cannot assume that users of an open-source library restrict themselves to just calling the existing classes. If the interfaces had been explicitly documented as being not intended for user implementation then this might be ok. Or if they had been placed in a special package, as Eclipse does, to explicitly separate internal from external apis. However if neither of these have been done, then I would personally expect these APIs to be binary-compatible, *at least* without a major version number update. In the branch for digester 2.x, I explicitly indicated the binary stability expectations for the Action interface: http://svn.apache.org/repos/asf/jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/Action.java Note that this is still experimental work, and I haven't received feedback from the commons community on whether this sort of comment would be considered adequate to allow an interface change in a minor release, but IMO without an indication of this sort an API really shouldn't change (without a major release at least). Ideally, existing public interfaces should not be changed *at all*, eg by introducing a new interface rather than changing the existing one. In cases where an application uses two different libraries that both depend on a commons lib, the existence of different versions of the commons lib with the same package names but different APIs can cause major headaches. As Rahul says this situation may well draw -1 votes at release time. We all want commons projects to have a good reputation for API stability. There have been mistakes made in the past, causing a lot of negative user feedback. Yes, it can be a hassle for development. However the reason that commons is a good place to host libraries is because commons is trusted, and that's because the software development processes here are reasonably strict. Writing libraries is hard - and quite different from writing full applications (eg tomcat, ant) or frameworks. Regards, Simon - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: [transaction] svn commit: r494203 - in /jakarta/commons/proper/transaction/trunk: RELEASE-NOTES.txt src/java/org/apache/commons/transaction/file/ResourceManager.java
Rahul Akolkar rahul.akolkar at gmail.com writes: Generally speaking, an interface-compatible change will at most change the private interface of a component, or simply add classes, methods and attributes whose use is optional to both internal and external interface clients. And this is not. In which way is it different from simply add [..] methods [..] whose use is optional to both internal and external interface clients. ?? Even simply replacing the former jar with the next version should work as the client does not know about the new methods. Only recompilation of implementations need adaptions before but that's not what I consider a use or a client. Jörg - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: [transaction] svn commit: r494203 - in /jakarta/commons/proper/transaction/trunk: RELEASE-NOTES.txt src/java/org/apache/commons/transaction/file/ResourceManager.java
On 1/10/07, Joerg Heinicke [EMAIL PROTECTED] wrote: Rahul Akolkar rahul.akolkar at gmail.com writes: Generally speaking, an interface-compatible change will at most change the private interface of a component, or simply add classes, methods and attributes whose use is optional to both internal and external interface clients. And this is not. In which way is it different from simply add [..] methods [..] whose use is optional to both internal and external interface clients. ?? Even simply replacing the former jar with the next version should work as the client does not know about the new methods. Only recompilation of implementations need adaptions before but that's not what I consider a use or a client. snip/ I suspect that bit is talking about Java classes (rather than interfaces), though I haven't tried to hunt it down in the guide. I flagged what I thought would lead to a versioning discussion at 1.2 voting time. Lets please move on, the Commons versioning criteria are quite objective, and I have nothing to add. -Rahul Jörg - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: [transaction] svn commit: r494203 - in /jakarta/commons/proper/transaction/trunk: RELEASE-NOTES.txt src/java/org/apache/commons/transaction/file/ResourceManager.java
On 1/8/07, [EMAIL PROTECTED] [EMAIL PROTECTED] wrote: Author: joerg Date: Mon Jan 8 13:41:21 2007 New Revision: 494203 URL: http://svn.apache.org/viewvc?view=revrev=494203 snip/ This change warrants a major release for [transaction]. -Rahul Log: TRANSACTION-11: Added setDefaultTransactionTimeout() and reset() to ResourceManager. Modified: jakarta/commons/proper/transaction/trunk/RELEASE-NOTES.txt jakarta/commons/proper/transaction/trunk/src/java/org/apache/commons/transaction/file/ResourceManager.java Modified: jakarta/commons/proper/transaction/trunk/RELEASE-NOTES.txt URL: http://svn.apache.org/viewvc/jakarta/commons/proper/transaction/trunk/RELEASE-NOTES.txt?view=diffrev=494203r1=494202r2=494203 == --- jakarta/commons/proper/transaction/trunk/RELEASE-NOTES.txt (original) +++ jakarta/commons/proper/transaction/trunk/RELEASE-NOTES.txt Mon Jan 8 13:41:21 2007 @@ -29,6 +29,7 @@ - Added functions to FileResourceManager for copying and moving resources. - Added possibility to append to (instead of overwriting) an existing resource with writeResource in FileResourceManager. - Added LoggerFacade implementation for Jakarta Commons Logging +- Added setDefaultTransactionTimeout() and reset() to ResourceManager (Jira issue TRANSACTION-11). BUGFIXES FROM 1.1 - Modified: jakarta/commons/proper/transaction/trunk/src/java/org/apache/commons/transaction/file/ResourceManager.java URL: http://svn.apache.org/viewvc/jakarta/commons/proper/transaction/trunk/src/java/org/apache/commons/transaction/file/ResourceManager.java?view=diffrev=494203r1=494202r2=494203 == --- jakarta/commons/proper/transaction/trunk/src/java/org/apache/commons/transaction/file/ResourceManager.java (original) +++ jakarta/commons/proper/transaction/trunk/src/java/org/apache/commons/transaction/file/ResourceManager.java Mon Jan 8 13:41:21 2007 @@ -133,6 +133,13 @@ public boolean recover() throws ResourceManagerSystemException; /** + * Resets the store if applicable (optional operation). + * + * @throws UnsupportedOperationException if the codereset/code operation is not supported by this ResourceManager. + */ +public void reset(); + +/** * Gets the default isolation level as an integer. * The higher the value the higher the isolation. * @@ -193,17 +200,27 @@ public void setIsolationLevel(Object txId, int level) throws ResourceManagerException; /** - * Gets the default transaction timeout. After this time expires and the concerned transaction - * has not finished - either rolled back or committed - the resource manager is allowed and - * also encouraged - but not required - to abort the transaction and to roll it back. + * Gets the default transaction timeout in milliseconds. + * After this time expires and the concerned transaction has not finished + * - either rolled back or committed - the resource manager is allowed and + * also encouraged - but not required - to abort the transaction and to roll it back. * - * @return default transaction timeout + * @return default transaction timeout in milliseconds * @throws ResourceManagerException if an error occured */ public long getDefaultTransactionTimeout() throws ResourceManagerException; /** - * Gets the transaction timeout of the specified transaction. + * Sets the default transaction timeout in milliseconds. + * + * @param mSecs default transaction timeout in milliseconds + * @throws ResourceManagerException if an error occured + * @see #getDefaultTransactionTimeout + */ +public void setDefaultTransactionTimeout(long mSecs) throws ResourceManagerException; + +/** + * Gets the transaction timeout of the specified transaction in milliseconds. * * @param txId identifier for the concerned transaction * @return transaction timeout of the specified transaction in milliseconds @@ -213,7 +230,7 @@ public long getTransactionTimeout(Object txId) throws ResourceManagerException; /** - * Sets the transaction timeout of the specified transaction. + * Sets the transaction timeout of the specified transaction in milliseconds. * * @param txId identifier for the concerned transaction * @param mSecs transaction timeout of the specified transaction in milliseconds - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: [transaction] svn commit: r494203 - in /jakarta/commons/proper/transaction/trunk: RELEASE-NOTES.txt src/java/org/apache/commons/transaction/file/ResourceManager.java
Rahul Akolkar rahul.akolkar at gmail.com writes: URL: http://svn.apache.org/viewvc?view=revrev=494203 snip/ This change warrants a major release for [transaction]. Really? I don't mind if the current code is release as 2.0. But for such a minor change (though in the interface)? Please find my reasoning in https://issues.apache.org/jira/browse/TRANSACTION-11. Also I read the versioning guideline and can't see whether it really needs a major release (http://jakarta.apache.org/commons/releases/versioning.html): Generally speaking, an interface-compatible change will at most change the private interface of a component, or simply add classes, methods and attributes whose use is optional to both internal and external interface clients. Developers must perform a major release whenever the new release is not at least interface-compatible the previous release. IMHO the condition is fulfilled, so the rule does not fire. Jörg - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: [transaction] svn commit: r494203 - in /jakarta/commons/proper/transaction/trunk: RELEASE-NOTES.txt src/java/org/apache/commons/transaction/file/ResourceManager.java
On 1/8/07, Joerg Heinicke [EMAIL PROTECTED] wrote: Rahul Akolkar rahul.akolkar at gmail.com writes: URL: http://svn.apache.org/viewvc?view=revrev=494203 snip/ This change warrants a major release for [transaction]. Really? I don't mind if the current code is release as 2.0. But for such a minor change (though in the interface)? Please find my reasoning in https://issues.apache.org/jira/browse/TRANSACTION-11. snip/ Thanks, but I am not questioning the absolute validity of the change, just its validity for the proposed release. Also I read the versioning guideline and can't see whether it really needs a major release (http://jakarta.apache.org/commons/releases/versioning.html): Generally speaking, an interface-compatible change will at most change the private interface of a component, or simply add classes, methods and attributes whose use is optional to both internal and external interface clients. Developers must perform a major release whenever the new release is not at least interface-compatible the previous release. snap/ And this is not. You could convince yourself by running the changes through clirr, for instance. -Rahul IMHO the condition is fulfilled, so the rule does not fire. Jörg - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
