Merge pull request #509 from som-snytt/issue/9684-java-conversions

SI-9684 Don't push JavaConversions

Author: heathermiller

overviews/collections/conversions-between-java-and-scala-collections.md

@@ -11,7 +11,7 @@ languages: [ja, zh-cn]
 
 Like Scala, Java also has a rich collections library. There are many similarities between the two. For instance, both libraries know iterators, iterables, sets, maps, and sequences. But there are also important differences. In particular, the Scala libraries put much more emphasis on immutable collections, and provide many more operations that transform a collection into a new one.
 
-Sometimes you might need to pass from one collection framework to the other. For instance, you might want to access to an existing Java collection, as if it was a Scala collection. Or you might want to pass one of Scala's collections to a Java method that expects its Java counterpart. It is quite easy to do this, because Scala offers implicit conversions between all the major collection types in the [JavaConversions](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/JavaConversions$.html) object. In particular, you will find bidirectional conversions between the following types.
+Sometimes you might need to pass from one collection framework to the other. For instance, you might want to access an existing Java collection as if it were a Scala collection. Or you might want to pass one of Scala's collections to a Java method that expects its Java counterpart. It is quite easy to do this, because Scala offers implicit conversions between all the major collection types in the [JavaConverters](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/JavaConverters$.html) object. In particular, you will find bidirectional conversions between the following types.
 
 
     Iterator               <=>     java.util.Iterator
@@ -23,25 +23,28 @@ Sometimes you might need to pass from one collection framework to the other. For
     mutable.Map            <=>     java.util.Map
     mutable.ConcurrentMap  <=>     java.util.concurrent.ConcurrentMap
 
-To enable these conversions, simply import them from the [JavaConversions](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/JavaConversions$.html) object:
+To enable these conversions, simply import them from the [JavaConverters](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/JavaConverters$.html) object:
 
-    scala> import collection.JavaConversions._
-    import collection.JavaConversions._
+    scala> import collection.JavaConverters._
+    import collection.JavaConverters._
 
-You have now automatic conversions between Scala collections and their corresponding Java collections.
+This enables conversions between Scala collections and their corresponding Java collections by way of extension methods called `asScala` and `asJava`:
 
     scala> import collection.mutable._
     import collection.mutable._
-    scala> val jul: java.util.List[Int] = ArrayBuffer(1, 2, 3)
+     
+    scala> val jul: java.util.List[Int] = ArrayBuffer(1, 2, 3).asJava
     jul: java.util.List[Int] = [1, 2, 3]
-    scala> val buf: Seq[Int] = jul
+     
+    scala> val buf: Seq[Int] = jul.asScala
     buf: scala.collection.mutable.Seq[Int] = ArrayBuffer(1, 2, 3)
-    scala> val m: java.util.Map[String, Int] = HashMap("abc" -> 1, "hello" -> 2)
-    m: java.util.Map[String,Int] = {hello=2, abc=1}
+     
+    scala> val m: java.util.Map[String, Int] = HashMap("abc" -> 1, "hello" -> 2).asJava
+    m: java.util.Map[String,Int] = {abc=1, hello=2}
 
 Internally, these conversion work by setting up a "wrapper" object that forwards all operations to the underlying collection object. So collections are never copied when converting between Java and Scala. An interesting property is that if you do a round-trip conversion from, say a Java type to its corresponding Scala type, and back to the same Java type, you end up with the identical collection object you have started with.
 
-The are some other common Scala collections than can also be converted to Java types, but which to not have a corresponding conversion in the other sense. These are:
+Certain other Scala collections can also be converted to Java, but do not have a conversion back to the original Scala type:
 
     Seq           =>    java.util.List 
     mutable.Seq   =>    java.util.List
@@ -50,9 +53,10 @@ The are some other common Scala collections than can also be converted to Java t
 
 Because Java does not distinguish between mutable and immutable collections in their type, a conversion from, say, `scala.immutable.List` will yield a `java.util.List`, where all mutation operations throw an "UnsupportedOperationException". Here's an example:
 
-    scala> jul = List(1, 2, 3)
+    scala> val jul = List(1, 2, 3).asJava
     jul: java.util.List[Int] = [1, 2, 3]
+
     scala> jul.add(7)
     java.lang.UnsupportedOperationException
-            at java.util.AbstractList.add(AbstractList.java:131)
+      at java.util.AbstractList.add(AbstractList.java:148)