clarify java_interop, wrt `(.instanceMember Classname args*)`

[uvtc]

In https://clojure.org/reference/java_interop, one example given is:

(.instanceMember Classname args*)

I found that confusing, and it was discussed at https://groups.google.com/forum/#!topic/clojure/7eEpEOn1B28 that the docs here could be clarified. Colin Fleming notes:

This doc is confusing - as Phill comments above, this is calling the getName() method on an instance of Class. In Clojure, a bare classname (String, ArrayList or whatever) resolves to the class itself if it has been imported (i.e. what would be String.class in Java). The doc is confusing because (.instanceMember Classname args*) is really just a special case of (.instanceMember instance args*), where "instance" refers to an instance of a Class object. I'm not sure why that doc makes that distinction, it doesn't seem useful to me.

[puredanger]

Regarding "because (.instanceMember Classname args*) is really just a special case of (.instanceMember instance args*)", it turns out while this makes logical sense, this actually is a different case in the expansion. This is actually discussed in the code block right after the example which describes the expansions of each different form. Taking the example in question:

user=> (macroexpand '(.getName String))
(. (clojure.core/identity String) getName)

vs something like

user=> (macroexpand '(.toString "abc"))
(. "abc" toString)

Because these are reference docs, I am inclined to leave the example because it is precisely describing an actual difference. (I would make a different choice in tutorials or guides.)

[cursive-ghost]

I still think this doc could be clarified. It doesn't say why identity is required for Class instances. Clearly it is:

(. java.lang.String getName)
CompilerException java.lang.NoSuchFieldException: getName, compiling:(null:1:1) 
(. (identity java.lang.String) getName)
Reflection warning, null:1:1 - reference to field getName can't be resolved.
=> "java.lang.String"

But I still have no idea why. I assume it's not because the . form args are not evaluated, since (identity java.lang.String) clearly gets evaluated. But the identity function literally just returns its argument, so maybe this is some weirdness with evaluations?

Either way, I'm still confused. I think saying that it's "discussed" in the following block stretches the truth somewhat :-). It really just shows that the expansion is different for some mysterious reason.

[bronsa]

(. Klass foo) tries to resolve to the foo static method of Klass, not to the foo instance method in the Class instance.
To access the foo instance method of Class, you have to work-around it by providing a non-literal that evaluates to Klass, such as ^Class (identity Klass) or ^Class (do Klass), or ^Class (let [] Klass) etc

(. java.util.UUID randomUUID)
user=> (macroexpand '(.getName java.util.UUID))
(. (clojure.core/identity java.util.UUID) getName)
user=> (binding [*print-meta* true] (prn *1))
(. ^Class (clojure.core/identity java.util.UUID) getName)

[seancorfield]

The docs on the dot special form explain why (emphasis mine):

"If the first operand is a symbol that resolves to a class name, the access is considered to be to a static member of the named class. ... Otherwise it is presumed to be an instance member and the first argument is evaluated to produce the target object."

So (. String getName) is considered to be a static member access (symbol String resolves to a class name), but (. (identity String) getName) is presumed to be an instance member access/call (and (identity String) is evaluated).

[cursive-ghost]

Interesting, thanks for the explanation @bronsa and @seancorfield.

[puredanger]

Thanks all. Is there more that should be done on this page from a reference point of view?

[jimrthy]

Could we get something like seancorfield's emphasis and explanation added? I've read that page at least a dozen times over the past few years, and this is a subtlety that's managed to escape me before now. (I get the "this is not a tutorial" point, but this seems like a good opportunity to reduce confusion).

[seancorfield]

I'll submit a PR along the lines of my comment above.

[uvtc]

Thanks for the explanations, all.

@bronsa, I think you shed light on the key insight I was looking for: that classes are instances too (of java.lang.Class), and that you may sometimes need to access instance members of those instances, but since (. SomeClass instanceMember) would go looking for a static member, a workaround was needed --- thus (. (identity SomeClass) instanceMember).

As far as changes to the reference doc, I'd add a comment to the code example at the top, like so:

(.toUpperCase "fred")
-> "FRED"
;; Call the getName instance method on the String class object.
(.getName String)
-> "java.lang.String"
...

[seancorfield]

I'll be interested to hear what people think about your change compared to my proposal in #172.

(I didn't think the current description was confusing so I don't have a dog in this fight 😀)