UploadDataProvider

public abstract class UploadDataProvider implements Closeable


抽象類別,可讓嵌入器將上傳主體提供給 UrlRequest。這項服務支援非分塊 (預先知道大小) 和分塊 (預先不知道大小) 上傳。請注意,並非所有伺服器都支援分塊上傳。

上傳作業一律會分塊,如果資料最終傳送多次,則每次上傳都會分塊,否則一律不會分塊。

摘要

公用建構函式

公用方法

void

當要求不再需要這個 UploadDataProvider 時呼叫,以便明確釋出資源 (例如檔案)。

abstract long

如果是未分塊上傳,則傳回上傳長度。

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。在呼叫其中一個方法或另一個方法之前,系統不會呼叫讀取或倒轉。即使關聯的 UrlRequest 已取消,仍須先呼叫其中一個,才能安全釋出資源。擲回例外狀況也會導致資源釋出,且要求發生錯誤。

注意:如果上傳作業未分塊,只有在讀取成功,且至少有一個位元組已讀取至 byteBuffer 時,才應呼叫 onReadSucceeded。如果是分塊上傳 (資料大小不明),則允許為最後一個分塊呼叫 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 的原因。