Skip to content

Commit 01d7abb

Browse files
committed
align documentation with module rename
1 parent 9f0a226 commit 01d7abb

File tree

2 files changed

+19
-19
lines changed

2 files changed

+19
-19
lines changed

README.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -169,7 +169,7 @@ In order to run JMH benchmarks you can:
169169
170170
```bash
171171
cd Samples/SwiftKitSampleApp
172-
gradle jmh
172+
./gradlew jmh
173173
```
174174
175175
Please read documentation of both performance testing tools and understand that results must be interpreted and not just taken at face value. Benchmarking is tricky and environment sensitive task, so please be careful when constructing and reading benchmarks and their results. If in doubt, please reach out on the forums.
@@ -183,8 +183,8 @@ To view the rendered docc documentation you can use the docc preview command:
183183
```bash
184184
xcrun docc preview Sources/SwiftJavaDocumentation/Documentation.docc
185185
186-
# OR JavaKit to view JavaKit documentation:
187-
# xcrun docc preview Sources/SwiftJNI/Documentation.docc
186+
# OR SwiftJava to view SwiftJava documentation:
187+
# xcrun docc preview Sources/SwiftJava/Documentation.docc
188188
189189
# ========================================
190190
# Starting Local Preview Server

Sources/SwiftJava/Documentation.docc/JavaKit.md renamed to Sources/SwiftJava/Documentation.docc/SwiftJava.md

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
# JavaKit
1+
# SwiftJava
22

33
Library and tools to make it easy to use Java libraries from Swift using the Java Native Interface (JNI).
44

5-
## JavaKit: Using Java libraries from Swift
5+
## SwiftJava: Using Java libraries from Swift
66

77
Existing Java libraries can be wrapped for use in Swift with the `swift-java`
88
tool. In a Swift program, the most direct way to access a Java API is to use the SwiftPM plugin to provide Swift wrappers for the Java classes. To do so, add a configuration file `swift-java.config` into the source directory for the Swift target. This is a JSON file that specifies Java classes and the Swift type name that should be generated to wrap them. For example, the following file maps `java.math.BigInteger` to a Swift type named `BigInteger`:
@@ -77,7 +77,7 @@ Swift ensures that the Java garbage collector will keep the object alive until `
7777

7878
### Creating a Java Virtual Machine instance from Swift
7979

80-
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):
80+
When SwiftJava 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):
8181

8282
```swift
8383
let javaVirtualMachine = try JavaVirtualMachine.shared()
@@ -100,7 +100,7 @@ let bigInt = BigInteger(veryBigNumber, environment: jniEnvironment)
100100
Java libraries are often distributed as Jar files. The `swift-java` tool can inspect a Jar file to create a `swift-java.config` file that will wrap all of the public classes for use in Swift. Following the example in `swift-java/Samples/JavaSieve`, we will wrap a small [Java library for computing prime numbers](https://github.com/gazman-sdk/quadratic-sieve-Java) for use in Swift. Assuming we have a Jar file `QuadraticSieve-1.0.jar` in the package directory, run the following command:
101101

102102
```swift
103-
swift-java generate --module-name JavaSieve --jar QuadraticSieve-1.0.jar
103+
swift-java configure --swift-module JavaSieve --jar QuadraticSieve-1.0.jar
104104
```
105105

106106
The resulting configuration file will look something like this:
@@ -138,7 +138,7 @@ The resulting configuration file will look something like this:
138138
}
139139
```
140140

141-
As with the previous `JavaProbablyPrime` sample, the `JavaSieve` target in `Package.swift` should depend on the `swift-java` package modules (`JavaKit`) and apply the `swift-java` plugin. This makes all of the Java classes found in the Jar file available to Swift within the `JavaSieve` target.
141+
As with the previous `JavaProbablyPrime` sample, the `JavaSieve` target in `Package.swift` should depend on the `swift-java` package modules (`SwiftJava`) and apply the `swift-java` plugin. This makes all of the Java classes found in the Jar file available to Swift within the `JavaSieve` target.
142142

143143
If you inspect the build output, there are a number of warnings that look like this:
144144

@@ -152,7 +152,7 @@ These warnings mean that some of the APIs in the Java library aren't available i
152152
.target(
153153
name: "JavaMath",
154154
dependencies: [
155-
.product(name: "JavaKit", package: "swift-java"),
155+
.product(name: "SwiftJava", package: "swift-java"),
156156
],
157157
plugins: [
158158
.plugin(name: "SwiftJavaPlugin", package: "swift-java"),
@@ -237,7 +237,7 @@ if let url = myObject.as(URL.self) {
237237
238238
### Implementing Java `native` methods in Swift
239239

240-
JavaKit supports implementing Java `native` methods in Swift using JNI with the `@JavaImplementation` macro. In Java, the method must be declared as `native`, e.g.,
240+
SwiftJava supports implementing Java `native` methods in Swift using JNI with the `@JavaImplementation` macro. In Java, the method must be declared as `native`, e.g.,
241241

242242
```java
243243
package org.swift.javakit.example;
@@ -261,7 +261,7 @@ On the Swift side, the Java class needs to be exposed to Swift through `swift-ja
261261
}
262262
```
263263

264-
Implementations of `native` methods are written in an extension of the Swift type that has been marked with `@JavaImplementation`. The methods themselves must be marked with `@JavaMethod`, indicating that they are available to Java as well. To help ensure that the Swift code implements all of the `native` methods with the right signatures, JavaKit produces a protocol with the Swift type name suffixed by `NativeMethods`. Declare conformance to that protocol and implement its requirements, for example:
264+
Implementations of `native` methods are written in an extension of the Swift type that has been marked with `@JavaImplementation`. The methods themselves must be marked with `@JavaMethod`, indicating that they are available to Java as well. To help ensure that the Swift code implements all of the `native` methods with the right signatures, SwiftJava produces a protocol with the Swift type name suffixed by `NativeMethods`. Declare conformance to that protocol and implement its requirements, for example:
265265

266266
```swift
267267
@JavaImplementation("org.swift.javakit.HelloSwift")
@@ -278,7 +278,7 @@ Java native methods that throw any checked exception should be marked as `throws
278278

279279
The Swift implementations of Java `native` constructors and static methods require an additional Swift parameter `environment: JNIEnvironment? = nil`, which will receive the JNI environment in which the function is being executed. In case of nil, the `JavaVirtualMachine.shared().environment()` value will be used.
280280

281-
## JavaKit: Using Java libraries from Swift
281+
## SwiftJava: Using Java libraries from Swift
282282

283283
This section describes how Java libraries and mapped into Swift and their use from Swift.
284284

@@ -353,7 +353,7 @@ for entry in jarFile.entries()! {
353353

354354
`JavaMethod` is a [function body macro](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0415-function-body-macros.md) that translates the argument and result types to/from Java and performs a call to the named method via JNI.
355355

356-
A Java method or constructor that throws a checked exception should be marked as `throws` in Swift. Swift's projection of Java throwable types (as `JavaKit.Throwable`) conforms to the Swift `Error` protocol, so Java exceptions will be rethrown as Swift errors.
356+
A Java method or constructor that throws a checked exception should be marked as `throws` in Swift. Swift's projection of Java throwable types (as `SwiftJava.Throwable`) conforms to the Swift `Error` protocol, so Java exceptions will be rethrown as Swift errors.
357357

358358
### Java <-> Swift Type mapping
359359

@@ -380,14 +380,14 @@ For Swift projections of Java classes, the Swift type itself conforms to the `An
380380
Because Java has implicitly nullability of references, `AnyJavaObject` types do not directly conform to `JavaValue`: rather, optionals of `AnyJavaObject`-conforming type conform to `JavaValue`. This requires Swift code to deal with the optionality
381381
at interface boundaries rather than invite implicit NULL pointer dereferences.
382382

383-
A number of JavaKit modules provide Swift projections of Java classes and interfaces. Here are a few:
383+
A number of SwiftJava modules provide Swift projections of Java classes and interfaces. Here are a few:
384384

385385
| Java class | Swift class | Swift module |
386386
| --------------------- | -------------- | ---------------- |
387-
| `java.lang.Object` | `JavaObject` | `JavaKit` |
388-
| `java.lang.Class<T>` | `JavaClass<T>` | `JavaKit` |
389-
| `java.lang.Throwable` | `Throwable` | `JavaKit` |
390-
| `java.net.URL` | `URL` | `JavaKitNetwork` |
387+
| `java.lang.Object` | `JavaObject` | `SwiftJava` |
388+
| `java.lang.Class<T>` | `JavaClass<T>` | `SwiftJava` |
389+
| `java.lang.Throwable` | `Throwable` | `SwiftJava` |
390+
| `java.net.URL` | `URL` | `JavaNet` |
391391

392392
The `swift-java` tool can translate any other Java classes into Swift projections. The easiest way to use `swift-java` is with the SwiftPM plugin described above. More information about using this tool directly are provided later in this document
393393

@@ -406,7 +406,7 @@ When building Java sources using the JavaCompilerPlugin this option is passed by
406406

407407
### Class objects and static methods
408408

409-
Every `AnyJavaObject` has a property `javaClass` that provides an instance of `JavaClass` specialized to the type. For example, `url.javaClass` will produce an instance of `JavaClass<URL>`. The `JavaClass` instance is a wrapper around a Java class object (`java.lang.Class`) that has two roles in Swift. First, it provides access to all of the APIs on the Java class object. The `JavaKitReflection` library, for example, exposes these APIs and the types they depend on (`Method`,
409+
Every `AnyJavaObject` has a property `javaClass` that provides an instance of `JavaClass` specialized to the type. For example, `url.javaClass` will produce an instance of `JavaClass<URL>`. The `JavaClass` instance is a wrapper around a Java class object (`java.lang.Class`) that has two roles in Swift. First, it provides access to all of the APIs on the Java class object. The `JavaLangReflect` library, for example, exposes these APIs and the types they depend on (`Method`,
410410
`Constructor`, etc.) for dynamic reflection. Second, the `JavaClass` provides access to the `static` methods on the Java class. For example, [`java.net.URLConnection`](https://docs.oracle.com/javase/8/docs/api/java/net/URLConnection.html) has static methods to access default settings, such as the default for the `allowUserInteraction` field. These are exposed as instance methods on `JavaClass`, e.g.,
411411

412412
```swift

0 commit comments

Comments
 (0)