Runtime Aspects of APIs
From APIDesign
(→Have You Ever Wondered...?) |
(→Have You Ever Wondered...?) |
||
| (3 intermediate revisions not shown.) | |||
| Line 1: | Line 1: | ||
== Have You Ever Wondered...? == | == Have You Ever Wondered...? == | ||
| - | Did you ever tried to find the border line between the API and its implementation? Is javadoc API? I guess, so. Do names of public classes and methods belong into the API? Are the checks for incorrect parameter types throwing ''IllegalArgumentException'' part of API? Are ''NullPointerException''s thrown from inside of the API method bodies part of API? And what about the order of callbacks to client code, order of event delivery, identity of threads the callbacks happen in? | + | Did you ever tried to find the border line between the API and its implementation? Is javadoc API? I guess, so. Do names of public classes and methods belong into the API? Are the checks for incorrect parameter types throwing ''IllegalArgumentException'' part of API? Are ''NullPointerException''s thrown from inside of the API method bodies part of API? And what about the order of callbacks to client code, order of event delivery, identity of threads the callbacks happen in? Are speed of method execution, the amount of allocated memory or [[WeakReference|type of references]] important for API users? I guess they may be, at least in the [[wikipedia::Real-time_computing|real-time]] world (as for example [[MemoryAllocations]] hack demonstrates). But then: Where is the border between API and its implementation!? The [[Runtime Aspects of APIs|chapter 11]] shows why the APIs do not end at method and class signatures. It explains why these ''runtime'' APIs are important and what needs to be done to evolve them in the right way - evolve them compatibly. The [[Runtime Aspects of APIs|chapter 11]] does not reveal the holy grail, but it presents a technique proven to work, capable to ensure runtime backward compatibility. |
| + | |||
| + | ==== Related [[API Design Tips|Podcast]] ==== | ||
| + | |||
| + | {{:Blogs:JaroslavTulach:Daily_Life:Podcast2}} | ||
==== Pitfalls of [[Java Monitor]]s ==== | ==== Pitfalls of [[Java Monitor]]s ==== | ||
[[Runtime_Aspects_of_APIs|This chapter]] also dedicates one section to discussion of problems one can face when dealing with [[Java Monitor]]s. Erwin Vervaet recently pointed out that the example is a little bit unclear and asked me to provide better explanation of the problem, where subclasses interfere with the parent class's [[monitor]]s. Please find the explanation at [[Java Monitor]] page. | [[Runtime_Aspects_of_APIs|This chapter]] also dedicates one section to discussion of problems one can face when dealing with [[Java Monitor]]s. Erwin Vervaet recently pointed out that the example is a little bit unclear and asked me to provide better explanation of the problem, where subclasses interfere with the parent class's [[monitor]]s. Please find the explanation at [[Java Monitor]] page. | ||
| + | |||
| + | ==== @Synchronized ==== | ||
| + | |||
| + | {{:Synchronized}} | ||
Current revision
Contents |
Have You Ever Wondered...?
Did you ever tried to find the border line between the API and its implementation? Is javadoc API? I guess, so. Do names of public classes and methods belong into the API? Are the checks for incorrect parameter types throwing IllegalArgumentException part of API? Are NullPointerExceptions thrown from inside of the API method bodies part of API? And what about the order of callbacks to client code, order of event delivery, identity of threads the callbacks happen in? Are speed of method execution, the amount of allocated memory or type of references important for API users? I guess they may be, at least in the real-time world (as for example MemoryAllocations hack demonstrates). But then: Where is the border between API and its implementation!? The chapter 11 shows why the APIs do not end at method and class signatures. It explains why these runtime APIs are important and what needs to be done to evolve them in the right way - evolve them compatibly. The chapter 11 does not reveal the holy grail, but it presents a technique proven to work, capable to ensure runtime backward compatibility.
Related Podcast
Listen to podcast #2: to learn about our take on Swing and its poor reentrancy. Find out what it may mean for your own API design and especially Runtime_Aspects_of_APIs that you create. Learn to fight with that problem by maximizing the declarative nature of your API.Pitfalls of Java Monitors
This chapter also dedicates one section to discussion of problems one can face when dealing with Java Monitors. Erwin Vervaet recently pointed out that the example is a little bit unclear and asked me to provide better explanation of the problem, where subclasses interfere with the parent class's monitors. Please find the explanation at Java Monitor page.
@Synchronized
Synchronization is getting more and more important in applications and libraries written these days. However synchronization is hard. The primitives available in Java (or other languages), are ... well, are primitive. Higher level abstractions are available, but still they don't guarantee completely deadlock prone system. This has all been discussed in Chapter 11, Runtime Aspects of APIs.
Java Monitors just aren't what they supposed to be (read why). Thus I am glad to see that the project Lombok's @Synchronized seems to successfully replace the synchronized keyword with annotation (vivat annotations!).
In the name of cluelessness of your Java API users, don't forget to prefer private locks to synchronized methods. Or switch to the beautiful @Synchronized annotation.
Follow
