‫UploadDataProvider

public abstract class UploadDataProvider implements Closeable

---

فئة مجرّدة تسمح للمضمِّن بتوفير نص أساسي للتحميل إلى UrlRequest. وهي تتيح عمليات التحميل غير المقسَّمة (التي يكون حجمها معروفًا مسبقًا) والمقسَّمة (التي يكون حجمها غير معروف مسبقًا). يُرجى العِلم أنّ بعض الخوادم لا تتيح عمليات التحميل المقسَّمة.

تكون عملية التحميل إما مقسَّمة دائمًا، أو مقسَّمة على مستوى عمليات تحميل متعدّدة إذا تم إرسال البيانات أكثر من مرة، أو غير مقسَّمة مطلقًا.

ملخّص

طُرق وضع التصميم العامة
UploadDataProvider()

الإجراءات العامة
void	close() يتم استدعاء هذا الإجراء عندما لا يعود الطلب بحاجة إلى UploadDataProvider، ما يسمح بإطلاق الموارد (مثل ملف) بشكلٍ صريح.
abstract long	getLength() إذا كانت عملية التحميل غير مقسَّمة، يعرض هذا الإجراء طول عملية التحميل.
abstract void	read(UploadDataSink uploadDataSink, ByteBuffer byteBuffer) يقرأ هذا الإجراء بيانات التحميل في byteBuffer.
abstract void	rewind(UploadDataSink uploadDataSink) يرجع هذا الإجراء بيانات التحميل إلى البداية.

طُرق وضع التصميم العامة

UploadDataProvider

public UploadDataProvider()

الإجراءات العامة

إغلاق

public void close()

يتم استدعاء هذا الإجراء عندما لا يعود الطلب بحاجة إلى UploadDataProvider، ما يسمح بإطلاق الموارد (مثل ملف) بشكلٍ صريح.

عمليات الطرح
java.io.IOException	إذا حدث أي IOException أثناء العملية. سيؤدي ذلك إلى فشل الطلب إذا لم يكتمل بعد، وإلا سيتم تسجيله.

getLength

public abstract long getLength()

إذا كانت عملية التحميل غير مقسَّمة، يعرض هذا الإجراء طول عملية التحميل. يجب أن يعرض هذا الإجراء دائمًا -1 إذا كانت عملية التحميل مقسَّمة.

المرتجعات
long	طول عملية التحميل لعمليات التحميل غير المقسَّمة، أو -1 في الحالات الأخرى.

عمليات الطرح
java.io.IOException	إذا حدث أي IOException أثناء العملية.

قراءة

public abstract void read(UploadDataSink uploadDataSink, ByteBuffer byteBuffer)

يقرأ هذا الإجراء بيانات التحميل في byteBuffer. عند اكتمال العملية، يتم تعديل موضع المخزن المؤقت إلى نهاية البايتات التي تمت قراءتها. ولا يتم تغيير حدّ المخزن المؤقت. يجب أن يتبع كل استدعاء لهذا الإجراء استدعاء واحد، متزامن أو غير متزامن، لـ uploadDataSink: onReadSucceeded في حال النجاح أو onReadError في حال الفشل. لن يتم استدعاء أي من الإجراءَين read أو rewind إلى أن يتم استدعاء أحدهما أو الآخر. حتى إذا تم إلغاء UrlRequest المرتبط، يجب استدعاء أحد الإجراءَين قبل إطلاق الموارد بأمان. سيؤدي طرح استثناء أيضًا إلى إطلاق الموارد وإظهار خطأ في الطلب.

ملاحظة: بالنسبة إلى عمليات التحميل غير المقسَّمة، يجب استدعاء onReadSucceeded فقط عندما تنجح عملية القراءة ويتم قراءة بايت واحد على الأقل في byteBuffer. بالنسبة إلى عمليات التحميل المقسَّمة (التي يكون حجم البيانات فيها غير معروف)، يُسمح باستدعاء onReadSucceeded للجزء الأخير باستخدام مخزن مؤقت فارغ للبايتات.

المعلَمات
UploadDataSink uploadDataSink	الكائن الذي يتم إعلامه عند اكتمال عملية القراءة.
ByteBuffer byteBuffer	المخزن المؤقت الذي يتم نسخ البايتات المقروءة إليه. لا تغيِّر حدّ byteBuffer.

عمليات الطرح
java.io.IOException	إذا حدث أي IOException أثناء العملية. سيتم استدعاء onFailed مع ضبط الاستثناء الذي تم طرحه كسبب في CallbackException.

ترجيع

public abstract void rewind(UploadDataSink uploadDataSink)

يرجع هذا الإجراء بيانات التحميل إلى البداية. يتم استدعاؤه عندما يتطلب Cronet أن يكون موفِّر بيانات التحميل في حالة مكافئة لحالة عدم استدعاء read بعد.

للإشارة إلى اكتمال العملية، يجب أن تستدعي عمليات تنفيذ هذه الدالة onRewindSucceeded للإشارة إلى النجاح، أو onRewindError في حال الفشل. حتى إذا تم إلغاء UrlRequest المرتبط، يجب استدعاء أحد الإجراءَين قبل إطلاق الموارد بأمان. إنّ طرح استثناء من الطريقة يعادل استدعاء onRewindError. إذا لم يكن الترجيع متاحًا (على سبيل المثال، إذا كانت القراءة من بث لمرة واحدة)، يجب أن يستدعي هذا الإجراء onRewindError على الفور.

يمكن للمنفِّذ أن يفترض بأمان أنّه لن يتم إصدار أي من الإجراءَين read أو استدعاء متزامن لـ rewind إلى أن يتم إعلام المصدر بأنّ عملية الترجيع قد اكتملت، كما هو موضّح في الفقرة السابقة.

يستخدم Cronet هذا الإجراء داخليًا إذا كان يجب تحميل النص الأساسي عدة مرات. ويمكن أن يحدث ذلك في العديد من الحالات المختلفة، على سبيل المثال عند اتّباع عمليات إعادة التوجيه أو عند إعادة محاولة الطلبات بعد انتهاء المهلة أو انقطاع الشبكة. يُرجى العِلم أنّه على الرغم من أنّ تنفيذ عملية الترجيع يكون اختياريًا بشكل عام، ستفشل الطلبات التي تتطلب ذلك إذا لم يتم تنفيذ عملية الترجيع.

المعلَمات
UploadDataSink uploadDataSink	الكائن الذي يتم إعلامه عند اكتمال عملية الترجيع، سواء نجحت أو لم تنجح.

عمليات الطرح
java.io.IOException	إذا حدث أي IOException أثناء العملية. سيتم استدعاء onFailed مع ضبط الاستثناء الذي تم طرحه كسبب في CallbackException.