SI-9684 Deprecate JavaConversions

Implicit conversions are now in package convert as ImplicitConversions,
ImplicitConversionsToScala and ImplicitConversionsToJava.

Deprecated WrapAsJava, WrapAsScala and the values in package object.

Improve documentation.

10 files changed, 927 insertions, 17 deletions

diff --git a/src/library/scala/collection/convert/AsJavaConverters.scala b/src/library/scala/collection/convert/AsJavaConverters.scala
new file mode 100644
index 0000000000..0fd98273ec
--- /dev/null
+++ b/src/library/scala/collection/convert/AsJavaConverters.scala
@@ -0,0 +1,274 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2006-2013, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://www.scala-lang.org/           **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+package scala
+package collection
+package convert
+
+import java.{ lang => jl, util => ju }, java.util.{ concurrent => juc }
+
+/** Defines converter methods from Scala to Java collections. */
+trait AsJavaConverters {
+  import Wrappers._
+
+  /**
+   * Converts a Scala Iterator to a Java Iterator.
+   *
+   * The returned Java Iterator is backed by the provided Scala
+   * Iterator and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Iterator was previously obtained from an implicit or
+   * explicit call of `asScalaIterator(java.util.Iterator)` then the original
+   * Java Iterator will be returned.
+   *
+   * @param  it The Iterator to be converted.
+   * @return    A Java Iterator view of the argument.
+   */
+  def asJavaIterator[A](it: Iterator[A]): ju.Iterator[A] = it match {
+    case null                       => null
+    case JIteratorWrapper(wrapped)  => wrapped.asInstanceOf[ju.Iterator[A]]
+    case _                          => IteratorWrapper(it)
+  }
+
+  /**
+   * Converts a Scala Iterator to a Java Enumeration.
+   *
+   * The returned Java Enumeration is backed by the provided Scala
+   * Iterator and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Iterator was previously obtained from an implicit or
+   * explicit call of `enumerationAsScalaIterator(java.util.Enumeration)` then the
+   * original Java Enumeration will be returned.
+   *
+   * @param it The Iterator to be converted.
+   * @return   A Java Enumeration view of the argument.
+   */
+  def asJavaEnumeration[A](it: Iterator[A]): ju.Enumeration[A] = it match {
+    case null                         => null
+    case JEnumerationWrapper(wrapped) => wrapped.asInstanceOf[ju.Enumeration[A]]
+    case _                            => IteratorWrapper(it)
+  }
+
+  /**
+   * Converts a Scala Iterable to a Java Iterable.
+   *
+   * The returned Java Iterable is backed by the provided Scala
+   * Iterable and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Iterable was previously obtained from an implicit or
+   * explicit call of `iterableasScalaIterable(java.lang.Iterable)` then the original
+   * Java Iterable will be returned.
+   *
+   * @param i The Iterable to be converted.
+   * @return A Java Iterable view of the argument.
+   */
+  def asJavaIterable[A](i: Iterable[A]): jl.Iterable[A] = i match {
+    case null                       => null
+    case JIterableWrapper(wrapped)  => wrapped.asInstanceOf[jl.Iterable[A]]
+    case _                          => IterableWrapper(i)
+  }
+
+  /**
+   * Converts a Scala Iterable to an immutable Java Collection.
+   *
+   * If the Scala Iterable was previously obtained from an implicit or
+   * explicit call of `collectionAsScalaIterable(java.util.Collection)` then the original
+   * Java Collection will be returned.
+   *
+   * @param it The SizedIterable to be converted.
+   * @return   A Java Collection view of the argument.
+   */
+  def asJavaCollection[A](it: Iterable[A]): ju.Collection[A] = it match {
+    case null                         => null
+    case JCollectionWrapper(wrapped)  => wrapped.asInstanceOf[ju.Collection[A]]
+    case _                            => new IterableWrapper(it)
+  }
+
+  /**
+   * Converts a Scala mutable Buffer to a Java List.
+   *
+   * The returned Java List is backed by the provided Scala
+   * Buffer and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Buffer was previously obtained from an implicit or
+   * explicit call of `asScalaBuffer(java.util.List)` then the original
+   * Java List will be returned.
+   *
+   * @param b The Buffer to be converted.
+   * @return A Java List view of the argument.
+   */
+  def bufferAsJavaList[A](b: mutable.Buffer[A]): ju.List[A] = b match {
+    case null                   => null
+    case JListWrapper(wrapped)  => wrapped
+    case _                      => new MutableBufferWrapper(b)
+  }
+
+  /**
+   * Converts a Scala mutable Seq to a Java List.
+   *
+   * The returned Java List is backed by the provided Scala
+   * Seq and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Seq was previously obtained from an implicit or
+   * explicit call of `asScalaBuffer(java.util.List)` then the original
+   * Java List will be returned.
+   *
+   * @param seq The Seq to be converted.
+   * @return    A Java List view of the argument.
+   */
+  def mutableSeqAsJavaList[A](seq: mutable.Seq[A]): ju.List[A] = seq match {
+    case null                   => null
+    case JListWrapper(wrapped)  => wrapped
+    case _                      => new MutableSeqWrapper(seq)
+  }
+
+  /**
+   * Converts a Scala Seq to a Java List.
+   *
+   * The returned Java List is backed by the provided Scala
+   * Seq and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Seq was previously obtained from an implicit or
+   * explicit call of `asScalaBuffer(java.util.List)` then the original
+   * Java List will be returned.
+   *
+   * @param seq The Seq to be converted.
+   * @return    A Java List view of the argument.
+   */
+  def seqAsJavaList[A](seq: Seq[A]): ju.List[A] = seq match {
+    case null                   => null
+    case JListWrapper(wrapped)  => wrapped.asInstanceOf[ju.List[A]]
+    case _                      => new SeqWrapper(seq)
+  }
+
+  /**
+   * Converts a Scala mutable Set to a Java Set.
+   *
+   * The returned Java Set is backed by the provided Scala
+   * Set and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Set was previously obtained from an implicit or
+   * explicit call of `asSet(java.util.Set)` then the original
+   * Java Set will be returned.
+   *
+   * @param s The Set to be converted.
+   * @return A Java Set view of the argument.
+   */
+  def mutableSetAsJavaSet[A](s: mutable.Set[A]): ju.Set[A] = s match {
+    case null                 => null
+    case JSetWrapper(wrapped) => wrapped
+    case _                    => new MutableSetWrapper(s)
+  }
+
+  /**
+   * Converts a Scala Set to a Java Set.
+   *
+   * The returned Java Set is backed by the provided Scala
+   * Set and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Set was previously obtained from an implicit or
+   * explicit call of `asScalaSet(java.util.Set)` then the original
+   * Java Set will be returned.
+   *
+   * @param s The Set to be converted.
+   * @return A Java Set view of the argument.
+   */
+  def setAsJavaSet[A](s: Set[A]): ju.Set[A] = s match {
+    case null                 => null
+    case JSetWrapper(wrapped) => wrapped
+    case _                    => new SetWrapper(s)
+  }
+
+  /**
+   * Converts a Scala mutable Map to a Java Map.
+   *
+   * The returned Java Map is backed by the provided Scala
+   * Map and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Map was previously obtained from an implicit or
+   * explicit call of `mapAsScalaMap(java.util.Map)` then the original
+   * Java Map will be returned.
+   *
+   * @param m The Map to be converted.
+   * @return A Java Map view of the argument.
+   */
+  def mutableMapAsJavaMap[A, B](m: mutable.Map[A, B]): ju.Map[A, B] = m match {
+    case null                 => null
+    case JMapWrapper(wrapped) => wrapped
+    case _                    => new MutableMapWrapper(m)
+  }
+
+  /**
+   * Converts a Scala mutable `Map` to a Java `Dictionary`.
+   *
+   * The returned Java `Dictionary` is backed by the provided Scala
+   * `Dictionary` and any side-effects of using it via the Java interface
+   * will be visible via the Scala interface and vice versa.
+   *
+   * If the Scala `Dictionary` was previously obtained from an implicit or
+   * explicit call of `dictionaryAsScalaMap(java.util.Dictionary)` then the original
+   * Java Dictionary will be returned.
+   *
+   * @param m The `Map` to be converted.
+   * @return A Java `Dictionary` view of the argument.
+   */
+  def asJavaDictionary[A, B](m: mutable.Map[A, B]): ju.Dictionary[A, B] = m match {
+    case null                         => null
+    case JDictionaryWrapper(wrapped)  => wrapped
+    case _                            => new DictionaryWrapper(m)
+  }
+
+  /**
+   * Converts a Scala `Map` to a Java `Map`.
+   *
+   * The returned Java `Map` is backed by the provided Scala `Map` and
+   * any side-effects of using it via the Java interface will be visible
+   * via the Scala interface and vice versa.
+   *
+   * If the Scala `Map` was previously obtained from an implicit or
+   * explicit call of `mapAsScalaMap(java.util.Map)` then the original
+   * Java `Map` will be returned.
+   *
+   * @param m The `Map` to be converted.
+   * @return A Java `Map` view of the argument.
+   */
+  def mapAsJavaMap[A, B](m: Map[A, B]): ju.Map[A, B] = m match {
+    case null                 => null
+    case JMapWrapper(wrapped) => wrapped.asInstanceOf[ju.Map[A, B]]
+    case _                    => new MapWrapper(m)
+  }
+
+  /**
+   * Converts a Scala mutable `concurrent.Map` to a Java `ConcurrentMap`.
+   *
+   * The returned Java `ConcurrentMap` is backed by the provided Scala
+   * `concurrent.Map` and any side-effects of using it via the Java interface
+   * will be visible via the Scala interface and vice versa.
+   *
+   * If the Scala `concurrent.Map` was previously obtained from an implicit or
+   * explicit call of `mapAsScalaConcurrentMap(java.util.concurrent.ConcurrentMap)`
+   * then the original Java ConcurrentMap will be returned.
+   *
+   * @param m The Scala `concurrent.Map` to be converted.
+   * @return A Java `ConcurrentMap` view of the argument.
+   */
+  def mapAsJavaConcurrentMap[A, B](m: concurrent.Map[A, B]): juc.ConcurrentMap[A, B] = m match {
+    case null                           => null
+    case JConcurrentMapWrapper(wrapped) => wrapped
+    case _                              => new ConcurrentMapWrapper(m)
+  }
+}
diff --git a/src/library/scala/collection/convert/AsScalaConverters.scala b/src/library/scala/collection/convert/AsScalaConverters.scala
new file mode 100644
index 0000000000..413292fbfc
--- /dev/null
+++ b/src/library/scala/collection/convert/AsScalaConverters.scala
@@ -0,0 +1,215 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2006-2013, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://www.scala-lang.org/           **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+package scala
+package collection
+package convert
+
+import java.{ lang => jl, util => ju }, java.util.{ concurrent => juc }
+
+/** Defines converter methods from Java to Scala collections. */
+trait AsScalaConverters {
+  import Wrappers._
+
+  /**
+   * Converts a Java `Iterator` to a Scala `Iterator`.
+   *
+   * The returned Scala `Iterator` is backed by the provided Java `Iterator`
+   * and any side-effects of using it via the Scala interface will be visible
+   * via the Java interface and vice versa.
+   *
+   * If the Java `Iterator` was previously obtained from an implicit or
+   * explicit call of `asJavaIterator(scala.collection.Iterator)` then the
+   * original Scala `Iterator` will be returned.
+   *
+   * @param it The `Iterator` to be converted.
+   * @return   A Scala `Iterator` view of the argument.
+   */
+  def asScalaIterator[A](it: ju.Iterator[A]): Iterator[A] = it match {
+    case null                     => null
+    case IteratorWrapper(wrapped) => wrapped
+    case _                        => JIteratorWrapper(it)
+  }
+
+  /**
+   * Converts a Java Enumeration to a Scala Iterator.
+   *
+   * The returned Scala Iterator is backed by the provided Java
+   * Enumeration and any side-effects of using it via the Scala interface will
+   * be visible via the Java interface and vice versa.
+   *
+   * If the Java Enumeration was previously obtained from an implicit or
+   * explicit call of `asJavaEnumeration(scala.collection.Iterator)`
+   * then the original Scala Iterator will be returned.
+   *
+   * @param i The Enumeration to be converted.
+   * @return A Scala Iterator view of the argument.
+   */
+  def enumerationAsScalaIterator[A](i: ju.Enumeration[A]): Iterator[A] = i match {
+    case null                     => null
+    case IteratorWrapper(wrapped) => wrapped
+    case _                        => JEnumerationWrapper(i)
+  }
+
+  /**
+   * Converts a Java `Iterable` to a Scala `Iterable`.
+   *
+   * The returned Scala `Iterable` is backed by the provided Java `Iterable`
+   * and any side-effects of using it via the Scala interface will be visible
+   * via the Java interface and vice versa.
+   *
+   * If the Java `Iterable` was previously obtained from an implicit or
+   * explicit call of `asJavaIterable(scala.collection.Iterable)`
+   * then the original Scala Iterable will be returned.
+   *
+   * @param i The Iterable to be converted.
+   * @return A Scala Iterable view of the argument.
+   */
+  def iterableAsScalaIterable[A](i: jl.Iterable[A]): Iterable[A] = i match {
+    case null                     => null
+    case IterableWrapper(wrapped) => wrapped
+    case _                        => JIterableWrapper(i)
+  }
+
+  /**
+   * Converts a Java `Collection` to an Scala `Iterable`.
+   *
+   * If the Java `Collection` was previously obtained from an implicit or
+   * explicit call of `asJavaCollection(scala.collection.Iterable)`
+   * then the original Scala `Iterable` will be returned.
+   *
+   * @param i The Collection to be converted.
+   * @return A Scala Iterable view of the argument.
+   */
+  def collectionAsScalaIterable[A](i: ju.Collection[A]): Iterable[A] = i match {
+    case null                     => null
+    case IterableWrapper(wrapped) => wrapped
+    case _                        => JCollectionWrapper(i)
+  }
+
+  /**
+   * Converts a Java `List` to a Scala mutable `Buffer`.
+   *
+   * The returned Scala `Buffer` is backed by the provided Java `List`
+   * and any side-effects of using it via the Scala interface will
+   * be visible via the Java interface and vice versa.
+   *
+   * If the Java `List` was previously obtained from an implicit or
+   * explicit call of `bufferAsJavaList(scala.collection.mutable.Buffer)`
+   * then the original Scala `Buffer` will be returned.
+   *
+   * @param l The `List` to be converted.
+   * @return A Scala mutable `Buffer` view of the argument.
+   */
+  def asScalaBuffer[A](l: ju.List[A]): mutable.Buffer[A] = l match {
+    case null                           => null
+    case MutableBufferWrapper(wrapped)  => wrapped
+    case _                              => new JListWrapper(l)
+  }
+
+  /**
+   * Converts a Java Set to a Scala mutable Set.
+   *
+   * The returned Scala Set is backed by the provided Java
+   * Set and any side-effects of using it via the Scala interface will
+   * be visible via the Java interface and vice versa.
+   *
+   * If the Java Set was previously obtained from an implicit or
+   * explicit call of `mutableSetAsJavaSet(scala.collection.mutable.Set)` then
+   * the original Scala Set will be returned.
+   *
+   * @param s The Set to be converted.
+   * @return A Scala mutable Set view of the argument.
+   */
+  def asScalaSet[A](s: ju.Set[A]): mutable.Set[A] = s match {
+    case null                       => null
+    case MutableSetWrapper(wrapped) => wrapped
+    case _                          => new JSetWrapper(s)
+  }
+
+  /**
+   * Converts a Java `Map` to a Scala mutable `Map`.
+   *
+   * The returned Scala `Map` is backed by the provided Java `Map` and any
+   * side-effects of using it via the Scala interface will be visible via
+   * the Java interface and vice versa.
+   *
+   * If the Java `Map` was previously obtained from an implicit or
+   * explicit call of `mutableMapAsJavaMap(scala.collection.mutable.Map)` then
+   * the original Scala Map will be returned.
+   *
+   * If the wrapped map is synchronized (e.g. from `java.util.Collections.synchronizedMap`),
+   * it is your responsibility to wrap all
+   * non-atomic operations with `underlying.synchronized`.
+   * This includes `get`, as `java.util.Map`'s API does not allow for an
+   * atomic `get` when `null` values may be present.
+   *
+   * @param m The Map to be converted.
+   * @return A Scala mutable Map view of the argument.
+   */
+  def mapAsScalaMap[A, B](m: ju.Map[A, B]): mutable.Map[A, B] = m match {
+    case null                       => null
+    case MutableMapWrapper(wrapped) => wrapped
+    case _                          => new JMapWrapper(m)
+  }
+
+  /**
+   * Converts a Java ConcurrentMap to a Scala mutable ConcurrentMap.
+   *
+   * The returned Scala ConcurrentMap is backed by the provided Java
+   * ConcurrentMap and any side-effects of using it via the Scala interface will
+   * be visible via the Java interface and vice versa.
+   *
+   * If the Java ConcurrentMap was previously obtained from an implicit or
+   * explicit call of `mapAsJavaConcurrentMap(scala.collection.mutable.ConcurrentMap)`
+   * then the original Scala ConcurrentMap will be returned.
+   *
+   * @param m The ConcurrentMap to be converted.
+   * @return A Scala mutable ConcurrentMap view of the argument.
+   */
+  def mapAsScalaConcurrentMap[A, B](m: juc.ConcurrentMap[A, B]): concurrent.Map[A, B] = m match {
+    case null                             => null
+    case cmw: ConcurrentMapWrapper[_, _]  => cmw.underlying
+    case _                                => new JConcurrentMapWrapper(m)
+  }
+
+  /**
+   * Converts a Java `Dictionary` to a Scala mutable `Map`.
+   *
+   * The returned Scala `Map` is backed by the provided Java
+   * `Dictionary` and any side-effects of using it via the Scala interface
+   * will be visible via the Java interface and vice versa.
+   *
+   * If the Java `Dictionary` was previously obtained from an implicit or
+   * explicit call of `asJavaDictionary(scala.collection.mutable.Map)` then the original
+   * Scala Map will be returned.
+   *
+   * @param p The Dictionary to be converted.
+   * @return  A Scala mutable Map view of the argument.
+   */
+  def dictionaryAsScalaMap[A, B](p: ju.Dictionary[A, B]): mutable.Map[A, B] = p match {
+    case null                       => null
+    case DictionaryWrapper(wrapped) => wrapped
+    case _                          => new JDictionaryWrapper(p)
+  }
+
+  /**
+   * Converts a Java `Properties` to a Scala `mutable Map[String, String]`.
+   *
+   * The returned Scala `Map[String, String]` is backed by the provided Java
+   * `Properties` and any side-effects of using it via the Scala interface
+   * will be visible via the Java interface and vice versa.
+   *
+   * @param p The Properties to be converted.
+   * @return  A Scala mutable Map[String, String] view of the argument.
+   */
+  def propertiesAsScalaMap(p: ju.Properties): mutable.Map[String, String] = p match {
+    case null => null
+    case _    => new JPropertiesWrapper(p)
+  }
+}
diff --git a/src/library/scala/collection/convert/DecorateAsJava.scala b/src/library/scala/collection/convert/DecorateAsJava.scala
index 0ed67a86d7..6088bce63f 100644
--- a/src/library/scala/collection/convert/DecorateAsJava.scala
+++ b/src/library/scala/collection/convert/DecorateAsJava.scala
@@ -12,10 +12,8 @@ package convert
 
 import java.{ lang => jl, util => ju }, java.util.{ concurrent => juc }
 import Decorators._
-import WrapAsJava._
 import scala.language.implicitConversions
 
-
 /** A collection of decorators that allow converting between
  *  Scala and Java collections using `asScala` and `asJava` methods.
  *
@@ -57,9 +55,10 @@ import scala.language.implicitConversions
  *{{{
  *    java.util.Properties => scala.collection.mutable.Map
  *}}}
+ *
  *  @since  2.8.1
  */
-trait DecorateAsJava {
+trait DecorateAsJava extends AsJavaConverters {
   /**
    * Adds an `asJava` method that implicitly converts a Scala `Iterator` to a
    * Java `Iterator`. The returned Java `Iterator` is backed by the provided Scala
diff --git a/src/library/scala/collection/convert/DecorateAsScala.scala b/src/library/scala/collection/convert/DecorateAsScala.scala
index 5448f5f91c..cbd37fa504 100644
--- a/src/library/scala/collection/convert/DecorateAsScala.scala
+++ b/src/library/scala/collection/convert/DecorateAsScala.scala
@@ -12,10 +12,9 @@ package convert
 
 import java.{ lang => jl, util => ju }, java.util.{ concurrent => juc }
 import Decorators._
-import WrapAsScala._
 import scala.language.implicitConversions
 
-trait DecorateAsScala {
+trait DecorateAsScala extends AsScalaConverters {
   /**
    * Adds an `asScala` method that implicitly converts a Java `Iterator` to
    * a Scala `Iterator`.
diff --git a/src/library/scala/collection/convert/Decorators.scala b/src/library/scala/collection/convert/Decorators.scala
index d232fa04e1..3e45a02254 100644
--- a/src/library/scala/collection/convert/Decorators.scala
+++ b/src/library/scala/collection/convert/Decorators.scala
@@ -12,7 +12,7 @@ package convert
 
 import java.{ util => ju }
 
-private[collection] trait Decorators {
+private[collection] object Decorators {
   /** Generic class containing the `asJava` converter method */
   class AsJava[A](op: => A) {
     /** Converts a Scala collection to the corresponding Java collection */
@@ -28,20 +28,18 @@ private[collection] trait Decorators {
   /** Generic class containing the `asJavaCollection` converter method */
   class AsJavaCollection[A](i: Iterable[A]) {
     /** Converts a Scala `Iterable` to a Java `Collection` */
-    def asJavaCollection: ju.Collection[A] = JavaConversions.asJavaCollection(i)
+    def asJavaCollection: ju.Collection[A] = JavaConverters.asJavaCollection(i)
   }
 
   /** Generic class containing the `asJavaEnumeration` converter method */
   class AsJavaEnumeration[A](i: Iterator[A]) {
     /** Converts a Scala `Iterator` to a Java `Enumeration` */
-    def asJavaEnumeration: ju.Enumeration[A] = JavaConversions.asJavaEnumeration(i)
+    def asJavaEnumeration: ju.Enumeration[A] = JavaConverters.asJavaEnumeration(i)
   }
 
   /** Generic class containing the `asJavaDictionary` converter method */
   class AsJavaDictionary[A, B](m : mutable.Map[A, B]) {
     /** Converts a Scala `Map` to a Java `Dictionary` */
-    def asJavaDictionary: ju.Dictionary[A, B] = JavaConversions.asJavaDictionary(m)
+    def asJavaDictionary: ju.Dictionary[A, B] = JavaConverters.asJavaDictionary(m)
   }
 }
-
-private[collection] object Decorators extends Decorators
diff --git a/src/library/scala/collection/convert/ImplicitConversions.scala b/src/library/scala/collection/convert/ImplicitConversions.scala
new file mode 100644
index 0000000000..2ddb16ec56
--- /dev/null
+++ b/src/library/scala/collection/convert/ImplicitConversions.scala
@@ -0,0 +1,407 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2006-2016, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://www.scala-lang.org/           **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+package scala
+package collection
+package convert
+
+import java.{ lang => jl, util => ju }, java.util.{ concurrent => juc }
+import scala.language.implicitConversions
+
+import JavaConverters._
+
+/** Defines implicit converter methods from Java to Scala collections. */
+trait ToScalaImplicits {
+
+  /**
+   * Implicitly converts a Java `Iterator` to a Scala `Iterator`.
+   *
+   * The returned Scala `Iterator` is backed by the provided Java `Iterator`
+   * and any side-effects of using it via the Scala interface will be visible
+   * via the Java interface and vice versa.
+   *
+   * If the Java `Iterator` was previously obtained from an implicit or
+   * explicit call of `asIterator(scala.collection.Iterator)` then the
+   * original Scala `Iterator` will be returned.
+   *
+   * @param it The `Iterator` to be converted.
+   * @return   A Scala `Iterator` view of the argument.
+   */
+  implicit def `iterator asScala`[A](it: ju.Iterator[A]): Iterator[A] = asScalaIterator(it)
+
+  /**
+   * Implicitly converts a Java Enumeration to a Scala Iterator.
+   * The returned Scala Iterator is backed by the provided Java
+   * Enumeration and any side-effects of using it via the Scala interface will
+   * be visible via the Java interface and vice versa.
+   *
+   * If the Java Enumeration was previously obtained from an implicit or
+   * explicit call of `enumerationAsScalaIterator(scala.collection.Iterator)`
+   * then the original Scala Iterator will be returned.
+   *
+   * @param i The Enumeration to be converted.
+   * @return A Scala Iterator view of the argument.
+   */
+  implicit def `enumeration AsScalaIterator`[A](i: ju.Enumeration[A]): Iterator[A] = enumerationAsScalaIterator(i)
+
+  /**
+   * Implicitly converts a Java `Iterable` to a Scala `Iterable`.
+   *
+   * The returned Scala `Iterable` is backed by the provided Java `Iterable`
+   * and any side-effects of using it via the Scala interface will be visible
+   * via the Java interface and vice versa.
+   *
+   * If the Java `Iterable` was previously obtained from an implicit or
+   * explicit call of `iterableAsScalaIterable(scala.collection.Iterable)`
+   * then the original Scala Iterable will be returned.
+   *
+   * @param i The Iterable to be converted.
+   * @return A Scala Iterable view of the argument.
+   */
+  implicit def `iterable AsScalaIterable`[A](i: jl.Iterable[A]): Iterable[A] = iterableAsScalaIterable(i)
+
+  /**
+   * Implicitly converts a Java `Collection` to an Scala `Iterable`.
+   *
+   * If the Java `Collection` was previously obtained from an implicit or
+   * explicit call of `collectionAsScalaIterable(scala.collection.SizedIterable)`
+   * then the original Scala `Iterable` will be returned.
+   *
+   * @param i The Collection to be converted.
+   * @return A Scala Iterable view of the argument.
+   */
+  implicit def `collection AsScalaIterable`[A](i: ju.Collection[A]): Iterable[A] = collectionAsScalaIterable(i)
+
+  /**
+   * Implicitly converts a Java `List` to a Scala mutable `Buffer`.
+   *
+   * The returned Scala `Buffer` is backed by the provided Java `List`
+   * and any side-effects of using it via the Scala interface will
+   * be visible via the Java interface and vice versa.
+   *
+   * If the Java `List` was previously obtained from an implicit or
+   * explicit call of `asScalaBuffer(scala.collection.mutable.Buffer)`
+   * then the original Scala `Buffer` will be returned.
+   *
+   * @param l The `List` to be converted.
+   * @return A Scala mutable `Buffer` view of the argument.
+   */
+  implicit def `list asScalaBuffer`[A](l: ju.List[A]): mutable.Buffer[A] = asScalaBuffer(l)
+
+  /**
+   * Implicitly converts a Java Set to a Scala mutable Set.
+   * The returned Scala Set is backed by the provided Java
+   * Set and any side-effects of using it via the Scala interface will
+   * be visible via the Java interface and vice versa.
+   *
+   * If the Java Set was previously obtained from an implicit or
+   * explicit call of `asScalaSet(scala.collection.mutable.Set)` then
+   * the original Scala Set will be returned.
+   *
+   * @param s The Set to be converted.
+   * @return A Scala mutable Set view of the argument.
+   */
+  implicit def `set asScala`[A](s: ju.Set[A]): mutable.Set[A] = asScalaSet(s)
+
+  /**
+   * Implicitly converts a Java `Map` to a Scala mutable `Map`.
+   *
+   * The returned Scala `Map` is backed by the provided Java `Map` and any
+   * side-effects of using it via the Scala interface will be visible via
+   * the Java interface and vice versa.
+   *
+   * If the Java `Map` was previously obtained from an implicit or
+   * explicit call of `mapAsScalaMap(scala.collection.mutable.Map)` then
+   * the original Scala Map will be returned.
+   *
+   * If the wrapped map is synchronized (e.g. from `java.util.Collections.synchronizedMap`),
+   * it is your responsibility to wrap all
+   * non-atomic operations with `underlying.synchronized`.
+   * This includes `get`, as `java.util.Map`'s API does not allow for an
+   * atomic `get` when `null` values may be present.
+   *
+   * @param m The Map to be converted.
+   * @return A Scala mutable Map view of the argument.
+   */
+  implicit def `map AsScala`[A, B](m: ju.Map[A, B]): mutable.Map[A, B] = mapAsScalaMap(m)
+
+  /**
+   * Implicitly converts a Java ConcurrentMap to a Scala mutable ConcurrentMap.
+   * The returned Scala ConcurrentMap is backed by the provided Java
+   * ConcurrentMap and any side-effects of using it via the Scala interface will
+   * be visible via the Java interface and vice versa.
+   *
+   * If the Java ConcurrentMap was previously obtained from an implicit or
+   * explicit call of `asConcurrentMap(scala.collection.mutable.ConcurrentMap)`
+   * then the original Scala ConcurrentMap will be returned.
+   *
+   * @param m The ConcurrentMap to be converted.
+   * @return A Scala mutable ConcurrentMap view of the argument.
+   */
+  implicit def `map AsScalaConcurrentMap`[A, B](m: juc.ConcurrentMap[A, B]): concurrent.Map[A, B] = mapAsScalaConcurrentMap(m)
+
+  /**
+   * Implicitly converts a Java `Dictionary` to a Scala mutable
+   * `Map`.
+   *
+   * The returned Scala `Map` is backed by the provided Java
+   * `Dictionary` and any side-effects of using it via the Scala interface
+   * will be visible via the Java interface and vice versa.
+   *
+   * @param p The Dictionary to be converted.
+   * @return  A Scala mutable Map view of the argument.
+   */
+  implicit def `dictionary AsScalaMap`[A, B](p: ju.Dictionary[A, B]): mutable.Map[A, B] = dictionaryAsScalaMap(p)
+
+  /**
+   * Implicitly converts a Java `Properties` to a Scala `mutable Map[String, String]`.
+   *
+   * The returned Scala `Map[String, String]` is backed by the provided Java
+   * `Properties` and any side-effects of using it via the Scala interface
+   * will be visible via the Java interface and vice versa.
+   *
+   * @param p The Properties to be converted.
+   * @return  A Scala mutable Map[String, String] view of the argument.
+   */
+  implicit def `properties AsScalaMap`(p: ju.Properties): mutable.Map[String, String] = propertiesAsScalaMap(p)
+}
+
+/** Defines implicit conversions from Scala to Java collections. */
+trait ToJavaImplicits {
+
+  /**
+   * Implicitly converts a Scala Iterator to a Java Iterator.
+   * The returned Java Iterator is backed by the provided Scala
+   * Iterator and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Iterator was previously obtained from an implicit or
+   * explicit call of `asIterator(java.util.Iterator)` then the original
+   * Java Iterator will be returned.
+   *
+   * @param  it The Iterator to be converted.
+   * @return    A Java Iterator view of the argument.
+   */
+  implicit def `iterator asJava`[A](it: Iterator[A]): ju.Iterator[A] = asJavaIterator(it)
+
+  /**
+   * Implicitly converts a Scala Iterator to a Java Enumeration.
+   * The returned Java Enumeration is backed by the provided Scala
+   * Iterator and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Iterator was previously obtained from an implicit or
+   * explicit call of `asIterator(java.util.Enumeration)` then the
+   * original Java Enumeration will be returned.
+   *
+   * @param it The Iterator to be converted.
+   * @return   A Java Enumeration view of the argument.
+   */
+  implicit def `enumeration asJava`[A](it: Iterator[A]): ju.Enumeration[A] = asJavaEnumeration(it)
+
+  /**
+   * Implicitly converts a Scala Iterable to a Java Iterable.
+   * The returned Java Iterable is backed by the provided Scala
+   * Iterable and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Iterable was previously obtained from an implicit or
+   * explicit call of `asIterable(java.lang.Iterable)` then the original
+   * Java Iterable will be returned.
+   *
+   * @param i The Iterable to be converted.
+   * @return A Java Iterable view of the argument.
+   */
+  implicit def `iterable asJava`[A](i: Iterable[A]): jl.Iterable[A] = asJavaIterable(i)
+
+  /**
+   * Implicitly converts a Scala Iterable to an immutable Java
+   * Collection.
+   *
+   * If the Scala Iterable was previously obtained from an implicit or
+   * explicit call of `asSizedIterable(java.util.Collection)` then the original
+   * Java Collection will be returned.
+   *
+   * @param it The SizedIterable to be converted.
+   * @return   A Java Collection view of the argument.
+   */
+  implicit def `collection asJava`[A](it: Iterable[A]): ju.Collection[A] = asJavaCollection(it)
+
+  /**
+   * Implicitly converts a Scala mutable Buffer to a Java List.
+   * The returned Java List is backed by the provided Scala
+   * Buffer and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Buffer was previously obtained from an implicit or
+   * explicit call of `asBuffer(java.util.List)` then the original
+   * Java List will be returned.
+   *
+   * @param b The Buffer to be converted.
+   * @return A Java List view of the argument.
+   */
+  implicit def `buffer AsJavaList`[A](b: mutable.Buffer[A]): ju.List[A] = bufferAsJavaList(b)
+
+  /**
+   * Implicitly converts a Scala mutable Seq to a Java List.
+   * The returned Java List is backed by the provided Scala
+   * Seq and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Seq was previously obtained from an implicit or
+   * explicit call of `asSeq(java.util.List)` then the original
+   * Java List will be returned.
+   *
+   * @param seq The Seq to be converted.
+   * @return    A Java List view of the argument.
+   */
+  implicit def `mutableSeq AsJavaList`[A](seq: mutable.Seq[A]): ju.List[A] = mutableSeqAsJavaList(seq)
+
+  /**
+   * Implicitly converts a Scala Seq to a Java List.
+   * The returned Java List is backed by the provided Scala
+   * Seq and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Seq was previously obtained from an implicit or
+   * explicit call of `asSeq(java.util.List)` then the original
+   * Java List will be returned.
+   *
+   * @param seq The Seq to be converted.
+   * @return    A Java List view of the argument.
+   */
+  implicit def `seq AsJavaList`[A](seq: Seq[A]): ju.List[A] = seqAsJavaList(seq)
+
+  /**
+   * Implicitly converts a Scala mutable Set to a Java Set.
+   * The returned Java Set is backed by the provided Scala
+   * Set and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Set was previously obtained from an implicit or
+   * explicit call of `asSet(java.util.Set)` then the original
+   * Java Set will be returned.
+   *
+   * @param s The Set to be converted.
+   * @return A Java Set view of the argument.
+   */
+  implicit def `mutableSet AsJavaSet`[A](s: mutable.Set[A]): ju.Set[A] = mutableSetAsJavaSet(s)
+
+  /**
+   * Implicitly converts a Scala Set to a Java Set.
+   * The returned Java Set is backed by the provided Scala
+   * Set and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Set was previously obtained from an implicit or
+   * explicit call of asSet(java.util.Set) then the original
+   * Java Set will be returned.
+   *
+   * @param s The Set to be converted.
+   * @return A Java Set view of the argument.
+   */
+  implicit def `set AsJavaSet`[A](s: Set[A]): ju.Set[A] = setAsJavaSet(s)
+
+  /**
+   * Implicitly converts a Scala mutable Map to a Java Map.
+   * The returned Java Map is backed by the provided Scala
+   * Map and any side-effects of using it via the Java interface will
+   * be visible via the Scala interface and vice versa.
+   *
+   * If the Scala Map was previously obtained from an implicit or
+   * explicit call of `asMap(java.util.Map)` then the original
+   * Java Map will be returned.
+   *
+   * @param m The Map to be converted.
+   * @return A Java Map view of the argument.
+   */
+  implicit def `mutableMap AsJavaMap`[A, B](m: mutable.Map[A, B]): ju.Map[A, B] = mutableMapAsJavaMap(m)
+
+  /**
+   * Implicitly converts a Scala mutable `Map` to a Java `Dictionary`.
+   *
+   * The returned Java `Dictionary` is backed by the provided Scala
+   * `Dictionary` and any side-effects of using it via the Java interface
+   * will be visible via the Scala interface and vice versa.
+   *
+   * If the Scala `Dictionary` was previously obtained from an implicit or
+   * explicit call of `asMap(java.util.Dictionary)` then the original
+   * Java Dictionary will be returned.
+   *
+   * @param m The `Map` to be converted.
+   * @return A Java `Dictionary` view of the argument.
+   */
+  implicit def `dictionary asJava`[A, B](m: mutable.Map[A, B]): ju.Dictionary[A, B] = asJavaDictionary(m)
+
+  /**
+   * Implicitly converts a Scala `Map` to a Java `Map`.
+   *
+   * The returned Java `Map` is backed by the provided Scala `Map` and
+   * any side-effects of using it via the Java interface will be visible
+   * via the Scala interface and vice versa.
+   *
+   * If the Scala `Map` was previously obtained from an implicit or
+   * explicit call of `asMap(java.util.Map)` then the original
+   * Java `Map` will be returned.
+   *
+   * @param m The `Map` to be converted.
+   * @return A Java `Map` view of the argument.
+   */
+  implicit def `map AsJavaMap`[A, B](m: Map[A, B]): ju.Map[A, B] = mapAsJavaMap(m)
+
+  /**
+   * Implicitly converts a Scala mutable `concurrent.Map` to a Java
+   * `ConcurrentMap`.
+   *
+   * The returned Java `ConcurrentMap` is backed by the provided Scala
+   * `concurrent.Map` and any side-effects of using it via the Java interface
+   * will be visible via the Scala interface and vice versa.
+   *
+   * If the Scala `concurrent.Map` was previously obtained from an implicit or
+   * explicit call of `mapAsScalaConcurrentMap(java.util.concurrent.ConcurrentMap)`
+   * then the original Java ConcurrentMap will be returned.
+   *
+   * @param m The Scala `concurrent.Map` to be converted.
+   * @return A Java `ConcurrentMap` view of the argument.
+   */
+  implicit def `map AsJavaConcurrentMap`[A, B](m: concurrent.Map[A, B]): juc.ConcurrentMap[A, B] = mapAsJavaConcurrentMap(m)
+}
+
+/**
+ * Convenience for miscellaneous implicit conversions from Scala to Java collections API.
+ *
+ * It is recommended to use explicit conversions provided by [[collection.JavaConverters]] instead.
+ * Implicit conversions may cause unexpected issues, see [[ImplicitConversions]].
+ */
+object ImplicitConversionsToJava extends ToJavaImplicits
+
+/**
+ * Convenience for miscellaneous implicit conversions from Java to Scala collections API.
+ *
+ * It is recommended to use explicit conversions provided by [[collection.JavaConverters]] instead.
+ * Implicit conversions may cause unexpected issues, see [[ImplicitConversions]].
+ */
+object ImplicitConversionsToScala extends ToScalaImplicits
+
+/**
+ * Convenience for miscellaneous implicit conversions between Java and Scala collections API.
+ *
+ * It is recommended to use explicit conversions provided by [[collection.JavaConverters]] instead.
+ * Implicit conversions may cause unexpected issues. Example:
+ *
+ * {{{
+ *   import collection.convert.ImplicitConversions._
+ *   case class StringBox(s: String)
+ *   val m = Map(StringBox("one") -> "uno")
+ *   m.get("one")
+ * }}}
+ *
+ * The above example returns `null` instead of producing a type error at compile-time. The map is
+ * implicitly converted to a `java.util.Map` which provides a method `get(x: AnyRef)`.
+ */
+object ImplicitConversions extends ToScalaImplicits with ToJavaImplicits
diff --git a/src/library/scala/collection/convert/WrapAsJava.scala b/src/library/scala/collection/convert/WrapAsJava.scala
index e97a2ff1fc..5a08f21eaa 100644
--- a/src/library/scala/collection/convert/WrapAsJava.scala
+++ b/src/library/scala/collection/convert/WrapAsJava.scala
@@ -13,6 +13,7 @@ package convert
 import java.{ lang => jl, util => ju }, java.util.{ concurrent => juc }
 import scala.language.implicitConversions
 
+@deprecated("Use JavaConverters or consider ToJavaImplicits", since="2.12")
 trait WrapAsJava {
   import Wrappers._
 
@@ -266,4 +267,5 @@ trait WrapAsJava {
   }
 }
 
-object WrapAsJava extends WrapAsJava { }
+@deprecated("Use JavaConverters or consider ImplicitConversionsToJava", since="2.12")
+object WrapAsJava extends WrapAsJava
diff --git a/src/library/scala/collection/convert/WrapAsScala.scala b/src/library/scala/collection/convert/WrapAsScala.scala
index ee161dcc87..8b7aee909c 100644
--- a/src/library/scala/collection/convert/WrapAsScala.scala
+++ b/src/library/scala/collection/convert/WrapAsScala.scala
@@ -13,6 +13,7 @@ package convert
 import java.{ lang => jl, util => ju }, java.util.{ concurrent => juc }
 import scala.language.implicitConversions
 
+@deprecated("Use JavaConverters or consider ToScalaImplicits", since="2.12")
 trait WrapAsScala {
   import Wrappers._
   /**
@@ -207,4 +208,5 @@ trait WrapAsScala {
   }
 }
 
-object WrapAsScala extends WrapAsScala { }
+@deprecated("Use JavaConverters or consider ImplicitConversionsToScala", since="2.12")
+object WrapAsScala extends WrapAsScala
diff --git a/src/library/scala/collection/convert/Wrappers.scala b/src/library/scala/collection/convert/Wrappers.scala
index 3edc5ba1b4..7fd105c24a 100644
--- a/src/library/scala/collection/convert/Wrappers.scala
+++ b/src/library/scala/collection/convert/Wrappers.scala
@@ -14,9 +14,16 @@ import java.{ lang => jl, util => ju }, java.util.{ concurrent => juc }
 import WrapAsScala._
 import WrapAsJava._
 
-/** Don't put the implementations in the same scope as the implicits
- *  which utilize them, or they will stow away into every scope which
- *  extends one of those implementations.  See SI-5580.
+/** Adapters for Java/Scala collections API.
+ *  
+ *  The implicit scope of these wrappers includes the current
+ *  lexical scope as well as enclosing package scopes, so the
+ *  implicit conversions provided by `AsScalaImplicits` and
+ *  `AsJavaImplicits` must not be installed in those enclosing
+ *  scopes.
+ *  
+ *  In particular, the implicit scope of classes extending these
+ *  wrappers also includes those contexts. See SI-5580.
  */
 private[collection] trait Wrappers {
   trait IterableWrapperTrait[A] extends ju.AbstractCollection[A] {
diff --git a/src/library/scala/collection/convert/package.scala b/src/library/scala/collection/convert/package.scala
index 13970f9a3e..7f48023b58 100644
--- a/src/library/scala/collection/convert/package.scala
+++ b/src/library/scala/collection/convert/package.scala
@@ -10,10 +10,17 @@ package scala
 package collection
 
 package object convert {
+  @deprecated("Use JavaConverters", since="2.12")
   val decorateAsJava  = new DecorateAsJava { }
+  @deprecated("Use JavaConverters", since="2.12")
   val decorateAsScala = new DecorateAsScala { }
-  val decorateAll     = new DecorateAsJava with DecorateAsScala { }
+  @deprecated("Use JavaConverters", since="2.12")
+  val decorateAll     = JavaConverters
+
+  @deprecated("Use JavaConverters or consider ImplicitConversionsToJava", since="2.12")
   val wrapAsJava      = new WrapAsJava { }
+  @deprecated("Use JavaConverters or consider ImplicitConversionsToScala", since="2.12")
   val wrapAsScala     = new WrapAsScala { }
+  @deprecated("Use JavaConverters or consider ImplicitConversions", since="2.12")
   val wrapAll         = new WrapAsJava with WrapAsScala { }
 }