Talk:Cooperating with Other APIs

From APIDesign

Revision as of 05:25, 4 April 2009

Forgive the linguist in me (I did work on speech recognition for 8 years), but the expression is "painting ourselves into a corner". You can't paint yourself into anything else, or it's a broken metaphor :) I saw this particular expression used wrongly a few times in the book.

--RichUnger 22:40, 10 April 2008 (UTC)

Talk to Tim, this is his sentence. As far as I can say, we have "Zahnat se do kouta" - chase yourself into a corner. Which is also a non-sense as you cannot chase yourself. But still it is widely used here and has the right meaning of doing wrong mistakes yourself that you are then sorry for.

--JaroslavTulach

Done: f69d2163f4c8

Page 154, code example: bad indentation of the class header.

Having a final class whose all methods return null really is bulletproof, but it can also confuse the reader. Please consider stating that in order to make the class do something meaningful you can use delegation, which you will show in the next section.

--AndreiBadea 09:01, 9 April 2008 (UTC)

Yes, I was very confused by this code. It didn't seem to have anything to do with what you were describing.

--RichUnger 22:40, 10 April 2008 (UTC)

Done: acc761a59107

Page 147, para 2: Java collections use size, not getSize. Also the Javadoc refers to the Collections API as to "Collections Framework".

Page 147, para -1: the 2.2 kernel doesn't seem to be actively maintained (cf. http://www.kernel.org), but the 2.4 one is. Say what the current state is instead of "I've heard".

Page 148, para 2: remove the TBD note.

Page 148, para 3: not apparent from the text what is the NP-C problem. You seem to be talking about conflicts in libraries, where both String 1.0 and 2.0 are needed, not about how hard is to compute the set of needed libraries. Moreover, does the wrapping in the example on page 149 make the computation polynomial?

--AndreiBadea 08:57, 9 April 2008 (UTC)

I'd like more discussion of java.lang.reflect.Proxy as a method for maintaining compatibility with 2 java versions.

--RichUnger 22:40, 10 April 2008 (UTC)

The reference to NP-completeness on p. 148 seems quite odd. As far as I can tell, you're not describing any problem which is actually NP-complete; you're just using "NP-complete" as a very loose synonym for "hard". But most of your readers won't have the theoretical computer science background to know what this term actually means, and this will just confuse them.

--AdamDingle 00:48, 13 April 2008 (UTC)

It really is NP-complete problem as described at LibraryReExportIsNPComplete.

Done: 414c75f60371

Page 161, para -2: "Javadoc" instead of "JavaDoc".

Page 162, code example: public not used on interface methods -- inconsistent with other sections. Also, whether to make Savepoint a nested class of Connection or not is irrelevant here. Only make the modifications you need to in order to make your point.

Page 163, top code example: inconsistent public usage on interface method even in a single example!

Page 164, para -2: I assume [book.effective] is Bloch's Effective Java. It doesn't recommend the Java 5 enums, since Java 5 hadn't been released yet when the book came out. But it is true that the typesafe enums recommended in the book are very similar to Java 5 enums.

"beaten to death" looks too colloquial to me, perhaps something like "this topic has been dealt with exhaustively" would be more appropriate.

--AndreiBadea 10:23, 9 April 2008 (UTC)

I would argue this is a good example of a case where your definition of cluelessness doesn't match the one of most Java developers out there. People are so used to implementing listener support, that even the TooManyListenersException way would look weird to them. Not to mention the Callback one.

--AndreiBadea 10:26, 9 April 2008 (UTC)

Page 155, Arithmetica code example: it is prone to overflows, and sumRange can throw NegativeArraySizeException. OK, this is probably a nitpick and readers will understand that it's only an example.

• Done: 6756df936f47

Page 156, para 1: if you want to provide assert message, please consider providing better ones. "+" and "10" are not good messages.

• Done: 6756df936f47

Page 156, para 3: no apparent reason for Factorial to be static and final.

• Done: 55f1eee7a9b0

Page 160, table 11-2: the way you rewrite public void method() and protected void method() modifies the contract of the class of these methods: in the original version the class didn't need to be abstract, but it needs to in the rewritten version. Perhaps you need to expand this part a bit and not talk about "eliminating" and "rewriting", but about splitting the method into two methods with single meanings. Also, for every split operation describe the result. I think a table is not the appropriate layout for this part.

• I changed a bit, but probably not much: 56fb37e7666a

Page 160, both code examples: no apparent reason for MixedClass and NonMixed to be static. These examples are inconsistently formatted.

Page 160, NonMixed code example: NonMixedImpl will be an unfamiliar name to most readers. To most Java developers, it looks like the implementation of a NonMixed interface. Definitely it doesn't look like something that needs to be implemented. At least this is what new developers in the NetBeans Java EE team say. Consider a name like NonMixedSpi.

Maybe the example needs to be a bit more real. Likely <t>apiForClients</tt> will need to call toBeImplementedBySubclass, so show how this is done. Moreover, this pattern is unfamiliar enough even without toBeCalledBySubclass and Callback. Consider starting with an example without toBeCalledBySubclass and ading this method in the second step.

Page 161, code example: no need to NonMixedImpl to be static.

Done: c6b3de9129ab

--AndreiBadea 09:37, 9 April 2008 (UTC)

I am not sure I understand table 10-2. In it you advise against classes with non-abstract, non-final protected methods, that is, non-final protected methods with an implementation in the super class. Let's call that superclass A.

My understanding for this prohibition is because A's methods, call them X , Y and Z, can call into each other in ways that are basically not part of the documented API (but in reality part of the real-world API) and if someone else overrides an implementation of one of them, say, Y, an undocumented and probably unintended side-effect is to change the semantics of calling the others, X and Z.

But how is it an improvement to make these protected methods abstract with no super class implementation? Suppose I have no super class implementation; let X Y and Z be truly abstract and protected and non-final, as you advise. At a later point in time, a subclass implementor comes along and implements X Y and Z in a new subclass, call it B. Now that implementor's class is exactly where you said we don't want to be, with non-abstract, non-final, protected methods implemented in B. B is of course open to being subclassed by a yet later implementor, call that subclass C.

So we don't escape anything really, or at best we escape it for one generation of subclasses.

What am I misunderstanding?

So this is the table on page 174 of the Apress book. Reading some of these posts it appears that the page numbers they refer to and the page numbers I have in my book are different.

--swv, April 3, 2009

Thanks swv for your questions. I'll try to provide blog answer soon, but here are short comments:

• if the class B is not part of API, then it does not matter how poorly (from evolution point of view it is designed)
• if the class B is in an API (probably it should not, as deep, including two, object hierarchies do not belong in API), it can still make all the overriden methods protected final. Potentially introduce some new protected abstract - e.g. positioning class C into similar situation as B was when it was created.
• Better than EliminateFuzzyModifiers is to use DelegationAndComposition and these problems shall be gone then.

Thanks and you are right about the page numbers. The previous comments are about draft of TheAPIBook, while you have final version.

--JaroslavTulach 05:25, 4 April 2009 (UTC)