Library Usage

Examples of how to use these APIs are included with your distribution. See the <package>/examples directory. In particular, hello.c illustrates the basic API usage to a store tjat does not require authentication, while hello_secured.c shows similar usage working with a secure store.

At a high level, you’ll complete these steps to use this library:

1. Initialize the Java Native Interface framework (JNI) using kv_create_jni_impl().

2. Create a store configuration using kv_create_config().

3. If you are using a store that requires authentication, define the security properties and the authentication credentials using these APIs kv_create_properties(), kv_set_property(), andkv_config_set_security_properties(). You create authentication credentials using kv_create_password_credentials().

4. Obtain a handle to the store using kv_open_store() or kv_open_store_login().

5. Perform data read and write operations using a variety of functions described in Data Operation Functions. Sometimes, these functions will require durability and consistency structures, and key/value structures. Functions used to create and manage such structures are described in Durability and Consistency Functions and Key/Value Pair Management Functions.

   If you are operating with a store that requires authentication, be prepared to handle KV_AUTH_FAILURE errors. When you see these errors, reauthenticate using kv_store_login().

6. Once you have finished accessing the store, close your store handle using kv_close_store(). If you logged the handle into the store, this will log your handle out.

7. Release your store configuration structure using kv_release_config().

8. Release your JNI implementation using kv_release_impl().

Notice that in this list of basic steps, you are responsible for allocating or initializing structures, and for release such structures once your complete your operations. You use some kinde of create and release functions to accomplish these tasks. This pattern of responsibility repeats throughout the API, with few exceptions. For example, creating a key requires  kv_create_key() and to releasing it uses  kv_release_key(). You are responsible for releasing any resources that you acquire through the use of these APIs.