Package ax.antpick.k2hash

Class 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.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());
     }
   }
 }

    • 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

      • 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.

      • 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

      • 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.