K2hashKeyQueue (k2hash 1.0.1 API)

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

All Implemented Interfaces:: Closeable, AutoCloseable

public class K2hashKeyQueue
extends Object
implements Closeable

Queue holds keys of k2hash database in a FIFO (first-in-first-out) manner. Order of elements is configurable by passing a boolean variable to the 2nd parameter of constructors. Passing a true variable creates a Queue instance, Otherwise a Stack instance

The difference of KeyQueue and Queue: KeyQueue stores references to keys in k2hash database whereas Queue holds any kinds of elements on the other.

Usage Examples. Suppose you want to make a new data collection from current keys. KeyQueue is very useful because current keys will not be deleted after removing date from keyQueue. You can use KeyQueue as a temporary data container. You could write this as:


 package ax.antpick;

 import IOException;
 import java.util.*;
 import java.util.stream.*;
 import java.math.*;

 public class App {
   public static void main(String[] args) {
     // 1. setvalues
     HashMap<String, String> data = new HashMap<String, String>() {{ put("k1","v1"); put("k2","v2"); put("k3","v3");}};
     try (K2hash db = K2hash.of("App.k2h")) {
       for(Map.Entry<String, String> entry : data.entrySet()) {
         db.setValue(entry.getKey(), entry.getValue()); // setValue
       }
     } catch (IOException ex) {
       System.out.println(ex.getMessage());
       return;
     }
     // 2. offer to KeyQueue
     try (K2hash db = K2hash.of("App.k2h")) {
       long handle = db.getHandle();
       K2hashKeyQueue queue = K2hashKeyQueue.of(handle);
       HashMap<String, String> k1v1 = new HashMap<String, String>() {{ put("k1","v1"); }};
       HashMap<String, String> k2v2 = new HashMap<String, String>() {{ put("k2","v3"); }};
       HashMap<String, String> k3v3 = new HashMap<String, String>() {{ put("k3","v3"); }};
       queue.offer(k1v1);
       queue.offer(k2v2);
       queue.offer(k3v3);
       queue.offer(k3v3);
       queue.offer(k2v2);
       queue.offer(k1v1);
     } catch (IOException ex) {
       System.out.println(ex.getMessage());
       return;
     }
     // 3. peek from KeyQueue
     try (K2hash db = K2hash.of("App.k2h")) {
       long handle = db.getHandle();
       K2hashKeyQueue queue = K2hashKeyQueue.of(handle);
       Map<String,String> val = null;
       do {
         if( (val = queue.poll()) != null) {
           System.out.println(val.toString());
         }
       } while (val != null);
     } catch (IOException ex) {
       System.out.println(ex.getMessage());
       return;
     }
   }
 }

Field Summary

Fields
Modifier and Type	Field and Description
`static K2hashAttrPack[]`	`DEFAULT_ATTRPACK` Default K2hashAttrPack array is `null`.
`static int`	`DEFAULT_ATTRPACK_SIZE` Default size of a K2hashAttrPack array is `0`.
`static long`	`DEFAULT_EXPIRATION_DURATION` Default data expiration duration is `0`.
`static boolean`	`DEFAULT_FIFO` Default FIFO is `true`.
`static String`	`DEFAULT_PASS` Default passphrase string is `null`.
`static int`	`DEFAULT_POSITION` Default position of a peek operation is `0`.
`static String`	`DEFAULT_PREFIX` Default prefix string is `null`.
`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`	`add(Object obj)` Inserts an element into the tail of this queue.
`void`	`clear()` Removes all of the elements from this collection (optional operation).
`void`	`close()` Free KeyQueueHandle
`long`	`count()` Returns the number of queue.
`Map<String,String>`	`element()` Finds and gets a object from the head of this queue.
`Map<String,String>`	`element(int position)` Finds and gets a object from the head of this queue.
`long`	`getQueueHandle()` Returns a K2hashKeyQueue handle.
`boolean`	`isEmpty()` Returns true if, and only if, queue size is 0.
`static K2hashKeyQueue`	`of(long handle)` Constructs a K2hashKeyQueue instance.
`static K2hashKeyQueue`	`of(long handle, boolean fifo)` Constructs a K2hashKeyQueue instance.
`static K2hashKeyQueue`	`of(long handle, boolean fifo, String prefix)` Constructs a K2hashKeyQueue instance.
`static K2hashKeyQueue`	`of(long handle, boolean fifo, String prefix, String pass, long expirationDuration)` Constructs a K2hashKeyQueue instance.
`boolean`	`offer(Object obj)` Inserts an element into the tail of this queue.
`Map<String,String>`	`peek()` Finds and gets a object at the head of this queue.
`Map<String,String>`	`peek(int position)` Finds and gets a object from the head of this queue.
`Map<String,String>`	`poll()` Finds and gets a object from the head of this queue.
`void`	`print()` Print the objects in this queue.
`Map<String,String>`	`remove()` Finds and removes the object at the top of this queue and returns the object.
`boolean`	`remove(Object o)` Removes the object(key) at the top of this queue and the object(value) outside of this queue This remove method is derived from the Collection interface.
`List<Map<String,String>>`	`removeList(long count)` Removes the objects from this queue.
`String`	`toString()`

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_FIFO
```
public static boolean DEFAULT_FIFO
```
    Default FIFO is true.
  - DEFAULT_PREFIX
```
public static String DEFAULT_PREFIX
```
    Default prefix string is null.
  - DEFAULT_POSITION
```
public static int DEFAULT_POSITION
```
    Default position of a peek operation is 0.
  - DEFAULT_PASS
```
public static String DEFAULT_PASS
```
    Default passphrase string is null.
  - DEFAULT_EXPIRATION_DURATION
```
public static long DEFAULT_EXPIRATION_DURATION
```
    Default data expiration duration is 0.
  - DEFAULT_ATTRPACK
```
public static K2hashAttrPack[] DEFAULT_ATTRPACK
```
    Default K2hashAttrPack array is null.
  - DEFAULT_ATTRPACK_SIZE
```
public static int DEFAULT_ATTRPACK_SIZE
```
    Default size of a K2hashAttrPack array is 0.
- Method Detail
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - of
```
public static K2hashKeyQueue of(long handle)
                         throws IOException
```
    Constructs a K2hashKeyQueue instance.
    
    Parameters:
    
    handle - a K2hash data handle
    
    Returns:
    
    a K2hashKeyQueue instance
    
    Throws:
    
    IOException - if a K2hash data handle is invalid
  - of
```
public static K2hashKeyQueue of(long handle,
                                boolean fifo)
                         throws IOException
```
    Constructs a K2hashKeyQueue instance.
    
    Parameters:
    
    handle - a K2hash data handle
    
    fifo - true if elements are in a FIFO (first-in-first-out) manner
    
    Returns:
    
    a K2hashKeyQueue instance
    
    Throws:
    
    IOException - if a K2hash data handle is invalid
  - of
```
public static K2hashKeyQueue of(long handle,
                                boolean fifo,
                                String prefix)
                         throws IOException
```
    Constructs a K2hashKeyQueue instance.
    
    Parameters:
    
    handle - a K2hash data handle
    
    fifo - true if elements are in a FIFO (first-in-first-out) manner
    
    prefix - a prefix string of this queue
    
    Returns:
    
    a K2hashKeyQueue instance
    
    Throws:
    
    IOException - if a K2hash data handle is invalid
  - of
```
public static K2hashKeyQueue of(long handle,
                                boolean fifo,
                                String prefix,
                                String pass,
                                long expirationDuration)
                         throws IOException
```
    Constructs a K2hashKeyQueue instance.
    
    Parameters:
    
    handle - a K2hash data handle
    
    fifo - true if elements are in a FIFO (first-in-first-out) manner
    
    prefix - a prefix string of this queue
    
    pass - a passphrase to access data
    
    expirationDuration - a duration to expire data in seconds
    
    Returns:
    
    a K2hashKeyQueue instance
    
    Throws:
    
    IOException - if a K2hash data handle is invalid
    
    IllegalArgumentException - if position is less than zero
  - close
```
public void close()
           throws IOException
```
    Free KeyQueueHandle
    
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable
    
    Throws:
    
    IOException
  - getQueueHandle
```
public long getQueueHandle()
```
    Returns a K2hashKeyQueue handle.
    
    Returns:
    
    a K2hashKeyQueue handle
  - isEmpty
```
public boolean isEmpty()
```
    Returns true if, and only if, queue size is 0.
    
    Returns:
    
    true if empty false otherwise
  - count
```
public long count()
```
    Returns the number of queue.
    
    Returns:
    
    the number of queue.
  - peek
```
public Map<String,String> peek()
```
    Finds and gets a object at the head of this queue. Null returns if this queue is empty. This operation is a read-only access. The object will not remove from this queue. This method is the same function as k2h_q_read in C API.
    
    Returns:
    
    an object at the head of this queue
  - peek
```
public Map<String,String> peek(int position)
```
    Finds and gets a object from the head of this queue. Null returns if this queue is empty. This operation is a read-only access. The object will not remove from this queue. This method is the same function as k2h_q_read in C API.
    
    Parameters:
    
    position - a position to peek in this queue
    
    Returns:
    
    an object at the position of this queue
    
    Throws:
    
    IllegalArgumentException - if the position is less than zero
  - offer
```
public boolean offer(Object obj)
```
    Inserts an element into the tail of this queue.
    
    Parameters:
    
    obj - an object to be inserted to this queue
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    IllegalArgumentException - - if arguments are illegal.
  - poll
```
public Map<String,String> poll()
```
    Finds and gets a object from the head of this queue. Null returns if this queue is empty. This operation is a write access. The object will remove from this queue.
    
    Returns:
    
    the object at the head of this queue. returns null if empty.
  - add
```
public boolean add(Object obj)
```
    Inserts an element into the tail of this queue.
    
    Parameters:
    
    obj - an object to be inserted into this queue
    
    Returns:
    
    true if success false otherwise
    
    Throws:
    
    NoSuchElementException - - if this queue is empty
  - remove
```
public Map<String,String> remove()
```
    Finds and removes the object at the top of this queue and returns the object.
    
    Returns:
    
    the object at the top of this queue
    
    Throws:
    
    NoSuchElementException - - if this queue is empty
  - remove
```
public boolean remove(Object o)
```
    Removes the object(key) at the top of this queue and the object(value) outside of this queue This remove method is derived from the Collection interface.
    
    Parameters:
    
    o - element to be removed from this collection, if present
    
    Returns:
    
    true if an element was removed as a result of this call
  - removeList
```
public List<Map<String,String>> removeList(long count)
```
    Removes the objects from this queue.
    
    Parameters:
    
    count - the number of objects to be removed
    
    Returns:
    
    list of removed objects
    
    Throws:
    
    NoSuchElementException - - if this queue is empty
    
    IllegalArgumentException - if an illegal augment exists
  - element
```
public Map<String,String> element()
```
    Finds and gets a object from the head of this queue. Throws NoSuchElementException if this queue is empty. This operation is a read-only access. The object will not remove from this queue.
    
    Returns:
    
    a copy of the string in queue
    
    Throws:
    
    NoSuchElementException - - if this queue is empty
  - element
```
public Map<String,String> element(int position)
```
    Finds and gets a object from the head of this queue. Throws NoSuchElementException if this queue is empty. This operation is a read-only access. The object will not remove from this queue.
    
    Parameters:
    
    position - position where the data exists in queue
    
    Returns:
    
    a copy of the string in queue
    
    Throws:
    
    NoSuchElementException - - if this queue is empty
    
    IllegalArgumentException - if an illegal augment exists
  - clear
```
public void clear()
```
    Removes all of the elements from this collection (optional operation). The collection will be empty after this method returns.
  - print
```
public void print()
```
    Print the objects in this queue.
    
    Throws:
    
    NoSuchElementException - - if this queue is empty

Class K2hashKeyQueue

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

K2H_INVALID_HANDLE

DEFAULT_FIFO

DEFAULT_PREFIX

DEFAULT_POSITION

DEFAULT_PASS

DEFAULT_EXPIRATION_DURATION

DEFAULT_ATTRPACK

DEFAULT_ATTRPACK_SIZE

Method Detail

toString

of

of

of

of

close

getQueueHandle

isEmpty

count

peek

peek

offer

poll

add

remove

remove

removeList

element

element

clear

print