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 后或 blob 前的数据。在检索主表上的下一个事件之后，可以读取句柄。数据将立即可用。（有关更多信息，请参见第 2.3.16 节，“NdbEventOperation 类”。）

Blobs 和 NdbOperations。 在 NdbBlob 对象上执行的 NdbOperation 方法具有以下特性：.

NdbOperation::insertTuple() 如果 blob 属性不可为空，则必须使用 NdbBlob::setValue()。
NdbOperation::readTuple() 在使用任何锁定模式时都可以读取但不能写入 blob 值。

当 readTuple() 使用 LM_CommittedRead 锁定模式时，只要访问 blob 属性，锁定模式就会自动升级到 LM_Read。
NdbOperation::updateTuple() 可以使用 NdbBlob::setValue() 覆盖现有值，或者在活动阶段更新它。
NdbOperation::writeTuple() 始终覆盖 blob 值，并且必须使用 NdbBlob::setValue() （如果 blob 属性不可为空）。
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 处理程序都已关闭后，才能解锁读取操作。

当包含 blob 的行以 LM_CommittedRead 锁定模式读取时，该模式会自动升级为 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 具有非空值。
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 节，“NdbOperation 类” 和第 2.3.24 节，“NdbScanOperation 类”，以获取更多信息。

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 设置为 NULL 指针 (0) 以创建 NULL 值。

签名

int setValue
    (
      const void*  data,
      Uint32       bytes
    )

参数

此方法接受此处列出的两个参数

要插入或用于覆盖 Blob 值的 data。
data 的字节数，即长度。

返回值

成功时为 0，失败时为 -1。

NdbBlob::State

这是一个枚举数据类型，它表示 NdbBlob 实例的可能状态。

描述

NdbBlob 可以处于以下任何一种状态

枚举值

下表显示了可能的值及其描述

表 2.36 NdbBlob::State 类型值及其描述

名称	描述
`闲置`	`NdbBlob` 尚未准备好在任何操作中使用。
`已准备`	这是 `NdbBlob` 在执行操作之前处于的状态。
`活动`	这是 Blob 处理程序在执行或获取下一个结果之后但交易提交之前处于的状态。
`已关闭`	此状态在交易提交后发生。
`无效`	此状态在回滚或关闭交易后发生。

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。

PREV HOME UP NEXT