Practical API design : confessions of a Java framework architect

You might think more than enough design books exist in the programming world already. In fact, there are so many that it makes sense to ask why you would read yet another. Is there really a need for yet another design book? In fact, there is a greater need than ever before, and Practical API Design: Confessions of a Java Framework Architect fills that need! - Teaches you how to write an API that will stand the test of Time - Written by the designer of the NetBeans API at Sun - Based on best practices, scalability, and API design patterns What you’ll learn - What an API is and what the theories are behind good API design - When and why to build an API - API design patterns applicable to all programming languages, especially modern, object–oriented languages - How to optimize and test APIs Who is this book for? This book is recommended to every API architect who prefers a bit more engineering design over a purely artistic one. Practical API Design: Confessions of a Java Framework Architect 1 Contents at a Glance 6 Contents 9 About the Author 15 Acknowledgments 17 Prologue: Yet Another Design Book? 19 API Design Is Different 20 Who Should Read This Book? 23 Is This Book Useful Only for Java? 24 Learning to Write APIs 27 Is This Book Really a Notebook? 28 Theory and Justification 31 The Art of Building Modern Software 35 Rationalism, Empiricism, and Cluelessness 35 Evolution of Software So Far 37 Gigantic Building Blocks 39 Beauty, Truth, and Elegance 40 More Cluelessness! 42 The Motivation to Create an API 45 Distributed Development 45 Modularizing Applications 47 Nonlinear Versioning 50 It’s All About Communication 52 Empirical Programming 53 The First Version Is Always Easy 55 Determining What Makes a Good API 57 Method and Field Signatures 57 Files and Their Content 58 Environment Variables and Command-Line Options 59 Text Messages As APIs 61 Protocols 62 Behavior 64 I18N Support and L10N Messages 65 Wide Definition of APIs 66 How to Check the Quality of an API 66 Comprehensibility 67 Consistency 68 Discoverability 68 Simple Tasks Should Be Easy 69 Preservation of Investment 69 Ever-Changing Targets 71 The First Version Is Never Perfect 71 Backward Compatibility 72 Source Compatibility 72 Binary Compatibility 73 Functional Compatibility—the Amoeba Effect 78 The Importance of Being Use Case Oriented 81 API Reviews 84 Life Cycle of an API 85 Incremental Improvements 89 Do Not Expose More Than You Want 99 A Method Is Better Than a Field 100 A Factory Is Better Than a Constructor 101 Make Everything Final 103 Do Not Put Setters Where They Do Not Belong 104 Allow Access Only from Friend Code 105 Give the Creator of an Object More Rights 109 Do Not Expose Deep Hierarchies 113 Code Against Interfaces, Not Implementations 117 Removing a Method or a Field 118 Removing or Adding a Class or an Interface 119 Inserting an Interface or a Class into an Existing Hierarchy 119 Adding a Method or a Field 120 Comparing Java Interfaces and Classes 121 In Weakness Lies Strength 122 A Method Addition Lover’s Heaven 123 Are Abstract Classes Useful? 125 Getting Ready for Growing Parameters 126 Interfaces vs. Classes 128 Use Modular Architecture 129 Types of Modular Design 131 Intercomponent Lookup and Communication 134 Writing an Extension Point 147 The Need for Cyclic Dependencies 148 Lookup Is Everywhere 152 Overuse of Lookup 156 Separate APIs for Clients and Providers 161 Expressing API/SPI in C and Java 161 API Evolution Is Different from SPI Evolution 163 Writer Evolution Between Java 1.4 and 1.5 164 Split Your API Reasonably 175 Keep Testability in Mind 179 API and Testing 180 The Fade of the Specification 182 Good Tools Make Any API Easier 184 Test Compatibility Kit 186 Cooperating with Other APIs 189 Beware of Using Other APIs 189 Leaking Abstractions 193 Enforcing Consistency of APIs 194 Delegation and Composition 198 Prevent Misuses of the API 206 Do Not Overuse the JavaBeans Listener Pattern 210 Runtime Aspects of APIs 215 Fixing Odyssey 217 Reliability and Cluelessness 220 Synchronization and Deadlocks 222 Document the Threading Model 223 Pitfalls of Java Monitors 224 Deadlock Conditions 226 Deadlock Test 231 Testing Race Conditions 234 Analyzing Random Failures 236 Advanced Usage of Logging 238 Execution Flow Control Using Logging 240 Preparing for Reentrant Calls 245 Memory Management 248 Declarative Programming 255 Make Objects Immutable 257 Immutable Behavior 261 Compatibility of Documents 262 Extreme Advice Considered Harmful 269 An API Must Be Beautiful 270 An API Has to Be Correct 271 An API Has to Be Simple 272 An API Has to Have Good Performance 274 An API Must Be 100 Percent Compatible 275 An API Needs to Be Symmetrical 278 Paradoxes of API Design 279 API Doublethink 280 The Invisible Job 283 Overcoming the Fear of Committing to a Stable API 284 Minimizing Maintenance Cost 287 Evolving the API Universe 291 Resuscitating Broken Libraries 292 Conscious vs. Unconscious Upgrades 298 Alternative Behavior 302 Bridges and the Coexistence of Similar APIs 307 Teamwork 321 Organizing Reviews Before Committing Code 321 Convincing Developers to Document Their API 324 Big Brother Never Sleeps 326 Accepting API Patches 330 Using Games to Improve API Design Skills 333 Overview 333 Day 1 334 Problem of Nonpublic API Classes 337 The Immutability Problem 337 The Problem of the Missing Implementation 341 The Problem of Possibly Incorrect Results 343 Solutions for Day 1 344 Day 2 347 I Want to Fix My Mistakes Problem 351 Solutions for Day 2 351 Day 3: Judgment Day 355 Conclusions 356 What Was Wrong with subclassingsolution and stackbasedsolution? 356 What Was Wrong with inputandoperation? 357 What Was Wrong with alwayscreatenewcircuit and welltestedsolution? 357 What Was Wrong with elementbasedsolution? 359 Play Too! 362 Extensible Visitor Pattern Case Study 363 Abstract Class 366 Preparing for Evolution 368 Default Traversal 370 Clean Definition of a Version 372 Nonmonotonic Evolution 374 Data Structure Using Interfaces 375 Client and Provider Visitors 376 Triple Dispatch 379 A Happy End for Visitors 381 Syntactic Sugar 381 End-of-Life Procedures 385 The Importance of a Specification Version 386 The Importance of Module Dependencies 386 Should Removed Pieces Lie Around Forever? 389 Splitting Monolithic APIs 390 The Future 393 Principia Informatica 394 Cluelessness Is Here to Stay 395 API Design Methodology 396 Languages Ready for Evolution 398 The Role of Education 400 Share! 402 Bibliography 403 Index 405 Provides Information On Api Design Using The Java Programming Language. Part 1: Theory And Justification -- Chapter 1 The Art Of Building Modern Software -- Rationalism, Empiricism, And Cluelessness -- Evolution Of Software So Far -- Gigantic Building Blocks -- Beauty, Truth, And Elegance -- More Cluelessness! -- Chapter 2 The Motivation To Create An Api -- Distributed Development -- Modularizing Applications -- It's All About Communication -- Empirical Programming -- The First Version Is Always Easy -- Chapter 3 Determining What Makes A Good Api -- Method And Field Signatures -- Files And Their Content -- Environment Variables And Command-line Options -- Text Messages As Apis -- Protocols -- Behavior -- I18n Support And L10n Messages -- Wide Definition Of Apis -- How To Check The Quality Of An Api -- Chapter 4 Ever-changing Targets -- The First Version Is Never Perfect -- Backward Compatibility -- The Importance Of Being Use Case Oriented -- Api Reviews -- Life Cycle Of An Api -- Incremental Improvements -- Part 2: Practical Design --^ Chapter 5 Do Not Expose More Than You Want -- A Method Is Better Than A Field -- A Factory Is Better Than A Constructor -- Make Everything Final -- Do Not Put Setters Where They Do Not Belong -- Allow Access Only From Friend Code -- Give The Creator Of An Object More Rights -- Do Not Expose Deep Hierarchies -- Chapter 6 Code Against Interfaces, Not Implementations -- Removing A Method Or A Field -- Removing Or Adding A Class Or An Interface -- Inserting An Interface Or A Class Into An Existing Hierarchy -- Adding A Method Or A Field -- Comparing Java Interfaces And Classes -- In Weakness Lies Strength -- A Method Addition Lover 's Heaven -- Are Abstract Classes Useful? -- Getting Ready For Growing Parameters -- Interfaces Vs. Classes -- Chapter 7 Use Modular Architecture -- Types Of Modular Design -- Intercomponent Lookup And Communication -- Writing An Extension Point -- The Need For Cyclic Dependencies -- Lookup Is Everywhere -- Overuse Of Lookup --^ Chapter 8 Separate Apis For Clients And Providers -- Expressing Api/spi In C And Java -- Api Evolution Is Different From Spi Evolution -- Writer Evolution Between Java 1.4 And 1.5 -- Split Your Api Reasonably -- Chapter 9 Keep Testability In Mind -- Api And Testing -- The Fade Of The Specification -- Good Tools Make Any Api Easier -- Test Compatibility Kit -- Chapter 10 Cooperating With Other Apis -- Beware Of Using Other Apis -- Leaking Abstractions -- Enforcing Consistency Of Apis -- Delegation And Composition -- Prevent Misuses Of The Api -- Do Not Overuse The Javabeans Listener Pattern -- Chapter 11 Runtime Aspects Of Apis -- Fixing Odyssey -- Reliability And Cluelessness -- Synchronization And Deadlocks -- Document The Threading Model -- Pitfalls Of Java Monitors -- Preparing For Reentrant Calls -- Memory Management -- Chapter 12 Declarative Programming -- Make Objects Immutable -- Immutable Behavior -- Compatibility Of Documents -- Part 3: Daily Life --^ Chapter 13 Extreme Advice Considered Harmful -- An Api Must Be Beautiful -- An Api Has To Be Correct -- An Api Has To Be Simple -- An Api Has To Hav. Jaroslav Tulach. Includes Bibliographical References (p. 373) And Index. You might think more than enough design books exist in the programming world already. In fact, there are so many that it makes sense to ask why you would read yet another. Is there really a need for yet another design book? In fact, there is a greater need than ever before, and Practical API Design: Confessions of a Java Framework Architect fills that need! Teaches you how to write an API that will stand the test of time Written by the designer of the NetBeans API at Sun Technologies Based on best practices, scalability, and API design patterns