DataStore   Android Jetpack का हिस्सा है.

Jetpack DataStore, डेटा स्टोर करने का एक तरीका है. इसकी मदद से, प्रोटोकॉल बफ़र की मदद से की-वैल्यू पेयर या टाइप किए गए ऑब्जेक्ट को स्टोर किया जा सकता है. DataStore, Kotlin के कोरयूटीन और Flow का इस्तेमाल करके, डेटा को असिंक्रोनस तरीके से, लगातार, और ट्रांज़ैक्शन के हिसाब से स्टोर करता है.

अगर फ़िलहाल डेटा सेव करने के लिए, SharedPreferences का इस्तेमाल किया जा रहा है, तो DataStore पर माइग्रेट करें.

Preferences DataStore और Proto DataStore

DataStore दो अलग-अलग तरीकों से लागू किया जा सकता है: Preferences DataStore और Proto DataStore.

  • Preferences DataStore, कुंजियों का इस्तेमाल करके डेटा को सेव और ऐक्सेस करता है. इस तरीके को लागू करने के लिए, पहले से तय किए गए स्कीमा की ज़रूरत नहीं होती. साथ ही, यह टाइप सेफ़्टी की सुविधा नहीं देता.
  • Proto DataStore, डेटा को कस्टम डेटा टाइप के इंस्टेंस के तौर पर सेव करता है. इसे लागू करने के लिए, आपको प्रोटोकॉल बफ़र का इस्तेमाल करके स्कीमा तय करना होगा. हालांकि, इससे डेटा सुरक्षित रहता है.

DataStore का सही तरीके से इस्तेमाल करना

DataStore का सही तरीके से इस्तेमाल करने के लिए, इन नियमों का हमेशा ध्यान रखें:

  1. एक ही प्रोसेस में, किसी फ़ाइल के लिए DataStore का एक से ज़्यादा इंस्टेंस कभी न बनाएं. ऐसा करने से, DataStore की सभी सुविधाएं काम करना बंद कर सकती हैं. अगर एक ही प्रोसेस में किसी फ़ाइल के लिए कई डेटास्टोर चालू हैं, तो डेटा पढ़ने या अपडेट करने के दौरान, डेटास्टोर IllegalStateException दिखाएगा.

  2. DataStore का सामान्य टाइप ऐसा होना चाहिए जिसे बदला न जा सके. DataStore में इस्तेमाल किए गए टाइप में बदलाव करने से, DataStore की ओर से दी गई किसी भी गारंटी की पुष्टि नहीं होती. साथ ही, इससे गंभीर और ऐसे गड़बड़ियां पैदा हो सकती हैं जिन्हें पहचानना मुश्किल होता है. हमारा सुझाव है कि आप प्रोटोकॉल बफ़र का इस्तेमाल करें. इससे, डेटा में बदलाव न होने की गारंटी मिलती है. साथ ही, यह एक आसान एपीआई है और डेटा को बेहतर तरीके से सीरियलाइज़ करता है.

  3. एक ही फ़ाइल के लिए, SingleProcessDataStore और MultiProcessDataStore का इस्तेमाल कभी एक साथ न करें. अगर आपको एक से ज़्यादा प्रोसेस से DataStore को ऐक्सेस करना है, तो हमेशा MultiProcessDataStore का इस्तेमाल करें.

सेटअप

अपने ऐप्लिकेशन में Jetpack DataStore का इस्तेमाल करने के लिए, अपनी Gradle फ़ाइल में यह जानकारी जोड़ें. यह इस बात पर निर्भर करता है कि आपको किस तरीके का इस्तेमाल करना है:

Preferences DataStore

Groovy

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation "androidx.datastore:datastore-preferences:1.1.1"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-preferences-rxjava2:1.1.1"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-preferences-rxjava3:1.1.1"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-preferences-core:1.1.1"
    }

Kotlin

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation("androidx.datastore:datastore-preferences:1.1.1")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-preferences-rxjava2:1.1.1")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-preferences-rxjava3:1.1.1")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-preferences-core:1.1.1")
    }

Proto DataStore

Groovy

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation "androidx.datastore:datastore:1.1.1"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-rxjava2:1.1.1"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-rxjava3:1.1.1"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-core:1.1.1"
    }

Kotlin

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation("androidx.datastore:datastore:1.1.1")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-rxjava2:1.1.1")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-rxjava3:1.1.1")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-core:1.1.1")
    }

Preferences DataStore की मदद से की-वैल्यू पेयर सेव करना

Preferences DataStore लागू करने के लिए, डिस्क में आसान की-वैल्यू पेयर को सेव करने के लिए, DataStore और Preferences क्लास का इस्तेमाल किया जाता है.

प्राथमिकताएं सेव करने के लिए डेटास्टोर बनाना

DataStore<Preferences> का इंस्टेंस बनाने के लिए, preferencesDataStore से बनाई गई प्रॉपर्टी डेलिगेट का इस्तेमाल करें. इसे अपनी Kotlin फ़ाइल के सबसे ऊपरी लेवल पर एक बार कॉल करें और अपने बाकी ऐप्लिकेशन में इस प्रॉपर्टी के ज़रिए इसे ऐक्सेस करें. इससे, DataStore को सिंगलटन के तौर पर रखना आसान हो जाता है. इसके अलावा, अगर RxJava का इस्तेमाल किया जा रहा है, तो RxPreferenceDataStoreBuilder का इस्तेमाल करें. ज़रूरी name पैरामीटर, प्राथमिकता वाले डेटा स्टोर का नाम होता है.

Kotlin

// At the top level of your kotlin file:
val Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "settings")

Java

RxDataStore<Preferences> dataStore =
  new RxPreferenceDataStoreBuilder(context, /*name=*/ "settings").build();

Preferences DataStore से डेटा पढ़ना

Preferences DataStore, पहले से तय किए गए स्कीमा का इस्तेमाल नहीं करता. इसलिए, आपको हर उस वैल्यू के लिए एक कुंजी तय करनी होगी जिसे आपको DataStore<Preferences> इंस्टेंस में सेव करना है. इसके लिए, आपको उससे जुड़े कुंजी टाइप फ़ंक्शन का इस्तेमाल करना होगा. उदाहरण के लिए, किसी int वैल्यू के लिए कोई कीवर्ड तय करने के लिए, intPreferencesKey() का इस्तेमाल करें. इसके बाद, Flow का इस्तेमाल करके सही सेव की गई वैल्यू दिखाने के लिए, DataStore.data प्रॉपर्टी का इस्तेमाल करें.

Kotlin

val EXAMPLE_COUNTER = intPreferencesKey("example_counter")
val exampleCounterFlow: Flow<Int> = context.dataStore.data
  .map { preferences ->
    // No type safety.
    preferences[EXAMPLE_COUNTER] ?: 0
}

Java

Preferences.Key<Integer> EXAMPLE_COUNTER = PreferencesKeys.int("example_counter");

Flowable<Integer> exampleCounterFlow =
  dataStore.data().map(prefs -> prefs.get(EXAMPLE_COUNTER));

प्राथमिकता वाले डेटास्टोर में लिखना

Preferences DataStore में एक ऐसा edit() फ़ंक्शन होता है जो DataStore में डेटा को ट्रांज़ैक्शन के हिसाब से अपडेट करता है. फ़ंक्शन का transform पैरामीटर, कोड का एक ब्लॉक स्वीकार करता है, जहां ज़रूरत के हिसाब से वैल्यू अपडेट की जा सकती हैं. ट्रांसफ़ॉर्म ब्लॉक में मौजूद सभी कोड को एक ही ट्रांज़ैक्शन माना जाता है.

Kotlin

suspend fun incrementCounter() {
  context.dataStore.edit { settings ->
    val currentCounterValue = settings[EXAMPLE_COUNTER] ?: 0
    settings[EXAMPLE_COUNTER] = currentCounterValue + 1
  }
}

Java

Single<Preferences> updateResult =  dataStore.updateDataAsync(prefsIn -> {
  MutablePreferences mutablePreferences = prefsIn.toMutablePreferences();
  Integer currentInt = prefsIn.get(INTEGER_KEY);
  mutablePreferences.set(INTEGER_KEY, currentInt != null ? currentInt + 1 : 1);
  return Single.just(mutablePreferences);
});
// The update is completed once updateResult is completed.

Proto DataStore की मदद से, टाइप किए गए ऑब्जेक्ट स्टोर करना

Proto DataStore लागू करने के लिए, DataStore और प्रोटोकॉल बफ़र का इस्तेमाल किया जाता है. इससे, टाइप किए गए ऑब्जेक्ट को डिस्क पर सेव किया जा सकता है.

स्कीमा तय करना

Proto DataStore के लिए, app/src/main/proto/ डायरेक्ट्री में मौजूद प्रोटो फ़ाइल में पहले से तय स्कीमा होना ज़रूरी है. यह स्कीमा, उन ऑब्जेक्ट के टाइप के बारे में बताता है जिन्हें आपने अपने Proto DataStore में सेव किया है. प्रोटो स्कीमा तय करने के बारे में ज़्यादा जानने के लिए, प्रोटोबफ़ भाषा की गाइड देखें.

syntax = "proto3";

option java_package = "com.example.application";
option java_multiple_files = true;

message Settings {
  int32 example_counter = 1;
}

प्रोटो DataStore बनाना

टाइप किए गए ऑब्जेक्ट को सेव करने के लिए, Proto DataStore बनाने के दो चरण होते हैं:

  1. ऐसी क्लास तय करें जो Serializer<T> को लागू करती हो. यहां T, प्रोटो फ़ाइल में तय किया गया टाइप है. यह सिरियलाइज़र क्लास, DataStore को आपके डेटा टाइप को पढ़ने और लिखने का तरीका बताती है. पक्का करें कि आपने सिरियलाइज़र के लिए डिफ़ॉल्ट वैल्यू शामिल की हो, ताकि अगर अब तक कोई फ़ाइल नहीं बनाई गई है, तो उसका इस्तेमाल किया जा सके.
  2. DataStore<T> का इंस्टेंस बनाने के लिए, dataStore से बनाए गए प्रॉपर्टी डेलिगेट का इस्तेमाल करें. यहां T, प्रोटो फ़ाइल में तय किया गया टाइप है. इसे अपनी Kotlin फ़ाइल के टॉप लेवल पर एक बार कॉल करें और अपने बाकी ऐप्लिकेशन में इस प्रॉपर्टी डेलिगेट के ज़रिए इसे ऐक्सेस करें. filename पैरामीटर, DataStore को बताता है कि डेटा को सेव करने के लिए किस फ़ाइल का इस्तेमाल करना है. साथ ही, serializer पैरामीटर, DataStore को पहले चरण में तय की गई सिरियलाइज़र क्लास का नाम बताता है.

Kotlin

object SettingsSerializer : Serializer<Settings> {
  override val defaultValue: Settings = Settings.getDefaultInstance()

  override suspend fun readFrom(input: InputStream): Settings {
    try {
      return Settings.parseFrom(input)
    } catch (exception: InvalidProtocolBufferException) {
      throw CorruptionException("Cannot read proto.", exception)
    }
  }

  override suspend fun writeTo(
    t: Settings,
    output: OutputStream) = t.writeTo(output)
}

val Context.settingsDataStore: DataStore<Settings> by dataStore(
  fileName = "settings.pb",
  serializer = SettingsSerializer
)

Java

private static class SettingsSerializer implements Serializer<Settings> {
  @Override
  public Settings getDefaultValue() {
    Settings.getDefaultInstance();
  }

  @Override
  public Settings readFrom(@NotNull InputStream input) {
    try {
      return Settings.parseFrom(input);
    } catch (exception: InvalidProtocolBufferException) {
      throw CorruptionException(“Cannot read proto.”, exception);
    }
  }

  @Override
  public void writeTo(Settings t, @NotNull OutputStream output) {
    t.writeTo(output);
  }
}

RxDataStore<Byte> dataStore =
    new RxDataStoreBuilder<Byte>(context, /* fileName= */ "settings.pb", new SettingsSerializer()).build();

Proto DataStore से डेटा पढ़ना

अपने सेव किए गए ऑब्जेक्ट से सही प्रॉपर्टी का Flow एक्सपोज़ करने के लिए, DataStore.data का इस्तेमाल करें.

Kotlin

val exampleCounterFlow: Flow<Int> = context.settingsDataStore.data
  .map { settings ->
    // The exampleCounter property is generated from the proto schema.
    settings.exampleCounter
  }

Java

Flowable<Integer> exampleCounterFlow =
  dataStore.data().map(settings -> settings.getExampleCounter());

Proto DataStore में डेटा लिखना

Proto DataStore में एक ऐसा updateData() फ़ंक्शन होता है जो सेव किए गए ऑब्जेक्ट को ट्रांज़ैक्शन के तौर पर अपडेट करता है. updateData(), आपके डेटा टाइप के इंस्टेंस के तौर पर, डेटा की मौजूदा स्थिति दिखाता है. साथ ही, डेटा को ट्रांज़ैक्शनल रीड-राइट-बदलाव करने वाले ऑपरेशन में अपडेट करता है.

Kotlin

suspend fun incrementCounter() {
  context.settingsDataStore.updateData { currentSettings ->
    currentSettings.toBuilder()
      .setExampleCounter(currentSettings.exampleCounter + 1)
      .build()
    }
}

Java

Single<Settings> updateResult =
  dataStore.updateDataAsync(currentSettings ->
    Single.just(
      currentSettings.toBuilder()
        .setExampleCounter(currentSettings.getExampleCounter() + 1)
        .build()));

सिंक करने वाले कोड में DataStore का इस्तेमाल करना

DataStore का एक मुख्य फ़ायदा, एसिंक्रोनस एपीआई है. हालांकि, हो सकता है कि आपके आस-पास मौजूद कोड को एसिंक्रोनस बनाने के लिए, हमेशा ऐसा करना मुमकिन न हो. ऐसा तब हो सकता है, जब किसी ऐसे मौजूदा कोडबेस के साथ काम किया जा रहा हो जो सिंक्रोनस डिस्क I/O का इस्तेमाल करता हो. इसके अलावा, ऐसा तब भी हो सकता है, जब आपकी कोई डिपेंडेंसी एसिंक्रोनस एपीआई उपलब्ध न कराती हो.

Kotlin कोरूटीन, runBlocking() कोरूटीन बिल्डर की सुविधा देते हैं. इससे सिंक्रोनस और एसिंक्रोनस कोड के बीच के अंतर को कम करने में मदद मिलती है. DataStore से डेटा को सिंक करके पढ़ने के लिए, runBlocking() का इस्तेमाल किया जा सकता है. RxJava, Flowable पर ब्लॉक करने के तरीके उपलब्ध कराता है. यह कोड, कॉल करने वाली थ्रेड को तब तक ब्लॉक करता है, जब तक कि DataStore डेटा नहीं दिखाता:

Kotlin

val exampleData = runBlocking { context.dataStore.data.first() }

Java

Settings settings = dataStore.data().blockingFirst();

यूज़र इंटरफ़ेस (यूआई) थ्रेड पर सिंक्रोनस I/O ऑपरेशन करने से, ANR या यूआई में रुकावट आ सकती है. DataStore से डेटा को असिंक्रोनस तरीके से प्रीलोड करके, इन समस्याओं को कम किया जा सकता है:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    lifecycleScope.launch {
        context.dataStore.data.first()
        // You should also handle IOExceptions here.
    }
}

Java

dataStore.data().first().subscribe();

इस तरह, DataStore डेटा को असिंक्रोनस तरीके से पढ़ता है और उसे मेमोरी में कैश मेमोरी में सेव करता है. runBlocking() का इस्तेमाल करके, बाद में सिंक्रोनस रीड करने की प्रोसेस तेज़ हो सकती है. इसके अलावा, अगर शुरुआती रीड पूरी हो गई है, तो डिस्क I/O ऑपरेशन पूरी तरह से बचा जा सकता है.

मल्टी-प्रोसेस कोड में DataStore का इस्तेमाल करना

DataStore को कॉन्फ़िगर करके, एक ही डेटा को अलग-अलग प्रोसेस में ऐक्सेस किया जा सकता है. साथ ही, डेटा की एक जैसी क्वालिटी की गारंटी भी मिलती है, जैसी कि एक ही प्रोसेस में मिलती है. खास तौर पर, DataStore ये गारंटी देता है:

  • सिर्फ़ पढ़ने की सुविधा, डिस्क में सेव किए गए डेटा को दिखाती है.
  • डेटा को लिखने के बाद उसे पढ़ने पर, डेटा में कोई बदलाव न होना.
  • डेटा को क्रम से लिखा जाता है.
  • रीड को कभी भी राइड से ब्लॉक नहीं किया जाता.

सेवा और गतिविधि वाले सैंपल ऐप्लिकेशन पर विचार करें:

  1. यह सेवा, अलग प्रोसेस में चल रही है और समय-समय पर DataStore को अपडेट करती है

    <service
  android:name=".MyService"
  android:process=":my_process_id" />

    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
      scope.launch {
          while(isActive) {
              dataStore.updateData {
                  Settings(lastUpdate = System.currentTimeMillis())
              }
              delay(1000)
          }
      }
}

  2. ऐप्लिकेशन उन बदलावों को इकट्ठा करेगा और अपना यूज़र इंटरफ़ेस (यूआई) अपडेट करेगा

    val settings: Settings by dataStore.data.collectAsState()
Text(
  text = "Last updated: $${settings.timestamp}",
)

अलग-अलग प्रोसेस में DataStore का इस्तेमाल करने के लिए, आपको MultiProcessDataStoreFactory का इस्तेमाल करके DataStore ऑब्जेक्ट बनाना होगा.

val dataStore: DataStore<Settings> = MultiProcessDataStoreFactory.create(
   serializer = SettingsSerializer(),
   produceFile = {
       File("${context.cacheDir.path}/myapp.preferences_pb")
   }
)

serializer, DataStore को आपके डेटा टाइप को पढ़ने और उसमें बदलाव करने का तरीका बताता है. पक्का करें कि आपने सिरियलाइज़र के लिए डिफ़ॉल्ट वैल्यू शामिल की हो, ताकि अगर अब तक कोई फ़ाइल न बनाई गई हो, तो उसका इस्तेमाल किया जा सके. यहां kotlinx.serialization का इस्तेमाल करके, इसे लागू करने का उदाहरण दिया गया है:

@Serializable
data class Settings(
   val lastUpdate: Long
)

@Singleton
class SettingsSerializer @Inject constructor() : Serializer<Settings> {

   override val defaultValue = Settings(lastUpdate = 0)

   override suspend fun readFrom(input: InputStream): Timer =
       try {
           Json.decodeFromString(
               Settings.serializer(), input.readBytes().decodeToString()
           )
       } catch (serialization: SerializationException) {
           throw CorruptionException("Unable to read Settings", serialization)
       }

   override suspend fun writeTo(t: Settings, output: OutputStream) {
       output.write(
           Json.encodeToString(Settings.serializer(), t)
               .encodeToByteArray()
       )
   }
}

Hilt डिपेंडेंसी इंजेक्शन का इस्तेमाल करके, यह पक्का किया जा सकता है कि हर प्रोसेस के लिए आपका DataStore इंस्टेंस यूनीक हो:

@Provides
@Singleton
fun provideDataStore(@ApplicationContext context: Context): DataStore<Settings> =
   MultiProcessDataStoreFactory.create(...)

फ़ाइल में हुए नुकसान को ठीक करना

बहुत कम मामलों में, DataStore की डिस्क पर मौजूद फ़ाइल खराब हो सकती है. डिफ़ॉल्ट रूप से, DataStore में डेटा खराब होने पर, वह अपने-आप ठीक नहीं होता. साथ ही, उसमें से डेटा पढ़ने की कोशिश करने पर, सिस्टम CorruptionException दिखाता है.

DataStore में, डेटा खराब होने पर उसे ठीक करने वाला एपीआई उपलब्ध होता है. इसकी मदद से, इस तरह की स्थिति में डेटा को आसानी से ठीक किया जा सकता है और अपवाद को रोका जा सकता है. कॉन्फ़िगर होने पर, बिगड़ने की समस्या को ठीक करने वाला हैंडलर, बिगड़ चुकी फ़ाइल को एक नई फ़ाइल से बदल देता है. इस नई फ़ाइल में, पहले से तय की गई डिफ़ॉल्ट वैल्यू होती है.

इस हैंडलर को सेट अप करने के लिए, by dataStore() या DataStoreFactory फ़ैक्ट्री विधि में DataStore इंस्टेंस बनाते समय corruptionHandler दें:

val dataStore: DataStore<Settings> = DataStoreFactory.create(
   serializer = SettingsSerializer(),
   produceFile = {
       File("${context.cacheDir.path}/myapp.preferences_pb")
   },
   corruptionHandler = ReplaceFileCorruptionHandler { Settings(lastUpdate = 0) }
)

सुझाव या राय दें

इन संसाधनों की मदद से, अपने सुझाव, शिकायत या राय हमारे साथ शेयर करें:

समस्या को ट्रैक करने वाला टूल
समस्याओं की शिकायत करें, ताकि हम उन्हें ठीक कर सकें.

अन्य संसाधन

Jetpack DataStore के बारे में ज़्यादा जानने के लिए, यहां दिए गए अन्य संसाधन देखें:

सैंपल

ब्लॉग

कोडलैब