MySQL :: MySQL NDB Cluster API 開發者指南 :: 2.3.13 NdbBlob 類別

MySQL NDB Cluster API 開發者指南 / ... / NdbBlob 類別

2.3.13 NdbBlob 類別

本節提供關於 NdbBlob 類別的資訊，此類別模擬 BLOB 欄的控制代碼，並提供對 BLOB 欄值的讀取和寫入存取權。此物件有多種不同的狀態，並提供對 BLOB 資料的多種存取模式；本節也會說明這些。

NdbBlob 類別概觀

父類別

無

子類別

無

描述

此類別沒有公用建構函式。在作業準備階段，會使用 NdbOperation::getBlobHandle() 方法建立 NdbBlob 的執行個體。（請參閱第 2.3.20 節「NdbOperation 類別」）。此物件作為 BLOB 欄的控制代碼。

方法

下表列出此類別的公用方法，以及每個方法的目的或用途

表 2.34 NdbBlob 類別方法和說明

名稱	描述
`blobsFirstBlob()`	取得清單中的第一個 BLOB。
`blobsNextBlob()`	取得清單中的下一個 BLOB
`close()`	在提交或中止之前釋放內部資源
`getBlobEventName()`	取得 BLOB 事件名稱
`getBlobTableName()`	取得 BLOB 資料區段的資料表名稱。
`getColumn()`	取得 BLOB 欄。
`getLength()`	取得 BLOB 的長度 (以位元組為單位)
`getNdbError()`	取得錯誤 (`NdbError` 物件)
`getNdbOperation()`	取得指向建立此 `NdbBlob` 物件時，所屬作業 (`NdbOperation` 物件) 的指標。
`getNull()`	檢查 BLOB 值是否為 `NULL`
`getPos()`	取得讀取/寫入的目前位置
`getState()`	取得 `NdbBlob` 物件的狀態
`getValue()`	準備讀取 BLOB 值
`getVersion()`	檢查 BLOB 是以陳述式為基礎還是以事件為基礎
`readData()`	從 BLOB 讀取資料
`setActiveHook()`	定義 BLOB 控制代碼啟動的回呼
`setNull()`	將 BLOB 設定為 `NULL`
`setPos()`	設定開始讀取/寫入的位置
`setValue()`	準備插入或更新 BLOB 值
`truncate()`	將 BLOB 截斷為指定的長度
`writeData()`	寫入 BLOB 資料

getBlobTableName() 和 getBlobEventName() 是靜態方法。

大部分的 NdbBlob 方法 (幾乎所有傳回類型為 int 的方法) 在成功時會傳回 0，在失敗時會傳回 -1。

類型

此處顯示 NdbBlob 定義的公用類型

表 2.35 NdbBlob 類型和說明

名稱	描述
`ActiveHook()`	`NdbBlob::setActiveHook()` 的回呼
`State()`	代表 `NdbBlob` 可能會假設的狀態。

BLOB 資料儲存體。 BLOB 資料儲存在 2 個位置

標頭和內嵌位元組儲存在 BLOB 欄中。
BLOB 的資料區段儲存在名為 NDB$BLOB_tid_cid 的個別資料表中，其中 tid 是資料表 ID，而 cid 是 BLOB 欄 ID。

內嵌和資料區段大小可以使用建立資料表時的適當 Column 方法設定。如需關於這些方法的詳細資訊，請參閱第 2.3.1 節「Column 類別」。

資料存取類型。 NdbBlob 支援 3 種資料存取類型：這些資料存取類型可以組合套用，前提是它們的使用順序與上述相同。

在準備階段中，NdbBlob 方法 getValue() 和 setValue() 用於準備已知大小的 BLOB 值的讀取或寫入。
同樣在準備階段中，setActiveHook() 用於定義在控制代碼變成作用中時立即呼叫的常式。
在作用中階段中，readData() 和 writeData() 用於讀取和寫入具有任意大小的 BLOB 值。

Blob 操作。 Blob 操作會在下一個交易執行時生效。在某些情況下，NdbBlob 會被迫執行隱式執行。為了避免這種情況，您應該始終操作完整的 blob 資料段。

使用 NdbTransaction::executePendingBlobOps() 來刷新讀取和寫入，如果沒有任何操作待處理，則可以避免任何執行損失。在執行操作之後或下一個掃描結果之後，這不是必要的。

NdbBlob 還支援從事件中讀取前或後的 blob 資料。可以在擷取主資料表上的下一個事件後讀取控制代碼。資料會立即可用。（詳情請參閱第 2.3.16 節「The NdbEventOperation Class」。）

Blob 和 NdbOperations。 作用於 NdbBlob 物件的 NdbOperation 方法具有以下特性：

如果 blob 屬性不可為 null，NdbOperation::insertTuple() 必須使用 NdbBlob::setValue()。
與任何鎖定模式一起使用的 NdbOperation::readTuple() 可以讀取但不能寫入 blob 值。

當 LM_CommittedRead 鎖定模式與 readTuple() 一起使用時，只要存取 blob 屬性，鎖定模式就會自動升級為 LM_Read。
NdbOperation::updateTuple() 可以使用 NdbBlob::setValue() 覆寫現有的值，或在活動階段期間更新它。
NdbOperation::writeTuple() 總是會覆寫 blob 值，如果 blob 屬性不可為 null，則必須使用 NdbBlob::setValue()。
NdbOperation::deleteTuple() 會建立隱式的、無法存取的 blob 控制代碼。
任何鎖定模式的掃描都可以使用其 blob 控制代碼來讀取 blob 值，但不能寫入它們。

使用 LM_Exclusive 鎖定模式的掃描可以使用 updateCurrentTuple() 更新列和 blob 值；傳回的操作必須明確建立自己的 blob 控制代碼。

使用 LM_Exclusive 鎖定模式的掃描可以使用 deleteCurrentTuple() 刪除列值（因此也刪除 blob 值）；這會建立隱式的、無法存取的 blob 控制代碼。
由 lockCurrentTuple() 傳回的操作無法更新 blob 值。

已知問題。 以下是使用 NdbBlob 物件時遇到的已知問題或限制

過多待處理的 blob 操作可能會使 I/O 緩衝區溢位。
資料表及其 blob 資料段資料表不是以原子方式建立的。

NdbBlob::ActiveHook

ActiveHook 是一種定義為 setActiveHook() 方法的回呼函數所用的資料類型。（請參閱 NdbBlob::setActiveHook()。）

定義。 ActiveHook 是一種自訂的資料類型，定義如下所示

typedef int ActiveHook
    (
      NdbBlob* me,
      void*    arg
    )

描述: 這是 NdbBlob::setActiveHook() 的回呼函數，會在準備好的操作執行後（但未提交）立即呼叫。任何對 getValue() 或 setValue() 的呼叫都會先執行。blob 控制代碼是活動的，因此可以使用 readData() 或 writeData() 來操作 blob 值。使用者定義的引數會與 NdbBlob 一起傳遞。如果發生錯誤，setActiveHook() 會傳回非零值。

NdbBlob::blobsFirstBlob()

描述

此方法會初始化屬於目前操作的 blob 清單，並傳回清單中的第一個 blob。

簽名

NdbBlob* blobsFirstBlob
    (
      void
    )

參數

無.

傳回值

指向所需 blob 的指標。

NdbBlob::blobsNextBlob()

描述

使用此方法來取得使用 blobsFirstBlob() 初始化的 blob 清單中的下一個 blob。請參閱 NdbBlob::blobsFirstBlob()。

簽名

NdbBlob* blobsNextBlob
    (
      void
    )

參數

無.

傳回值

指向所需 blob 的指標。

NdbBlob::close()

描述

關閉 blob 控制代碼，並在提交或中止交易之前釋放內部資源。換句話說，這表示應用程式已完成從給定 blob 讀取。只有當 blob 的 State 為 Active 時，才能呼叫此方法。

簽名

int close
    (
      bool execPendingBlobOps = true
    )

參數

此方法有一個布林參數 execPendingBlobOps。如果此參數的值為 true（預設值），則會在關閉 blob 控制代碼之前刷新任何待處理的 blob 操作。如果 execPendingBlobOps 為 false，則假設 blob 控制代碼沒有待刷新的讀取或寫入操作。

傳回值

成功時為 0。

讀取操作和鎖定。 當使用 LM_Read 或 LM_Exclusive 作為 LockMode 在讀取操作上建立 blob 控制代碼時，只有在關閉此操作上建立的所有 Blob 控制代碼之後，才能解除鎖定讀取操作。

當以鎖定模式 LM_CommittedRead 讀取包含 blob 的列時，模式會自動升級為 LM_Read，以確保一致性。在這種情況下，當列的所有 blob 控制代碼都已關閉時，呼叫 close() 方法會自動執行該列的解除鎖定操作，這會將待處理的寫入操作新增至 blob。在呼叫 execute() 之後，會釋放升級的鎖定。

NdbBlob::getBlobEventName()

描述

此方法會取得 blob 事件名稱。如果主要事件監視 blob 資料行，則會建立 blob 事件。名稱包含主要事件名稱。

簽名

static int getBlobEventName
    (
      char*       name,
      Ndb*        ndb,
      const char* event,
      const char* column
    )

參數

此方法採用此處列出的四個參數

name：blob 事件的名稱。
ndb：相關的 Ndb 物件。
event：主要事件的名稱。
column：blob 資料行。

傳回值

成功時為 0，失敗時為 -1。

NdbBlob::getBlobTableName()

描述

此方法會取得 blob 資料段資料表名稱。

此方法通常僅適用於測試和偵錯目的。

簽名

static int getBlobTableName
    (
      char*       name,
      Ndb*        ndb,
      const char* table,
      const char* column
    )

參數

此方法採用此處列出的四個參數

name：blob 資料段資料表的名稱。
ndb：相關的 Ndb 物件。
table：主要資料表的名稱。
column：blob 資料行。

傳回值

成功時傳回 0，失敗時傳回 -1。

NdbBlob::getColumn()

描述

使用此方法來取得 NdbBlob 所屬的 blob 資料行。

簽名

const Column* getColumn
    (
      void
    )

參數

無.

傳回值

Column 物件。

NdbBlob::getLength()

描述

此方法會取得 blob 目前的長度（以位元組為單位）。

簽名

int getLength
    (
      Uint64& length
    )

參數

參考長度。

傳回值

blob 的長度（以位元組為單位）。對於 NULL blob，此方法會傳回 0。若要區分長度為 0 的 blob 與 NULL 的 blob，請使用 getNull() 方法。

NdbBlob::getNull()

描述

此方法會檢查 blob 的值是否為 NULL。

簽名

int getNull
    (
      int& isNull
    )

參數

參考整數 isNull。在呼叫之後，此參數具有下列其中一個值，如下所示解譯

-1：blob 未定義。如果這是非事件 blob，則此結果會造成狀態錯誤。
0：blob 具有非 null 值。
1：blob 的值為 NULL。

傳回值

無.

NdbBlob::getNdbError()

描述

使用此方法來取得錯誤物件。錯誤可能是 blob 特有的，也可能是從失敗的隱式操作複製而來。錯誤碼會複製回操作，除非該操作已具有非零錯誤碼。

簽名

const NdbError& getNdbError
    (
      void
    ) const

參數

無。

傳回值

NdbError 物件。

NdbBlob::getNdbOperation()

描述

可以使用此方法來尋找與此 NdbBlob 控制代碼相關聯的操作。

簽名

const NdbOperation* getNdbOperation
    (
      void
    ) const

參數

無.

傳回值

指向操作的指標。

此方法傳回的指標所參考的操作，可以用 NdbOperation 或 NdbScanOperation 物件來表示。

如需詳細資訊，請參閱第 2.3.20 節「The NdbOperation Class」和第 2.3.24 節「The NdbScanOperation Class」。

NdbBlob::getPos()

描述

此方法會取得 blob 中目前的讀取/寫入位置。

簽名

int getPos
    (
      Uint64& pos
    )

參數

一個參數，參考位置。

傳回值

成功時傳回 0，失敗時傳回 -1。（成功呼叫後，pos 將保留 blob 中目前的讀取/寫入位置，以從開頭開始的位元組數表示。）

NdbBlob::getState()

描述

此方法會取得呼叫此方法的 NdbBlob 物件的目前狀態。可能的狀態說明於 NdbBlob::State 中。

簽名

State getState
    (
      void
    )

參數

無。

傳回值

State 類型的值。

NdbBlob::getValue()

描述

使用此方法來準備讀取 blob 值；該值會在呼叫之後可用。使用 getNull() 來檢查是否有 NULL 值；使用 getLength() 來取得 blob 的實際長度，並檢查是否已截斷。getValue() 會將目前的讀取/寫入位置設定為讀取資料結尾之後的位置。

簽名

int getValue
    (
      void*  data,
      Uint32 bytes
    )

參數

此方法採用兩個參數。第一個參數是指向要讀取的 data 的指標；第二個參數是要讀取的 bytes 數目。

傳回值

成功時為 0，失敗時為 -1。

NdbBlob::getVersion()

描述

此方法用於區分 blob 操作是基於語句還是基於事件。

簽名

void getVersion
    (
      int& version
    )

參數

此方法採用一個參數，即參考 blob 版本（操作類型）的整數。

傳回值

下列三個值之一

-1：這是「正常」的（基於語句的）blob。
0：這是基於事件操作的 blob，在資料變更之後。
1：這是基於事件操作的 blob，在資料變更之前。

假設 getVersion() 是以有效的 NdbBlob 執行個體的方法呼叫，則它總是會成功。

NdbBlob::readData()

描述

此方法用於從 blob 讀取資料。

簽名

int readData
    (
      void*     data,
      Uint32&  bytes
    )

參數

readData() 接受一個指向要讀取的 data 的指標，以及一個讀取到的 bytes 數量的參考。

傳回值

成功時返回 0，失敗時返回 -1。成功呼叫後，data 指向已讀取的資料，而 bytes 則保存讀取的位元組數。

NdbBlob::setActiveHook()

描述

此方法定義 blob 句柄啟用的回呼函數。準備好的操作佇列將在此點之前以非提交模式執行；然後，將呼叫回呼函數。如需更多資訊，請參閱 NdbBlob::ActiveHook。

簽名

int setActiveHook
    (
      ActiveHook*  activeHook,
      void*        arg
    )

參數

此方法需要此處列出的兩個參數

一個指向 ActiveHook 的指標。
一個指向 void 的指標，用於傳遞給回呼函數的任何資料。

傳回值

成功時為 0，失敗時為 -1。

NdbBlob::setNull()

描述

此方法將 blob 的值設定為 NULL。

簽名

int setNull
    (
      void
    )

參數

無.

傳回值

成功時返回 0；失敗時返回 -1。

NdbBlob::setPos()

描述

此方法設定在 blob 內讀取或寫入資料的位置。

簽名

int setPos
    (
      Uint64 pos
    )

參數

setPos() 方法採用單一參數 pos（一個無符號 64 位元整數），它是讀取或寫入資料的位置。pos 的值必須介於 0 與 blob 的目前長度之間。

重要

“稀疏” blob 在 NDB API 中不受支援；換句話說，blob 內不能有未使用的資料位置。

傳回值: 成功時為 0，失敗時為 -1。

NdbBlob::setValue()

描述

此方法用於準備插入或更新 blob 值。任何現有的 blob 資料若長度大於新資料，將被截斷。資料緩衝區必須保持有效，直到操作已執行。 setValue() 會將目前的讀/寫位置設定為資料末端之後的位置。您可以將 data 設定為空指標 (0) 以建立 NULL 值。

簽名

int setValue
    (
      const void*  data,
      Uint32       bytes
    )

參數

此方法採用此處列出的兩個參數

要插入或用於覆寫 blob 值的 data。
bytes 的數量，即 data 的長度。

傳回值

成功時為 0，失敗時為 -1。

NdbBlob::State

這是一個列舉資料類型，表示 NdbBlob 執行個體的可能狀態。

描述

NdbBlob 可以採用以下任何一種狀態

列舉值

下表顯示了可能的值以及描述

表 2.36 NdbBlob::State 類型的值和描述

名稱	描述
`Idle (閒置)`	`NdbBlob` 尚未準備好用於任何操作。
`Prepared (已準備)`	這是 `NdbBlob` 在操作執行之前的狀態。
`Active (啟用中)`	這是執行或擷取下一個結果後，但在交易提交之前 blob 句柄的狀態。
`Closed (已關閉)`	此狀態發生在交易已提交之後。
`Invalid (無效)`	這是在回滾或關閉交易之後發生的。

NdbBlob::truncate()

描述

此方法用於將 blob 截斷為給定的長度。

簽名

int truncate
    (
      Uint64 length = 0
    )

參數

truncate() 採用單一參數，用於指定 blob 要截斷到的新 length。如果 length 大於 blob 的目前長度（您可以使用 getLength() 進行檢查），則此方法不會有任何效果。

傳回值

成功時為 0，失敗時為 -1。

NdbBlob::writeData()

描述

此方法用於將資料寫入 NdbBlob。成功呼叫後，讀/寫位置將位於寫入 blob 的資料之後的第一個位元組。

寫入超過 blob 資料目前結尾的位置會自動延伸 blob。

簽名

int writeData
    (
      const void*  data,
      Uint32       bytes
    )

參數

此方法採用兩個參數，一個指向要寫入的 data 的指標，以及要寫入的 bytes 數量。

傳回值

成功時為 0，失敗時為 -1。