[Clirr-devel] CVS: clirr/xdocs exegesis.xml,NONE,1.1
Status: Alpha
Brought to you by:
lkuehne
Menu
▾
▴
[Clirr-devel] CVS: clirr/xdocs exegesis.xml,NONE,1.1
|
From: Simon K. <s_k...@us...> - 2004-06-29 07:33:31
|
Update of /cvsroot/clirr/clirr/xdocs In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv13007 Added Files: exegesis.xml Log Message: Verbose explanations of MethodSetCheck messages. --- NEW FILE --- <?xml version="1.0" encoding="ISO-8859-1"?> <document> <properties> <title>Difference Message Reference Manual</title> <author>The Clirr Development Team</author> </properties> <body> <section name="Introduction"> <p> When clirr generates an ERROR, WARNING or INFO message about a change in the jars being compared, there is an associated message reference code. This document contains an explanation of the meaning of that message which may contain information which could not be fitted into the brief message summary. </p> <p> Messages are separated into three severity levels: <ul> <li>ERROR</li> <li>WARNING</li> <li>INFO</li> </ul> </p> <p> Errors come in two flavours: <ul> <li> Link-time failures, where an exception will be thrown as soon as code compiled against an old version of a class and the new version of the class are loaded into the same classloader hierarchy. </li> <li> Run-time failures, where an exception is thrown when code compiled against the old version of a class attempts to call a method on a new version of the class, or vice versa. </li> </ul> <p> Clirr reports "errors" for cases where it is <i>possible</i> to get a run-time failure. Whether one actually occurs can depend upon the way the library is called, ie changes reported as an error may in fact work when used as long as the patterns of use of the library do not trigger the failure situation. </p> </p> <p> Warnings are issued for situations where no link or runtime exception will occur, but where the application may behave unexpectedly due to the changes that have occurred. </p> <p> Information messages provide users with information about new features which have been added without breaking backward compatibility in any way. </p> <p> In the following sections, the term "old" is used to refer to a class, interface, method or field from the set of jars which represent the old/previous/original/baseline version of the library being inspected. The term "new" is used to refer to a class, interface, method or field from the set of jars which represent the new/current/latest version of the library being inspected. </p> </section> <section name="Messages"> <section name="7000 - Method now in Superclass"> <p>Severity: <code>INFO</code></p> <p> The old class had a method named X. The new class no longer has this method, but a parent class does define this method, so no binary or source incompatibility has occurred. </p> <p> Note that this change may have the effect of forcing the new class to become 'abstract'. If this is the case, then this change is reported separately. </p> </section> <section name="7001 - Method now in Interface"> <p>Severity: <code>INFO</code></p> <p> The old class or interface previously had a method named X. The new class or interface no longer has this method, but a parent interface does define this method, so no binary or source incompatibility has occurred. </p> <p> Note that this change may have the effect of forcing the new class to become 'abstract'. If this is the case, then this change is reported separately. </p> </section> <section name="7002 - Method Removed"> <p>Severity: <code>ERROR</code></p> <p> The old class or interface had a method named X. The new class or interface no longer has this method, and this method is not defined on any parent class or interface. </p> <p> Whether an error actually occurs at runtime for this change depends on usage patterns. The modified class can be used with existing code as long as that existing code does not attempt to call the removed method. If a call to the missing method is made, then a NoSuchMethodError exception is generated when the method invocation occurs. </p> </section> <section name="7003 - Unused"> <p>This message code is not currently used.</p> </section> <section name="7004 - Method Argument Count Changed"> <p>Severity: <code>ERROR</code></p> <p> The specified method has had arguments added or removed. This means that code which previously invoked it will no longer invoke the same method. </p> <p> If there is an inherited method definition with the old prototype, then there is no binary incompatibility; code which was compiled against the old version of this class will now invoke the inherited implementation. <em>In this situation, clirr should output an INFO message rather than an error. However at the current date, clirr does not check for this situation</em>. </p> <p> If there is no inherited method definition with the old prototype, then the change is a binary incompatibility. </p> </section> <section name="7005 - Method Argument Type changed"> <p>Binary Severity: <code>INFO or ERROR</code></p> <p>Source Severity: <code>ERROR</code></p> <p> The specified method has had the type of one or more of its arguments modified. This means that code compiled against the old version of the class will no longer invoke the same method. However exactly the same old source code, when compiled against the new class version <i>may</i> invoke this method if the argument types are assignment-compatible. </p> <p> If there is an inherited method definition with the old prototype, then there is no binary incompatibility; code which was compiled against the old version of this class will now invoke the inherited implementation. <em>At the current date, clirr does not check for this situation</em>. </p> <p> If there is no inherited method definition with the old prototype, then the change is a binary incompatibility. </p> <p> If the parameter types changed were all changed to <i>supertypes</i> of their previous declared types, or for primitive parameter types if they were changed to "larger" types in every case, then the new code is <i>source-code-compatible</i> with the previous release even if it is not binary-compatible. Note that in this situation, recompiling code which uses the library may change its behaviour from calling an inherited method to calling a method on the class which has a slightly different prototype. <em>At the current date, clirr does not check for this situation</em>. </p> </section> <section name="7006 - Method Return Type changed"> <p>Binary Severity: <code>ERROR</code></p> <p>Source Severity: <code>INFO or ERROR</code></p> <p> The specified method has had its declared return type changed. Whether a problem actually occurs at runtime when using code compiled against the old version of this library depends upon usage patterns. Old code may call other methods on this class. However any attempt to call the method whose return type has changed will result in a NoSuchMethodError being thrown when the method is invoked, because the return type is part of the "method signature". </p> <p> The change is <i>source-code-compatible</i> if and only if the new return type is <i>assignable to</i> the old return type. This means that: <ul> <li> if the old return type was a primitive type, then the new return type must be <i>narrower</i> than the old type. </li> <li> if the old return type was an interface, then the new return type must be a class or interface which implements the old return type. </li> <li> if the old return type was a class, then the new return type must be a subclass of the previously returned type. </li> </ul> Clirr does not currently check for source-code compatibility for changes in method return types; currently these are simply reported as an ERROR. </p> </section> <section name="7007 - Method has been Deprecated"> <p>Severity: <code>INFO</code></p> <p> The specified method has been declared as "deprecated". This is always a binary-compatible change as well as a source-code-compatible change. </p> </section> <section name="7008 - Method has been Undeprecated"> <p>Severity: <code>INFO</code></p> <p> The specified method was declared "deprecated" in the previous version, but is no longer deprecated in the current release. While slightly unusual, this is permitted. This change is always a binary-compatible change as well as a source-code-compatible change. </p> </section> <section name="7009 - Method is now Less Accessable"> <p>Severity: <code>ERROR</code></p> <p> The access permissions associated with the specified method have been tightened to permit less user code to access the method. </p> <p> Whether this change is truly a binary-compatibility error depends upon patterns of usage. If the change is from public to protected, and the protected method is only invoked from code which subclasses the modified class then the new accessability for the method is still adequate and no problem will occur. Old code will also continue to work correctly as long as the modified method is not invoked. If it is invoked, then an IllegalAccessException is thrown at the time of method invocation. </p> <p> Whether this change is a source-code compatibility issue or not also depends upon patterns of usage. This change is therefore always reported as an ERROR. </p> </section> <section name="7010 - Method is now More Accessable"> <p>Severity: <code>INFO</code></p> <p> The access permissions associated with the specified method have been loosened to permit more user code to access the method. This is always a binary and source-code compatible change. </p> </section> <section name="7011 - Method Added"> <p>Severity: <code>INFO</code></p> <p> A non-abstract method has been added to the specified class. This is always a binary-compatible change. </p> <p> It is also a source-code compatible change. </p> <p> Q: if the new method overrides an inherited one, then which version does code compiled against the old library invoke? </p> </section> <section name="7012 - Method Added to Interface"> <p>Binary Severity: <code>ERROR</code></p> <p>Source Severity: <code>ERROR</code></p> <p> A method declaration has been added to the specified interface. This is always reported as a binary-compatibility error, but in practice the changed class <i>might</i> be used successfully with code compiled against the old interface depending upon usage patterns. </p> <p> Old code which invokes methods upon code compiled against the new (expanded) interface will continue to work without issues. And old code which implements the old version of the interface will also continue to work correctly as long as no code attempts to invoke any of the newly-added methods against that instance. But code which (validly) invokes one of the new methods in the interface against an object which implements only the old version of the interface will cause an AbstractMethodError to be thrown at the time the method invocation is attempted. </p> <p> Adding a method to an interface is always reported as an ERROR, because classes that implement that interface must now be modified to implement the declared method. </p> </section> <section name="7013 - Abstract Method Added to Class"> <p>Binary Severity: <code>ERROR</code></p> <p>Source Severity: <code>ERROR</code></p> <p> An abstract method declaration has been added to the specified class. This is always reported as a binary-compatibility error, but in practice the changed class <i>might</i> be used successfully with code compiled against the old class depending upon usage patterns. </p> <p> If instances of objects compiled against the old class are created, then their methods can be invoked without problems. But if the newly-added abstract method is ever invoked, then an AbstractMethodError is thrown at the time the method invocation is attempted. </p> </section> </section> </body> </document> |
