> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ditto.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Java for Servers & Desktop

> Integrate the Ditto SDK into Java Server & Desktop projects

## Prerequisites

Following are the minimum requirements that must be met before attempting to install Ditto.

* Java Development Kit (JDK) version 17 {/* TODO: This should probably change to JDK 11 once we fix build scripts */}
* One of the following platforms and architectures:
  * Windows x86\_64
  * Linux x86\_64 and aarch64
  * macOS arm64 (Apple Silicon)

## Additional Resources

* [Java Quickstart](/sdk/latest/quickstarts/java-server)
* [Java Release Notes](/sdk/latest/release-notes/java)
* [API Reference](https://software.ditto.live/java/ditto-java/5.0.0-java/api-reference/)↗️

## Setting Up Your Environment

Include the Maven Central repository in your Gradle file, and then synchronize it with your project.

<Steps>
  <Step>
    From your project-level build.gradle file located in the project's root directory,
    ensure the `mavenCentral()` repository is included in the repositories section:

    <CodeGroup>
      ```groovy build.gradle (Groovy) theme={null}
      allprojects {
          repositories {
              mavenCentral()
          }
      }
      ```

      ```kotlin build.gradle.kts (Kotlin) theme={null}
      allprojects {
          repositories {
              mavenCentral()
          }
      }
      ```
    </CodeGroup>
  </Step>

  <Step>
    Synchronize your project with the Gradle file by clicking **Build > Sync Project with Gradle Files**
  </Step>
</Steps>

## Adding the Ditto SDK Dependency

To reduce the size of your final application archive,
we provide binaries for each supported platform and architecture separately.
You can include all supported binaries or only the ones you need.

<Steps>
  <Step>
    Add the Ditto SDK to your module's `build.gradle` file in the `dependencies` block with the appropriate version.
    This is the Java API that you will use to interact with Ditto.

    <CodeGroup>
      ```gradle build.gradle (Groovy) theme={null}
      implementation 'com.ditto:ditto-java:5.0.0-java'
      ```

      ```kotlin build.gradle.kts (Kotlin) theme={null}
      implementation("com.ditto:ditto-java:5.0.0-java")
      ```
    </CodeGroup>
  </Step>

  <Step>
    Add binaries to the same `dependencies` block based on what platforms you are targeting.

    <CodeGroup>
      ```gradle build.gradle (Groovy) theme={null}
      // This will include binaries for all supported platforms and architectures
      implementation 'com.ditto:ditto-binaries:5.0.0-java'

      // Or you can use one or more of the following declarations to include binaries for specific platforms
      implementation('com.ditto:ditto-binaries:5.0.0-java') {
          capabilities {
              requireCapability('com.ditto:ditto-binaries-windows-x64')
          }
      }

      implementation('com.ditto:ditto-binaries:5.0.0-java') {
          capabilities {
              requireCapability('com.ditto:ditto-binaries-linux-x64')
          }
      }

      implementation('com.ditto:ditto-binaries:5.0.0-java') {
          capabilities {
              requireCapability('com.ditto:ditto-binaries-macos-arm64')
          }
      }
      ```

      ```kotlin build.gradle.kts (Kotlin) theme={null}
      // This will include binaries for all supported platforms and architectures
      implementation("com.ditto:ditto-binaries:5.0.0-java")

      // Or you can use one or more of the following declarations to include binaries for specific platforms
      implementation("com.ditto:ditto-binaries:5.0.0-java") {
          capabilities {
              requireCapability("com.ditto:ditto-binaries-windows-x64")
          }
      }

      implementation("com.ditto:ditto-binaries:5.0.0-java") {
          capabilities {
              requireCapability("com.ditto:ditto-binaries-linux-x64")
          }
      }

      implementation("com.ditto:ditto-binaries:5.0.0-java") {
          capabilities {
              requireCapability("com.ditto:ditto-binaries-macos-arm64")
          }
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

# Integrating and Initializing

<Steps>
  <Step>
    Add the following code to import Ditto, at the top of your project file.

    ```java Java theme={null}
    import com.ditto.java.*;
    ```
  </Step>

  <Step>
    Most apps require that Ditto run as a singleton. A singleton is an
    implementation ensuring your Ditto instance accesses and shares a single object
    instance throughout your app.

    To store the Ditto instance as a singleton object, create a custom Ditto
    subclass that can be used throughout the application.

    By doing so, you ensure that there is only one instance of Ditto throughout the
    app's lifecycle, and it remains available for use by any activity or component
    that needs it. This approach helps in efficient resource management and avoids
    unnecessary object instantiation and destruction.

    ```java Java theme={null}
    import com.ditto.java.Ditto;
    import com.ditto.java.DittoConfig;
    import com.ditto.java.Authenticator;

    // Your HTTP Cloud URL Endpoint
    String endpoint = "REPLACE_ME_WITH_YOUR_URL";
    String databaseId = "REPLACE_ME_WITH_YOUR_DATABASE_ID";

    DittoConfig config = new DittoConfig.Builder(databaseId)
        .connect(new DittoConfig.Connect.Server(endpoint))
        .build();

    try {
        Ditto ditto = Ditto.open(config);

        // Set up authentication expiration handler (required for server connections)
        ditto.getAuth().setExpirationHandler((expiringDitto, timeUntilExpiration) -> {
            // Authenticate when token is expiring
            expiringDitto.getAuth().login(
                "REPLACE_ME_WITH_YOUR_DEVELOPMENT_TOKEN",
                Authenticator.DEVELOPMENT_PROVIDER,
                (clientInfo, error) -> {
                    if (error != null) {
                        System.out.println("Authentication failed: " + error);
                    } else {
                        System.out.println("Authentication successful");
                    }
                }
            );
        });

        // Start sync (v5 pattern: ditto.getSync().start())
        ditto.getSync().start();
    } catch (DittoError e) {
        System.out.println("Ditto initialization failed: " + e.getMessage());
    }
    ```
  </Step>

  <Step>
    Replace the database ID and development token with your access credentials available in the portal.

    <Info>
      For instructions on how to obtain your access credentials, see [Getting SDK Connection Details](/cloud/portal/getting-sdk-connection-details).
    </Info>
  </Step>
</Steps>