quick-start-sync.txt

.. meta::
   :robots: noindex, nosnippet

.. _java-client-quick-start-sync:

================================
Quick Start with Sync - Java SDK
================================

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

.. tip:: This Guide uses Device Sync

   This guide helps you get started with an Android application that
   communicates with an App backend. The App provides features
   like :ref:`Sync <sync>`, Realm Functions, and user management. If
   your application requires only local database functionality,
   check out the :ref:`Quick Start (Local-only)
   <java-client-quick-start-local>` guide.

This page contains information to quickly get Atlas App Services
integrated into your app. Before you begin, ensure you have:

- :ref:`Created an App <create-a-realm-app>`
- :ref:`Enabled Sync <enable-sync>`
- :ref:`Installed the Java SDK <java-install>`

.. include:: /includes/java-initialize-realm.rst

.. _java-quick-start-init-app:

Initialize the App
------------------

.. include:: /includes/access-app-id.rst

.. tabs-realm-languages::

   .. tab::
      :tabid: java

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.initialize-the-app.java
         :language: java
         :copyable: false
   
   .. tab::
      :tabid: kotlin

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.initialize-the-app.kt
         :language: kotlin
         :copyable: false

.. note:: Android Studio Errors?

   If Android Studio does not recognize the ``Realm``, ``App``, or
   ``AppConfiguration`` types, there could be a problem with the
   your Gradle build configuration. To fix the issue:

   - Clean your project with ``Build > Clean Project``

   - Rebuild your project based on your updated ``build.gradle`` file
     with ``Build > Rebuild Project``

   - Revisit the :ref:`Install the Java SDK <java-install>`
     guide to make sure that you installed the dependencies correctly.

Define Your Object Model
------------------------

Your application's **data model** defines the structure of data
stored within Realm and synchronized to and from
App Services. You can define your application's data model in two ways:

- Via :ref:`schemas <schemas>` in App Services.

- Via Kotlin or Java classes in your application code with
  :ref:`Realm Object Models <create-schema-from-rom>`.

This quick start uses the latter approach, which defines your schema
using classes in your mobile application code. To define your App's
object model in this way, you need to enable :ref:`Development Mode
<development-mode>`.

Once you've enabled Development Mode, add the following class
definitions to your application code:

.. tabs-realm-languages::

   .. tab::
      :tabid: java

      .. literalinclude:: /examples/generated/java/sync/Task.snippet.define-object-model.java
         :language: java
         :copyable: false

      .. literalinclude:: /examples/generated/java/sync/TaskStatus.snippet.complete.java
         :language: java
         :copyable: false

   .. tab::
      :tabid: kotlin

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.define-object-model.kt
         :language: kotlin
         :copyable: false

.. _java-quick-start-authenticate:

Authenticate a User
-------------------

When you have enabled :ref:`anonymous authentication <anonymous-authentication>` in the
App Services UI, users can immediately log into your app without providing any identifying
information:

.. tabs-realm-languages::

   .. tab::
      :tabid: java

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.authenticate-a-user.java
         :language: java
         :copyable: false
   
   .. tab::
      :tabid: kotlin

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.authenticate-a-user.kt
         :language: kotlin
         :copyable: false

Realm provides many additional ways to authenticate, register, and link users.

Open a Realm
------------

Once you have :ref:`enabled Sync <enable-sync>` and authenticated a
user, you can open a synced :ref:`realm <java-realms>`. Use
``SyncConfiguration`` to control the specifics of how your application
synchronizes data with App Services, including timeouts, synchronous
reads and writes on the UI thread, and more.

.. tabs-realm-languages::

   .. tab::
      :tabid: java

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.open-a-realm.java
         :language: java
         :copyable: false
   
   .. tab::
      :tabid: kotlin

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.open-a-realm.kt
         :language: kotlin
         :copyable: false

Create, Read, Update, and Delete Objects
----------------------------------------

Once you have opened a realm, you can modify the
:ref:`objects <java-realm-objects>` within that realm in a
:ref:`write transaction <java-open-a-transaction>` block.

.. include:: /includes/java-synchronous-reads-writes-ui-thread.rst

To create a new ``Task``, instantiate an instance of the
``Task`` class and add it to the realm in a write block:

.. tabs-realm-languages::

   .. tab::
      :tabid: java

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.create-object.java
         :language: java
         :copyable: false
   
   .. tab::
      :tabid: kotlin

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.create-object.kt
         :language: kotlin
         :copyable: false

You can retrieve a live :ref:`collection <java-client-collections>`
of all items in the realm:

.. tabs-realm-languages::

   .. tab::
      :tabid: java

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.read-object.java
         :language: java
         :copyable: false
   
   .. tab::
      :tabid: kotlin

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.read-object.kt
         :language: kotlin
         :copyable: false

You can also filter that collection using a :ref:`filter
<java-client-query-engine>`:

.. tabs-realm-languages::

   .. tab::
      :tabid: java

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.filter-collection.java
         :language: java
         :copyable: false
   
   .. tab::
      :tabid: kotlin

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.filter-collection.kt
         :language: kotlin
         :copyable: false

To modify a task, update its properties in a write transaction block:

.. tabs-realm-languages::

   .. tab::
      :tabid: java

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.update-object.java
         :language: java
         :copyable: false
   
   .. tab::
      :tabid: kotlin

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.update-object.kt
         :language: kotlin
         :copyable: false

Finally, you can delete a task by calling the ``deleteFromRealm()``
method in a write transaction block:

.. tabs-realm-languages::

   .. tab::
      :tabid: java

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.delete-object.java
         :language: java
         :copyable: false
   
   .. tab::
      :tabid: kotlin

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.delete-object.kt
         :language: kotlin
         :copyable: false

Watch for Changes
-----------------

You can :ref:`watch a realm, collection, or object for changes
<java-client-notifications>` by attaching a custom
``OrderedRealmCollectionChangeListener`` with the ``addChangeListener()``
method:

.. tabs-realm-languages::

   .. tab::
      :tabid: java

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.watch-for-changes.java
         :language: java
         :copyable: false
   
   .. tab::
      :tabid: kotlin

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.watch-for-changes.kt
         :language: kotlin
         :copyable: false

Log Out
-------

Once logged in, you can log out:

.. tabs-realm-languages::

   .. tab::
      :tabid: java

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.log-out.java
         :language: java
         :copyable: false
   
   .. tab::
      :tabid: kotlin

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.log-out.kt
         :language: kotlin
         :copyable: false

Complete Example
----------------

Run the complete example by replacing the appId with your realm app ID.
If you're running this project in a fresh Android Studio project, you can
copy and paste this file into your application's ``MainActivity`` -- just
remember to:

- change the package declaration so it matches your project

- replace the App ID placeholder with your App's App ID

- update the ``import`` statements for ``Task`` and ``TaskStatus`` if
  you're using Java

.. tabs-realm-languages::

   .. tab::
      :tabid: java

      .. literalinclude:: /examples/generated/java/sync/Task.snippet.define-object-model.java
         :caption: Task.java
         :language: java

      .. literalinclude:: /examples/generated/java/sync/TaskStatus.snippet.complete.java
         :caption: TaskStatus.java
         :language: java

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.complete.java
         :caption: MainActivity.java
         :language: java

   .. tab::
      :tabid: kotlin

      .. literalinclude:: /examples/generated/java/sync/MainActivity.snippet.complete.kt
         :caption: MainActivity.kt
         :language: kotlin

Output
------
Running the above code should produce output resembling the following:

.. code-block:: shell

   Successfully authenticated anonymously.

   Updated range: 0 to 1

   Deleted range: 0 to 1

   Successfully logged out.