Skip to main content

Java SDK

The Mobiscroll Connect Java SDK provides a convenient way to integrate Mobiscroll Connect in Java backend applications. It targets Java 11 and is built on top of OkHttp 4 and Jackson, so it works in any modern JVM application (plain Java, Spring Boot, Quarkus, etc.).

Setup​

Add the dependency using your build tool of choice:

<dependency>
  <groupId>com.mobiscroll</groupId>
  <artifactId>connect-sdk</artifactId>
  <version>1.1.0</version>
</dependency>

Client Initialization​

To use the SDK, initialize MobiscrollConnectClient with your client credentials.

Class: com.mobiscroll.connect.MobiscrollConnectClient

constructorMobiscrollConnectClient

Constructor arguments.

clientIdString

Your Client ID obtained from the Mobiscroll Connect dashboard.

clientSecretString

Your Client Secret obtained from the Mobiscroll Connect dashboard.

redirectUriString

Your application's redirect URI that matches the one configured in the Mobiscroll Connect dashboard.

Usage:

import com.mobiscroll.connect.MobiscrollConnectClient;

MobiscrollConnectClient client = new MobiscrollConnectClient(
    "YOUR_CLIENT_ID",
    "YOUR_CLIENT_SECRET",
    "YOUR_REDIRECT_URI"
);

For a custom base URL, HTTP timeout, OkHttp client, or a token-refresh callback for persistence, use the configuration builder:

import com.mobiscroll.connect.MobiscrollConnectClient;
import com.mobiscroll.connect.MobiscrollConnectConfig;
import java.time.Duration;

MobiscrollConnectClient client = new MobiscrollConnectClient(
    MobiscrollConnectConfig.builder()
        .clientId("YOUR_CLIENT_ID")
        .clientSecret("YOUR_CLIENT_SECRET")
        .redirectUri("YOUR_REDIRECT_URI")
        .baseUrl("https://connect.mobiscroll.com/api")
        .timeout(Duration.ofSeconds(60))
        .onTokensRefreshed(updatedTokens -> {
            // Persist updatedTokens.getAccessToken() / getRefreshToken()
        })
        .build()
);

Methods​

setCredentials​

Sets the access token for the client. This is required before making any API calls that require authentication.

Method: client.setCredentials(tokens)

tokensTokenResponse

The token response object returned by client.auth().getToken(code).

onTokensRefreshed​

Registers a callback to be invoked whenever the SDK automatically refreshes the access token. Use this to persist the updated tokens so they survive future requests.

Method: client.onTokensRefreshed(callback)

callbackConsumer<TokenResponse>

A consumer that receives the updated TokenResponse after a successful automatic token refresh.

Token Refresh​

The Java SDK handles token refresh automatically. When any API call returns a 401 Unauthorized response and the client has a refresh_token stored, the SDK silently exchanges it for a new access token and retries the original request — with no action required from your application. Concurrent calls that hit the same expired token share a single refresh attempt.

When the refresh succeeds, the SDK invokes your onTokensRefreshed callback with the updated TokenResponse. You must register this callback and persist the new tokens, otherwise they will be lost between requests.

client.onTokensRefreshed(updatedTokens -> {
    // Persist updatedTokens in your database or session store
    // so the new access_token and refresh_token survive future requests
    httpSession.setAttribute("access_token", updatedTokens.getAccessToken());
    httpSession.setAttribute("refresh_token", updatedTokens.getRefreshToken());
});

If the refresh token itself is invalid or has been revoked, the SDK throws an AuthenticationException and the user must re-authorize.

Error Handling​

All SDK methods throw exceptions that extend com.mobiscroll.connect.exceptions.MobiscrollConnectException. You can catch the base class or any specific subclass.

ExceptionHTTP StatusExtra
AuthenticationException401, 403— (raised after refresh + retry has been exhausted)
ValidationException400, 422getDetails() (JsonNode)
NotFoundException404—
RateLimitException429getRetryAfter() (Integer, seconds)
ServerException5xxgetStatusCode() (int)
NetworkException—wraps the underlying IOException cause
import com.mobiscroll.connect.exceptions.*;
import com.mobiscroll.connect.models.EventListParams;
import java.time.OffsetDateTime;

try {
    var response = client.events().list(EventListParams.builder()
        .start(OffsetDateTime.parse("2026-01-01T00:00:00Z"))
        .end(OffsetDateTime.parse("2026-02-01T00:00:00Z"))
        .build());
} catch (AuthenticationException e) {
    // Token expired and refresh failed — re-authorize the user
} catch (ValidationException e) {
    // Invalid request parameters
    var details = e.getDetails();
} catch (RateLimitException e) {
    Integer retryAfter = e.getRetryAfter(); // seconds
} catch (MobiscrollConnectException e) {
    // Catch-all for any other SDK error
}

API​

The client exposes resources that map directly to the API endpoints.

Auth​

The client.auth() resource handles the OAuth authorization flow, including generating authorization URLs, exchanging codes for tokens, managing connection status, and disconnecting providers.

To localize the Connect pages, pass an optional lng (en, es, fr, ar) to generateAuthUrl, e.g. AuthUrlParams.builder().userId(...).lng("es").build(). When omitted, the UI falls back to the browser's Accept-Language header, then English; Arabic renders right-to-left.

Calendars​

The client.calendars() resource allows you to list available calendars from all connected providers (Google, Outlook, etc.). It corresponds to the /calendars endpoints.

Events​

The client.events() resource provides methods to create, read, update, and delete calendar events across all connected accounts. It corresponds to the /events endpoints.