استفاده از دیتابیس ROOM در اندروید

استفاده از دیتابیس ROOM در اندروید

بررسی اجمالی

Room کتابخانه جدید Google برای ذخیره اطلاعات در دیتابیس است که برای سهولت ساخت برنامه های آفلاین طراحی شده است. Room سعی دارد درحالی که امکان استفاده از تمام قدرت SQL را فراهم می کند، امکان مدیریت داده ها به صورت شی های جاوا را نیز ممکن کند. همچنین Room با سایر اجزای کتابخانه معماری گوگل (Google's Architecture Components) که برای ساخت برنامه های با کیفیت است نیز به خوبی سازگار است. Room برای مدیریت داده های حجیم با استفاده از کتابخانه صفحه بندی، نیز به خوبی کارآمد هست.

پیاده سازی

در ادامه یک برنامه نمونه با استفاده از Room پیاده سازی می کنیم.

افزودن نیازمندی ها به فایل گریدل

در ابتدا اطمینان حاصل کنید که مخزن کتابخانه های Google Maven را به فایل گریدل اضافه کرده باشید:

allprojects {
    repositories {
        google()
        jcenter()
    }
}

سپس در فایل app/build.gradle کتابخانه Room را به لیست نیازمندی ها اضافه کنید. در کد زیر برای راحتی در تغییر نسخه Room از یک متغیر برای ذخیره نسخه Room استفاده شده:

ext {
   roomVersion = "2.1.0"
}

dependencies {
  // Room for simple persistence with an ORM
  implementation "androidx.room:room-runtime:$roomVersion"
  annotationProcessor "androidx.room:room-compiler:$roomVersion"  
}

تعیین مکان ذخیره ساختارها

اگر کد زیر را به فایل app/build.gradle اضافه کنید، در هنگام کامپایل کد ، ساختار جدول ها در پوشه schemas ذخیره می شوند. سپس این ساختارها را می توانید بررسی کنید.

android {
    defaultConfig {

        javaCompileOptions {
            annotationProcessorOptions {
                arguments = ["room.schemaLocation": "$projectDir/schemas".toString()]
            }
        }
    }

}

تعریف جدول ها

به صورت زیر مدل هر جدول دیتابیس را با Entity@ نشان گذاری کنید:

import androidx.room.Entity;

@Entity
public class Organization {
   // ستون های این جدول را به صورت فیلد کلاس اینجا می نویسیم
}

در مرحله بعد باید هر یک از فیلد های کلاس که می خواهیم ستون جدول باشد را نشان گذاری کنیم:

// Mohamadreza Amani
// Email: help4usr@gmail.com
import androidx.room.ColumnInfo;
import androidx.room.Entity;
import androidx.room.PrimaryKey;

@Entity
public class Organization {

  @ColumnInfo
  @PrimaryKey(autoGenerate=true)
  Long id;

  @ColumnInfo
  String name;
}

نکته: باید حداقل یک فیلد را به عنوان کلید اصلی از طریق نشان گذاری PrimaryKey@ مشخص کنید. کد autoGenerate=true برای تعیین خودکار کلید اصلی (بدون نیاز به وارد کردن مقدار برای آن هنگام افزودن سطر جدید به جدول) استفاده شده. در این حالت کلید اصلی از عدد یک شروع می شود و با هر بار وارد کردن سطر جدید به جدول مقدار آن یک واحد اضافه می شود. کلید اصلی به صورت ۱و۲و۳و۴و۵و... می باشد. اگر بعد از ساخته شدن دیتابیس این کد را اضافه کردید باید schema ی دیتابیس به روز رسانی شود.

تعریف کلیدهای خارجی

Room اجازه می دهد تا کلیدهای خارجی بین اشیا تعریف شوند ، اما به صورت خودکار اجازه استفاده از این روابط برای جابجایی بین اشیا را نمی دهد. به طور نمونه جستجو برای یک شی خاص از جنس Organization داخل شیئی از جنس User در داخل حافظه امکان پذیر نیست. با این حال تعریف ارتباطات از طریق کلاس ها بین این دو جدول امکان پذیر هست:

// Mohamadreza Amani
// Email: help4usr@gmail.com
@Entity(foreignKeys = @ForeignKey(entity=Organization.class, parentColumns="id", childColumns="organization_id"))
public class User  {
    @ColumnInfo
    @PrimaryKey(autoGenerate=true)
    Long id;

    @ColumnInfo
    String name;

    @ColumnInfo
    Long organization_id;
}

تعیین کلاس های دسترسی به داده ها

می توانیم نوع کوئری هایی که می خواهیم انجام دهیم را در کلاس های مربوط به دسترس به داده ها مشخص کنیم. به این لایه DAO می گوییم. DAO مخفف Data Access Object است.  نشان گذاری های زیر با @ برای خواندن، اضافه کردن و حذف کردن شیئی از نوع User استفاده می شود:

// Mohamadreza Amani
// Email: help4usr@gmail.com
@Dao
public interface UserDao {
  @Query("SELECT * FROM User where userId := :id")
  public User getById(int id);

  @Insert(onConflict = OnConflictStrategy.REPLACE)
  public Long insertUser(User user);

  @Delete
  public void deleteUser(User user);

  @Insert(onConflict = OnConflictStrategy.REPLACE)
  public Long insertOrganization(Organization org);

}

ساختن دیتابیس

فایلی با نام MyDatabase.java بسازید و کد زیر را در آن قرار دهید. در کد زیر از نشان گذاری Database@ برای تعیین دیتابیس استفاده شده است. این کد شامل نام دیتابیس و نسخه آن نیز هست:

// Mohamadreza Amani
// Email: help4usr@gmail.com
// هر وقت تعریف جدول های دیتابیس را تغییر دادید شماره نسخه را افزایش بدید
@Database(entities={User.class, Organization.class}, version=1)
public abstract class MyDatabase extends RoomDatabase {
  // متد دسترسی به داده ها را به صورت انتزاعی تعریف می کنیم
  public abstract UserDao userDao();

  // نام دیتابیس
  public static final String NAME = "MyDataBase";

توجه: اگر بعداً تصمیم به تغییر هر جدول دیتابیس گرفتید حتماً باید شماره نسخه دیتابیس را تغییر دهید. هنگام تغییر شماره نسخه همیشه آن را افزایش دهید. چون در صورت کاهش شماره نسخه ممکن است با نسخه های قبلی تعارض پیدا کند. با توجه به تغییراتی که در مرحله های قبل در فایل گریدل ایجاد کردیم فایلهای داخل پوشه app/schemas در صورت تغییر جداول دیتابیس ، تغییر می کنند. می توانید کدهای  SQL برای ایجاد این جداول  را در پوشه app/schemas پیدا کنید. این کدهای SQL به صورت خودکار هنگام کامپایل برنامه تولید می شوند.

نمونه سازی از دیتابیس Room

کارهایی که تا این مرحله انجام دادیم مربوط به تعریف دیتابیس و جداول آن بود. حالا زمان استفاده از این جداول برای وارد کردن داده ها یا خواندن داده ها و یا تغییر داده ها است.  قبل از استفاده از Room باید شیئی از نوع دیتابیسی که در مرحله قبلی تعریف کردیم بدست آوریم. کد مربوط به دسترسی به این شی را در متد onCreate از کلاس Application می نویسیم. اگر قبلاً این کلاس را به پروژه اضافه نکرده اید کلاسی با نام اختیاری مثلاً MyDatabaseApplication  بسازید که از Application ارث بری کند به صورت زیر:

// Mohamadreza Amani
// Email: help4usr@gmail.com
public class MyDatabaseApplication extends Application {
    
    MyDatabase myDatabase;

    @Override
    public void onCreate() {
        super.onCreate();
      
        // fallbackToDestructiveMigration() متد 
        // استفاده شده تا اگر نسخه را تغییر دادید تمام داده های دیتابیس پاک شود
        // در برنامه کاربردی بجای پاک کردن داده ها باید داده ها را متناسب با تغییرات به روز کنید
       myDatabase = Room.databaseBuilder(this, MyDatabase.class, MyDatabase.NAME).fallbackToDestructiveMigration().build();
    }

    public MyDatabase getMyDatabase() {
        return myDatabase;
    }
    
}

برای استفاده از کلاس Application باید نام آن را در Manifest مشخص کنید. نام این کلاس را در کد بالا MyDatabaseApplication انتخاب کرده بودیم، حالا نام آن را در فایل AndroidManifest.xml در ویژگی android:name وارد می کنیم:

<application
        android:name=".MyDatabaseApplication"
        ...>
  <!--سایر کدهای مانیفست  -->
</application>

عملیات های اولیه CRUD

CRUD مخفف کلمه های Create به معنی «ساختن»، Read به معنی «خواندن»، Update به معنی «به روز رسانی» و  Delete به معنی «حذف کردن» است و اشاره به دستوراتی در SQL دارند که برای تغییر داده ها استفاده می شوند.

در کد زیر عملیات Create (ساختن) را می بینید. یک شی از جنس User و یک شی از جنس Organization می سازیم و آنها را از طریق یک تراکنش (Transaction) در دیتابیس ذخیره می کنیم:

// Mohamadreza Amani
// Email: help4usr@gmail.com
final Organization organization = new Organization();
organization.setName("Android");

final User user = new User();
user.setName("Mohamadreza Amani");

// Get the DAO
final UserDao userDao = ((MyDatabaseApplication) getApplicationContext()).getMyDatabase().userDao();

// Define the task
((MyDatabaseApplication) getApplicationContext()).getMyDatabase().runInTransaction(new Runnable() {
  @Override
  public void run() {
    userDao.insertOrganization(organization);
    userDao.insertUser(user);
  }
});

کوئری دیتابیس

تمامی کوئری ها باید در کلاس های مربوط به دسترسی به داده ها (DAO) نوشته شوند.

اگر بخواهیم به شکلی درباره کاربر (User) جست و جو کنیم که نام سازمان (Organization) او را نیز بدست آوریم. می توانیم به صورت زیر کوئری را بنویسیم:

// declare inner join here
  @Query("SELECT User.*, Organization.name AS organization_name FROM User INNER JOIN Organization " +
        "ON User.organization_id = Organization.id WHERE User.id = :id")
  public UserWithOrganization getWithOrgById(int id);

در کوئری بالا بجای استفاده از (organization.name)  از organization_name استفاده کردیم و برای اینکار از حرف AS استفاده کردیم. با اینکار می توان مشکل همنام بودن ستون ها در جدول های مختلف را حل کرد مثلاً هر دو جدول Organization و User ستونی به نام name دارند. برای استفاده از مقدار بازگشتی این متد که شامل User و organization_name است باید کلاس جدیدی بسازیم. نام این کلاس را در کد بالا UserWithOrganization گذاشتیم که کد آن به صورت زیر است. این کلاس باید شامل فیلد هایی باشد که در دستور select بالا انتخاب کردیم یعنی تمام ستون های جدول user و organization_name :

// Mohamadreza Amani
// Email: help4usr@gmail.com
class UserWithOrganization {
     // @Embedded نشان گذاری
    // با حفظ کپسوله سازی ، آبجکت کاربر را در این شی قرار می دهد
    @Embedded User user;

   // organization_name renamed during SELECT query w/ Organization.name AS organizaiton_name
   @ColumnInfo(name = "organization_name")
   String organizationName;

}

   پس از استفاده از نشان گذاری Embedded@ برای User می توانید به تمام صفات کلاس User داخل کلاس بالا دسترسی داشته باشید:

UserWithOrganization userWithOrg = new UserWithOrganization();
User user = userWithOrg.user;

فرض کنید که می خواهیم تمام ستون های جدول Organization را کوئری کنیم و در کنار جدول User داخل یک کلاس داشته باشیم. مشکل اینجاست که هر دوی جدول های Organization و User ستون های همنام مثل id دارند. روش رفع این مشکل استفاده از الگوی prefix یا پیشوندی است. به صورت زیر:

// Mohamadreza Amani
// Email: help4usr@gmail.com
class UserWithOrganization {
     // @Embedded نشان گذاری
    // با حفظ کپسوله سازی ، آبجکت کاربر را در این شی قرار می دهد
   @Embedded User user;

    //Organization تمام فیلد های جدول 
   // پیشوند می گیرند:   
   //( org_id, org_name, …)
   @Embedded(prefix="org_") Organization organization;

}

متد داخل کلاس DAO برای گرفتن داده ها از نوع بالا به صورت زیر می شود:

// declare inner join here
  @Query("SELECT User.*, Organization.name AS org_name, Organization.id as org_id FROM User INNER JOIN Organization " +
        "ON User.organization_id = Organization.id WHERE User.id = :id")
  public UserWithOrganization getWithOrgById(int id);

این کوئری را می توان با کمک AsyncTask به صورت زیر استفاده کرد:

final UserDao userDao = ((MyDatabaseApplication) getApplicationContext()).getMyDatabase().userDao();

AsyncTask.execute(new Runnable() {
   @Override
   public void run() {
     UserWithOrganization userWithOrganization = userDao.getWithOrgById(1);
   });
};

به روز رسانی داده ها

با نشان گذاری Insert@ می توان متدی که برای ورود داده جدید به جدول است را مشخص کرد. این متد کلید اصلی استفاده شده برای داده جدید را بر می گرداند. مثلاً در کد زیر کلید اصلی از نوع long است:

@Dao
public interface UserDao {
  @Insert(onConflict = OnConflictStrategy.REPLACE)
  // return primary key as Long
  public Long insertUser(User user);

اگر DAO شامل چند پارامتر باشد ، چند کلید اصلی نیز قابل بازگشت هست:

@Dao
public interface UserDao {
  @Insert(onConflict = OnConflictStrategy.REPLACE)
  public Long[] insertUser(User... users);

چون نباید در Thread اصلی با دیتابیس کار کنید، باید کار را در یک Thread جداگانه انجام دهید:

final UserDao userDao = ((MyDatabaseApplication) getApplicationContext()).getMyDatabase().userDao();

AsyncTask.execute(new Runnable() {
  @Override
  protected void run() {
      userDao.insertUsers(users);
  }
});

حذف داده ها

برای حذف داده ها از نشان گذاری Delete@ استفاده می کنیم:

@Delete
public void deleteUser(User user);

@Delete
public void deleteAll(User user1, User user2);

تراکنش های دیتابیس

تراکنش به مجموعه دستوراتی در دیتابیس می گوییم که باید به صورت یک دستور واحد اجرا شود یعنی یا همه دستورات تراکنش موفق شود یا اگر یکی از دستورات ناموفق بود وضعیت دیتابیس به زمان قبل از اجرای اولین دستور بازگردد گویی اصلاً تراکنش اجرا نشده. یعنی تمام دستورات داخل یک تراکنش واحد باید به صورت همه یا هیچ اجرا شود.  در کد زیر یک روش برای اجرای تراکنش ها در Room را می بینید:

((MyDatabaseApplication) getApplicationContext()).getMyDatabase().runInTransaction(new Runnable() {
  @Override
  public void run() {
    UserDao userDao = ((MyDatabaseApplication) getApplicationContext()).getMyDatabase().userDao();
    userDao.insertOrganization(organization);
    userDao.insertUser(user);
  }
});

پرسش های متداول

چگونه نوع داده (int ، text) را مشخص می کنید؟ آیا Room به طور خودکار می داند نوع ستون باید چگونه باشد؟

نوع داده هر ستون به طور خودکار از نوع داده ای که داخل کلاس استفاده می کنید مشخص می شود.

چگونه می توانم تاریخ و زمان را در Room ذخیره کنم؟

Room از مبدل های نوع پشتیبانی می کند.

نوع داده در کلاس را از نوع Date مشخص کنید:

@ColumnInfo
Date timestamp;

سپس می توانید یک کلاس DataConverter مشابه کلاس زیر تعریف کنید:

// Mohamadreza Amani
// Email: help4usr@gmail.com
public class DateConverter {
    @TypeConverter
    public static Date toDate(Long timestamp) {
        return timestamp == null ? null : new Date(timestamp);
    }

    @TypeConverter
    public static Long toTimestamp(Date date) {
        return date == null ? null : date.getTime();
    }
}

این کلاس نوع های Date و Long را به هم تبدیل می کند. Room با کمک این کلاس نوع داده Long را در دیتابیس ذخیره می کند ولی در کلاس شما نوع داده Date را به شما ارائه می دهد.

تفاوت ROOM با سایر کتابخانه های  ORM چیست؟

ORM مخفف Object Relational Mapping است و به کتابخانه هایی گفته می شود که دیتابیس را به صورت شی هایی داخل کد برنامه در دسترس قرار می دهند. چند جنبه اساسی در Room وجود دارد که با روش سنتی استفاده شده در کتابخانه های تبدیل جداول دیتابیس به اشیا (کتابخانه های ORM) متفاوتند:

• معمولاً کتابخانه های ORM زیر مجموعه ای از دستورات SQL را فراهم می کنند. جداول به صورت اشیای جاوا تعریف می شوند و رابطه بین این جداول مشخص می کنند که چه نوع دستوراتی از SQL را می توان استفاده کرد. در Room دستورات SQL برای وارد کردن داده ها ،  به روز رسانی داده ها ، حذف کردن داده ها و اتصالات (join) پیچیده بین جداول به صورت اشیای مخصوص دسترسی به داده ها (DAO) تعریف می شوند. DAO مخفف عبارت Data Access Object است. داده هایی که از این کوئری ها بدست می آید به شی های جاوا تبدیل می شوند و داخل حافظه قرار می گیرند تا دسترسی به آنها راحت تر باشد.  به این ترتیب ، هیچ فرضی در مورد چگونگی دسترسی به داده ها وجود ندارد و تعاریف جداول جدا از کوئری های واقعی انجام می شود.
• ORM ها معمولاً رابطه های « یک به یک » و « یک به چند » داخل دیتابیس را به صورت رابطه بین جداول مدیریت می کنند و Interface ها یا مجموعه ای از رابط ها فراهم می کنند که در پشت صحنه کوئری های SQL را اجرا می کنند. به دلیل فراهم کردن کارایی بیشتر Room برخلاف این روش تعریف صریح این ارتباطات را اجباری کرده است. پس در Room کوئری باید به صورت اشیای DAO تعریف شود و داده هایی که از این DAO ها بدست می آید باید به شکل صریح به اشیای مناسب جاوا تبدیل شوند.
• یک تفاوت دیگر این است که Room نیازی به تعریف جداول SQL شما به عنوان یک شی منفرد جاوا ندارد و با اجازه دادن به تعریف سایر اشیا Java جاوا به عنوان جزئی از یک جدول امکان حفظ کپسوله سازی اشیا (قرار دادن هر شی با تمام اجزای آن درون یک کلاس) را فراهم می کند. دستورات ابتدایی ایجاد، خواندن، به روز رسانی و حذف داده ها (CRUD) باید داخل شی مخصوص به دسترسی به داده ها (DAO) قرار گیرد. یک تفاوت عمده در این است که نمی توان پرس و جوها را در Thread اصلی انجام داد. علاوه بر این ، می توان اشیا را با AsyncTask یا با استفاده از روش runInTransaction وارد کرد.