Connection
Skapi
import com.skapi.Skapi
val skapi = Skapi(
projectId: String,
storage: SkapiStorage = MemoryStorage(),
timeoutSeconds: Long = 120,
targetCdn: String? = null,
encryption: EncryptionOptions? = null,
)import com.skapi.java.SkapiJava;
SkapiJava skapi = new SkapiJava(
String projectId,
SkapiStorage storage, // default new MemoryStorage()
long timeoutSeconds, // default 120
String targetCdn, // default null
EncryptionOptions encryption // default null
);
// leave out arguments from the right: new SkapiJava("<Project ID>")| argument | |
|---|---|
projectId | the Project ID from your project's Settings page on skapi.com |
storage | where the signed-in session is kept: MemoryStorage() (this object only), FileStorage(path) (a JSON file created readable by you only), skapi-android's SharedPreferencesStorage(context), or any SkapiStorage |
timeoutSeconds | seconds to wait for each request (connect, read and write) |
targetCdn | advanced: the CDN host the SDK reads the project's endpoint list from. Leave it null. |
encryption | EncryptionOptions(...): encrypts the data of private records on the device before upload. See Encryption. |
The constructor is a plain (not suspend) call and sends nothing. The object connects on its first call.
Properties
| property | type | |
|---|---|---|
projectId | String | the Project ID |
service | String | the project's service ID, read from the Project ID |
owner | String | the project owner's ID, read from the Project ID |
version | String | "2.4.1" (also the constant SKAPI_VERSION) |
user | JsonObject? | the signed-in profile (a copy), or null. See user. |
session | SkapiSession? | the signed-in session's tokens: idToken, accessToken, refreshToken (each a String), or null |
Errors
| code | message |
|---|---|
INVALID_PARAMETER | Project ID is required. / Project ID is invalid. (thrown by the constructor) |
INVALID_PARAMETER | "encryption.iterations" must be at least 100000. (thrown by the constructor) |
NOT_EXISTS | The project ID does not exist. Create your project from skapi.com (thrown by the first call) |
getConnectionInfo
suspend fun getConnectionInfo(refresh: Boolean = false): JsonObjectCompletableFuture<Map<String, Object>> getConnectionInfo(boolean refresh)
// also getConnectionInfo()The project's name and settings, and the caller as the server sees it. refresh = true asks the server again instead of using the answer from the first call.
{
"project_id": "...",
"user_ip": "203.0.113.7",
"user_agent": "okhttp/4.12.0",
"user_location": "KR",
"service_name": "My Project",
"version": "2.4.1",
"conf": {"prevent_signup": false, "require_login": false, "anonymous_login": false, "...": "..."},
"encryption_recovery": {"code": null, "message": "..."}
}"encryption_recovery" is there only with encryption on and a signed-in user. It holds the user's encryption recovery code on the first call after it was created (their first password login with encryption on), and null after that, with a "message" saying what to do. See Encryption recovery codes.
onForeground
fun onForeground()void onForeground()Call when the app comes back to the foreground, as skapi-js does on the browser's visibilitychange. A temporary account is checked with the server at once (unless it was confirmed in the last minute) and signed out if it was deleted, and the realtime connection is pinged, or reopened now if it dropped. Returns at once; the work runs in the background. skapi-android's SkapiLifecycle calls it for you.
onNetworkAvailable
fun onNetworkAvailable()void onNetworkAvailable()Call when the network comes back, as skapi-js does on the browser's online event. The same checks as onForeground. skapi-android's SkapiLifecycle calls it for you.
close
fun close()void close() // SkapiJava also cancels the calls still runningCloses the realtime connection, stops this object's background timers (the temporary account keep-alive, the realtime keep-alive and reconnects) and releases its network threads, so a JVM program can exit. The session stays saved in storage. Do not use the object after close(); make a new one.
FetchOptions
FetchOptions(
limit: Int? = null,
ascending: Boolean? = null,
startKey: JsonElement? = null,
fetchMore: Boolean = false,
)FetchOptions fetchOptions = new FetchOptionsBuilder()
.limit(100) // int
.ascending(false) // boolean
.startKey("start") // Object: an earlier answer's "startKey" (a Map), "start" or "end"
.fetchMore(true) // boolean
.build(); // leave out any setting you do not needPaging options for every method that returns a list (getRecords(), getUsers(), getSubscriptions(), getTickets() and the others). See Paging.
| option | |
|---|---|
limit | items per page, up to 1000. The server's default is 50 unless the method says otherwise. |
ascending | the sort direction |
startKey | where to start: the startKey of an earlier answer, JsonPrimitive("start") to start over, or JsonPrimitive("end") |
fetchMore | true reads the next page of the same query, continuing from the last answer |
A list answer is a JsonObject with list, startKey, endOfList and startKeyHistory.
SkapiStorage
interface SkapiStorage {
fun getItem(key: String): String?
fun setItem(key: String, value: String)
fun removeItem(key: String)
}public interface SkapiStorage {
String getItem(String key); // or null
void setItem(String key, String value);
void removeItem(String key);
}Where the signed-in session is kept. Keys and values are strings, the same keys skapi-js keeps in localStorage. The methods are called on background threads, sometimes from several at once.
| class | |
|---|---|
MemoryStorage() | the default: kept for the life of the Skapi object |
FileStorage(path: String) | one JSON file. ~/ is the home folder. Created readable by its owner only where the system has POSIX permissions. Writes go to a temporary file first, then replace the old one. |
SharedPreferencesStorage(context, name = "skapi-session", encrypt = true) | skapi-android: the app's private preferences, each value sealed by the Android Keystore. See Android. |
JSON helpers
fun jsonOf(vararg pairs: Pair<String, Any?>): JsonObject
fun jsonArrayOf(vararg items: Any?): JsonArray
fun Any?.toJsonElement(): JsonElement
fun JsonElement.toJsString(): String// Java uses SkapiJson (com.skapi.java) instead
static Map<String, Object> obj(Object... keysAndValues)
static List<Object> list(Object... items)
static JsonElement fromJava(Object value)
static String stringify(Object value)
static Object parse(String text)| helper | |
|---|---|
jsonOf("key" to value, ...) | a JsonObject from pairs |
jsonArrayOf(a, b, ...) | a JsonArray from values |
toJsonElement() | a Map, List, Array, String, number, Boolean, null or JsonElement as JSON. Anything else becomes its toString() text. |
toJsString() | compact JSON text, as JSON.stringify writes it: whole numbers without .0 |
See JSON in and out.
SkapiException
class SkapiException(
override val message: String,
val code: String = "ERROR",
cause: Throwable? = null,
val details: JsonElement? = null,
) : Exceptionpublic final class SkapiException extends Exception {
public SkapiException(String message, String code, Throwable cause, JsonElement details)
public String getMessage()
public String getCode()
public JsonElement getDetails() // or null
}
// a failed SkapiJava future: get() throws ExecutionException, getCause() is the SkapiExceptionWhat every method throws. code is a short name such as INVALID_PARAMETER; details is what the server sent with the error, when it sent more than a message. See Errors.
