K2hashQueue (k2hash 1.0.1 API)

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

All Implemented Interfaces:: Closeable, AutoCloseable

public class K2hashQueue
extends Object
implements Closeable

Queue holds elements 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 constructs a Queue instance, Otherwise a Stack instance is created.

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

Usage Examples. Suppose you want to make a new sorted data collection in a K2hashQueue. You could write this as:


 package com.example;

 import java.io.IOException;
 import java.util.*;
 import java.util.stream.*;
 import ax.antpick.*;

 public class App {
   public static void main(String[] args) {
     // 1. make a random string array for test
     String[] suffleArray = {"e", "b", "d", "a", "c"};
     // 2. sort it!
     Arrays.sort(suffleArray);
     // 3. offer to a Queue
     Stream<String> stream = Stream.of(suffleArray);
     try (K2hash db = K2hash.of("App.k2h")) {
       long handle = db.getHandle();
       K2hashQueue queue = K2hashQueue.of(handle);
       stream.forEach(s -> { queue.offer(s); });
     } catch (IOException ex) {
       System.out.println(ex.getMessage());
       return;
     }
     // 4. poll from the Queue
     try (K2hash db = K2hash.of("App.k2h")) {
       long handle = db.getHandle();
       K2hashQueue queue = K2hashQueue.of(handle);
       String s = null;
       do {
         s = queue.poll();
         System.out.println(s);
       } while (s != 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.
`String`	`element()` Finds and gets a object from the head of this queue.
`String`	`element(int position)` Finds and gets a object from the head of this queue.
`long`	`getQueueHandle()` Returns a K2hashQueue handle.
`boolean`	`isEmpty()` Returns true if, and only if, queue size is 0.
`static K2hashQueue`	`of(long handle)` Constructs a K2hashQueue instance.
`static K2hashQueue`	`of(long handle, boolean fifo, String prefix)` Constructs a K2hashQueue instance.
`static K2hashQueue`	`of(long handle, boolean fifo, String prefix, String pass, long expirationDuration)` Constructs a K2hashQueue instance.
`boolean`	`offer(Object obj)` Inserts an element into the tail of this queue.
`String`	`peek()` Finds and gets a object at the head of this queue.
`String`	`peek(int position)` Finds and gets a object from the head of this queue.
`String`	`poll()` Finds and gets a object from the head of this queue.
`void`	`print()` Print the objects in this queue.
`String`	`remove()` Finds and removes the object at the top of this queue and returns the object.
`List<String>`	`removeList(long count)` Removes 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 final boolean DEFAULT_FIFO
```
    Default FIFO is true.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_PREFIX
```
public static final String DEFAULT_PREFIX
```
    Default prefix string is null.
  - DEFAULT_POSITION
```
public static final int DEFAULT_POSITION
```
    Default position of a peek operation is 0.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_PASS
```
public static final String DEFAULT_PASS
```
    Default passphrase string is null.
  - DEFAULT_EXPIRATION_DURATION
```
public static final long DEFAULT_EXPIRATION_DURATION
```
    Default data expiration duration is 0.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_ATTRPACK
```
public static final K2hashAttrPack[] DEFAULT_ATTRPACK
```
    Default K2hashAttrPack array is null.
  - DEFAULT_ATTRPACK_SIZE
```
public static final int DEFAULT_ATTRPACK_SIZE
```
    Default size of a K2hashAttrPack array is 0.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - of
```
public static K2hashQueue of(long handle)
                      throws IOException
```
    Constructs a K2hashQueue instance.
    
    Parameters:
    
    handle - a K2hash data handle
    
    Returns:
    
    a K2hashQueue instance
    
    Throws:
    
    IOException - if a K2hash data handle is invalid
  - of
```
public static K2hashQueue of(long handle,
                             boolean fifo,
                             String prefix)
                      throws IOException
```
    Constructs a K2hashQueue 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 K2hashQueue instance
    
    Throws:
    
    IOException - if a K2hash data handle is invalid
  - of
```
public static K2hashQueue of(long handle,
                             boolean fifo,
                             String prefix,
                             String pass,
                             long expirationDuration)
                      throws IOException
```
    Constructs a K2hashQueue 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 string to access data
    
    expirationDuration - a duration to expire data in seconds
    
    Returns:
    
    a K2hashQueue instance
    
    Throws:
    
    IOException - if a K2hash handle is invalid
    
    IllegalArgumentException - if an illegal augment exists
  - 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 K2hashQueue handle.
    
    Returns:
    
    a K2hashQueue 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 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 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 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
    
    IllegalArgumentException - if an illegal augment exists
  - remove
```
public 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
  - removeList
```
public List<String> removeList(long count)
```
    Removes 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 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 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 K2hashQueue

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

close

getQueueHandle

isEmpty

count

peek

peek

offer

poll

add

remove

removeList

element

element

clear

print