Java APIs

Announcement

For appeals, questions and feedback about Oracle Forums, please email oracle-forums-moderators_us@oracle.com. Technical questions should be asked in the appropriate category. Thank you!

Interested in getting your voice heard by members of the Developer Marketing team at Oracle? Check out this post for AppDev or this post for AI focus group information.

Capture Conv: rev/reverse - what's the point?

843793Mar 1 2005 — edited Mar 15 2005

Take this example from http://www.langer.camelot.de/GenericsFAQ/FAQSections/TechnicalDetails.html

public static List<?> reverse(List<?> list) { return rev(list); }
private static <T> List<T> rev(List<T> list) {
	List<T> tmp = new ArrayList<T>(list);
	for (int i = 0; i < list.size(); i++)
		list.set(i, tmp.get(list.size() - i - 1);
	return tmp;
}

Now, I've read the JLS, the Generics tutorial, the JOT.fm article and the langer.camelot.de FAQ, but I can't for the life of me figure out one thing:

What's the point!? The wildcard version of reverse returns List<?> whereas the naive alternative (public static <T> List<T> reverse(List<T> list)) returns whatever you pass in. That seems much more useful! You pass in a List<String> and you get back a List<String> The JLS says that the templatized version "is undesirable, as it exposes implementation information to the caller."

My question is this: is that the real reason? It's not, right? What implementation information is exposed? The type parameter? How is that bad? Is it bad enough to reduce the functionality of the method?

I have a hunch that "exposing implementation information" is low on the tradeoff scale - and that the real reason for the wildcard version is backward compatibility. If you only had the templatized version, old code that tries to pass in a plain-old List to reverse would now generate unchecked warnings because of the conversion from raw List to the formal parameter's type List<T>. The preferred wildcard version doesn't generate unchecked warnings because the conversion from raw List to List<?> is 'safe'.

Isn't that right? The reason that "public static <T> List<T> reverse(List<T> list)" is bad is not because it exposes implementation details, but because it causes old code to generate unchecked warnings, non?

If I'm right, then my follow up question would be: who cares? Who cares if old code generates unchecked warnings? Isn't that fair? - a sort of gentle pseudo-deprecation of raw types?

And furthermore, if you'll allow me to smush several questions together, why the preoccupation with eliminating unchecked conversions all over the place? Doesn't the bytecode that comes out look the same either way? What benefit does an unchecked-conversion-free program or CompilationUnit have over one with such conversions? Does provability make possible some future JVM optimizations where some casts or instanceofs can be eliminated? I don't really see how, unless we're talking about some wacky static compiler. Why go to so much trouble to avoid unchecked conversions?

843793

> public static List<?> reverse(List<?> list) { ... }

What's the point!?

Beats me. I would prefer the private version in this case.
The correspondence between the argument and the result
is not an implementation detail.

However, had the result type been void, then I would vote
for wildcards. But I'm biased ;-)

843793

Actually, I cannot follow. I don't understand the question.

The JLS uses the example of a method "public static void reverse(List<?>list)" for explaining capture conversion (in section 5.1.10).

The generics FAQ uses "public static List<?> reverse(List<?> list)" for the same purpose (in http://www.AngelikaLanger.com/GenericsFAQ/FAQSections/TechnicalDetails.html#FAQ501).

Which is the one you are talking of?

In the case of "static void reverse(List<?> list)" there is not much of a difference between the wildcard version and the generic version "static <T> void reverse(List<T>list)" of the method. One produces "unchecked" warnings when used with raw types, while the other does not. But beyond that I think it's mostly a matter of taste or style which one you prefer. I would consider the two signatures mostly equivalent. (Peter obviously disagrees. Perhaps he can expand on it and explain why.)

The situation is fundamentally different for "static List<?> reverse(List<?> list)" and "static <T> List<T> reverse(List<T> list)".

A method such as "static List<?> reverse(List<?> list)" is saying that there is no interest in the type of elements stored in the list. Neither the method cares, nor does the caller. It's like a method "Object modify(Object)". You don't even know that what goes in does come out. Barely any guarantee, barely any requirement. With signatures like this you might stuff in a list of apples and get back a list of oranges. (Whether this is an appropriate signature for a reverse method is another question. In the FAQ I just used this example for explaining wildcard capture. There is no statement implied that this is a example of brilliant API design.)

In contrast, a method such as "static <T> List<T> reverse(List<T> list)" demands and guarantees that what goes in does come out. Quite obviously the guarantee and the requirement to the caller is much stronger, and so are the restrictions for the implementation of the method. With this signature you get back a list of apples when you stuff in a list of apples, but the signature does not say whether the returned list the same list you supplied; it might be a new list object with the same content in different order. It's like a method "Date update(Date)" or "List unmodifiableList(List list)".

And methods like "static void reverse(List<?>list)" and "<T> void reverse(List<T>list)" say that they modify the list object that was supplied to the method - the exact same, identical object. That is yet another expression of semantics - and probably the best one for a reverse method.

So, we are having 4 different signatures expressing at least 3 different semantics. Which one is to be prefered?

JLS section 5.1.10 prefers the wildcard version "static void reverse(List<?>list)" over the generic version "<T> void reverse(List<T>list)".

The Generics FAQ prefers "static <T> List<T> reverse(List<T> list)" over "static List<?> reverse(List<?> list)" (see http://www.AngelikaLanger.com/GenericsFAQ/FAQSections/ProgrammingIdioms.html#FAQ302 and http://www.AngelikaLanger.com/GenericsFAQ/FAQSections/ProgrammingIdioms.html#FAQ303).

Now, what is your question?

843793

Angelika, you caught me. I was writing about the 'void reverse(List<?>)' example from the JLS when I went back to your page and realized that your example had a return type. It confused the matter slightly, but not enough to detract from my main point, I thought. In fact, it seemed to prove my point - to provide a good counter-example to the JLS reasoning! But let me start from the beginning:

In the draft JLS, it mentions that

<T> void reverse(List<T> list) {}

is preferable to

void reverse(List<?> list) {}

which is "undesirable" because "it exposes implementation information to the caller."

What implementation information? The only difference between the two is that the 'unknown element type' has a different name. '?' as opposed to 'T'. In both cases, it means the same thing! A List with some unknown element type.

Whether it's called 'T' or '?' is inconsequential, it seemed to me. Perhaps one could argue that one is 'prettier' than the other but I didn't see how any implementation detail was exposed.

I didn't see any real reason to prefer the wildcard version over the other, except the reason I gave: the wildcard version avoids unchecked warnings for legacy code.

I now see that there is one other important difference - the type parameter T is actually part of the method signature. That could have important implications for overriding. In that sense, the 'List<T>' version does 'expose' and impose an unnecessary implementation constraint. I haven't thought through how that could be a problem, but I certainly can imagine that it might.

However, neither the 'avoid-unchecked-warnings-on-legacy-code' reason nor the 'typeparameter-is-part-of-method-signature' reason is mentioned in the JLS example. Without those two pieces of information, the preference just seems arbitrary.

So that was my initial question: "am I incorrect? The dont-expose-implementation-information reason seems much less important than the avoid-legacy-warnings reason - shouldn't the JLS mention *that* instead?"

-

THEN, to add to my feeling, I noticed that the similar-looking example on your page involved a return type of List<T>. It seemed to follow the JLS recommendation to its detriment! The preference in the JLS example seemed arbitrary yet harmless, but here it seemed actually wrong! In trying to avoid the hand-wavy concept of 'exposing implementation information to the caller', the usefulness and semantics were ruined! That seemed like alot to give up, just to spare legacy people some unchecked warnings. I thought this just drove home my original point about the JLS example - but instead it just made my question a confusing mixture of two different issues. I should have realized that and left the FAQ version out of the discussion.

Given all of that, consider now only the JLS's 'void reverse(List<?> list)' case and let me ask this refined question:

I think the JLS should say that '<T> void reverse(List<T> list)' is undesirable not because of the vaguely unconvincing reason that "it exposes implementation information" but rather because of these two explicit reasons:
. the type parameter is part of the method signature (which can cause strange 'gotchas' with overriding) and because
. it causes previously acceptable code to now unnecessarily generate unchecked warnings.
Does anyone else think differently?

POSTSCRIPT:

Of course, the thing I didn't realize was that that code snippet in the FAQ is crazy. ie. 'List<?> reverse(List<?> list)' is absurd! You would probably never do that. What kind of reverse method would return a List of a different parameterization than it gets? That would be a really weird reverse method, I think.

Given that, it seems to me that you should modify the 'reverse' snippets in the FAQ, under sections "What is the capture of a wildcard?" and "What is a wildcard capture assignment-compatible to?". I think you should do one of three things:

1. Make rev/reverse return 'void'. Then your example code becomes the same as the JLS, the wildcard version makes sense, and preferring it makes sense too.
2. Remove one of the two methods and only have 'public <T> List<T> reverse(List<T>)' which gives the correct implication.
3. Keep the example but give the methods a different name and purpose than 'reverse', like
'List<?> examineListAndMaybeReturnOneWithDifferentElementTypes(List<?> list)'. :)

843793

Excuse me again. I edited that post about 20 times, but of course I missed the biggest typo of all: I reversed the order of the first two method declarations. It should say:

In the draft JLS, it mentions that

void reverse(List<?> list) {}

is preferable to

<T> void reverse(List<T> list) {}

which is "undesirable" because "it exposes implementation information to the caller."

843793

I think the JLS should say that '<T> void
reverse(List<T> list)' is undesirable not because of
the vaguely unconvincing reason that "it exposes
implementation information" but rather because of
these two explicit reasons:
. the type parameter is part of the method signature
e (which can cause strange 'gotchas' with overriding)
and because
. it causes previously acceptable code to now
w unnecessarily generate unchecked warnings.
Does anyone else think differently?

I don't understand why you feel this is so important. The JLS
is final and it will not be changed. The text you're referring to
is in non-normative text (called discussion). Furthermore,
I think you're misunderstanding the purpose of the discussion:
the discussion explains why wildcard capture is useful and
what the consquences of not having capture conversion
would be. In that case you would be required to use a generic
method and not be able to accept List<?>.

I don't think we thought of the extra benefit from wildcards:
no unchecked warning. If so, the discussion might have
been simpler.

843793

Sorry to make such a fuss. I really don't "feel this is so important." I guess I'm just fascinated by it all and I'm wondering about everything out loud - perhaps too loud.

I do think that the discussion portions are 'de facto' normative or at least 'instructive' if they raise new issues not mentioned elsewhere. The discussion may be to explain why capture is useful, but it also opens up a whole new separate topic. It suggests that we should split

<T> void reverse(List<T> list)

into two separate methods, and then gives a confusing reason for why the split version is preferable.

It's no big deal. But it is there and it seems worth mentioning. I guess, if I could boil my question down even further, it would be simply this:

The JLS says "public static <T> void reverse(List<T> list) ... is undesirable, as it exposes implementation information to the caller." What implementation information? Why is that undesirable?

I do apologize if any of my writing seems self-righteous or hostile. I appreciate your help here and your writings elsewhere on the web. That goes for both of you, Angelika and Peter.

843793

Sorry to make such a fuss. I really don't "feel this
is so important." I guess I'm just fascinated by it
all and I'm wondering about everything out loud -
perhaps too loud.

Now I'm sorry. I didn't mean to imply you were out of
order.

I do think that the discussion portions are 'de
facto' normative or at least 'instructive' if they
raise new issues not mentioned elsewhere.

I don't think our lawyers agree ;-)

The JLS says "public static <T> void
reverse(List<T> list) ... is undesirable, as it
exposes implementation information to the caller."
What implementation information? Why is that
t undesirable?

Not all Java programmers will feel comfortable with
generic methods. They are more complicated because of
inference (and harder to read because of the type variable).

Furthermore, the extra type parameter is an implementation detail
just as local variables. You wouldn't list local variables in
a method signature :-)

Finally, as a general principle of software engineering it is a
good idea to strive for simplicity and eliminate unnecessary
clutter. The type variable is unnecessary.

Anyways, I discussed how capture conversion avoids an
unchecked warnings with the rest of the wildcard gang. It
turns out that this is more of an oversight in how we deal
with raw types. Using the same rationale as for why
capture conversion is type safe, you can see that calling
<T> void reverse(List<T> l) with an argument of type List
is just as safe.

1 - 7

Locked Post

New comments cannot be posted to this locked post.

Locked on Apr 12 2005

Added on Mar 1 2005

#generics

7 comments

157 views

Java APIs

Capture Conv: rev/reverse - what's the point?

Comments

Post Details