we should have a "Java interop" guide

[SethTisue]

it would cover topics such as:

• how to call Java libraries from Scala
• how to write Scala code that is easily callable from Java
• JavaConverters
• hey, scala-java8-compat exists, consider using it!
• boxing
• generics
  • Scala's type system allows type parameters to be primitive types, Java's doesn't
  • use-site variance (Java) vs. declaration-site variance (Scala)
• default parameters

and probably a lot of other stuff. there is a Java interop chapter in the Odersky/Venners/Spoon book that we could mine for ideas.

a first draft of such a guide wouldn't need to be anywhere near complete, it would be fine just to get something in place and then it could expand over time from there

there are a ton of Stack Overflow answers that would be useful here, it would be fine to sometimes just link to those, doing that can be a real time-saver when writing docs, even if ideally the SO links might eventually get replaced with our own text

[SethTisue]

a few of my own SO answers that answer FAQs in this area:

• https://stackoverflow.com/questions/3299776/in-scala-how-can-i-subclass-a-java-class-with-multiple-constructors/
• https://stackoverflow.com/questions/6545066/using-scala-from-java-passing-functions-as-parameters/8380694#8380694
• https://stackoverflow.com/questions/1997433/how-to-use-scala-none-from-java-code/3720044#3720044
• https://stackoverflow.com/questions/2561415/how-do-i-get-a-scala-case-object-from-java/2561436#2561436

[SethTisue]

relevant: https://docs.scala-lang.org/overviews/collections/conversions-between-java-and-scala-collections.html

[SethTisue]

it should cover the difference between Scala's access model and the JVM's. for example, any top-level trait or class must be public in the bytecode, in order for it to be accessible by nested packages, since Scala has the nested-package concept but the JVM does not.

[SethTisue]

https://github.com/akka/akka/blob/master/CONTRIBUTING.md#java-apis-in-akka has a lot of valuable information in area of designing-for-calling-from-Java /cc @raboof (and there is a variant at https://github.com/akka/alpakka/blob/master/contributor-advice.md#implementing-the-java-api-in-scala)

[SethTisue]

does @jsuereth's Scala in Depth have a chapter on this? I can't remember. (if it does it's presumably out of date, but it could still be a good source to mine.)

[SethTisue]

I haven't seen this book, but it sounds relevant: https://leanpub.com/jvm-scala-book