K2hash (k2hash 1.0.1 API)

java.lang.Object
- ax.antpick.k2hash.K2hash

All Implemented Interfaces:: Closeable, AutoCloseable

public class K2hash
extends Object
implements Closeable

The class K2hash encapsulates the K2hashLibrary class and represents a K2hash key-value store.

Usage Examples. Suppose you want to set a key of "keystring" with a value of "valuestring". You could write this as:


 import com.sun.jna.*;
 import com.sun.jna.ptr.*;
 import java.io.IOException;
 import ax.antpick.K2hash;

 public class App {
   public static void main(String[] args) {
     try (K2hash db = K2hash.of("App.k2h")) {
       db.setValue("keystring", "valstring");
       System.out.println(db.getValue("keystring"));
     } catch (IOException ex) {
       System.out.println(ex.getMessage());
     }
   }
 }

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`K2hash.OPEN_MODE` Defines access modes used to open a file.
`static class`	`K2hash.STATS_DUMP_LEVEL` Defines levels used to dump a k2hash data.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`DEFAULT_CMASK_BITS` Default key collision mask bits.
`static boolean`	`DEFAULT_IS_FULLMAP` The library maps the whole file to memory using mmap.
`static boolean`	`DEFAULT_IS_READONLY` The library opens a k2hash file with read only access.
`static boolean`	`DEFAULT_IS_REMOVE_FILE` The library doesn't remove a k2hash file when no process has attached it.
`static int`	`DEFAULT_MASK_BITS` Default key mask bits.
`static int`	`DEFAULT_MAX_ELEMENT` Default maximum elements of a collision key.
`static int`	`DEFAULT_PAGE_SIZE` Default page size.
`static long`	`K2H_INVALID_HANDLE` Default k2hash data handle.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`addAttributePluginLib(String path)` Adds a shared library that handles an attribute.
`boolean`	`addDecryptionPassword(String password)` Adds a passphrase to decrypt a value.
`boolean`	`addSubkey(String key, String subkey)` Adds a subkey to a key.
`boolean`	`addSubkeys(String key, String[] newKeys)` Adds subkeys to a key.
`boolean`	`beginTx(String txFile)` Starts a transaction.
`boolean`	`beginTx(String txFile, String prefix, String param, long expirationDuration)` Starts a transaction logging.
`void`	`close()` Closes a k2h file.
`static boolean`	`create(String pathname)` Creates a k2hash file.
`static boolean`	`create(String pathname, int maskBit, int cmaskBit, int maxElement, int pageSize)` Creates a k2hash file.
`boolean`	`dumpToFile(String path)` Dumps k2hash data to a file.
`boolean`	`dumpToFile(String path, boolean isSkipError)` Dumps data to a file.
`boolean`	`enableEncryption(boolean enable)` Enables a feature to encrypt a value.
`boolean`	`enableHistory(boolean enable)` Enables a feature to record a key modification history.
`boolean`	`enableMtime(boolean enable)` Enables a feature to record value modification time.
`String`	`getAttribute(String key, String attribute)` Gets an attribute of a key.
`Map<String,String>`	`getAttributes(String key)` Gets attributes of a key.
`static CLibrary`	`getCLibrary()` Creates a C Library instance.
`long`	`getHandle()` Returns a k2hash data handle.
`static ax.antpick.k2hash.K2hashLibrary`	`getLibrary()` Creates a K2hashLibrary instance.
`List<String>`	`getSubkeys(String key)` Gets keys of subkeys of a key.
`int`	`getTxFileFd()` Gets a transaction log file descriptor.
`int`	`getTxPoolSize()` Gets the number of transaction thread pool.
`byte[]`	`getValue(byte[] key, String pass)` Gets the value of a key in binary format.
`String`	`getValue(String key)` Gets the value of a key.
`String`	`getValue(String key, String pass)` Gets the value of a key.
`boolean`	`loadFromFile(String path)` Loads data from a file.
`boolean`	`loadFromFile(String path, boolean isSkipError)` Loads data from a file.
`static K2hash`	`of(String pathname)` Creates a k2hash instance.
`static K2hash`	`of(String pathname, K2hash.OPEN_MODE mode)` Creates a k2hash instance.
`void`	`printAttributePlugins()` Prints attribute plugins to stderr.
`void`	`printAttributes()` Prints attributes to stderr.
`void`	`printDataStats()` Prints data statistics.
`void`	`printTableStats(K2hash.STATS_DUMP_LEVEL level)` Prints k2hash key table information.
`boolean`	`remove(String key)` Removes a key.
`boolean`	`remove(String key, boolean removeAllSubkeys)` Removes a key.
`boolean`	`remove(String key, String subkey)` Removes a key from a subkey list and removes the subkey itself.
`boolean`	`rename(String key, String newkey)` Renames a key with a new key.
`boolean`	`setAttribute(String key, String attrName, String attrVal)` Sets an attribute of a key.
`boolean`	`setDefaultEncryptionPassword(String password)` Sets the default encryption passphrase.
`boolean`	`setEncryptionPasswordFile(String path)` Sets the data encryption password file.
`boolean`	`setExpirationDuration(int duration, TimeUnit unit)` Sets the duration to expire a value.
`boolean`	`setSubkey(String key, String subkey)` Sets a subkey of a key.
`boolean`	`setSubkeys(String key, String[] subkeys)` Sets subkeys.
`boolean`	`setTxPoolSize(int txPoolSize)` Sets the number of transaction thread pool.
`boolean`	`setValue(String key, String val)` Sets a key with a value.
`boolean`	`setValue(String key, String val, String password, long duration, TimeUnit unit)` Sets a key with a value.
`boolean`	`stopTx()` Stops a transaction logging.
`String`	`toString()` Returns full of members as a string.
`void`	`version()` Prints version information.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - K2H_INVALID_HANDLE
```
public static final long K2H_INVALID_HANDLE
```
    Default k2hash data handle.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_IS_FULLMAP
```
public static final boolean DEFAULT_IS_FULLMAP
```
    The library maps the whole file to memory using mmap.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_IS_READONLY
```
public static final boolean DEFAULT_IS_READONLY
```
    The library opens a k2hash file with read only access.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_IS_REMOVE_FILE
```
public static final boolean DEFAULT_IS_REMOVE_FILE
```
    The library doesn't remove a k2hash file when no process has attached it.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_MASK_BITS
```
public static final int DEFAULT_MASK_BITS
```
    Default key mask bits.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_CMASK_BITS
```
public static final int DEFAULT_CMASK_BITS
```
    Default key collision mask bits.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_MAX_ELEMENT
```
public static final int DEFAULT_MAX_ELEMENT
```
    Default maximum elements of a collision key.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_PAGE_SIZE
```
public static final int DEFAULT_PAGE_SIZE
```
    Default page size.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - toString
```
public String toString()
```
    Returns full of members as a string.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    full of members as a string in a key=value manner
  - getLibrary
```
public static ax.antpick.k2hash.K2hashLibrary getLibrary()
                                                  throws IOException
```
    Creates a K2hashLibrary instance.
    
    Returns:
    
    a K2hashLibrary instance
    
    Throws:
    
    IOException - if failed to load the k2hash library
  - getCLibrary
```
public static CLibrary getCLibrary()
                            throws IOException
```
    Creates a C Library instance.
    
    Returns:
    
    a C library instance
    
    Throws:
    
    IOException - if failed to load the C library
  - of
```
public static K2hash of(String pathname)
                 throws IOException
```
    Creates a k2hash instance.
    
    Parameters:
    
    pathname - a k2hash file path string
    
    Returns:
    
    a K2hash instance
    
    Throws:
    
    IllegalArgumentException - if pathname is null
    
    IOException - if creating a k2hash file failed
  - of
```
public static K2hash of(String pathname,
                        K2hash.OPEN_MODE mode)
                 throws IOException
```
    Creates a k2hash instance.
    
    Parameters:
    
    pathname - a k2hash file path string
    
    mode - an access mode to open a file
    
    Returns:
    
    a K2hash instance
    
    Throws:
    
    IllegalArgumentException - if pathname is null
    
    IOException - if creating a k2hash file failed
  - create
```
public static boolean create(String pathname)
```
    Creates a k2hash file.
    
    Parameters:
    
    pathname - a k2hash file path string
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - create
```
public static boolean create(String pathname,
                             int maskBit,
                             int cmaskBit,
                             int maxElement,
                             int pageSize)
```
    Creates a k2hash file.
    
    Parameters:
    
    pathname - a k2hash file path string
    
    maskBit - key mask bits
    
    cmaskBit - key collision mask bits
    
    maxElement - maximum elements of a collision key
    
    pageSize - page size
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - getHandle
```
public long getHandle()
```
    Returns a k2hash data handle.
    
    Returns:
    
    a k2hash data handle.
  - close
```
public void close()
           throws IOException
```
    Closes a k2h file.
    
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable
    
    Throws:
    
    IOException
  - beginTx
```
public boolean beginTx(String txFile)
```
    Starts a transaction.
    
    Parameters:
    
    txFile - a transaction log file path string
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - beginTx
```
public boolean beginTx(String txFile,
                       String prefix,
                       String param,
                       long expirationDuration)
```
    Starts a transaction logging.
    
    Parameters:
    
    txFile - a transaction log file path
    
    prefix - a prefix of transaction log entry
    
    param - a parameter string to pass to a transaction processing handler
    
    expirationDuration - transaction log entry expiration(second)
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - getTxFileFd
```
public int getTxFileFd()
```
    Gets a transaction log file descriptor.
    
    Returns:
    
    a transaction file descriptor
  - stopTx
```
public boolean stopTx()
```
    Stops a transaction logging.
    
    Returns:
    
    true if success false otherwise
  - getTxPoolSize
```
public int getTxPoolSize()
```
    Gets the number of transaction thread pool.
    
    Returns:
    
    the number of transaction thread pool
  - setTxPoolSize
```
public boolean setTxPoolSize(int txPoolSize)
```
    Sets the number of transaction thread pool.
    
    Parameters:
    
    txPoolSize - the number of threads
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - dumpToFile
```
public boolean dumpToFile(String path)
```
    Dumps k2hash data to a file.
    
    Parameters:
    
    path - a path string to dump data to
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - dumpToFile
```
public boolean dumpToFile(String path,
                          boolean isSkipError)
```
    Dumps data to a file.
    
    Parameters:
    
    path - a path string to dump data to
    
    isSkipError - true if a dump process continues on errors
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - loadFromFile
```
public boolean loadFromFile(String path)
                     throws IOException
```
    Loads data from a file.
    
    Parameters:
    
    path - a path string to load data from
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
    
    IOException - if a path doesn't exist
  - loadFromFile
```
public boolean loadFromFile(String path,
                            boolean isSkipError)
                     throws IOException
```
    Loads data from a file.
    
    Parameters:
    
    path - a path string to load data from
    
    isSkipError - true if a dump process continues on errors
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
    
    IOException - if a path doesn't exist
  - enableMtime
```
public boolean enableMtime(boolean enable)
```
    Enables a feature to record value modification time.
    
    Parameters:
    
    enable - true if enable false if disable null set K2H_ATTR_DEFAULT
    
    Returns:
    
    true if success false otherwise
  - enableEncryption
```
public boolean enableEncryption(boolean enable)
```
    Enables a feature to encrypt a value.
    
    Parameters:
    
    enable - true if enable false if disable null set K2H_ATTR_DEFAULT
    
    Returns:
    
    true if success false otherwise
  - setEncryptionPasswordFile
```
public boolean setEncryptionPasswordFile(String path)
                                  throws IOException
```
    Sets the data encryption password file.
    
    Parameters:
    
    path - file string that contains passphrase. null for initializing the current value.
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
    
    IOException - if a path doesn't exist
  - enableHistory
```
public boolean enableHistory(boolean enable)
```
    Enables a feature to record a key modification history.
    
    Parameters:
    
    enable - true if enable false if disable null set K2H_ATTR_DEFAULT
    
    Returns:
    
    true if success false otherwise
  - setExpirationDuration
```
public boolean setExpirationDuration(int duration,
                                     TimeUnit unit)
```
    Sets the duration to expire a value.
    
    Parameters:
    
    duration - the duration to expire a value in second null set K2H_ATTR_DEFAULT
    
    unit - unit of duration. 0 for initializing the current value.
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - addDecryptionPassword
```
public boolean addDecryptionPassword(String password)
```
    Adds a passphrase to decrypt a value.
    
    Parameters:
    
    password - a passphrase string to decrypt a value
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - setDefaultEncryptionPassword
```
public boolean setDefaultEncryptionPassword(String password)
```
    Sets the default encryption passphrase.
    
    Parameters:
    
    password - a passphrase string to encrypt a value
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - addAttributePluginLib
```
public boolean addAttributePluginLib(String path)
                              throws IOException
```
    Adds a shared library that handles an attribute.
    
    Parameters:
    
    path - a path string to the library
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
    
    IOException - if a path does't exist
  - printAttributePlugins
```
public void printAttributePlugins()
```
    Prints attribute plugins to stderr.
  - printAttributes
```
public void printAttributes()
```
    Prints attributes to stderr.
  - getValue
```
public String getValue(String key)
```
    Gets the value of a key.
    
    Parameters:
    
    key - a key string to retrieve the value
    
    Returns:
    
    the value of the key
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - getValue
```
public String getValue(String key,
                       String pass)
```
    Gets the value of a key.
    The 2nd parameter is a password to decrypt the value. The value is same with either the 2nd augment of the setValue or the 1st augment of the setDefaultEncryptionPassword.
    
    Parameters:
    
    key - a key string to retrieve the value
    
    pass - a passphrase string to decrypt the value
    
    Returns:
    
    value of the key
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - getValue
```
public byte[] getValue(byte[] key,
                       String pass)
```
    Gets the value of a key in binary format.
    The 2nd parameter is a password to decrypt the value. The value is same with either the 2nd augment of the setValue or the 1st augment of the setDefaultEncryptionPassword.
    Note: TODO add a test.
    
    Parameters:
    
    key - a key string to retrieve the value
    
    pass - a passphrase string to decrypt the value
    
    Returns:
    
    value of the key
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - getSubkeys
```
public List<String> getSubkeys(String key)
```
    Gets keys of subkeys of a key. Values of keys are not returned.
    
    Parameters:
    
    key - a key string to retrieve the value
    
    Returns:
    
    list of subkeys of the key. null if no subkeys exist.
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - setSubkey
```
public boolean setSubkey(String key,
                         String subkey)
```
    Sets a subkey of a key. The current key will be replaces with new one.
    
    Parameters:
    
    key - a key string
    
    subkey - the value of a subkey
    
    Returns:
    
    true if succeeded. false otherwise.
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - setSubkeys
```
public boolean setSubkeys(String key,
                          String[] subkeys)
```
    Sets subkeys.
    
    Parameters:
    
    key - a key string
    
    subkeys - an array of subkeys
    
    Returns:
    
    true if succeeded. false otherwise.
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - addSubkey
```
public boolean addSubkey(String key,
                         String subkey)
```
    Adds a subkey to a key.
    
    Parameters:
    
    key - a key string
    
    subkey - a subkey string
    
    Returns:
    
    true if succeeded. false otherwise.
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - addSubkeys
```
public boolean addSubkeys(String key,
                          String[] newKeys)
```
    Adds subkeys to a key.
    
    Parameters:
    
    key - a key string
    
    newKeys - an array of subkey string
    
    Returns:
    
    true if succeeded. false otherwise.
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - setAttribute
```
public boolean setAttribute(String key,
                            String attrName,
                            String attrVal)
```
    Sets an attribute of a key.
    
    Parameters:
    
    key - a key string
    
    attrName - an attribute name
    
    attrVal - an attribute value
    
    Returns:
    
    true if succeeded. false otherwise.
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - getAttributes
```
public Map<String,String> getAttributes(String key)
```
    Gets attributes of a key.
    
    Parameters:
    
    key - a key string to retrieve the value
    
    Returns:
    
    attributes of the key
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - getAttribute
```
public String getAttribute(String key,
                           String attribute)
```
    Gets an attribute of a key.
    
    Parameters:
    
    key - a key string
    
    attribute - an attribute name of the key
    
    Returns:
    
    the value of the attribute name of the key
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - setValue
```
public boolean setValue(String key,
                        String val)
```
    Sets a key with a value.
    
    Parameters:
    
    key - a key string
    
    val - the value of the key
    
    Returns:
    
    true if succeeded. false otherwise.
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - setValue
```
public boolean setValue(String key,
                        String val,
                        String password,
                        long duration,
                        TimeUnit unit)
```
    Sets a key with a value.
    
    Parameters:
    
    key - the key string
    
    val - the value of the key
    
    password - the password
    
    duration - duration to expire
    
    unit - unit of duration
    
    Returns:
    
    true if succeeded. false otherwise.
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - remove
```
public boolean remove(String key)
```
    Removes a key.
    
    Parameters:
    
    key - a key string
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - remove
```
public boolean remove(String key,
                      boolean removeAllSubkeys)
```
    Removes a key.
    
    Parameters:
    
    key - a key string
    
    removeAllSubkeys - true if removes all subkeys
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - remove
```
public boolean remove(String key,
                      String subkey)
```
    Removes a key from a subkey list and removes the subkey itself.
    Note: TODO add a test.
    
    Parameters:
    
    key - a key string
    
    subkey - a subkey string
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - rename
```
public boolean rename(String key,
                      String newkey)
```
    Renames a key with a new key.
    
    Parameters:
    
    key - a key string
    
    newkey - a subkey string
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - if an illegal augment exists
  - printTableStats
```
public void printTableStats(K2hash.STATS_DUMP_LEVEL level)
```
    Prints k2hash key table information.
    
    Parameters:
    
    level - level of details of dump table information
  - printDataStats
```
public void printDataStats()
```
    Prints data statistics.
  - version
```
public void version()
```
    Prints version information.

Class K2hash

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

K2H_INVALID_HANDLE

DEFAULT_IS_FULLMAP

DEFAULT_IS_READONLY

DEFAULT_IS_REMOVE_FILE

DEFAULT_MASK_BITS

DEFAULT_CMASK_BITS

DEFAULT_MAX_ELEMENT

DEFAULT_PAGE_SIZE

Method Detail

toString

getLibrary

getCLibrary

of

of

create

create

getHandle

close

beginTx

beginTx

getTxFileFd

stopTx

getTxPoolSize

setTxPoolSize

dumpToFile

dumpToFile

loadFromFile

loadFromFile

enableMtime

enableEncryption

setEncryptionPasswordFile

enableHistory

setExpirationDuration

addDecryptionPassword

setDefaultEncryptionPassword

addAttributePluginLib

printAttributePlugins

printAttributes

getValue

getValue

getValue

getSubkeys

setSubkey

setSubkeys

addSubkey

addSubkeys

setAttribute

getAttributes

getAttribute

setValue

setValue

remove

remove

remove

rename

printTableStats

printDataStats

version