Clean up and fix samples

Author: DougGregor

Samples/JavaProbablyPrime/Package.swift

@@ -26,6 +26,7 @@ let package = Package(
     .executableTarget(
       name: "JavaProbablyPrime",
       dependencies: [
+        .product(name: "JavaKitCollection", package: "swift-java"),
         .product(name: "JavaKit", package: "swift-java"),
         .product(name: "ArgumentParser", package: "swift-argument-parser"),
       ],

Samples/JavaProbablyPrime/README.md

@@ -9,5 +9,4 @@ swift run JavaProbablyPrime <very big number>
 The package itself demonstrates how to:
 
 * Use the Java2Swift build tool plugin to wrap the `java.math.BigInteger` type in Swift.
-* Create a `JavaVirtualMachine` instance in a Swift command-line program.
 * Create an instance of `BigInteger` in Swift and use its `isProbablyPrime`.

Samples/JavaProbablyPrime/Sources/JavaProbablyPrime/prime.swift

@@ -24,10 +24,7 @@ struct ProbablyPrime: ParsableCommand {
   var certainty: Int32 = 10
 
   func run() throws {
-    let javaVirtualMachine = try JavaVirtualMachine.shared()
-    let jniEnvironment = try javaVirtualMachine.environment()
-
-    let bigInt = BigInteger(number, environment: jniEnvironment)
+    let bigInt = BigInteger(number)
     if bigInt.isProbablePrime(certainty) {
       print("\(number) is probably prime")
     } else {

Samples/JavaSieve/Sources/JavaSieve/main.swift

@@ -13,11 +13,10 @@
 //===----------------------------------------------------------------------===//
 
 import JavaKit
-import JavaKitVM
 
 let jvm = try JavaVirtualMachine.shared(classPath: ["QuadraticSieve-1.0.jar"])
 do {
-  let sieveClass = try JavaClass<SieveOfEratosthenes>(in: jvm.environment())
+  let sieveClass = try JavaClass<SieveOfEratosthenes>(environment: jvm.environment())
   for prime in sieveClass.findPrimes(100)! {
     print("Found prime: \(prime.intValue())")
   }

USER_GUIDE.md

@@ -61,35 +61,43 @@ public struct BigInteger {
 
 This Swift type wraps `java.math.BigInteger`, exposing its constructors, methods, and fields for use directly to Swift. Let's try using it!
 
-### Creating a Java Virtual Machine instance from Swift
+### Creating a `BigInteger` and determine whether it is probably prime
 
-The `JavaVirtualMachine` class, which is part of the `JavaKitVM` module, provides the ability to create and query the Java Virtual Machine. One can create a shared instance of `JavaVirtualMachine` by calling `JavaVirtualMachine.shared()`, optionally passing along extra options to the JVM (such as the class path):
+Now, we can go ahead and create a `BigInteger` instance from a Swift string like this:
 
 ```swift
-let javaVirtualMachine = try JavaVirtualMachine.shared()
+let bigInt = BigInteger(veryBigNumber)
 ```
 
-If the JVM is already running, a `JavaVirtualMachine` instance will be created to reference that existing JVM. Given a `JavaVirtualMachine` instance, one can query the JNI environment for the currently-active thread by calling `environment()`, e.g.,
+And then call methods on it. For example, check whether the big integer is a probable prime with some certainty:
 
 ```swift
-let jniEnvironment = try javaVirtualMachine.environment()
+if bigInt.isProbablePrime(10) {
+  print("\(bigInt.toString()) is probably prime")
+}
 ```
 
-This JNI environment can be used to create instances of Java objects. For example, we can create a `BigInteger` instance from a Swift string like this:
+Swift ensures that the Java garbage collector will keep the object alive until `bigInt` (and any copies of it) are been destroyed. 
+
+### Creating a Java Virtual Machine instance from Swift
+
+When JavaKit requires a running Java Virtual Machine to use an operation (for example, to create an instance of `BigInteger`), it will query to determine if one is running and, if not, create one. To exercise more control over the creation and configuration of the Java virtual machine, use the `JavaVirtualMachine` class, which provides creation and query operations. One can create a shared instance by calling `JavaVirtualMachine.shared()`, optionally passing along extra options to the JVM (such as the class path):
 
 ```swift
-let bigInt = BigInteger(veryBigNumber, environment: jniEnvironment)
+let javaVirtualMachine = try JavaVirtualMachine.shared()
 ```
 
-And then call methods on it. For example, check whether the big integer is a probable prime with some certainty:
+If the JVM is already running, a `JavaVirtualMachine` instance will be created to reference that existing JVM. Given a `JavaVirtualMachine` instance, one can query the JNI environment for the currently-active thread by calling `environment()`, e.g.,
 
 ```swift
-if bigInt.isProbablePrime(10) {
-  print("\(bigInt.toString()) is probably prime")
-}
+let jniEnvironment = try javaVirtualMachine.environment()
 ```
 
-Swift ensures that the Java garbage collector will keep the object alive until `bigInt` (and any copies of it) are been destroyed. 
+This JNI environment can be used to create instances of Java objects in a specific JNI environment. For example, we can pass this environment along when we create the `BigInteger` instance from a Swift string, like this:
+
+```swift
+let bigInt = BigInteger(veryBigNumber, environment: jniEnvironment)
+```
 
 ### Importing a Jar file into Swift
 
@@ -134,7 +142,7 @@ The resulting configuration file will look something like this:
 }
 ```
 
-As with the previous `JavaProbablyPrime` sample, the `JavaSieve` target in `Package.swift` should depend on the `swift-java` package modules (`JavaKit`, `JavaKitVM`) and apply the `Java2Swift` plugin. This makes all of the Java classes found in the Jar file available to Swift within the `JavaSieve` target.
+As with the previous `JavaProbablyPrime` sample, the `JavaSieve` target in `Package.swift` should depend on the `swift-java` package modules (`JavaKit`) and apply the `Java2Swift` plugin. This makes all of the Java classes found in the Jar file available to Swift within the `JavaSieve` target.
 
 If you inspect the build output, there are a number of warnings that look like this:
 
@@ -197,7 +205,6 @@ Putting it all together, we can define a main program in `Sources/JavaSieve/main
 
 ```swift
 import JavaKit
-import JavaKitVM
 
 let jvm = try JavaVirtualMachine.shared(classPath: ["QuadraticSieve-1.0.jar"])
 do {