Skip to content

Latest commit

 

History

History
162 lines (122 loc) · 8.29 KB

README.md

File metadata and controls

162 lines (122 loc) · 8.29 KB

Firebase Java SDK GitHub last commit

Built and maintained with 🧡 by GitLive
Development teams merge faster with GitLive


The Firebase Java SDK is a pure java port of the Firebase Android SDK to run in clientside java environments such as the desktop.

Note this is different to the official Firebase Admin Java SDK which enables access to Firebase services from privileged environments (such as servers or cloud).

It is used by the Firebase Kotlin SDK to support the JVM target for multiplatform projects, enabling you to use Firebase directly from your common source targeting Desktop, iOS, Android and Web, enabling the use of Firebase as a backend for Compose Multiplatform, for example.

It's currently in an alpha state, to be used at your own discretion, and contributions are very welcome!

Using in your projects

You can add the library via Gradle:

dependencies {
    implementation("dev.gitlive:firebase-java-sdk:0.4.7")
}

Or Maven:

<dependency>
    <groupId>dev.gitlive</groupId>
    <artifactId>firebase-java-sdk</artifactId>
    <version>0.4.7</version>
</dependency>

You can skip the above if you are using the SDK via the Firebase Kotlin SDK

Initializing the SDK

Before you can use the SDK you need to call the FirebasePlatform.initializeFirebasePlatform function to provide an implementation for logging, and persistent storage for simple key value pairs. This is used by the various Firebase products, for example, to persist the signed-in user in Firebase Auth.

Here's a simple example implementation in Kotlin that only persists in-memory:

FirebasePlatform.initializeFirebasePlatform(object : FirebasePlatform() {
    val storage = mutableMapOf<String, String>()
    override fun store(key: String, value: String) = storage.set(key, value)
    override fun retrieve(key: String) = storage[key]
    override fun clear(key: String) { storage.remove(key) }
    override fun log(msg: String) = println(msg)
})

Customizing Firestore offline data persistence database location

The FirebasePlatform interface also includes a getDatabasePath method for you to override if the following default implementation is not suitable:

    open fun getDatabasePath(name: String): File = File("${System.getProperty("java.io.tmpdir")}${File.separatorChar}$name")

This is used by Firestore to support offline data persistence.

Initialize the Firebase application

It is also up to you to initialize the Firebase application object manually (unlike the Android SDK which is normally initialized via the configuration file).

You first need to create a Firebase options object to hold the configuration data for the Firebase application. Full documentation for the options can be found in the Android API reference documentation.

The use of FirebaseOptions.Builder is shown in the following example:

// Manually configure Firebase Options. The following fields are REQUIRED:
//   - Project ID
//   - App ID
//   - API Key
FirebaseOptions options = new FirebaseOptions.Builder()
        .setProjectId("my-firebase-project")
        .setApplicationId("1:27992087142:android:ce3b6448250083d1")
        .setApiKey("AIzaSyADUe90ULnQDuGShD9W23RDP0xmeDc6Mvw")
        // setDatabaseURL(...)
        // setStorageBucket(...)
        .build();

You can then pass this to the initialize function, along with a mock Android context supplied by the firebase-java-sdk, like so:

import android.app.Application

val app = Firebase.initialize(new Application(), options)

Project status

The following libraries are available for the various Firebase products.

Service or Product Port of Android version
Firebase Android BoM 32.7.0
Authentication N/A1
Cloud Firestore 24.10.0
Realtime Database 20.3.0
Cloud Functions 20.4.0
Remote Config 21.6.02
Installations 17.2.02

Is the Firebase library or API you need missing? Create an issue to request additional API coverage or be awesome and submit a PR.

Limitations

Currently, the following limitations are observed:

Firebase Auth implementation is minimal and only supports a small subset of the API:

  • signInAnonymously
  • signInWithCustomToken
  • signInWithEmailAndPassword
  • currentUser
  • getAccessToken
  • getUid
  • addIdTokenListener
  • removeIdTokenListener
  • addAuthStateListener
  • removeAuthStateListener
  • signOut

Realtime Database does not support Disk Persistence, and should be setup as follows:

FirebaseDatabase.getInstance().setPersistenceEnabled(false)

Building and contributing

This library is built with Gradle.

Run ./gradlew build to build the library locally.

Implementation details

Apart from Firebase Auth, the Firebase Android libraries and their dependencies are used as-is from the published maven artifacts available at Google's Maven Repository. These are obviously designed to run on Android so to use them without modification we include a minimal Android emulation layer in the SDK only implementing the functionality used by the Firebase libraries at runtime.

Robolectric is included as a compile-only dependency to overcome compilation errors due to missing Android APIs as they are many more compile-time dependencies on the Android SDK than what is required for proper functioning at run-time. This makes development of the SDK somewhat challenging as the compiler is unable to assist you on what Android functionality needs to be emulated before the library will function correctly (instead the library will error at runtime usually with one of the ReflectiveOperationException subclasses.)

The best way to support more of the Firebase SDKs is via writing unit tests to test the required functionality at runtime and assert the correct behavior.

Footnotes

  1. Google has not open-sourced the Firebase Auth implementation for Android so a basic implementation using the Rest API is provided.

  2. Although the libraries are inlcuded they are currently not funtional 2