1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
|
<?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>
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.
</p>
<p>
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 (ie the same compilation unit).
</p>
<p>
Clirr does not report binary incompatibility WARNINGs or ERRORs for
package-scoped items either, because java packages are intended to be
"release units", ie 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
(eg 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.
</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>
<p>
In the following sections, the term "type" is used to refer to
something which may be either a class or interface.
</p>
</section>
<section name="Messages">
<section name="1000 - Increased visibility of class">
<p>Severity: <code>INFO</code></p>
<p>
The specified type exists in both versions, but its declared access
specifier has changed to relax restrictions on what other code can
access it.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
Note that the declaration "protected" provides access to <i>both</i>
code derived from the type <i>and</i> to code within the same package,
ie "protected" accessibility also implies package accessibility.
</p>
</section>
<section name="1001 - Decreased visibility of class">
<p>Severity: <code>ERROR</code></p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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 <i>should</i> be an error, and so clirr reports
this change as a binary-compatibility ERROR.
</p>
</section>
<section name="2000 - Changed from class to interface">
<p>Severity: <code>ERROR</code></p>
<p>
The specified class has become an interface in the new version.
This change is always a binary and source-code incompatibility, for
obvious reasons.
</p>
</section>
<section name="2001 - Changed from interface to class">
<p>Severity: <code>ERROR</code></p>
<p>
The specified interface has become an class in the new version.
This change is always a binary and source-code incompatibility, for
obvious reasons.
</p>
</section>
<section name="3001 - Removed final modifier from class">
<p>Severity: <code>INFO</code></p>
<p>
The specified class was declared final in the old version, but is
no longer final in the new version.
</p>
</section>
<section name="3002 - Added final modifier to effectively final class">
<p>Severity: <code>INFO</code></p>
<p>
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.
</p>
</section>
<section name="3003 - Added final modifier to class">
<p>Severity: <code>ERROR</code></p>
<p>
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.
</p>
<p>
A VerifyError is thrown by the classloader when an attempt is made to
load a subclass of a final class.
</p>
<p>
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 <em>not</em> cause class Y to be loaded.
</p>
</section>
<section name="3004 - Removed abstract modifier from class">
<p>Severity: <code>INFO</code></p>
<p>
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.
</p>
</section>
<section name="3005 - Added abstract modifier to class">
<p>Severity: <code>ERROR</code></p>
<p>
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.
</p>
</section>
<section name="4000 - Added interface to the set of implemented interfaces">
<p>Severity: <code>INFO</code></p>
<p>
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.
</p>
<p>
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.
</p>
</section>
<section name="4001 - Removed interface from the set of implemented interfaces">
<p>Severity: <code>ERROR</code></p>
<p>
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.
</p>
<p>
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.
</p>
</section>
<section name="5000 - Added class to the set of superclasses">
<p>Severity: <code>INFO or WARNING</code></p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
</section>
<section name="5001 - Removed class from the set of superclasses">
<p>Severity: <code>ERROR</code></p>
<p>
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.
</p>
<p>
Existing code which explicitly or implicitly casts objects of this
type to the now missing class type is no longer valid.
</p>
<p>
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.
</p>
<p>
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.
</p>
</section>
<section name="6000 - Added field">
<p>Severity: <code>INFO</code></p>
<p>
The new class has an additional static or instance member. This
change is completely backwards-compatible.
</p>
</section>
<section name="6001 - Removed field">
<p>Severity: <code>ERROR</code></p>
<p>
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.
</p>
</section>
<section name="6002 - Value of field no longer a compile-time constant">
<p>Severity: <code>WARNING</code></p>
<p>
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).
</p>
</section>
<section name="6003 - Value of compile-time constant has changed">
<p>Severity: <code>WARNING</code></p>
<p>
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.
</p>
</section>
<section name="6004 - Field type changed">
<p>Severity: <code>ERROR</code></p>
<p>
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.
</p>
</section>
<section name="6005 - Field now non-final">
<p>Severity: <code>INFO</code></p>
<p>
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.
</p>
<p>
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.
</p>
</section>
<section name="6006 - Field now final">
<p>Severity: <code>ERROR</code></p>
<p>
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.
</p>
</section>
<section name="6007 - Field now non-static">
<p>Severity: <code>ERROR</code></p>
<p>
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.
</p>
</section>
<section name="6008 - Field now static">
<p>Severity: <code>ERROR</code></p>
<p>
The field is now a class variable rather than an instance variable.
</p>
<p>
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.
</p>
<p>
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.
</p>
</section>
<section name="6009 - Field More Accessible">
<p>Severity: <code>INFO</code></p>
<p>
In the new version, the specified field is accessible to more
code than it was previously.
</p>
</section>
<section name="6010 - Field Less Accessible">
<p>Severity: <code>ERROR</code></p>
<p>
In the new version, the specified field is accessible to less
code than it was previously. Therefore existing code may no longer
be valid.
</p>
</section>
<section name="6011 - Removed Constant Field">
<p>Binary Severity: <code>WARNING</code></p>
<p>Source Severity: <code>ERROR</code></p>
<p>
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.
</p>
<p>
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.
</p>
</section>
<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 - Method Overide Removed">
<p>Severity: <code>INFO</code></p>
<p>
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.
</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 Accessible">
<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 a source-code compatibility issue or not
depends upon patterns of usage.
</p>
<p>
This change <i>should</i> 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.
</p>
</section>
<section name="7010 - Method is now More Accessible">
<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 name="7014 - Method now final">
<p>Severity: <code>ERROR</code></p>
<p>
The method was previously non-final, and is now final.
Subclasses of this class will no longer compile or
run.
</p>
<p>
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.
</p>
</section>
<section name="7015 - Method now non-final">
<p>Severity: <code>INFO</code></p>
<p>
The method was previously final, and is now non-final. This is
always a binary-compatible change.
</p>
</section>
<section name="8000 - Class Added">
<p>Severity: <code>INFO</code></p>
<p>
The new version of the library has a class which was not present
in the old version.
</p>
</section>
<section name="8001 - Class Removed">
<p>Severity: <code>ERROR</code></p>
<p>
The new version of the library no longer contains the specified
class.
</p>
</section>
</section>
</body>
</document>
|
