Library Version 12.1.3.0

LOB APIs
Prev | Chapter 14. Using Large Objects | Next

## LOB APIs

Due to their representation as a sequence of chunks, LOBs must be accessed exclusively using the LOB APIs. If you use a LOB key with the family of `KVStore.getXXX` methods, you will receive a value that is internal to the KVS implementation and cannot be used directly by the application.

The LOB API is declared in the `KVLargeObject` interface. This is a superinterface of `KVStore`, so you create a `KVStore` handle in the usual way and then use that to access the LOB methods.

The LOB methods are:

- `KVLargeObject.deleteLOB()`

  Deletes a LOB from the store.

- `KVLargeObject.getLOB()`

  Retrieves a LOB from the store.

- `KVLargeObject.putLOB()`

  `KVLargeObject.putLOBIfAbsent()`

  `KVLargeObject.putLOBIfPresent()`

  Writes a LOB to the store.

The methods used to read and insert LOBs are not atomic. Relaxing the atomicity requirement permits distribution of chunks across the entire store. It is the application's responsibility to coordinate operations on a LOB. The LOB implementation will make a good faith effort to detect concurrent modification of a LOB and throw `ConcurrentModificationException` when it detects such concurrency conflicts but does not guarantee that it will detect all such conflicts. The safe course of action upon encountering this exception is to delete the LOB and replace it with a new value after fixing the application level coordination issue that provoked the exception.

Failures during a LOB modification operation result in the creation of a partial LOB. The LOB value of a partial LOB is in some intermediate state, where it cannot be read by the application; attempts to `getLOB()` on a partial LOB will result in a `PartialLOBException`. A partial LOB resulting from an incomplete `putLOB()` operation can be repaired by retrying the operation. Or it can be deleted and a new key/value pair can be created in its place. A partial LOB resulting from an incomplete delete operation must have the delete retried. The documentation associated with individual LOB methods describes their behavior when invoked on partial LOBs in greater detail.

Prev | Up | Next
Chapter 14. Using Large Objects | Home | LOB Example