کار با اشیاء - Android

پیش‌نیازها

  1. در صورتی که با سرویس پایگاه‌داده آشنایی ندارید، به معرفی سرویس پایگاه‌داده مراجعه کنید.
  2. در صورتی که هنوز در پنل توسعه‌دهنده خود تنظیمات لازم برای سرویس پایگاه‌داده خود را انجام نداده‌اید، به تنظیمات پنل مراجعه کنید.
  3. در صورتی که هنوز SDK اندروید را راه‌اندازی نکرده‌اید، به راه‌اندازی SDK بکتوری در اندروید مراجعه کنید.

راه‌اندازی سرویس پایگاه‌داده

در ابتدا برای آن که بتوانید اعمال مربوط به پایگاه داده را به کمک SDK بکتوری انجام دهید، می‌بایست در قسمت راه‌اندازی SDK تابع setObjectStorageKey را اضافه کنید:

// Extending android application to initialize backtory
public class MainApplication extends Application {
    @Override
    public void onCreate(){
        super.onCreate();
        BacktoryClient.init(KeyConfiguration.newBuilder().
            setAuthKeys("<X-Backtory-Authentication-Id>",
                        "<X-Backtory-Authentication-Key (Client)>").
            setObjectStorageKey("<X-Backtory-Object-Storage-Id>").
            build(), this);
    }
}

نکته‌ی مهم: دقت کنید که برای کار با سرویس دیتابیس باید در بکتوری لاگین کنید. در صورتی که با نحوه‌ی لاگین کردن به کمک sdk بکتوری آشنایی ندارید، این‌جا را مشاهده کنید.

کار با اشیاء

ذخیره‌ی یک شیء

فرض کنید که در حال نوشتن برنامه‌ی مدیریت یادداشت‌های روزانه هستید و می‌خواهید یادداشت‌ها کاربر در برنامه را در سرور ذخیره کنید. ابتدا مطابق این‌جا در پنل یک جدول برای یادداشت‌ها بسازید (مثلا به نام Note). هر سطر این جدول متناظر یادداشت یکی از کاربران برنامه شما خواهد بود. یک یادداشت جدید می‌تواند به صورت زیر باشد:

title: "Checkout Backtory MBaaS",
content: "Wow! Take a look at backtory.com",
pinned: true

این یادداشت را با استفاده از کلاس BacktoryObject به صورت زیر بسازید:

BacktoryObject note = new BacktoryObject("Note");
note.put("title", "Checkout Backtory MBaaS");
note.put("content", "Wow! Take a look at backtory.com");
note.put("pinned", true);

دقت کنید که رشته‌ای که به Constructor کلاس BacktoryObject پاس می‌دهید، باید دقیقا نام جدولی باشد که در پنل تعریف کرده‌اید. پیشنهاد ما این است که نام جداول را مطابق LikeThis و نام ستون‌های جداول را مطابق likeThis بگذارید.

بعد از آن‌که شیء یادداشت را به وجود آوردید، ‌ قصد دارید که آن را در سمت سرور ذخیره کنید. برای این کار می‌توانید از کد زیر استفاده کنید:

note.saveInBackground(new BacktoryCallBack<Void>() {
    @Override
    public void onResponse(BacktoryResponse<Void> response) {
        if (response.isSuccessful()){
            // successful save. good place to show a toast
        }
        else {
            // see response.message() to know the cause of error
        }
    }
});

بازیابی یک شیء

هر داده‌ای که در دیتابیس ذخیره شود، یک شناسه منحصر به فرد خواهد گرفت. چنانچه شما این شناسه را داشته باشید، می‌توانید به راحتی آن شیء را از سرور بازیابی (retrieve) کنید. فرض کنید که یادداشتی که در مرحله قبل ذخیره کردیم، شناسه 58f48d0c5169da0001adf3db را گرفته باشد. در این صورت، برای گرفتن این شیء مطابق زیر عمل می‌کنیم: (برای بازیابی یک یا مجموعه‌ای از اشیاء، وقتی از شناسه‌ی آنها اطلاع ندارید، به بخش جستارها مراجعه کنید.)

BacktoryQuery noteQuery = new BacktoryQuery("Note");
noteQuery.getInBackground("58f48d0c5169da0001adf3db",
    new  BacktoryCallBack<BacktoryObject>() {
    @Override
    public void onResponse(BacktoryResponse<BacktoryObject> response) {
        if (response.isSuccessful()) {
            BacktoryObject note = response.body();

            // get note data by calling get functions on received BacktoryObject
            // for example, titleTextView.setText(note.getString("title"))

        } else {
            // see response.message() to know the cause of error
        
}
    }
});

اکنون که به شیء note مطابق بالا دست یافته‌ایم، می‌خواهیم مقادیر ستون‌های مختلف را به ازای این BacktoryObject ببینیم. این کار مطابق زیر به کمک دستور getX به ازای هر داده‌گونه قابل انجام است:

String title = note.getString("title");
String content = note.getString("content");
boolean pinned = note.getBoolean("pinned");

به‌روزرسانی یک شیء

بسیار محتمل است که کاربر بخواهد یادداشتش را تغییر دهد. با فرض داشتن BacktoryObject متناظر آن (مثلا بازیابی با شناسه مانند قسمت قبل) کافیست برای دستیابی به این هدف، مقادیر ستون‌هایی را که می‌خواهیم، تغییر دهیم و مجددا از تابع saveInBackground استفاده کنیم. به صورت زیر:

note.put("title", "USE BACKTORY NOW!");
note.put("pinned", false);
note.saveInBackground(new BacktoryCallBack<Void>() {
    @Override

    public void onResponse(BacktoryResponse<Void> response) {

        if (response.isSuccessful()) {
            // object is updated on server
        } else {
            // see response.message() to know the cause of error
        }
    }
});

شمارنده‌ها

در مثال بالا یک نیاز متداول دیده می‌شود؛ اضافه کردن مقدار یک فیلد BacktoryObject. این عمل باید مستقل از مقدار فعلی این فیلد باشد. به طور مثال فرض کنید دو همدست (collaborator) به طور همزمان این یادداشت را میخوانند، فرض کنید تعداد دفعات تغییر این یادداشت در آن لحظه 5 باشد، بعد از اینکه هر دو همدست تغییراتی در فایل اعمال کردند، اگر بخواهیم مانند روش بالا عمل کنیم، عدد 6 برای یادداشت در دیتابیس ذخیره خواهد شد، اما می‌دانیم که در حقیقت عدد 7 باید ثبت می‌شد.

جهت ذخیره کردن فیلدهایی از جنس شمارندها، بکتوری توابع Atomicای برای زیاد کردن و کم کردن شمارنده‌ها فراهم می‌کند. مثال بالا را می‌توان به صورت زیر بازنویسی کرد:

note.increment("editCount");

مقدار اضافه یا کم شدن را نیز می‌توان با استفاده از تابع (increment(key, amount تعیین کرد.

حذف یک شیء

برای حذف یک شیء در سرور، با فرض داشتن BacktoryObject متناظر آن به شیوه‌ی زیر عمل می‌کنیم:

note.deleteInBackground(new BacktoryCallBack<Void>() {

    @Override

    public void onResponse(BacktoryResponse<Void> response) {

        if (response.isSuccessful()) {
            
// note is deleted on server
        }
 else {

            // see response.message() to know the cause of error

        }
    }
});

کار با آرایه‌ها

می‌توان در BacktoryObject یک آرایه را به عنوان مقدار یک فیلد گذاشت. مثلا فرض کنید که امکان اضافه کردن هم‌دست (collaborator) به یک یادداشت وجود دارد. به صورت زیر:

note.put("collaborators", Arrays.asList("Alireza Farahani", "Javad Abedi",
                        "Mohammad Mesbah");
note.saveInBackground(new BacktoryCallBack(){…});

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

note.addUnique("collaborators", "Mohammad Taheri");
note.saveInBackground(new BacktoryCallBack(){…});

چنان‌چه عضو تکراری (مثلا “Javad Abedi”) پاس داده بودیم، محتویات collaborators تغییری نمی‌کرد.

اکنون می‌خواهیم یک یا چند هم‌دست را حذف کنیم:

note.removeAll("collaborators", Arrays.asList("Mohammad Mesbah", "Mohammad Taheri"));
note.saveInBackground(new BacktoryCallBack(){…});

هنگامی که بخواهیم هم‌دست‌ها را بازیابی کنیم، به شیوه‌ی زیر عمل می‌کنیم:

List<String> collaborators = note.getList("collaborators");

به طور خلاصه:

داده‌گونه‌ها

در حال حاضر به یک BacktoryObject می‌توان داده‌هایی از جنس زیر اضافه کرد:

دقت کنید که امکان تودرتو کردن (nested) لیست و نگاشت وجود دارد.

پاک کردن تغییرات

تابع (revert(String key از یک BacktoryObject تمامی تغییرات اعمال شده روی “فیلد متناظر با key” را پاک کرده و آنرا به آخرین وضعیت پایدار بر‌می‌گرداند؛ یعنی، اگر شیء قبلا در سرور ذخیره شده بوده، به ورژن سرور برمی‌گرداند و در غیر این صورت فیلد را حذف می‌کند. تابع ()revert نیز همان عمل تابع (revert(String key را برای تمامی فیلدهای BacktoryObject انجام می‌دهد.

فیلدهای خاص

هر BacktoryObjectای که در سرور ذخیره شود، یا از سرور بازیابی شود، یک سری فیلد ثابت خواهد داشت که شما قادر به تغییر آنها نیستید، ولی می‌توانید از طریق توابع زیر آن‌ها را ببینید:

گام بعدی