Provided by: clirr_0.6-7_all bug

NAME

       clirr - Check source and binary compatibility of Java libraries

SYNOPSIS

       clirr -o oldjar -n newjar [options]

DESCRIPTION

       Clirr  is a tool that checks Java libraries for binary and source compatibility with older
       releases. Basically you give it two sets of jar files  and  Clirr  dumps  out  a  list  of
       changes in the public API.

OPTIONS

       -a, --show-all-scopes

              show private and package classes

       -f, --output-file <arg>

              output file name

       -i, --include-pkg <arg>

              include only classes from this package and its subpackages

       -n, --new-version <arg>

              jar files of new version

       -ncp, --new-classpath <arg>

              3rd party classpath that is referenced by new-version

       -o, --old-version <arg>

              jar files of old version

       -ocp, --orig-classpath <arg>

              3rd party classpath that is referenced by old-version

       -p, --show-pkg-scope

              show package scope classes

       -s, --style [text|xml]

              output style

MESSAGES

       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  manual  contains  an
       explanation  of  the meaning of that message which may contain information which could not
       be fitted into the brief message summary.

       Messages are separated into three severity levels: ERROR, WARNING and INFO.

       Errors come in two flavours:

              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.

              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.

       Clirr reports "errors" for cases where it is possible to get a run-time  failure.  Whether
       one  actually  occurs can depend upon the way the library is called, i.e. 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.

       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.

       Information messages provide users with information about new  features  which  have  been
       added without breaking backward compatibility in any way.

       When  using clirr to report on changes to items which have private or package scope, these
       changes are always reported as INFO level changes, never  WARNING  or  ERROR  level.  This
       allows  users  of  clirr  to  generate "change reports" at a level suitable for developers
       without having some of those changes marked (irrelevantly) as binary incompatibilities.

       There can never be binary incompatibilities for changes to  private  classes,  methods  or
       fields as that access can only occur from within the same class (i.e. the same compilation
       unit).

       Clirr does not report binary incompatibility WARNINGs or ERRORs for  package-scoped  items
       either,  because Java packages are intended to be "release units", i.e. all classes within
       a package are compiled together (ensuring compatibility) then released as a unit. The only
       time  that  package-scope  incompatibilities could possibly be an issue is when users of a
       library write their own classes using a package declaration  belonging  to  some  external
       library,  or when a subset of updated classes (e.g. a single class) from a package is used
       to override certain classes from  a  previous  release  of  the  library.  Both  of  these
       situations are considered very poor practice by Java programming convention.

       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.

       In  the  following  sections,  the  term "type" is used to refer to something which may be
       either a class or interface.

       1000 - Increased visibility of class

              Severity: INFO

              The specified type exists in both versions, but its declared access  specifier  has
              changed to relax restrictions on what other code can access it.

              Top-level  types (ie those which are not nested within another class) may only have
              "package" or "public" accessibility. Nested types can  take  on  any  of  the  four
              available accessibility values.

              Regardless  of whether the object is top-level or nested, a change in accessibility
              from  left-to-right  of  the  sequence  private->package->protected->public  always
              ensures that all code which could previously access that type can still access that
              type. Therefore such a change is always binary and source-code compatible.

              Note that the declaration "protected" provides access to both code derived from the
              type and to code within the same package, ie "protected" accessibility also implies
              package accessibility.

       1001 - Decreased visibility of class

              Severity: ERROR

              The specified type exists in both versions, but its declared access  specifier  has
              changed to tighten the restrictions on what other code may access it.

              Top-level  types (ie those which are not nested within another class) may only have
              "package" or "public" accessibility. Nested types can  take  on  any  of  the  four
              available accessibility values.

              Regardless  of  whether  the type is top-level or nested, a change in accessibility
              from left-to-right of the sequence  public->protected->package->private  may  cause
              existing code which could previously access the type to no longer be able to do so.

              Section  13.4.3  of  the  Java  Language  Specification  states  explicitly that an
              IllegalAccessError should occur if a pre-existing binary tries  to  access  a  type
              when  the  type  accessibility  has  been  changed  to something that would cause a
              compile-time error. However this does not appear to be  enforced  in  practice,  at
              least  in  current JVMs. Nevertheless this should be an error, and so clirr reports
              this change as a binary-compatibility ERROR.

       2000 - Changed from class to interface

              Severity: ERROR

              The specified class has become an interface in the  new  version.  This  change  is
              always a binary and source-code incompatibility, for obvious reasons.

       2001 - Changed from interface to class

              Severity: ERROR

              The  specified  interface  has  become  an class in the new version. This change is
              always a binary and source-code incompatibility, for obvious reasons.

       3001 - Removed final modifier from class

              Severity: INFO

              The specified class was declared final in the old version, but is no  longer  final
              in the new version.

       3002 - Added final modifier to effectively final class

              Severity: INFO

              The  specified class was not declared final in the old version, but is now declared
              final. Normally, this would be  an  incompatibility  because  pre-existing  derived
              classes  would  no  longer  be  valid when used with the new version of this class.
              However in this case the old class version had no public or protected constructors,
              so it was not possible for any derived classes to exist even for the old version of
              the library. Changing such a class to final therefore can not  break  any  existing
              code.

       3003 - Added final modifier to class

              Severity: ERROR

              The  specified class was not declared final in the old version, but is now declared
              final. Any pre-existing classes which were declared as  subclasses  of  this  class
              will therefore not be valid with the new version of the library.

              A  VerifyError  is  thrown  by  the  classloader  when an attempt is made to load a
              subclass of a final class.

              Note that a class Y is loaded by the  standard  classloader  only  when  the  first
              attempt  is  made  to  create  an instance of Y, or to directly reference the Class
              object for class Y. If some other class X has class Y as a declared member, or as a
              parameter to some method, then loading class X does not cause class Y to be loaded.

       3004 - Removed abstract modifier from class

              Severity: INFO

              The old version of this class was declared to be an abstract class. The new version
              is not abstract, allowing users to create instances of the class.

       3005 - Added abstract modifier to class

              Severity: ERROR

              The old version of this class was not declared to be abstract. The new  version  is
              abstract.  Pre-existing  code  which  creates  instances of this class is no longer
              valid with the new version.

       4000 - Added interface to the set of implemented interfaces

              Severity: INFO

              The new version of the type now implements an additional interface. This  does  not
              invalidate   any   existing   code   (source   or  binary),  and  is  a  completely
              backward-compatible change.

              Note that this message  can  be  reported  without  any  change  occurring  in  the
              specified  type;  a  change to the set of interfaces supported by a type will cause
              this message to be reported for every descendant of that type.

       4001 - Removed interface from the set of implemented interfaces

              Severity: ERROR

              The old version of this type declared that it implemented an  interface  which  the
              new class or interface does not. Existing code which explicitly or implicitly casts
              objects of this type to the now missing interface is no longer valid.

              Note that this message  can  be  reported  without  any  change  occurring  in  the
              specified  type;  a  change to the set of interfaces supported by a type will cause
              this message to be reported for every descendant of that type.

       5000 - Added class to the set of superclasses

              Severity: INFO or WARNING

              The new version of the class has a class in its inheritance hierarchy which the old
              version  did  not,  either  because  its direct parent is now a different class, or
              because one of its parent classes has changed its inheritance hierarchy.

              If the specified class has java.lang.Throwable as an ancestor, then this change  is
              reported  as a WARNING, because this class change may change the exception-catching
              behaviour of programs that use this class.

              Note that this message  can  be  reported  without  any  change  occurring  in  the
              specified  class;  a  change  to  the set of superclasses of an ancestor class will
              cause this message to be reported for every descendant class.

       5001 - Removed class from the set of superclasses

              Severity: ERROR

              The old version of this class has a class in its inheritance  hierarchy  which  the
              new version does not, either because its direct parent is now a different class, or
              because one of its parent classes has changed its inheritance hierarchy.

              Existing code which explicitly or implicitly casts objects of this type to the  now
              missing class type is no longer valid.

              Note  that  this  message  can  be  reported  without  any  change occurring in the
              specified class; a change to the set of superclasses  of  an  ancestor  class  will
              cause this message to be reported for every descendent class.

              Note  also  that  if  this  class  has  Throwable  in  its ancestry, then the class
              hierarchy change can also cause changes  in  the  exception-catching  behaviour  of
              programs using this class.

       6000 - Added field

              Severity: INFO

              The  new  class  has  an  additional  static  or  instance  member.  This change is
              completely backwards-compatible.

       6001 - Removed field

              Severity: ERROR

              The new class has removed a field present in the  old  version.  Pre-existing  code
              which directly accesses that field will no longer be valid.

       6002 - Value of field no longer a compile-time constant

              Severity: WARNING

              Code  compiled  against  the old version of the class was permitted to "inline" the
              value of this field because it was a  compile-time  constant.  Therefore,  existing
              binary  code  will  continue to use the old value of this field, instead of the new
              value (which cannot be inlined).

       6003 - Value of compile-time constant has changed

              Severity: WARNING

              Code compiled against the old version of the class was permitted  to  "inline"  the
              value  of  this  field  because it was a compile-time constant. Therefore, existing
              binary code will continue to use the old value of this field, instead  of  the  new
              value.

       6004 - Field type changed

              Severity: ERROR

              The  type  associated with the specified static or instance member of the specified
              class has changed. Pre-existing code which directly  accesses  that  field  may  no
              longer be valid, and therefore this is an incompatible change.

       6005 - Field now non-final

              Severity: INFO

              The  field  was previously final, and is no longer final. This means that the field
              value can now be modified during the lifetime of the class or instance.

              Whether a value in a field could previously be "inlined" into other classes  is  an
              issue addressed by messages 6002 and 6003, not this message.

       6006 - Field now final

              Severity: ERROR

              The  field  can no longer be modified during the lifetime of the class or instance.
              Code which previously modified this field is therefore no longer valid.

       6007 - Field now non-static

              Severity: ERROR

              The field is now an instance variable rather than  a  class  variable.  Code  which
              previously  accessed  this field via the Class rather than an instance of the class
              is no longer valid.

       6008 - Field now static

              Severity: ERROR

              The field is now a class variable rather than an instance variable.

              For some reason (presumably internal  implementation  issues),  the  Java  standard
              declares    that    this   change   is   not   binary-compatible,   and   that   an
              IncompatibleClassChangeError will be thrown if  code  compiled  against  the  "old"
              version  of  a class is used together with a "new" version for which a field is now
              static.

              Because source code is permitted to access class variables via  instances  of  that
              class,  this  is  expected to be a source-code compatible change. However currently
              CLIRR reports this as an ERROR for source-code compatibility too.

       6009 - Field More Accessible

              Severity: INFO

              In the new version, the specified field is accessible to  more  code  than  it  was
              previously.

       6010 - Field Less Accessible

              Severity: ERROR

              In  the  new  version,  the  specified field is accessible to less code than it was
              previously. Therefore existing code may no longer be valid.

       6011 - Removed Constant Field

              Binary Severity: WARNING

              Source Severity: ERROR

              The new class has removed a field present in the old version.  Pre-existing  source
              code which directly accesses that field will no longer be valid.

              Previously, however, the field was final and was initialised with a constant value.
              Therefore code compiled against the previous version of the class will have inlined
              this  constant and will continue to work, using the previous value of this field. A
              warning is issued as this is often not desirable behaviour. However  it  is  not  a
              binary incompatibility.

       7000 - Method now in Superclass

              Severity: INFO

              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.

              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.

       7001 - Method now in Interface

              Severity: INFO

              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.

              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.

       7002 - Method Removed

              Severity: ERROR

              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.

              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.

       7003 - Method Overide Removed

              Severity: INFO

              The  specified  method  on  the  old class or interface was overriding an inherited
              definition. The new class  or  interface  no  longer  has  this  method  explicitly
              declared  on  it,  but  it  still  inherits  a  definition  so  there  is no binary
              incompatibility.  7004 - Method Argument Count Changed

              Severity: ERROR

              The specified method has had arguments added or removed. This means that code which
              previously invoked it will no longer invoke the same method.

              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. 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.

              If  there is no inherited method definition with the old prototype, then the change
              is a binary incompatibility.

       7005 - Method Argument Type changed

              Binary Severity: INFO or ERROR

              Source Severity: ERROR

              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  may invoke this method if the argument types are
              assignment-compatible.

              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. At the current date, clirr does
              not check for this situation.

              If  there is no inherited method definition with the old prototype, then the change
              is a binary incompatibility.

              If the parameter types changed were all changed to  supertypes  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 source-code-compatible 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. At the current date, clirr does not check for this situation.

       7006 - Method Return Type changed

              Binary Severity: ERROR

              Source Severity: INFO or ERROR

              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".

              The  change  is  source-code-compatible  if  and  only  if  the  new return type is
              assignable to the old return type. This means that:

                  if the old return type was a primitive type, then the new return type  must  be
              narrower than the old type.
                  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.
                  if the old return type was a class, then the new return type must be a subclass
              of the previously returned type.

              Clirr  does not currently check for source-code compatibility for changes in method
              return types; currently these are simply reported as an ERROR.

       7007 - Method has been Deprecated

              Severity: INFO

              The  specified  method  has  been  declared  as  "deprecated".  This  is  always  a
              binary-compatible change as well as a source-code-compatible change.

       7008 - Method has been Undeprecated

              Severity: INFO

              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.

       7009 - Method is now Less Accessible

              Severity: ERROR

              The access permissions associated with the specified method have been tightened  to
              permit less user code to access the method.

              Whether  this  change  is  a  source-code  compatibility  issue or not depends upon
              patterns of usage.

              This change should be a binary incompatibility. Note, however, that current JVMs do
              not  validate  this.  Code  compiled  against  a  previous  version  of a class can
              successfully  invoke  methods  for  which  they  no  longer  have  access   rights.
              Nevertheless,  the  Java  Language  Specification  states that this is an error, so
              clirr reports this change as a binary incompatibility.

       7010 - Method is now More Accessible

              Severity: INFO

              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.

       7011 - Method Added

              Severity: INFO

              A non-abstract method has been added to the  specified  class.  This  is  always  a
              binary-compatible change.

              It is also a source-code compatible change.

              Q:  if  the  new  method  overrides  an inherited one, then which version does code
              compiled against the old library invoke?

       7012 - Method Added to Interface

              Binary Severity: ERROR

              Source Severity: ERROR

              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 might
              be used successfully with code compiled against the old  interface  depending  upon
              usage patterns.

              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.

              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.

       7013 - Abstract Method Added to Class

              Binary Severity: ERROR

              Source Severity: ERROR

              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
              might  be used successfully with code compiled against the old class depending upon
              usage patterns.

              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.

       7014 - Method now final

              Severity: ERROR

              The  method  was  previously  non-final, and is now final. Subclasses of this class
              will no longer compile or run.

              When the old class containig this method was final (explicitly or by only providing
              private  constructors) then subclasses cannot exist. Clirr currently does not check
              for this situation, so this will raise a false alarm in some corner cases.

       7015 - Method now non-final

              Severity: INFO

              The  method  was  previously  final,  and  is  now  non-final.  This  is  always  a
              binary-compatible change.

       8000 - Class Added

              Severity: INFO

              The  new  version  of  the  library  has  a  class which was not present in the old
              version.

       8001 - Class Removed

              Severity: ERROR

              The new version of the library no longer contains the specified class.

EXAMPLES

       Check the compatibility of a library with a previous version:

              clirr -o foo-1.0.jar -n foo-2.0.jar

       Check the backward compatibility of a new library depending on Apache Commons Logging:

              clirr -o foo-1.0.jar -n foo-2.0.jar -ocp  /usr/share/java/commons-logging.jar  -ncp
              /usr/share/java/commons-logging.jar

HOMEPAGE

       http://clirr.sourceforge.net

                                          November 2013                                  CLIRR(1)