UploadDataProvider

public abstract class UploadDataProvider implements Closeable

---

מחלקה מופשטת שמאפשרת למטמיע לספק גוף העלאה ל-UrlRequest. הוא תומך בהעלאות לא מחולקות (הגודל ידוע מראש) ובהעלאות מחולקות (הגודל לא ידוע מראש). חשוב לדעת שלא כל השרתים תומכים בהעלאות מקוטעות.

ההעלאה תמיד תהיה מחולקת לחלקים, גם אם הנתונים יישלחו יותר מפעם אחת, או שהיא אף פעם לא תהיה מחולקת לחלקים.

סיכום

‫constructors ציבוריים
UploadDataProvider()

‫methods ציבוריים
void	close() הפונקציה נקראת כשהבקשה כבר לא צריכה את UploadDataProvider, כדי שיהיה אפשר לשחרר משאבים (כמו קובץ) באופן מפורש.
abstract long	getLength() אם ההעלאה לא מחולקת לחלקים, הפונקציה מחזירה את אורך ההעלאה.
abstract void	read(UploadDataSink uploadDataSink, ByteBuffer byteBuffer) קורא נתוני העלאה אל byteBuffer.
abstract void	rewind(UploadDataSink uploadDataSink) מחזיר את נתוני ההעלאה לתחילתם.

‫constructors ציבוריים

UploadDataProvider

public UploadDataProvider()

‫methods ציבוריים

סגירה

public void close()

הפונקציה נקראת כשהבקשה כבר לא צריכה את UploadDataProvider, כדי שיהיה אפשר לשחרר משאבים (כמו קובץ) באופן מפורש.

הקפצת הודעות שגיאה (throw)
java.io.IOException	אם אירעה שגיאת קלט/פלט במהלך התהליך. אם הבקשה לא הושלמה, היא תיכשל. אחרת, היא תתועד.

getLength

public abstract long getLength()

אם ההעלאה לא מחולקת לחלקים, הפונקציה מחזירה את אורך ההעלאה. אם מדובר בהעלאה של נתונים בחלקים, הפונקציה תמיד מחזירה את הערך ‎-1.

החזרות
long	משך ההעלאה להעלאות שלא מחולקות לחלקים, אחרת -1.

הקפצת הודעות שגיאה (throw)
java.io.IOException	אם אירעה שגיאת קלט/פלט במהלך התהליך.

קריאה

public abstract void read(UploadDataSink uploadDataSink, ByteBuffer byteBuffer)

קורא נתוני העלאה אל byteBuffer. בסיום, המיקום של המאגר מתעדכן לסוף הבייטים שנקראו. המגבלה של המאגר לא משתנה. אחרי כל קריאה של ה-method הזו, צריך לבצע קריאה אחת, סינכרונית או אסינכרונית, אל uploadDataSink: onReadSucceeded במקרה של הצלחה או onReadError במקרה של כישלון. הקריאה או ההרצה אחורה לא יופעלו עד שאחת מהשיטות האלה או השנייה יופעלו. גם אם UrlRequest המשויך מבוטל, עדיין צריך להפעיל את אחד מהם כדי לשחרר את המשאבים בצורה בטוחה. העלאת חריגה תגרום גם לשחרור משאבים ולשגיאה בבקשה.

הערה: בהעלאות לא מקוטעות, צריך לקרוא לפונקציה onReadSucceeded רק אם הקריאה הצליחה ונקרא לפחות בייט אחד לתוך byteBuffer. בהעלאות של נתונים בחלקים (גודל הנתונים לא ידוע), מותר לקרוא ל-onReadSucceeded עבור החלק האחרון עם מאגר בייטים ריק.

פרמטרים
UploadDataSink uploadDataSink	האובייקט שיישלח אליו עדכון כשהקריאה תסתיים.
ByteBuffer byteBuffer	המאגר שאליו יועתקו הבייטים שנקראו. אל תשנו את המגבלה של byteBuffer.

הקפצת הודעות שגיאה (throw)
java.io.IOException	אם אירעה שגיאת קלט/פלט במהלך התהליך. הקריאה ל-onFailed תתבצע כשהחריגה שהופעלה מוגדרת כסיבה ל-CallbackException.

אחורה

public abstract void rewind(UploadDataSink uploadDataSink)

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

כדי לציין שהפעולה הסתיימה, הטמעות של הפונקציה הזו חייבות לקרוא ל-onRewindSucceeded כדי לציין הצלחה, או ל-onRewindError כדי לציין כשל. גם אם UrlRequest המשויך מבוטל, עדיין צריך להפעיל את אחד מהם כדי לשחרר את המשאבים בצורה בטוחה. העלאת חריגה מהשיטה שקולה לקריאה ל-onRewindError. אם ההרצה לאחור לא נתמכת (לדוגמה, אם הקריאה מתבצעת משידור חד-פעמי), צריך להפעיל את onRewindError באופן מיידי.

המטמיע יכול להניח בבטחה שלא תונפק קריאה של read או של rewind בו-זמנית עד שהוא יודיע ל-sink שההרצה לאחור הסתיימה, כפי שמתואר בפסקה הקודמת.

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

פרמטרים
UploadDataSink uploadDataSink	האובייקט שיודיע כשהפעולה של ההרצה לאחור תושלם, בהצלחה או לא.

הקפצת הודעות שגיאה (throw)
java.io.IOException	אם אירעה שגיאת קלט/פלט במהלך התהליך. הקריאה ל-onFailed תתבצע כשהחריגה שהופעלה מוגדרת כסיבה ל-CallbackException.