Practical API Design. Confessions of a Java Framework Architect

Practical API Design: Confessions of a Java Framework Architect......Page 1
Contents at a Glance......Page 6
Contents......Page 9
About the Author......Page 15
Acknowledgments......Page 17
Prologue: Yet Another Design Book?......Page 19
API Design Is Different......Page 20
Who Should Read This Book?......Page 23
Is This Book Useful Only for Java?......Page 24
Learning to Write APIs......Page 27
Is This Book Really a Notebook?......Page 28
Theory and Justification......Page 31
Rationalism, Empiricism, and Cluelessness......Page 35
Evolution of Software So Far......Page 37
Gigantic Building Blocks......Page 39
Beauty, Truth, and Elegance......Page 40
More Cluelessness!......Page 42
Distributed Development......Page 45
Modularizing Applications......Page 47
Nonlinear Versioning......Page 50
It’s All About Communication......Page 52
Empirical Programming......Page 53
The First Version Is Always Easy......Page 55
Method and Field Signatures......Page 57
Files and Their Content......Page 58
Environment Variables and Command-Line Options......Page 59
Text Messages As APIs......Page 61
Protocols......Page 62
Behavior......Page 64
I18N Support and L10N Messages......Page 65
How to Check the Quality of an API......Page 66
Comprehensibility......Page 67
Discoverability......Page 68
Preservation of Investment......Page 69
The First Version Is Never Perfect......Page 71
Source Compatibility......Page 72
Binary Compatibility......Page 73
Functional Compatibility—the Amoeba Effect......Page 78
The Importance of Being Use Case Oriented......Page 81
API Reviews......Page 84
Life Cycle of an API......Page 85
Incremental Improvements......Page 89
Do Not Expose More Than You Want......Page 99
A Method Is Better Than a Field......Page 100
A Factory Is Better Than a Constructor......Page 101
Make Everything Final......Page 103
Do Not Put Setters Where They Do Not Belong......Page 104
Allow Access Only from Friend Code......Page 105
Give the Creator of an Object More Rights......Page 109
Do Not Expose Deep Hierarchies......Page 113
Code Against Interfaces, Not Implementations......Page 117
Removing a Method or a Field......Page 118
Inserting an Interface or a Class into an Existing Hierarchy......Page 119
Adding a Method or a Field......Page 120
Comparing Java Interfaces and Classes......Page 121
In Weakness Lies Strength......Page 122
A Method Addition Lover’s Heaven......Page 123
Are Abstract Classes Useful?......Page 125
Getting Ready for Growing Parameters......Page 126
Interfaces vs. Classes......Page 128
Use Modular Architecture......Page 129
Types of Modular Design......Page 131
Intercomponent Lookup and Communication......Page 134
Writing an Extension Point......Page 147
The Need for Cyclic Dependencies......Page 148
Lookup Is Everywhere......Page 152
Overuse of Lookup......Page 156
Expressing API/SPI in C and Java......Page 161
API Evolution Is Different from SPI Evolution......Page 163
Writer Evolution Between Java 1.4 and 1.5......Page 164
Split Your API Reasonably......Page 175
Keep Testability in Mind......Page 179
API and Testing......Page 180
The Fade of the Specification......Page 182
Good Tools Make Any API Easier......Page 184
Test Compatibility Kit......Page 186
Beware of Using Other APIs......Page 189
Leaking Abstractions......Page 193
Enforcing Consistency of APIs......Page 194
Delegation and Composition......Page 198
Prevent Misuses of the API......Page 206
Do Not Overuse the JavaBeans Listener Pattern......Page 210
Runtime Aspects of APIs......Page 215
Fixing Odyssey......Page 217
Reliability and Cluelessness......Page 220
Synchronization and Deadlocks......Page 222
Document the Threading Model......Page 223
Pitfalls of Java Monitors......Page 224
Deadlock Conditions......Page 226
Deadlock Test......Page 231
Testing Race Conditions......Page 234
Analyzing Random Failures......Page 236
Advanced Usage of Logging......Page 238
Execution Flow Control Using Logging......Page 240
Preparing for Reentrant Calls......Page 245
Memory Management......Page 248
Declarative Programming......Page 255
Make Objects Immutable......Page 257
Immutable Behavior......Page 261
Compatibility of Documents......Page 262
Extreme Advice Considered Harmful......Page 269
An API Must Be Beautiful......Page 270
An API Has to Be Correct......Page 271
An API Has to Be Simple......Page 272
An API Has to Have Good Performance......Page 274
An API Must Be 100 Percent Compatible......Page 275
An API Needs to Be Symmetrical......Page 278
Paradoxes of API Design......Page 279
API Doublethink......Page 280
The Invisible Job......Page 283
Overcoming the Fear of Committing to a Stable API......Page 284
Minimizing Maintenance Cost......Page 287
Evolving the API Universe......Page 291
Resuscitating Broken Libraries......Page 292
Conscious vs. Unconscious Upgrades......Page 298
Alternative Behavior......Page 302
Bridges and the Coexistence of Similar APIs......Page 307
Organizing Reviews Before Committing Code......Page 321
Convincing Developers to Document Their API......Page 324
Big Brother Never Sleeps......Page 326
Accepting API Patches......Page 330
Overview......Page 333
Day 1......Page 334
The Immutability Problem......Page 337
The Problem of the Missing Implementation......Page 341
The Problem of Possibly Incorrect Results......Page 343
Solutions for Day 1......Page 344
Day 2......Page 347
Solutions for Day 2......Page 351
Day 3: Judgment Day......Page 355
What Was Wrong with subclassingsolution and stackbasedsolution?......Page 356
What Was Wrong with alwayscreatenewcircuit and welltestedsolution?......Page 357
What Was Wrong with elementbasedsolution?......Page 359
Play Too!......Page 362
Extensible Visitor Pattern Case Study......Page 363
Abstract Class......Page 366
Preparing for Evolution......Page 368
Default Traversal......Page 370
Clean Definition of a Version......Page 372
Nonmonotonic Evolution......Page 374
Data Structure Using Interfaces......Page 375
Client and Provider Visitors......Page 376
Triple Dispatch......Page 379
Syntactic Sugar......Page 381
End-of-Life Procedures......Page 385
The Importance of Module Dependencies......Page 386
Should Removed Pieces Lie Around Forever?......Page 389
Splitting Monolithic APIs......Page 390
The Future......Page 393
Principia Informatica......Page 394
Cluelessness Is Here to Stay......Page 395
API Design Methodology......Page 396
Languages Ready for Evolution......Page 398
The Role of Education......Page 400
Share!......Page 402
Bibliography......Page 403
Index......Page 405