streamalism.org

1. הקדמה

במבוא זה ל- Couchbase SDK עבור Java אנו מדגימים כיצד ליצור אינטראקציה עם מסד נתונים של מסמכי Couchbase, מכסים מושגים בסיסיים כגון יצירת סביבת Couchbase, חיבור לאשכול, פתיחת דליי נתונים, שימוש בפעולות ההתמדה הבסיסיות ועבודה עם מסמך. העתקים.

2. תלות Maven

אם אתה משתמש ב- Maven, הוסף את הקובץ הבא לקובץ pom.xml שלך:

 com.couchbase.client java-client 2.2.6 

3. תחילת העבודה

ה- SDK מספק את CouchbaseEnvironment ממשק ושיעור יישום DefaultCouchbaseEnvironment המכיל הגדרות ברירת מחדל לניהול גישה לאשכולות ודליים. ניתן לעקוף את הגדרות ברירת המחדל של הסביבה במידת הצורך, כפי שנראה בסעיף 3.2.

חָשׁוּב: התיעוד הרשמי של Couchbase SDK מזהיר את המשתמשים להבטיח רק אחד CouchbaseEnvironment פעיל ב- JVM, מכיוון שהשימוש בשניים או יותר עלול לגרום להתנהגות בלתי צפויה.

3.1. חיבור לאשכול עם סביבת ברירת מחדל

כדי שה- SDK ייצור אוטומטית א CouchbaseEnvironment עם הגדרות ברירת מחדל ולקשר אותו לאשכול שלנו, אנו יכולים להתחבר לאשכול פשוט על ידי מתן כתובת ה- IP או שם המארח של אחד או יותר צמתים באשכול.

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

אשכול אשכול = CouchbaseCluster.create ("localhost");

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

אשכול אשכול = CouchbaseCluster.create ("192.168.4.1", "192.168.4.2");

הערה: אין צורך לציין כל צומת באשכול בעת יצירת החיבור הראשוני. ה CouchbaseEnvironment ישאיל את האשכול ברגע שנוצר החיבור על מנת לגלות את הצמתים הנותרים (אם ישנם).

3.2. שימוש בסביבה מותאמת אישית

אם היישום שלך דורש כיוונון עדין של אחת מההגדרות המסופקות על ידי DefaultCouchbaseEnvironment, באפשרותך ליצור סביבה מותאמת אישית ולאחר מכן להשתמש בסביבה זו בעת התחברות לאשכול שלך.

הנה דוגמה שמתחברת לאשכול של צומת יחיד באמצעות מותאם אישית CouchbaseEnvironment עם פסק זמן לחיבור של עשר שניות ופסק זמן לחיפוש של ערך מפתח של שלוש שניות:

CouchbaseEnvironment env = DefaultCouchbaseEnvironment.builder () .connectTimeout (10000) .kvTimeout (3000) .build (); אשכול אשכול = CouchbaseCluster.create (env, "localhost");

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

אשכול אשכול = CouchbaseCluster.create (env, "192.168.4.1", "192.168.4.2");

3.3. פתיחת דלי

לאחר שהתחברת לאשכול Couchbase, באפשרותך לפתוח דל אחד או יותר.

כאשר אתה מגדיר לראשונה אשכול Couchbase, חבילת ההתקנה יוצרת באופן אוטומטי דלי בשם "בְּרִירַת מֶחדָל" עם סיסמה ריקה.

הנה דרך אחת לפתוח את "בְּרִירַת מֶחדָל" דלי כאשר יש לו סיסמה ריקה:

דלי דלי = cluster.openBucket ();

תוכל גם לציין את שם הדלי בעת פתיחתו:

דלי דלי = cluster.openBucket ("ברירת מחדל");

עבור כל דלי אחר עם סיסמה ריקה, אתה צריך ספק את שם הדלי:

דלי myBucket = cluster.openBucket ("myBucket");

כדי לפתוח דלי עם סיסמה שאינה ריקה, עליך לספק את שם הדלי ו סיסמה:

דלי דלי = cluster.openBucket ("bucketName", "bucketPassword");

4. פעולות התמדה

בחלק זה אנו מראים כיצד לבצע פעולות CRUD ב- Couchbase. בדוגמאות שלנו נעבוד עם מסמכי JSON פשוטים המייצגים אדם, כמו במסמך לדוגמה זה:

{"name": "John Doe", "type": "Person", "email": "[email protected]", "homeTown": "Chicago"}

ה "סוּג" מאפיין אינו נדרש, אולם נהוג לכלול מאפיין המציין את סוג המסמך למקרה שאחד מחליט לאחסן מספר סוגים באותו דלי.

4.1. תעודות זהות

כל מסמך המאוחסן ב- Couchbase משויך ל- תְעוּדַת זֶהוּת הייחודי לדלי בו מאוחסן המסמך. המסמך תְעוּדַת זֶהוּת מקביל לעמודת המפתח הראשית בשורת מסדי נתונים יחסיים מסורתית.

מסמך תְעוּדַת זֶהוּת הערכים חייבים להיות מחרוזות UTF-8 של 250 בתים או פחות.

מכיוון ש- Couchbase אינו מספק מנגנון ליצירה אוטומטית של ה- תְעוּדַת זֶהוּת עם הכניסה, עלינו לספק משלנו.

אסטרטגיות נפוצות לייצור מזהים לכלול נגזרת מפתח באמצעות מפתח טבעי, כגון ה- "אימייל" המאפיין המוצג במסמך המדגם שלנו והשימוש ב UUID מיתרים.

לדוגמאות שלנו, ניצור אקראי UUID מיתרים.

4.2. הכנסת מסמך

לפני שנוכל להוסיף מסמך חדש לדלי שלנו, ראשית עלינו ליצור מופע של JSONObject המכיל את תוכן המסמך:

תוכן JsonObject = JsonObject.empty () .put ("שם", "ג'ון דו") .put ("סוג", "אדם") .put ("דוא"ל", "[מוגן באמצעות דוא"ל]) .put (" עיר עיר "," שיקגו ");

לאחר מכן, אנו יוצרים a JSONDocument אובייקט המורכב מ תְעוּדַת זֶהוּת ערך ו JSONObject:

מזהה מחרוזת = UUID.randomUUID (). ToString (); מסמך JsonDocument = JsonDocument.create (מזהה, תוכן);

כדי להוסיף מסמך חדש לדלי, אנו משתמשים ב- לְהַכנִיס שיטה:

JsonDocument הוכנס = bucket.insert (מסמך);

ה JsonDocument הוחזר מכיל את כל המאפיינים של המסמך המקורי, בתוספת ערך המכונה "CAS" (השווה והחלפה) ערך בו משתמש Couchbase למעקב אחר גרסאות.

אם מסמך עם המסופק המצורף תְעוּדַת זֶהוּת כבר קיים בדלי, Couchbase זורק א DocumentAlreadyExistsException.

אנחנו יכולים גם להשתמש ב- עלייה שיטה שתכניס את המסמך (אם תְעוּדַת זֶהוּת לא נמצא) או עדכן את המסמך (אם ה- תְעוּדַת זֶהוּת נמצא):

JsonDocument upserted = bucket.upsert (מסמך);

4.3. אחזור מסמך

כדי לאחזר מסמך לפי תְעוּדַת זֶהוּת, אנו משתמשים ב- לקבל שיטה:

JsonDocument אחזר = bucket.get (id);

אם לא קיים מסמך עם הנתון תְעוּדַת זֶהוּת, השיטה חוזרת ריק.

4.4. עדכון או החלפה של מסמך

אנו יכולים לעדכן מסמך קיים באמצעות עלייה שיטה:

JsonObject content = document.content (); content.put ("homeTown", "קנזס סיטי"); JsonDocument upserted = bucket.upsert (מסמך);

כפי שהזכרנו בסעיף 4.2, עלייה יצליח אם מסמך עם הנתון תְעוּדַת זֶהוּת נמצא או לא.

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

אם עלינו לשמור מפני תרחיש זה ביישום שלנו, נוכל להשתמש ב- החלף שיטה, שנכשלת עם DocumentDoesNotExistException אם מסמך עם הנתון תְעוּדַת זֶהוּת לא נמצא ב- Couchbase:

JsonDocument הוחלף = bucket.replace (מסמך);

4.5. מחיקת מסמך

כדי למחוק מסמך Couchbase, אנו משתמשים ב- לְהַסִיר שיטה:

JsonDocument הוסר = bucket.remove (מסמך);

אתה יכול גם להסיר עד תְעוּדַת זֶהוּת:

JsonDocument הוסר = bucket.remove (id);

ה JsonDocument לאובייקט שהוחזר יש רק את תְעוּדַת זֶהוּת ו CAS קביעת מאפיינים; כל המאפיינים האחרים (כולל תוכן JSON) מוסרים מהאובייקט שהוחזר.

אם לא קיים מסמך עם הנתון תְעוּדַת זֶהוּת, Couchbase זורק א DocumentDoesNotExistException.

5. עבודה עם העתקים

פרק זה דן בארכיטקטורת הדלי וההעתק הווירטואלית של Couchbase ומציג מנגנון לאחזור העתק של מסמך במקרה שהצומת הראשי של המסמך אינו זמין.

5.1. דליים והעתקים וירטואליים

Couchbase מפיץ מסמכים של דלי על פני אוסף של 1024 דליים וירטואליים, או דליים, באמצעות אלגוריתם hashing במסמך תְעוּדַת זֶהוּת כדי לקבוע את vbucket בו ניתן לאחסן כל מסמך.

ניתן לקבוע את התצורה של כל דלי Couchbase כך שישמור על אחת או יותר העתקים מכל אחד vbucket. בכל פעם שמסמך מוכנס או מתעדכן ונכתב אליו vbucket, Couchbase יוזם תהליך לשכפול המסמך החדש או המעודכן אליו העתק vbucket.

באשכול רב-צומת, Couchbase מפיץ דליים ו עותקים משוכפלים בין כל צמתי הנתונים באשכול. א vbucket וזה שלה העתק vbucket נשמרים על צמתים נתונים נפרדים על מנת להשיג מידה מסוימת של זמינות גבוהה.

5.2. אחזור מסמך מהעתק

בעת אחזור מסמך לפי שלו תְעוּדַת זֶהוּת, אם הצומת הראשי של המסמך נמצא למטה או שאינו ניתן להשגה אחרת עקב שגיאת רשת, Couchbase מציג יוצא מן הכלל.

אתה יכול לגרום ליישום שלך לתפוס את החריג ולנסות לאחזר העתק אחד או יותר של המסמך באמצעות ה- getFromReplica שיטה.

הקוד הבא ישתמש בהעתק הראשון שנמצא:

מסמך JsonDocument; נסה {doc = bucket.get (id); } לתפוס (CouchbaseException e) {List list = bucket.getFromReplica (id, ReplicaMode.FIRST); אם (! list.isEmpty ()) {doc = list.get (0); }}

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

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

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

maxCasValue ארוך = -1; עבור (העתק JsonDocument: bucket.getFromReplica (id, ReplicaMode.ALL)) {if (replica.cas ()> maxCasValue) {doc = replica; maxCasValue = replica.cas (); }}

6. מסקנה

הצגנו כמה תרחישי שימוש בסיסיים שתזדקק להם בכדי להתחיל לעבוד עם Couchbase SDK.

קטעי קוד המוצגים במדריך זה ניתן למצוא בפרויקט GitHub.

תוכל ללמוד עוד על ה- SDK באתר התיעוד הרשמי של Couchbase SDK למפתחים.