Using from Java
skapi-java lets Java code use Skapi without Kotlin coroutines or kotlinx JSON. It is a thin layer on top of skapi-kotlin: the same methods with the same names, each returning a CompletableFuture, and plain Java maps and lists in place of JsonObject.
It works with Java 8 or later and on Android (minSdk 24).
Install
Gradle (build.gradle.kts):
dependencies {
implementation("com.skapi:skapi-java:2.4.1")
// Android apps, also:
implementation("com.skapi:skapi-android:2.4.1")
}Gradle (build.gradle):
dependencies {
implementation 'com.skapi:skapi-java:2.4.1'
}Maven (pom.xml):
<dependency>
<groupId>com.skapi</groupId>
<artifactId>skapi-java</artifactId>
<version>2.4.1</version>
</dependency>skapi-java brings in skapi-kotlin and the Kotlin standard library, so there is nothing else to add. You do not need the Kotlin compiler or the Kotlin Gradle plugin.
Create a SkapiJava object
import com.skapi.java.SkapiJava;
SkapiJava skapi = new SkapiJava("<Project ID>");The constructor takes the same options as the Kotlin Skapi constructor, left to right. Leave out the ones at the end that you do not need:
import com.skapi.FileStorage;
import com.skapi.java.SkapiJava;
SkapiJava skapi = new SkapiJava("<Project ID>", new FileStorage("~/.myapp/session.json"));
SkapiJava withTimeout = new SkapiJava("<Project ID>", new FileStorage("~/.myapp/session.json"), 30);| constructor or method | |
|---|---|
new SkapiJava(projectId) | one project, its connection and the signed-in user's session |
new SkapiJava(projectId, storage, timeoutSeconds, targetCdn, encryption) | the same options as Skapi(...); each one from the right can be left out |
new SkapiJava(skapi) or SkapiJava.wrap(skapi) | a SkapiJava over a Skapi object you already have, for example one your Kotlin code made |
skapi.getSkapi() | the Skapi object underneath |
For record encryption, build the options with EncryptionOptionsBuilder, which starts from the defaults:
import com.skapi.java.EncryptionOptionsBuilder;
SkapiJava skapi = new SkapiJava("<Project ID>", new FileStorage("~/.myapp/session.json"), 120, null,
new EncryptionOptionsBuilder().withheld("sentinel").build());How calls work
Every method that talks to the server returns a CompletableFuture. The request runs on a background thread, and the future completes when the answer arrives.
Wait for the answer with get() (the calling thread waits):
Map<String, Object> info = skapi.getConnectionInfo().get();
System.out.println(info.get("service_name")); // your project's nameOr give the future a callback, and the calling thread carries on:
skapi.getConnectionInfo()
.thenAccept(info -> System.out.println(info.get("service_name")))
.exceptionally(err -> { System.out.println("failed: " + err.getCause()); return null; });Chain calls that depend on each other with thenCompose:
skapi.login("user@example.com", "password")
.thenCompose(user -> skapi.getRecords(SkapiJson.obj("table", SkapiJson.obj("name", "posts", "access_group", "public"))))
.thenAccept(page -> System.out.println(page.get("list")));- Threads. Requests run on a shared pool of background threads. A callback such as
thenAcceptruns on the background thread that finished the call, or right away on your thread when the future was already done. - Android. Never call
get()on the main thread: it freezes the screen until the server answers. UsethenAcceptand move to the main thread before you touch views, for example withrunOnUiThread(...)or aHandleron the main looper. - Cancelling.
future.cancel(true)stops the request. A request the server already received may still have done its work, for example a record may have been written. - Many at once. One object can run many calls at the same time. They share its session and its token refreshes.
// Android: an Activity
skapi.getRecords(SkapiJson.obj("table", SkapiJson.obj("name", "posts", "access_group", "public")))
.thenAccept(page -> runOnUiThread(() -> showPosts((List<Object>) page.get("list"))));JSON as maps and lists
What the Kotlin pages show as JsonObject is a Map<String, Object> in Java, and a JSON array is a List<Object>.
Values you pass in can be:
| Java | JSON |
|---|---|
Map<String, ?> | object (the keys keep their order with a LinkedHashMap) |
List<?>, any Iterable, arrays | array |
String, Character | string |
Integer, Long, Short, Byte, BigInteger | whole number |
Double, Float, BigDecimal | number (NaN and infinity become null) |
Boolean | true / false |
an enum value | its name, as a string |
null | null |
Anything else (a Date, your own class) fails the call with INVALID_PARAMETER. Turn it into one of the types above first.
Answers come back as:
| JSON | Java |
|---|---|
| object | Map<String, Object> (a LinkedHashMap, in the server's order) |
| array | List<Object> |
| string | String |
| whole number | Long |
| other number | Double |
true / false | Boolean |
null | null |
Every map and list you get back is a new one, so you may change it. Numbers come back as Long even when you sent an Integer, so read them with ((Number) value).intValue() or longValue().
SkapiJson builds and converts values:
import com.skapi.java.SkapiJson;
Map<String, Object> config = SkapiJson.obj(
"table", SkapiJson.obj("name", "posts", "access_group", "public"),
"tags", SkapiJson.list("news", "java"));
String text = SkapiJson.stringify(config); // {"table":{"name":"posts","access_group":"public"},"tags":["news","java"]}
Object back = SkapiJson.parse(text); // a Map<String, Object> again| method | |
|---|---|
SkapiJson.obj(key, value, key, value, ...) | a Map<String, Object> from keys and values in turn, in that order |
SkapiJson.list(a, b, ...) | a List<Object> |
SkapiJson.stringify(value) | compact JSON text |
SkapiJson.parse(text) | JSON text as Java values |
SkapiJson.toJava(jsonElement) | a kotlinx JsonElement as Java values (also toJavaMap, toJavaList) |
SkapiJson.fromJava(value) | Java values as a kotlinx JsonElement (also fromJavaMap), for code that also calls the Kotlin Skapi |
obj, list and fromJava throw IllegalArgumentException for a value that is not JSON, and parse does for text that is not JSON. Your own Map and List objects work just as well as the ones obj and list make.
Paging options
FetchOptions is built with FetchOptionsBuilder:
import com.skapi.FetchOptions;
import com.skapi.java.FetchOptionsBuilder;
Map<String, Object> query = SkapiJson.obj("table", SkapiJson.obj("name", "posts", "access_group", "public"));
Map<String, Object> page = skapi.getRecords(query, new FetchOptionsBuilder().limit(100).build()).get();
while (!Boolean.TRUE.equals(page.get("endOfList"))) {
page = skapi.getRecords(query, new FetchOptionsBuilder().limit(100).fetchMore(true).build()).get();
}The builder has limit(int), ascending(boolean), startKey(Object) and fetchMore(boolean). They mean what they mean on the Fetching Records page.
Errors
When a call fails, its future completes with the same SkapiException the Kotlin call throws, with the same getCode() and getMessage().
get() wraps it in an ExecutionException. The SkapiException is its getCause():
import com.skapi.SkapiException;
import java.util.concurrent.ExecutionException;
try {
skapi.login("user@example.com", "wrong password").get();
} catch (ExecutionException e) {
SkapiException err = (SkapiException) e.getCause();
System.out.println(err.getCode()); // INCORRECT_USERNAME_OR_PASSWORD
System.out.println(err.getMessage()); // Incorrect username or password.
}In a callback, the error arrives as the Throwable of exceptionally, handle or whenComplete. A failure in an earlier stage of a chain reaches it wrapped in a CompletionException, so look at getCause() when the error is not a SkapiException itself:
skapi.login("user@example.com", "password")
.whenComplete((user, err) -> {
if (err == null) { System.out.println(user.get("email")); return; }
Throwable cause = err instanceof SkapiException ? err : err.getCause();
if (cause instanceof SkapiException && "MFA_REQUIRED".equals(((SkapiException) cause).getCode())) {
askForCode(); // then skapi.verifyMfa(code)
}
});A parameter that is not a JSON value fails the future with code INVALID_PARAMETER. A cancelled future throws CancellationException from get().
Callbacks
Methods that take a callback in Kotlin take a java.util.function interface in Java:
| method | callback |
|---|---|
connectRealtime(callback) | Consumer<Map<String, Object>>, called with every message, notice and connection event |
forwardRequest(options, form, onStream), forwardRequestPoll(...), forwardRequestStream(...) | BiConsumer<String, Integer>, called with each piece of streamed text and its number |
skapi.connectRealtime(event -> {
if ("message".equals(event.get("type"))) {
System.out.println(event.get("sender") + ": " + event.get("message"));
}
}).get();
skapi.joinRealtime("lobby").get();
skapi.postRealtime(SkapiJson.obj("text", "Hello"), "lobby").get();Callbacks run on a background thread. On Android, move to the main thread before you touch views.
Files
Files to upload are the same FileUpload values the Kotlin pages use. Their factories are static methods:
import com.skapi.FileUpload;
import java.io.File;
import java.util.Arrays;
skapi.postRecord(
SkapiJson.obj("caption", "Holiday"),
SkapiJson.obj("table", SkapiJson.obj("name", "photos", "access_group", "authorized")),
Arrays.asList(FileUpload.fromFile("picture", new File("beach.jpg"), null, null))
).get();getFile(url) completes with a byte[], getFileText(url) with a String, and downloadFile(url, file) with the File it wrote.
close()
close() cancels the calls still running and closes the Skapi object underneath: its realtime connection, timers and network threads. A JVM program can then exit. The signed-in session stays saved in storage. Calls made after close() return a cancelled future.
SkapiJava is AutoCloseable, so a short program can use try-with-resources:
public static void main(String[] args) throws Exception {
try (SkapiJava skapi = new SkapiJava("<Project ID>")) {
skapi.login("user@example.com", "password").get();
System.out.println(skapi.getRecords(SkapiJson.obj("table", SkapiJson.obj("name", "posts", "access_group", "public"))).get());
}
}An Android app keeps one object for as long as the app runs and does not need to close it.
Reading the rest of these docs
Every code example in these docs has a Kotlin and a Java tab. The text and the tables around them use the Kotlin names. Every method has the same name and the same arguments, in the same order, on SkapiJava. Read the Kotlin names like this:
- Kotlin
skapi.getRecords(query)isskapi.getRecords(query)on SkapiJava, returning aCompletableFutureof aMap. - A
JsonObjectyou pass is aMap<String, Object>;jsonOf("name" to "posts")isSkapiJson.obj("name", "posts"), andlistOf(...)orjsonArrayOf(...)isSkapiJson.list(...)or anyList. - Kotlin's named and default arguments become Java overloads: leave out arguments from the right.
logout(globalLogout = true)islogout(true), andlogin(email, password)islogin(email, password). To give a later argument, passnullfor the ones before it, as inlogin(null, "password", "ana")for a username. - A
JsonObjectyou get back is aMap<String, Object>:result["list"]!!.jsonArrayis(List<Object>) result.get("list"). - Kotlin properties are getters:
skapi.userisskapi.getUser(),skapi.sessionisskapi.getSession(),skapi.versionisskapi.getVersion(). - A call that returns nothing in Kotlin (
pinPeerKey,connectRealtime,closeRealtime) completes withnull. try { ... } catch (err: SkapiException)around a Kotlin call is a catch ofExecutionExceptionaroundget(), with theSkapiExceptionas its cause.
