Organize JDK converters: extension methods for Scala in scala.jdk, explicit converters for Java in jdk.javaapi

[lrytz]

Reorganize JDK converters: import scala.jkd.XConverters._ now brings in extension methods, intended for Scala code. `scala.jdk.javaapi.XConverters has explicit conversion methods, intended for Java code.

Those explicit conversion methods (in javaapi) that refer to a primitive type, e.g., def toJavaOptionalDouble(o: Option[jl.Double]): OptionalDouble, now use the Java box types instead of the Scala primitive types. The reason is the generic signature.

Option[Double] in Scala has generic signature Option[Object] (scala/bug#4214), which makes the explicit converter methods really annoying to use in Java code. But that's the main goal of having these methods - for Scala code, we recommend the extension methods defined in the scala.jdk objects.

So for 2.13.0, as it's too late to change the compiler, we use the java primitive box types directly in the signatures.

   def toJavaOptionalDouble(o: Option[jl.Double]): OptionalDouble

This makes the explicit conversion methods hard to use in Scala, but the Scaladocs tell people to go for the extension methods.

We never had this issue with collection.JavaConverters (now jdk.CollectionConverters) because there are no signatures with primitives in there.

[eed3si9n]

using package name (in addition to Scaladocs)?

I think there are different use cases targeting two different audiences.

1. Scala programmers who need to convert Scala functions/Options into Java Platform equivalent.
2. Scala programmers who need to convert Java functions/Optionals to Scala library equivalent.
3. Java programmers who need to convert Scala functions/Options to Java Platform equivalent.
4. Java programmers who need to convert Java functions/Optionals to Scala library equivalent.

The situation is similar to Akka HTTP having both Scala and Java DSL for Routing DSL for example. In case of Akka HTTP, the APIs are given different packages akka.http.scaladsl and akka.http.javadsl so the paths will not cross.

I think the current scala.jdk API might be difficult to use because it's not immediately clear which use case it's trying to serve.

make "Scala DSL" the primary

As opposed to import scala.jdk.FunctionConverters.Ops._, could we provide all of the ex-java8 compat under import scala.jdk.interops._?

This is to make it more consistent with other DSLs import scala.concurrent.duration._, import scala.util.chaining._. (I used to call this ChainingOps but changed it to chaining per #7007 (comment)).
I think it's safe to assume that someone who wants Java functions would also want Optional.

name for Java DSL

The name of Java DSL package should be obvious that it's targeting Java programmers. Like import scala.jdk.javadsl.interops._.

"a la carte" import

If we want to still provide "a la carte" DSL, such as FunctionConverters, I suggest we use the following convention:

// scala
import scala.jdk.FunctionConverters._

// java
import scala.jdk.javadsl.FunctionConverters._

In general though I think we should point people to import scala.jdk.interops._ and add documentation on that package and/or object.

[eed3si9n]

Added a comment on the overall "feel".

[lrytz]

could we provide all of the ex-java8 compat under import scala.jdk.interops._?

I'm not in favor of this, I think it's a good thing to force people to be explicit and import conversions for the kind of types that they want to convert (options, functions, collections, streams, futures).

I suggest we use the following convention:

// scala
import scala.jdk.FunctionConverters._

// java
import scala.jdk.javadsl.FunctionConverters._

That looks fine to me, except for the javadsl package name, it's not a DSL, just some conversion methods. javaapi package name? Or import static scala.jdk.FunctionConvertersJava.*?

I think we should point people to import scala.jdk.interops._

As I said above, -1 from me on this one.

[eed3si9n]

I'm not in favor of this, I think it's a good thing to force people to be explicit and import conversions for the kind of types that they want to convert (options, functions, collections, streams, futures).

Collection gets a lumping of scala.collection._, but I'm fine if you don't want to combine ex-java8 converters.

That looks fine to me, except for the javadsl package name, it's not a DSL, just some conversion methods. javaapi package name? Or import static scala.jdk.FunctionConvertersJava.*?

javaapi sounds good to me.

[lrytz]

OK, I moved the stuff around :-)

import scala.jkd.XConverters._ now brings in extension methods.

scala.jdk.javaapi.XConverters has explicit conversion methods.

[eed3si9n]

LGTM