'. '

EnforcingProperUsage

From APIDesign

(Difference between revisions)
Jump to: navigation, search
(Engineering solution)
(Engineering solution)
Line 23: Line 23:
Enough to mention the famous [[JDK]]'s ''sun.misc.Unsafe'' & co. You can put warnings all over the documention, you can even modify [[Javac]] to print warnings that the [[API]] is going to disappear. No chance, if the non-public [[API]] is useful, hackers will continue to use it.
Enough to mention the famous [[JDK]]'s ''sun.misc.Unsafe'' & co. You can put warnings all over the documention, you can even modify [[Javac]] to print warnings that the [[API]] is going to disappear. No chance, if the non-public [[API]] is useful, hackers will continue to use it.
-
To prevent that one can play tricks with [[classloader]]s. [[NetBeans Runtime Container]], [[OSGi]] and [[Jigsaw]] allows you to differentiate between public and private packages of your [[JAR]]. The runtime containers then enforce the rules by loading user classes with different [[classloader]] which does not see the classes in private packages. This prevents direct linkage against such classes.
+
To prevent that one can play tricks with [[ClassLoader]]s. [[NetBeans Runtime Container]], [[OSGi]] and [[Jigsaw]] allows you to differentiate between public and private packages of your [[JAR]]. The runtime containers then enforce the rules by loading user classes with different [[ClassLoader]] which does not see the classes in private packages. This prevents direct linkage against such classes.
Still not enough: the shameless hackers are not afraid to use reflection (and taking away the right to use reflection would seriously hurt most of existing [[library|libraries]])!
Still not enough: the shameless hackers are not afraid to use reflection (and taking away the right to use reflection would seriously hurt most of existing [[library|libraries]])!
=== Legal solution ===
=== Legal solution ===

Revision as of 07:58, 14 June 2015

API design is about communication between the API designer and its API users. Good API can be recognized by quality of the communication between the designer and the users. Does the vision of proper API usage (in header of the designer) recreates properly in heads of the users? If not, your API is probably suffering from a poor clarity. Do you users hack around your API - e.g. use things clearly stated as not being part of the API? Can you prevent them to do so? Those are question this essay is about to analyze.

Contents

Striving for Clarity

If an API reaches clarity - e.g. everything in the API has a single meaning - then there is no reason to enforce anything - users either use something (method, class) or not. However, as everything (method, class) in the API has a single meaning, if they use it, they have to (or at least chances are very high) use it correctly. That is the reason why it is important to follow the API design patterns for Clarity and focus on ClarityOfAccessModifiers, ClarityOfTypes and separate API from a service provider interfaces.

Trying to Hack

On the other hand, when striving for clarity, it often happens that the API is more restrictive than its users might want it to be. What the users do then? They hack!

Of course good API users shouldn't hack - they should contribute! As described in Chapter 16 (Teamwork), proper API designing project should have guidelines for accepting patches (like netbeans:APIReviews) and should be ready to accept contributions from its users.

However it is way easier to hack than to contribute an API patch! Some projects (for example OpenJDK comes to my mind) are hostile to random community contributions and getting simple patch in is almost impossible (as my own experience with small enhancements to ReferenceQueue and ServiceLoader shows), however even project open to contribution like NetBeans require one to justify the change, write a test, document it and make sure it is BackwardCompatible. That is still quite a lot of work.

No wonder users resolve to hacking. How can API designers prevent that?

Engineering solution

API designers are primarily engineers and thus it is no surprise they seek a technical solution. Using language encapsulation constructs like private or package private in Java to hide something from the eyes of API users works as it makes such elements (types or methods or fields) inaccessible (unless one resorts to reflection). Even languages without access modifiers allow ways to declare things privately - for example in JavaScript one can use scope to make objects inaccessible for external world.

However sometimes one structures implementation code to split multiple packages. Then some classes need to be publicly visible. With the help of FriendPackages pattern, one can still forbid users of the API to hook into them, but not everyone knows the FriendPackages pattern and as it is common to find Javadoc like: Implementation only, don't use! Guess what your hacking ready API users will do?

Enough to mention the famous JDK's sun.misc.Unsafe & co. You can put warnings all over the documention, you can even modify Javac to print warnings that the API is going to disappear. No chance, if the non-public API is useful, hackers will continue to use it.

To prevent that one can play tricks with ClassLoaders. NetBeans Runtime Container, OSGi and Jigsaw allows you to differentiate between public and private packages of your JAR. The runtime containers then enforce the rules by loading user classes with different ClassLoader which does not see the classes in private packages. This prevents direct linkage against such classes.

Still not enough: the shameless hackers are not afraid to use reflection (and taking away the right to use reflection would seriously hurt most of existing libraries)!

Legal solution

Personal tools
buy