021a - פרסום חדרי משחק ב־Firebase RTDB

כל נתוני הדוגמה יישמרו תחת ענף נפרד:

/TicTacToeRtdb

אם בקובץ החוקים שלכם אין כלל כללי בשם $key, אפשר להוסיף תחת rules:

"TicTacToeRtdb": {
  ".read": true,
  ".write": true
}

במסד הנתונים המשותף של הפרויקט כבר קיים כלל כללי בשם $key. כללי Firebase החופפים אינם מסננים זה את זה, ולכן במקרה הזה לא מוסיפים לידו כלל נוסף. מעדכנים את הכלל הקיים כך:

"$key": {
  ".read": "$key.endsWith('*' + auth.uid)",
  ".write": "$key.endsWith('*' + auth.uid)"
}

"$key": {
  ".read": "$key === 'TicTacToeRtdb' || $key.endsWith('*' + auth.uid)",
  ".write": "$key === 'TicTacToeRtdb' || $key.endsWith('*' + auth.uid)"
}

איזו מחלקה זו, והיכן כבר פגשנו דבר דומה?

המחלקה היא GameRoom, המופיעה בשלמותה למעלה. היא נוספה לשיעור 021a בקומיט 4697c9a מ־31.8.2026, ולפרויקט TicTacMenu בקומיט 0f6d018 מאותו תאריך (implemented 021a). שיעור 021b נוסף בקומיט c03b570 ומשתמש באותה מחלקה כדי לקרוא שחקנים ומהלכים; הוא אינו מוסיף מחלקת נתונים אחרת.

ב־Presence המקבילה הקטנה והישירה ביותר היא Obj/User.java: שדות פרטיים, בנאי ריק, בנאי מלא ו־getters/setters. גם Obj/Task.java משתמשת באותה שיטה לשמירת משימות ולקריאת רשימה מתעדכנת. models/Student.java מכילה הרבה יותר זוגות כאלה. לעומתן, מסך הנוכחות PresenceActivity מרכיב חלק מנתוניו באמצעות Map וקורא ענפים ידנית; זה כנראה החלק שנראה שונה כשעובדים על הנוכחות עצמה.

זו הרחבת קריאה והשוואה, ללא שינוי נוסף בפרויקט Android. קטעי Presence מובאים כאן כדי שאפשר יהיה ללמוד בלי גישה למאגר האחר. הם נבדקו בקוד המקומי ב־14.9.2026 (HEAD: cdf2425); דוגמאות הנתונים בהסבר מומצאות. קוד המשחק של 021b הוא המשך מתועד: פרויקט TicTacMenu שנבדק עדיין נמצא בסוף 021a.

אפשר לקרוא לפי הסדר, או לדלג אל בחירת שיטת הייצוג ואל בדיקת ההבנה. אחרי השיחה בין שתי האפליקציות נעקוב בתרשימי שני המכשירים ב־021b.

מחלקה שנראית כמו ממשק — אבל היא אובייקט ממשי

GameRoom היא POJO — מחלקת Java רגילה — המשמשת כאן כ־DTO, אובייקט להעברת נתונים. אלו תיאורי תפקיד, לא מילות מפתח שצריך לכתוב ב־Java. הצורה של בנאי ריק ומאפיינים עם getters/setters מוכרת גם כסגנון JavaBean.

interface מתאר חוזה שאחרים מממשים. אי אפשר לכתוב new SomeInterface() כדי ליצור ישירות מופע שלו. לעומת זאת, new GameRoom(...) יוצר מופע עם ארבעה שדות, והמתודות שלו כבר ממומשות. דווקא ValueEventListener שבהמשך הוא ממשק: המחלקה האנונימית new ValueEventListener() { ... } מממשת את שתי מתודות האירוע.

למשל, room.setPlayerO("uid-o") משנה את room בזיכרון בלבד. הוא לא כותב למסד, לא מוסיף מאזין ולא מודיע למכשיר אחר. גם שינוי ה־snapshot לא נעשה דרך האובייקט שהופק ממנו. לשמירה צריך פעולה מפורשת על הפניה למסד.

המקבילה המדויקת ב־Presence: User

להלן גוף המחלקה המלא, כולל כל הבנאים והמתודות. רק שורת ה־package ותיעוד המחבר שבראש הקובץ הושמטו. הקרדיט המופיע במקור: Albert Levy.

מקור: Presence — Obj/User.java, שורות 12–69.

public class User {
    private String uid;
    private String username;

    /**
     * Default constructor for the User class.
     * Initializes a new User object with null values for UID and username.
     * This constructor is often used by data mapping frameworks like Firebase.
     */
    public User() {}

    /**
     * Constructs a new User object with the specified UID and username.
     *
     * @param uid The unique identifier for the user.
     * @param username The username of the user.
     */
    public User(String uid, String username) {
        this.uid = uid;
        this.username = username;
    }

    /**
     * Gets the unique identifier (UID) of the user.
     *
     * @return The UID string of the user.
     */
    public String getUid() {
        return uid;
    }

    /**
     * Sets the unique identifier (UID) of the user.
     *
     * @param uid The new UID string for the user.
     */
    public void setUid(String uid) {
        this.uid = uid;
    }

    /**
     * Gets the username of the user.
     *
     * @return The username string of the user.
     */
    public String getUsername() {
        return username;
    }

    /**
     * Sets the username of the user.
     *
     * @param username The new username string for the user.
     */
    public void setUsername(String username) {
        this.username = username;
    }
}

זו אותה טכנולוגיה כמו GameRoom. ההבדל הוא במספר המאפיינים ובמשמעותם. ב־MainActivity של Presence הקריאה היא tsk.getResult().getValue(User.class); ב־LoginActivity הכתיבה היא refUsers.child(uid).setValue(userdb). בשני הכיוונים Firebase ממפה אובייקטים, ללא JSONObject וללא Gson בקוד הזה.

למה Presence משתמשת ב־User ו־TicTacMenu מסתדרת בלעדיה?

כן, בשלב הנוכחי ההבדל נובע מן המידע שהאפליקציה צריכה. במשחק אנחנו צריכים לזהות מי מחובר ומי משחק X או O; ב־Presence שומרים גם שם משתמש של היישום וקוראים אותו להצגה. אבל עצם קיומו של מסך פרופיל אינו מחייב מחלקה משלנו: אפשר להציג פרטים בסיסיים מתוך FirebaseUser, ואפשר לשמור פרופיל באמצעות Map.

שני סוגים שונים של “משתמש”

ה־Users שבתפריט Authentication ב־Firebase Console אינו הענף /Users של Realtime Database. יצירת חשבון ב־Authentication אינה יוצרת אוטומטית רשומה בענף שבחרנו במסד. הקוד של Presence מבצע את שתי הפעולות במפורש.

Presence: יוצרים חשבון, שומרים פרופיל, ואז קוראים אותו

לאחר הצלחת createUserWithEmailAndPassword, קטע ההצלחה בהרשמה מבצע:

מקור: Presence — Activities/LoginActivity.java, שורות 425–432.

FirebaseUser user = getUserAndSetUidFromFBuserAndStoreLast("createUserWithEmail:success");
userdb = new User(uid, name);
refUsers.child(uid).setValue(userdb);
settings.edit()
        .putBoolean("stayConnect", cBstayconnect.isChecked())
        .apply();
Toast.makeText(LoginActivity.this, "Successful registration", Toast.LENGTH_SHORT).show();
setActiveYear();

getUserAndSetUidFromFBuserAndStoreLast(...) מקבלת את חשבון Firebase ומעדכנת את ה־UID המקומי. אחר כך new User(uid, name) יוצרת אובייקט נתונים משלנו, ו־setValue(userdb) מבקשת לשמור אותו. לדוגמה, נתונים מומצאים בנתיב /Users/uid-demo ייראו כך:

{
  "uid": "uid-demo",
  "username": "Demo Teacher"
}

אותו UID מחבר בין החשבון לרשומה. שמירתו גם בתוך הרשומה היא בחירת המודל של Presence; אפשר לתכנן מודל שבו המזהה מתקבל רק ממפתח ה־snapshot. בכניסה עם Google, firebaseAuthWithGoogle(...) יוצרת רשומה כזו רק כאשר isNewUser() מחזירה true, ומשתמשת בשם שמגיע מחשבון Google. למשתמש Google קיים היא ממשיכה לאפליקציה בלי לכתוב מחדש את הפרופיל.

ב־MainActivity הפרופיל נקרא כדי להציג ברכה. זהו כל קטע הקריאה וה־callback:

מקור: Presence — Activities/MainActivity.java, שורות 129–140.

refUsers.child(FBRef.uid).get().addOnCompleteListener(new OnCompleteListener<DataSnapshot>(){
    @Override
    public void onComplete(@NonNull com.google.android.gms.tasks.Task<DataSnapshot> tsk) {
        if (tsk.isSuccessful()) {
            user = tsk.getResult().getValue(User.class);
            tVMainHeader.setText("Hi "+user.getUsername()+",\nYour active tasks:");
        }
        else {
            Log.e("firebase", "Error getting data", tsk.getException());
        }
    }
});

getValue(User.class) מפיקה את האובייקט, ו־getUsername() נותנת את השם לכותרת המסך. זו התועלת המעשית של User כאן. המחלקה אינה מבצעת את הכניסה, אינה שומרת סיסמה ואינה מנהלת את רשימת המשימות.

בקטע ההרשמה אין המתנה לאישור כתיבת הפרופיל, ובקטע הקריאה אין בדיקה שהרשומה קיימת לפני user.getUsername(). לכן חשבון Auth יכול להתקיים גם אם כתיבת הפרופיל נכשלה; קריאה מוצלחת של נתיב ריק עדיין יכולה להחזיר null. באפליקציה שמטפלת במצב הזה צריך מסלול השלמת פרופיל וטיפול בכשל כתיבה. isNewUser() לבדו אינו בדיקה לקיום הרשומה ב־RTDB.

הפרופיל של Presence רחב יותר ממחלקת User

ProfileActivity מטפלת גם בשנה הפעילה (activvvYear, כך מאוית המפתח בקוד), במסך המועדף, בשפה, בתמונה ובקישור לגיליון תלמידים. אלה אינם שדות במחלקת User שהצגנו. היא קוראת וכותבת אותם ישירות תחת הפניית המשתמש. למשל, זו כל המתודה לשינוי שפה:

מקור: Presence — Activities/ProfileActivity.java, שורות 201–223.

private void changeLanguage(String selectedLanguage) {
    // Save to SharedPreferences
    languagePrefs.edit()
            .putString(SELECTED_LANGUAGE, selectedLanguage)
            .apply();

    // Save to Firebase for sync across devices
    userRef.child("preferredLanguage").setValue(selectedLanguage);

    // Apply language change using LanguageHelper
    String languageCode;
    if (selectedLanguage.equals("עברית")) {
        languageCode = "he";
    } else {
        languageCode = "en";
    }

    // Use the LanguageHelper to set locale properly
    LanguageHelper.setLocale(this, languageCode);

    // Restart the activity to apply changes
    recreate();
}

העדפת השפה נשמרת מקומית וגם ב־/Users/{uid}/preferredLanguage. זה מדגים ששתי הגישות יכולות להתקיים באותו פרופיל: DTO קטן לקריאה מסוימת, וגישה ישירה לילדים לצרכים אחרים. שינוי שפת הממשק עצמו נעשה ב־LanguageHelper וב־recreate(), לא באמצעות הכתיבה למסד.

מכאן גם מגבלה חשובה: לא כדאי לשמור מאוחר יותר new User(uid, name) עם setValue על כל /Users/{uid} רק כדי לשנות שם. האובייקט מכיל שני מאפיינים בלבד, ולכן ההחלפה עלולה להסיר את העדפות הפרופיל האחרות. לשינוי שם בלבד מתאים עדכון ממוקד של username; זו אותה הבחנה בין החלפה לעדכון שנלמד בהמשך.

TicTacMenu: ה־UID מספיק לתפקיד של השחקן

ב־Main2Activity של סוף 021a מופיע הקטע הבא:

מקור: TicTacMenu — activities/Main2Activity.java, שורות 61–68.

FirebaseUser currentUser = FBRef.refAuth.getCurrentUser();
if (currentUser == null) {
    Toast.makeText(this, R.string.rtdb_login_required, Toast.LENGTH_SHORT).show();
    finish();
    return;
}

currentUid = currentUser.getUid();

בהמשך נוצרת new GameRoom(gameName, currentUid, "", ""), ולכן ה־UID של היוצר נשמר ב־playerX. ב־021b המצטרף נשמר ב־playerO, וכל מכשיר משווה את ה־currentUid שלו לשני השדות כדי להחליט אם הוא X, O או צופה. אין צורך בשם, בתמונה או בהעדפות כדי לבצע את ההשוואה הזאת; גם name של GameRoom הוא שם החדר, לא שם המשתמש.

למרות השם, FBRef.getUser(...) של TicTacMenu אינה קוראת רשומת User מהמסד. זו כל המתודה, כפי שנלמדה גם ב־018c:

מקור: TicTacMenu — services/FBRef.java, שורות 32–41.

public static void getUser(FirebaseUser fbuser) {
    if (fbuser == null) {
        uid = null;
        refUser = null;
        return;
    }

    uid = fbuser.getUid();
    refUser = refUsers.child(uid);
}

השורה refUser = refUsers.child(uid) רק בונה הפניה ל־/Users/{uid}. אין בה get(), מאזין או כתיבה, והיא אינה מוכיחה שקיים שם מידע. במצב הפרויקט שנבדק, ProfileFragment מנפחת layout עם הטקסט hello_blank_fragment; היא עדיין אינה טוענת או עורכת פרופיל. לכן קיום כפתור “Profile”, מחלקת Fragment או הפניה בשם refUser אינו מעיד שכבר מימשנו שמירת פרופילים.

מתי נוסיף פרופיל משלנו?

Firebase Authentication כבר מציע פרטי פרופיל בסיסיים. אם נבחר להעתיק את השם ל־RTDB, כפי ש־Presence עושה בהרשמת Google, יהיו שני מקומות שמחזיקים שם; צריך להחליט מי מקור האמת והאם שינוי באחד יעדכן גם את האחר. אין ביניהם סנכרון אוטומטי שהקוד המצוטט מגדיר. מקור: פרטי המשתמש ועדכון פרופיל ב־Firebase Authentication.

ההחלטה היא לפי הנתונים הדרושים: כרגע TicTacMenu צריכה זהות ונתוני חדר, ולכן FirebaseUser יחד עם GameRoom מספיקים. כשנוסיף מידע ייחודי לשחקן, נבחר איך לשמור ולמפות אותו. גם אז User משלנו ישלים את Authentication; הוא לא יחליף אותו, וה־UID הכתוב ברשומה לא יחליף בדיקת הרשאות בשרת.

Task מוסיפה גם int year,‏ boolean fullClass, ובדיקות עזר equals(Task) ו־isIn(ArrayList<Task>). המתודות האלה הן לוגיקה מקומית ואינן נשלחות לענן. equals(Task) היא העמסה ייעודית, לא דריסה של equals(Object) לכל אוספי Java; זו הבחנה ב־Java, שאינה נדרשת למיפוי RTDB.

מה באמת עובר בין Java לעץ JSON?

הביטוי הבא יוצר רק אובייקט מקומי:

GameRoom room = new GameRoom("Demo", "uid-x", "", "");

לאחר newRoomReference.setValue(room) התוכן בכתובת החדר יהיה:

{
  "name": "Demo",
  "playerX": "uid-x",
  "playerO": "",
  "moves": ""
}

אין בנתונים שם מחלקה, בנאים או קוד של מתודות. מפתח החדר נמצא מעל האובייקט: מקבלים אותו באמצעות roomSnapshot.getKey(). הוא אינו מוכנס אוטומטית לאחד משדות GameRoom. גם שם להצגה אינו מזהה ייחודי; שני חדרים יכולים להיקרא Demo.

ה־SDK משתמש ב־reflection: הוא בוחן את מבנה המחלקה בזמן ריצה ומפעיל את הבנאי והגישה למאפיינים. ב־GameRoom אנו בוחרים בנאי ריק ומאפיינים עם getter ו־setter. זו צורה קריאה וצפויה; אין חובה גורפת לכתוב setter לכל שדה בכל מודל Firebase. הממפה תומך גם בשדות ציבוריים, ובנסיבות מתאימות בהשמה לשדה מזוהה גם בלי setter. העיקר הוא מבנה נתונים שהממפה יודע לכתוב ולשחזר. מקור: הממפה של Firebase Android.

לשחזור אובייקט נדרש בנאי ללא פרמטרים. כשאין במחלקה שום בנאי מפורש, Java יוצרת בנאי ברירת מחדל; כך קורה ב־Student. כשמוסיפים בנאי עם פרמטרים, הבנאי הזה כבר אינו נוצר אוטומטית — ולכן כתבנו גם public GameRoom(). אין לשים בבנאי הזה התחברות לרשת או פעולות מסך: ה־SDK מפעיל אותו במהלך המיפוי.

השמות המקצועיים: serialization ו־deserialization

כן — יצירת האובייקט ומילויו בזמן הקריאה הם deserialization. בכיוון ההפוך, המרת נתוני האובייקט לצורה שאפשר לשמור ולהעביר היא serialization:

הבנאי הריק משתתף בכיוון הקריאה והשחזור. בכיוון הכתיבה כבר יש לנו אובייקט room, ולכן הממפה קורא ממנו את הערכים ואינו צריך ליצור חדר חדש בבנאי הריק. במימוש הנוכחי שלנו הוא משתמש ב־getters לכתיבה וב־setters למילוי האובייקט בקריאה.

דיוק קטן: כאשר אנחנו מקבלים DataSnapshot, ה־SDK כבר טיפל בקבלת הנתונים ובפענוח התקשורת. getValue(GameRoom.class) ממפה את המבנה שב־snapshot למחלקת Java מסוימת; הקוד שלנו אינו מקבל מחרוזת JSON גולמית ומפרק אותה ידנית. אפשר לתאר זאת כ־deserialization לאובייקט מטיפוס מוגדר. מקור: getValue ומיפוי למחלקה ב־DataSnapshot.

המונח serialization אינו אומר שצריך להוסיף implements Serializable. java.io.Serializable שייך למנגנון הסריאליזציה של Java, ואילו כאן Firebase משתמש בממפה שלו. גם Parcelable אינו דרישה של RTDB. הקריאות הרגילות שלנו ל־room.getMoves() או ל־room.setMoves(...) הן גישה מקומית לשדה; לבדן הן אינן שומרות, קוראות או מסנכרנות נתונים עם המסד.

חשוב להפריד בין JSON כמבנה נתונים לבין טקסט שמכיל JSON. RTDB שומר עץ JSON; כשמשתמשים ב־SDK, בדרך כלל מוסרים אובייקטים, מפות, רשימות וערכים פשוטים, וה־SDK מטפל בהמרה. לא צריך לבנות מחרוזת JSON בעצמנו. מקור: מבנה הנתונים ב־RTDB.

אותו דפוס גם למשימות: כותבים אובייקט, קוראים אובייקטים

זו כל המתודה confirmation ב־Presence. המשתנים שמגיעים מהמסך כבר קיימים ב־Activity; refTasks הוא ענף המשימות. הפרמטרים לבנאי Task הם תאריכי התחלה וסיום, כיתה, מספר משימה, שנה והאם המשימה לכל הכיתה.

מקור: Presence — Activities/TaskActivity.java, שורות 247–277.

public void confirmation(View view) {
    int taskNum = Integer.parseInt(eTTaskNum.getText().toString());
    serNum = String.format("%02d",taskNum);
    if (startDate == null || dueDate == null || className == null || serNum == null) {
        Toast.makeText(this, "Missing data", Toast.LENGTH_SHORT).show();
    } else {
        Task newTask = new Task(startDate, dueDate,className, serNum, activeYear, cbFullClass.isChecked());
        if (!isNewTask) {
            refTasks.child(String.valueOf(activeYear))
                    .child(String.valueOf(!task.isFullClass()))
                    .child(task.getDateEnd())
                    .child(task.getClassName()+task.getSerNum())
                    .removeValue();
            refTasks.child(String.valueOf(activeYear))
                    .child(String.valueOf(!cbFullClass.isChecked()))
                    .child(dueDate)
                    .child(className+serNum)
                    .setValue(newTask);
            finish();
        } else if (newTask.isIn(MainActivity.tasksList)) {
            Toast.makeText(this, "Task already exist!", Toast.LENGTH_SHORT).show();
        } else {
            refTasks.child(String.valueOf(activeYear))
                    .child(String.valueOf(!cbFullClass.isChecked()))
                    .child(dueDate)
                    .child(className+serNum)
                    .setValue(newTask);
            finish();
        }
    }
}

בדומה לחדר, מחליטים בנפרד איפה לכתוב (child(...)) ומה לכתוב (newTask). כאן המפתח נגזר מנתוני המשימה; אצלנו push() מייצר מפתח חדש. המבנה המקונן מסביר מדוע הקורא בהמשך עובר בשלוש לולאות: קבוצה, תאריך ומשימה.

לעומת זאת, ב־startGameAndWait() שלנו הודעת ההצלחה ב־021a, וב־021b פתיחת החדר, נמצאות ב־addOnSuccessListener. זו הפרדה טובה יותר בין התחלת הבקשה להצלחתה. להלן כל קטע יצירת המאזין ורישומו מתוך onCreate של Presence:

מקור: Presence — Activities/MainActivity.java, שורות 141–160.

vel = new ValueEventListener() {
    @Override
    public void onDataChange(@NonNull DataSnapshot dS) {
        tasksList.clear();
        for(DataSnapshot dataFull : dS.getChildren()) {
            for(DataSnapshot dataDate : dataFull.getChildren()) {
                for(DataSnapshot data : dataDate.getChildren()) {
                    tasksList.add(data.getValue(Task.class));
                }
            }
        }
        taskAdp.notifyDataSetChanged();
        if (pd != null) {
            pd.dismiss();
        }
    }
    @Override
    public void onCancelled(@NonNull DatabaseError error) {}
};
refTasks.child(String.valueOf(activeYear)).addValueEventListener(vel);

השוו ל־listenForRooms() בשיעור הזה: ניקוי רשימה, מעבר על ילדים, המרה באמצעות getValue(SomeClass.class), ולבסוף הודעה ל־adapter. שני הקטעים בונים מחדש את הרשימה מתוך צילום מלא. זו בחירה פשוטה וסבירה לרשימה קטנה. ב־Presence ענף onCancelled כאן ריק; אצלנו מוצגת שגיאה, ולכן קל יותר להבחין בין חוסר הרשאה לבין רשימה שאין בה פריטים. בשני הקטעים כדאי, כשמקשיחים את האפליקציה, לטפל גם בנתון חסר ובכשל המרה במקום להניח שכל ילד תקין.

בחירת POJO אינה גורמת לזמן אמת. המאזין הוא שמספק את העדכונים. Presence טוענת תלמידים ב־FBRef באמצעות addListenerForSingleValueEvent, ומסך הנוכחות משתמש באותה צורת קריאה כדי לשחזר שיעור קיים. הקריאה הזו מסתיימת אחרי אירוע אחד. לעומתם, addValueEventListener ממשיך להאזין עד הסרתו. get() מחזיר בקשת קריאה בודדת כ־Task, לא אובייקט זמין מיד. מקור: קריאה והאזנה ב־Android.

החלק שבאמת שונה: נוכחות שנבנית באמצעות Map

studentStatus היא מפה מקומית מכינוי תלמיד למצב; disturbanceSet היא קבוצה נפרדת של הפרעות; rawTranscripts היא רשימת התמלולים. המתודה הבאה בונה מהם רשומה אחת של שיעור. זו המתודה המלאה, ללא השמטות פנימיות:

מקור: Presence — Activities/PresenceActivity.java, שורות 688–733.

private void pushRawTranscript(String newEntry) {
    if (currentTimestampAndLesson == null) {
        Log.e("PresenceActivity", "currentTimestampAndLesson is null");
        return;
    }

    Map<String, Object> payload = new HashMap<>();
    payload.put("class", detectedClassName);

    // Group by status using English constants, but EXCLUDE ON_TIME
    Map<String, List<String>> grouped = new HashMap<>();
    for (Map.Entry<String, String> e : studentStatus.entrySet()) {
        String statusKey = e.getValue();
        // Skip ON_TIME students - we don't want them in Firebase
        if (!StudentStatus.ON_TIME.equals(statusKey)) {
            grouped.computeIfAbsent(statusKey, k -> new ArrayList<>()).add(e.getKey());
        }
    }

    // Push structured status data using English keys for DB (excluding ON_TIME)
    Map<String, Object> statusMap = new HashMap<>();
    for (Map.Entry<String, List<String>> entry : grouped.entrySet()) {
        List<String> names = entry.getValue();
        if (names != null && !names.isEmpty()) {
            // Use English constant as key in database (ON_TIME already excluded above)
            statusMap.put(entry.getKey(), names);
        }
    }

    // Only add statusSummary if there are actual statuses to report
    if (!statusMap.isEmpty()) {
        payload.put("statusSummary", statusMap);
    }

    if (!disturbanceSet.isEmpty()) {
        payload.put("disturbances", new ArrayList<>(disturbanceSet));
    }

    payload.put("rawTranscript", rawTranscripts);

    refPresUidCurrentWeek
            .child(currentTimestampAndLesson)
            .setValue(payload)
            .addOnSuccessListener(unused -> Log.i("PresenceActivity", "Upload success"))
            .addOnFailureListener(e -> Log.e("PresenceActivity", "Upload failed", e));
}

כאן אין AttendanceRecord עם getters/setters. payload.put(...) בונה במפורש את שמות הענפים. למשל, הנתונים המומצאים הבאים מתארים מבנה אפשרי; ABSENT ו־LATE משמשים כאן כשמות המחשה לקבועי המצבים:

{
  "class": "DemoClass",
  "statusSummary": {
    "ABSENT": ["student-a"],
    "LATE": ["student-b"]
  },
  "rawTranscript": ["demo transcript"]
}

computeIfAbsent יוצר רשימה עבור מצב שטרם הופיע ואז מוסיף אליה כינוי. הקיבוץ משנה את צורת המידע: מכינוי ← מצב בזיכרון, למצב ← רשימת כינויים במסד. זהו עיבוד שאנחנו כתבנו, לא קסם של Firebase. הממפה רק שומר את המפה שהוכנה.

יש כאן כמה בחירות מועילות: שמות מצבים שאינם תלויים בשפת הממשק, קיבוץ נוח לדוח, השמטת ON_TIME במכוון, והמרת Set ל־ArrayList לפני מסירתו ל־SDK. הפרמטר newEntry אינו נקרא בגוף המתודה: למרות השם pushRawTranscript, היא אינה מפעילה push() ואינה שומרת רק את התמלול החדש. היא שומרת את המצב המצטבר.

setValue מחליף — גם כאשר האובייקט הוא Map

setValue(payload) מחליף את כל השיעור בנתיב currentTimestampAndLesson. אם נשמר קודם disturbances, וכעת הקבוצה ריקה ולכן הענף הושמט מן המפה, ההחלפה תסיר גם את ההפרעות הישנות. זה מתאים לשמירת תמונה מלאה של מצב מקומי. אם לקוח אחר הוסיף שם שדה שהקוד שלנו אינו מכיר, גם הוא עלול להיעלם.

לעומת זאת, ב־021b הכתיבה היא אל selectedRoomReference.child("moves"), ולכן רק הרצף מוחלף; name,‏ playerX ו־playerO נשארים במקומם. היקף ההחלפה נקבע לפי הכתובת, לא לפי מספר השדות במחלקה.

updateChildren מעדכן את הנתיבים שנמסרו במפה, ו־null בנתיב מסמן מחיקה. אין לראות בו מיזוג עמוק אוטומטי: updates.put("statusSummary", wholeMap) מחליף את כל statusSummary; מפתח כמו "statusSummary/LATE" מצביע רק לתת־הענף הזה. Presence עצמה משתמשת גם ב־updateChildren(batch) ב־LoadActivity, בהעלאת תלמידים. כל ערך ב־batch הוא רשומת תלמיד מלאה, ולכן הוא מחליף את אותו תלמיד, אך תלמידים שמפתחותיהם לא נשלחו נשארים בענף. מקור: setValue, updateChildren וערכי null.

אם נחליף את setValue(payload) ב־updateChildren(payload) בלבד, השמטת disturbances ריק כבר לא תמחק את ההפרעות הישנות. החלפת API בלי להגדיר את משמעות ההשמטה משנה את ההתנהגות. גם עדכון אטומי אינו פותר תחרות של שני כותבים שמעדכנים את אותו ערך על סמך עותק ישן.

קריאה ידנית: פחות מחלקות, יותר אחריות אצל הקורא

זהו בלוק שחזור statusSummary בשלמותו מתוך restoreDataFromSnapshot. בתחילת המתודה המלאה מתבצע studentStatus.clear(), ולכן מתבצעת בנייה מחדש:

מקור: Presence — Activities/PresenceActivity.java, שורות 286–298.

// Restore status summary
DataSnapshot statusSnapshot = snapshot.child("statusSummary");
if (statusSnapshot.exists()) {
    for (DataSnapshot statusGroup : statusSnapshot.getChildren()) {
        String status = statusGroup.getKey();
        for (DataSnapshot nameSnapshot : statusGroup.getChildren()) {
            String name = nameSnapshot.getValue(String.class);
            if (name != null && status != null) {
                studentStatus.put(name, status);
            }
        }
    }
}

getKey() מחזיר כאן את שם המצב, לא מזהה תלמיד. getValue(String.class) מחזיר את הכינוי בכל ילד. שתי הלולאות הופכות בחזרה מצב ← רשימת כינויים לכינוי ← מצב. המפה הדינמית מתאימה לכך שמספר המצבים והתלמידים משתנה. הקוד ברור לגבי ערכים חסרים, אך עדיין מניח שהעלים הם מחרוזות; בדיקת null לא תתקן עלה שהטיפוס שלו שגוי.

אפשר לשלב שיטות: מחלקת AttendanceRecord עם שדות קבועים, ובתוכה Map<String, List<String>> statusSummary. זו אפשרות תכנונית להמשך, לא קוד שקיים כאן. גם GenericTypeIndicator<Map<String, List<String>>> יכול לספק ל־getValue מידע על טיפוס מקונן שנמחק בזמן ריצה; הוא אינו בודק שהמצב המתקבל מותר לפי חוקי היישום. מקור: GenericTypeIndicator.

JSON מפורש ב־Presence שייך למסלול אחר

Presence בונה גם JSONObject, אבל לשם הכנת מידע ל־MashovActivity. זו כל מתודת ההכנה; שימו לב להמרת כינויים לשמות מלאים ול־JSONArray:

מקור: Presence — Activities/PresenceActivity.java, שורות 812–880.

private JSONObject buildMashovAttendanceData() {
    try {
        JSONObject data = new JSONObject();

        // Add class name
        data.put("class", detectedClassName);

        // Build status summary with full names instead of nicknames
        JSONObject statusSummary = new JSONObject();

        // Group by status (using English constants)
        Map<String, List<String>> grouped = new HashMap<>();
        for (Map.Entry<String, String> e : studentStatus.entrySet()) {
            String statusKey = e.getValue();
            // Skip ON_TIME students - we don't need them in Mashov
            if (!StudentStatus.ON_TIME.equals(statusKey)) {
                grouped.computeIfAbsent(statusKey, k -> new ArrayList<>()).add(e.getKey());
            }
        }

        // Convert nicknames to full names
        for (Map.Entry<String, List<String>> entry : grouped.entrySet()) {
            String status = entry.getKey();
            List<String> nicknames = entry.getValue();
            List<String> fullNames = new ArrayList<>();

            for (String nickname : nicknames) {
                Student student = FBRef.findStudentByNick(nickname, detectedClassName);
                if (student != null) {
                    fullNames.add(student.getFullName());
                } else {
                    Log.w("PresenceActivity", "Could not find full name for nickname: " + nickname);
                    fullNames.add(nickname); // fallback to nickname
                }
            }

            if (!fullNames.isEmpty()) {
                JSONArray statusArray = new JSONArray();
                for (String fullName : fullNames) {
                    statusArray.put(fullName);
                }
                statusSummary.put(status, statusArray);
            }
        }

        data.put("statusSummary", statusSummary);

        // Handle disturbances with full names
        if (!disturbanceSet.isEmpty()) {
            JSONArray disturbancesArray = new JSONArray();
            for (String nickname : disturbanceSet) {
                Student student = FBRef.findStudentByNick(nickname, detectedClassName);
                if (student != null) {
                    disturbancesArray.put(student.getFullName());
                } else {
                    Log.w("PresenceActivity", "Could not find full name for disturbance nickname: " + nickname);
                    disturbancesArray.put(nickname); // fallback to nickname
                }
            }
            data.put("disturbances", disturbancesArray);
        }

        return data;

    } catch (JSONException e) {
        Log.e("PresenceActivity", "Error building Mashov attendance data", e);
        return null;
    }
}

וזו כל המתודה שמעבירה את התוצאה למסך הבא:

מקור: Presence — Activities/PresenceActivity.java, שורות 885–900.

private void launchMashovUpdate() {
    if (detectedClassName == null) {
        Toast.makeText(this, "No class detected yet", Toast.LENGTH_SHORT).show();
        return;
    }

    JSONObject attendanceData = buildMashovAttendanceData();
    if (attendanceData == null) {
        Toast.makeText(this, "Failed to prepare attendance data", Toast.LENGTH_SHORT).show();
        return;
    }

    Intent intent = new Intent(this, MashovActivity.class);
    intent.putExtra("ATTENDANCE_DATA", attendanceData.toString());
    startActivity(intent);
}

כאן attendanceData.toString() יוצר טקסט JSON שמועבר ב־Intent. ב־MashovActivity נעשית הפעולה ההפוכה: new JSONObject(attendanceJson). המסלול הזה אינו כותב ל־RTDB, והוא גם אינו שולח דבר למכשיר השני. JSONObject נוח כשצריך ליצור או לפרש מסמך JSON מפורש, במיוחד עבור ממשק חיצוני. Gson הוא ממפה JSON אחר; הוא אינו מנגנון ההמרה של RTDB שבקטעים האלה. מקור: JSONObject ב־Android.

לא מוסרים ל־RTDB payload.toString() של Map: זו מחרוזת תצוגה של Java, שאינה בהכרח JSON. גם JSONObject.toString() תקין שיישמר ב־setValue יישמר כערך מחרוזת, ולא יתפרק אוטומטית לילדים שאפשר לקרוא ב־child("class"). לכתיבת עץ משתמשים בערכים הנתמכים של ה־SDK, כגון Map או POJO מתאים.

מה פשוט יותר, ומה עדיף כאן?

למשל, זו חלופה קצרה להמחשה בלבד, שמייצגת את אותם ארבעה מאפיינים:

/** Data-only alternative for comparing RTDB representations. */
public class GameRoomFields {
    public String name = "";
    public String playerX = "";
    public String playerO = "";
    public String moves = "";

    /** Creates an empty value object for snapshot conversion. */
    public GameRoomFields() {}
}

השדות הציבוריים חוסכים זוג מתודות לכל מאפיין. getter/setter שרק קורא ומשים אינו מוסיף כשלעצמו בדיקת תקינות או הגנה; הוא כן נותן נקודת גישה עקבית שאפשר לתעד ולשנות. אורך GameRoom נובע גם מה־Javadoc, שמופיע ב־Quick Documentation של Android Studio. התיעוד לא מגדיל את נתוני החדר שעוברים במסד.

לרצף השיעורים הזה כדאי להשאיר את GameRoom: המבנה קטן, קבוע, וכבר משמש את הלובי ואת המשחק. אין סיבה להעביר אותו ל־Map רק כדי להעלים getters. במסך הנוכחות, Map נוחה לנתונים המקובצים; אם כמה מסכים יתחילו לשכפל את אותו קוד פענוח, DTO משותף עם מפה פנימית יכול לרכז את החוזה. מספר שורות קצר יותר אינו מדד מספיק: חשוב גם היכן נגלות שגיאות וכמה קוראים צריכים להבין את המבנה.

דברים שחוזה הנתונים חייב להבהיר

• חסר, ריק ו־null: בחדר קיים שחסר בו playerO, האתחול = "" נשאר לאחר הבנאי אם לא הושם ערך מהנתונים. כשכל החדר חסר, getValue(GameRoom.class) מחזיר null, לא חדר ריק. setValue(null) מוחק נתון; "" היא מחרוזת ריקה. אוסף ריק אינו ערך נשמר שמבטיח ענף קיים ב־RTDB, לכן בודקים היעדר ילדים.
• טיפוסים: 0,‏ "0" ו־false אינם אותו סוג ערך. בקריאה ללא טיפוס, getValue() משתמש בין היתר ב־Long למספר שלם וב־Double למספר עשרוני. אין להמיר בעיוורון באמצעות cast ל־Integer. המרה למחלקה דורשת טיפוסים תואמים, וגם null check אינו תחליף לטיפול ב־DatabaseException במקרה שגוי.
• שמות: playerO ו־player0 הם מפתחות שונים. שינוי getter עלול לשנות את השם שנכתב למסד. Student מדגימה שמות שדות כמו FullName, אבל getFullName() מגדיר במיפוי הרגיל את fullName; אין להסיק את שם המפתח רק מהשדה הפרטי. יש להתאים את הכותב והקורא לאותן אותיות.
• זהות: מזהה חדר או תלמיד עדיף שישמש זהות יציבה; שם או כינוי יכולים להשתנות ולהתנגש. כינוי ברשימת נוכחות נוח לקריאה, אך מגביל שינויי שם והבחנה בין שני תלמידים בעלי אותו כינוי. UID בתוך הנתונים אינו הוכחת זהות.

הטיפוסים והמשמעות של snapshot חסר מתועדים ב־DataSnapshot. לשמירה על שם חיצוני קבוע אפשר להשתמש ב־@PropertyName על ה־getter ועל ה־setter המתאימים. getter מחושב שאינו מיועד לשמירה מסמנים ב־@Exclude, כדי שלא ייכנס בטעות לחוזה הנתונים. בגרסאות עתידיות יש גם להחליט כיצד קוראים שדות חדשים וישנים; התעלמות משדה לא מוכר אינה ממירה שם ישן לשם חדש, וכתיבת אובייקט ישן בשלמותו עלולה למחוק שדה חדש שהוא לא מכיר.

רצף המהלכים הוא פורמט נוסף בתוך JSON

ב־021b הערך "0,0,X;1,1,O" הוא String אחד בתוך עץ JSON. הפסיקים והנקודה־פסיק שייכים לפרוטוקול הפשוט שהגדרנו, לא לתחביר JSON. Firebase אינו יודע ש־1,1,O הוא מהלך, ואינו בודק תור, גבולות לוח או ניצחון. ה־Activity מפרקת את הרצף ומזינה אותו ל־TicTacToeModel.

עד תשעה מהלכים, שמירת הרצף ובניית הלוח מחדש הן בחירה פשוטה שמאפשרת גם לצופה שמצטרף באמצע לקבל את כל המצב. רצף ארוך יותר עשוי להצדיק ילדים מובנים עם row,‏ col ו־player, אך צריך אז להגדיר סדר וזהות לכל מהלך. push() מונע התנגשות במפתחות, אך אינו קובע מי רשאי לשחק או מהו התור הבא.

שני מכשירים שקראו אותו רצף ואז כתבו כל אחד רצף מורחב יכולים לדרוס זה את זה. גם שני מצטרפים יכולים לראות playerO ריק ולנסות לתפוס אותו יחד. להמשך, runTransaction מאפשר לחשב שינוי מחדש אם המצב השתנה; פונקציית העסקה יכולה לרוץ שוב, ולכן אינה מקום להודעות UI או לתופעות לוואי. צריך לתכנן בנפרד אימות נתונים והרשאות. זה כיוון להעמקה, ואינו מיושם ב־021b. מקור: עסקאות לשמירת נתונים במקביל.

זמן אמת אינו אישור שמירה או הגנת שרת

אירוע מקומי יכול להגיע לכותב לפני אישור השרת. לכן onDataChange מציין מצב שהלקוח רואה, ו־callback של הצלחת כתיבה מציין שהכתיבה אושרה; הוא אינו אישור שהמכשיר האחר כבר צייר את המסך. אופליין אפשר לראות עדכון מקומי בזמן שהכתיבה ממתינה לרשת. שמירה לדיסק בין הפעלות היא הגדרה נפרדת, ולא תכונה שנובעת מ־DTO. מקור: עבודה אופליין ב־Android.

אין לבצע כתיבה חוזרת מתוך מאזין רק כדי לצייר: הדבר עלול ליצור עדכונים מיותרים ואף לולאת תגובות. שומרים את המאזין ומסירים אותו מההפניה שאליה נרשם בסיום ההאזנה. יש להימנע מרישום כפול של אותו מאזין במתודות lifecycle שונות. ב־Presence, למשל, מאזין המשימות נרשם הן ב־onCreate והן ב־onResume; כשמשתמשים בקוד כדוגמה לתכנון lifecycle, צריך לבחור זוג רישום/הסרה עקבי.

בדיקות במסך וב־model עוזרות ללקוח שלנו; Security Rules צריכות לאכוף בשרת מי רשאי לקרוא ולכתוב ומהו מבנה מותר. getter/setter, מפה ו־JSON נותנים שלוש דרכי ייצוג, ואינם שלוש רמות אבטחה. למשל, אימות UID מול auth.uid ואימות שינוי מותר בחדר הם החלטות של כללי המסד, לא של setPlayerO. מקור: תנאים ואימות בכללי RTDB.

בדיקת הבנה: צפו את התוצאה לפני הרצה

ענו קודם על סמך הקוד. אם רוצים לאמת, משתמשים רק בחדר הדגמה או ב־Emulator עם נתונים מומצאים, ללא שינוי ברשומות Presence.

1. קראנו חדר, הפעלנו room.setMoves("0,0,X") וסיימנו. מה יראה המכשיר השני?
2. שמרנו שיעור ובו הפרעות. בשמירה הבאה המפה אינה מכילה disturbances. מה ההבדל בין setValue(payload) ל־updateChildren(payload)?
3. האם החלפת GameRoom ב־Map תגרום לשני שחקנים לקבל עדכונים מהר יותר?
4. מה נקבל אם נקרא getValue(GameRoom.class) על /games במקום על ילד אחד?
5. מכשיר X אופליין והלוח שלו השתנה בעקבות כתיבה. האם O כבר ראה את המהלך?
6. האם הוספת getDisplayLabel() למודל היא בהכרח שינוי תצוגה בלבד?