19.2.3 Notes on manipulating data

If the specified key is already stored in the cache, ead_put() simply overwrites its value. If you do not want the value updated blindly in this way, use one of the following functions instead.

• ead_create()

  Stores the value with the key only when a new key is stored.

• ead_update()

  Stores the value with the specified key only if the key is already stored.

• ead_replace()

  Compares the value associated with the specified key to the value information specified in a comparison condition, and stores the value with the key only if the values match.

When you execute ead_get(), NULL is returned in the value member of the ead_value_element structure in any of the following circumstances:

• The key does not exist in the cache.

• The value information could not be retrieved.

• The data size of the value is 0 bytes (it retrieves a byte array of length 0 that was stored using the Java language API).

When you execute a function such as ead_get(), the memory area that is returned as the return value is not freed automatically. Instead, you must free it in the application program. For details, see 19.1.1(10) Freeing a memory area returned as a return value.

When you execute ead_replace(), if the specified key does not exist, it returns EAD_ERROR_SERVER_REPLACE_METHOD_KEY_NOT_EXIST.

When you execute ead_replace(), if the value associated with the specified key does not match the value specified in the comparison condition, it returns EAD_ERROR_SERVER_REPLACE_METHOD_NOT_MATCHED.

When you execute ead_create(), if the specified key already exists, it returns EAD_ERROR_SERVER_CREATE_METHOD_KEY_EXIST.

When you execute ead_update(), if the specified key does not exist, it returns EAD_ERROR_SERVER_UPDATE_METHOD_KEY_NOT_EXIST.

If a specified key has already been stored in cache, ead_put_all() updates the value unconditionally.

Because caches are not locked while operations are ongoing, a target value might be changed by another cache operation during a batch operation.

When batch operations are performed on a large amount of data, a large amount of memory might be required by EADS clients and EADS servers.

When batch operations are performed on a large amount of data, it might take a long time to complete the processing. To ensure proper operation, make sure that you design a timeout value that is appropriate for the processing time.

A memory area returned as a return value during processing, such as by execution of ead_put_all(), is not freed automatically. The application program must free such a memory area. For details, see 19.1.1(10) Freeing a memory area returned as a return value.

If manipulation of a key fails or the cluster configuration is changed while batch operation with multiple keys specified is underway, the batch operation will terminate and any operation that has not been performed at that point will be cancelled. Similarly, when the cluster configuration is changed during batch operation by a user operation, such as scale-out processing (adding EADS servers) or restoration processing, any operations that have not been performed are cancelled.

Identify the key resulting in an error and determine the cause of the error from each function's return value. You can identify a key whose manipulation was cancelled based on the error code of EAD_ERROR_CLIENT_BATCH_CANCEL.

When batch operation with multiple keys specified is performed and all key manipulations fail, EAD_ERROR_BATCH_FAILED_ALL is returned.

When batch operation with multiple keys specified is performed but only some key manipulations fail, EAD_ERROR_BATCH_FAILED_PART is returned.