QueueSimple

java.lang.Object
- ch.cern.dirq.QueueSimple

All Implemented Interfaces:

Queue, java.lang.Iterable<java.lang.String>
```
public class QueueSimple
extends java.lang.Object
implements Queue
```
QueueSimple - object oriented interface to a simple directory based queue.
A port of Perl module Directory::Queue::Simple http://search.cpan.org/dist/Directory-Queue/
The documentation from Directory::Queue::Simple module was adapted for Java.

Usage
```
 // sample producer
 QueueSimple dirq = new QueueSimple("/tmp/test");
 for (int i=0; i < 100; i++) {
 	String name = dirq.add("element " + i);
 	System.out.println("# added element " + i + " as " + name);
 }

 // sample consumer
 dirq = QueueSimple('/tmp/test');
 for (String name:dirq) {
 	if (! dirq.lock(name)) {
 		continue;
 	}
 	System.out.println("# reading element " + name);
 	String data = dirq.get(name);
 	// one could use dirq.unlock(name) to only browse the queue...
 	dirq.remove(name);
 }
 
 
```
Description

This module is very similar to normal dirq, but uses a different way to store data in the filesystem, using less directories. Its API is almost identical.
Compared to normal dirq, this module:
- is simpler
- is faster
- uses less space on disk
- can be given existing files to store
- does not support schemas
- can only store and retrieve byte strings
- is not compatible (at filesystem level) with Queue
Directory Structure

The toplevel directory contains intermediate directories that contain the stored elements, each of them in a file.
The names of the intermediate directories are time based: the element insertion time is used to create a 8-digits long hexadecimal number.
The granularity (see the constructor) is used to limit the number of new directories. For instance, with a granularity of 60 (the default), new directories will be created at most once per minute.
Since there is usually a filesystem limit in the number of directories a directory can hold, there is a trade-off to be made. If you want to support many added elements per second, you should use a low granularity to keep small directories. However, in this case, you will create many directories and this will limit the total number of elements you can store.
The elements themselves are stored in files (one per element) with a 14-digits long hexadecimal name SSSSSSSSMMMMMR where:
- SSSSSSSS represents the number of seconds since the Epoch
- MMMMM represents the microsecond part of the time since the Epoch
- R is a random digit used to reduce name collisions
A temporary element (being added to the queue) will have a .tmp suffix.
A locked element will have a hard link with the same name and the .lck suffix.
Please refer to Queue for general information about directory queues.
Author:

Massimo Paladin - massimo.paladin@gmail.com
Copyright (C) CERN 2012-2013

Field Summary

Fields
Modifier and Type	Field and Description
`static java.util.regex.Pattern`	`DIRECTORY_REGEXP`
`static java.util.regex.Pattern`	`ELEMENT_REGEXP`
`static java.lang.String`	`LOCKED_SUFFIX`
`static java.lang.String`	`TEMPORARY_SUFFIX`

Constructor Summary

Constructors
Constructor and Description
`QueueSimple(java.lang.String queuePath)` Constructor which takes only the path of the queue and set umask and granularity to default values.
`QueueSimple(java.lang.String queuePath, int umask)` Constructor which takes the path of the directory queue, its granularity option and the umask the created folder.
`QueueSimple(java.lang.String queuePath, int umask, int granularity)` Constructor which takes the path of the directory queue, its granularity option and the umask the created folder.

Method Summary

Methods
Modifier and Type	Method and Description
`java.lang.String`	`add(byte[] data)` Add data as byte array to the queue.
`java.lang.String`	`add(java.lang.String data)` Add data as a string to the queue.
`java.lang.String`	`addPath(java.lang.String path)` Add the given file (identified by its path) to the queue and return the corresponding element name, the file must be on the same filesystem and will be moved to the queue.
`int`	`count()` Return the number of elements in the queue, locked or not (but not temporary).
`java.lang.String`	`get(java.lang.String name)` Get locked element as a string.
`byte[]`	`getAsByteArray(java.lang.String name)` Get locked element as a byte array.
`int`	`getGranularity()` Return the granularity value.
`java.lang.String`	`getId()`
`java.lang.String`	`getPath(java.lang.String name)` Return the path given the name of the element.
`java.lang.String`	`getQueuePath()`
`java.util.Iterator<java.lang.String>`	`iterator()`
`boolean`	`lock(java.lang.String name)` Lock an element in permissive mode.
`boolean`	`lock(java.lang.String name, boolean permissive)` Lock an element.
`void`	`purge()` Purge the queue by removing unused intermediate directories, removing too old temporary elements and unlocking too old locked elements (aka staled locks); note: this can take a long time on queues with many elements.
`void`	`purge(int maxLock)` Purge the queue by removing unused intermediate directories, removing too old temporary elements and unlocking too old locked elements (aka staled locks); note: this can take a long time on queues with many elements.
`void`	`purge(int maxTemp, int maxLock)` Purge the queue by removing unused intermediate directories, removing too old temporary elements and unlocking too old locked elements (aka staled locks); note: this can take a long time on queues with many elements.
`void`	`purge(java.util.Map<java.lang.String,java.lang.Integer> options)` Purge the queue by removing unused intermediate directories, removing too old temporary elements and unlocking too old locked elements (aka staled locks); note: this can take a long time on queues with many elements.
`void`	`remove(java.lang.String name)` Remove a locked element from the queue.
`void`	`setGranularity(int granularity)` Set the granularity property.
`boolean`	`unlock(java.lang.String name)` Unlock an element in non-permissive mode.
`boolean`	`unlock(java.lang.String name, boolean permissive)` Unlock an element.

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

- Field Detail
  - TEMPORARY_SUFFIX
```
public static final java.lang.String TEMPORARY_SUFFIX
```
    See Also:
    Constant Field Values
  - LOCKED_SUFFIX
```
public static final java.lang.String LOCKED_SUFFIX
```
    See Also:
    Constant Field Values
  - DIRECTORY_REGEXP
```
public static final java.util.regex.Pattern DIRECTORY_REGEXP
```
  - ELEMENT_REGEXP
```
public static final java.util.regex.Pattern ELEMENT_REGEXP
```
- Constructor Detail
  - QueueSimple
```
public QueueSimple(java.lang.String queuePath)
            throws java.io.IOException
```
    Constructor which takes only the path of the queue and set umask and granularity to default values.
    
    Parameters:
    queuePath - the path of the directory queue
    
    Throws:
    
    java.io.IOException
  - QueueSimple
```
public QueueSimple(java.lang.String queuePath,
           int umask)
            throws java.io.IOException
```
    Constructor which takes the path of the directory queue, its granularity option and the umask the created folder.
    
    Parameters:
    queuePath - the path of the directory queue
    umask - umask the umask value to be set during folder creation
    
    Throws:
    
    java.io.IOException
  - QueueSimple
```
public QueueSimple(java.lang.String queuePath,
           int umask,
           int granularity)
            throws java.io.IOException
```
    Constructor which takes the path of the directory queue, its granularity option and the umask the created folder.
    
    Parameters:
    queuePath - the path of the directory queue
    umask - the umask value to be set during folder creation
    granularity - the granularity of the directory queue
    
    Throws:
    
    java.io.IOException
- Method Detail
  - getGranularity
```
public int getGranularity()
```
    Return the granularity value.
    
    Returns:
    granularity value
  - setGranularity
```
public void setGranularity(int granularity)
```
    Set the granularity property.
    
    Parameters:
    granularity - value to be set as granularity
  - getId
```
public java.lang.String getId()
```
    Specified by:
    
    getId in interface Queue
    
    Returns:
    the queue id
  - getQueuePath
```
public java.lang.String getQueuePath()
```
    Returns:
    the queue path
  - add
```
public java.lang.String add(byte[] data)
                     throws java.io.IOException
```
    Description copied from interface: Queue
    
    Add data as byte array to the queue.
    
    Specified by:
    
    add in interface Queue
    
    Parameters:
    data - data to be added to the queue
    
    Returns:
    return the element name (/)
    
    Throws:
    
    java.io.IOException - if any file operation fail
  - add
```
public java.lang.String add(java.lang.String data)
                     throws java.io.IOException
```
    Description copied from interface: Queue
    
    Add data as a string to the queue.
    
    Specified by:
    
    add in interface Queue
    
    Parameters:
    data - data to be added to the queue
    
    Returns:
    return the element name (/)
    
    Throws:
    
    java.io.IOException - if any file operation fail
  - addPath
```
public java.lang.String addPath(java.lang.String path)
                         throws java.io.IOException
```
    Description copied from interface: Queue
    
    Add the given file (identified by its path) to the queue and return the corresponding element name, the file must be on the same filesystem and will be moved to the queue.
    
    Specified by:
    
    addPath in interface Queue
    
    Parameters:
    path - the path of the file to be added
    
    Returns:
    return the element name (/)
    
    Throws:
    
    java.io.IOException - if any file operation fail
  - get
```
public java.lang.String get(java.lang.String name)
```
    Description copied from interface: Queue
    
    Get locked element as a string.
    
    Specified by:
    
    get in interface Queue
    
    Parameters:
    name - the name of the element to be returned
    
    Returns:
    return the value associated to the given name
  - getAsByteArray
```
public byte[] getAsByteArray(java.lang.String name)
```
    Description copied from interface: Queue
    
    Get locked element as a byte array.
    
    Specified by:
    
    getAsByteArray in interface Queue
    
    Parameters:
    name - the name of the element to be returned
    
    Returns:
    the value associated to the given name
  - getPath
```
public java.lang.String getPath(java.lang.String name)
```
    Description copied from interface: Queue
    
    Return the path given the name of the element.
    
    Specified by:
    
    getPath in interface Queue
    
    Parameters:
    name - the name of the element
    
    Returns:
    the path of the element
  - lock
```
public boolean lock(java.lang.String name)
             throws java.io.IOException
```
    Description copied from interface: Queue
    
    Lock an element in permissive mode.
    
    Specified by:
    
    lock in interface Queue
    
    Parameters:
    name - name of the element to be locked
    
    Returns:
    true on success, false if the element could not be locked
    
    Throws:
    
    java.io.IOException - if any file operation fail
  - lock
```
public boolean lock(java.lang.String name,
           boolean permissive)
             throws java.io.IOException
```
    Description copied from interface: Queue
    
    Lock an element.
    
    Specified by:
    
    lock in interface Queue
    
    Parameters:
    name - name of the element to be locked
    permissive - work in permissive mode
    
    Returns:
    true on success, false if the element could not be locked
    
    Throws:
    
    java.io.IOException - if any file operation fail
  - unlock
```
public boolean unlock(java.lang.String name)
               throws java.io.IOException
```
    Description copied from interface: Queue
    
    Unlock an element in non-permissive mode.
    
    Specified by:
    
    unlock in interface Queue
    
    Parameters:
    name - name of the element to be locked
    
    Returns:
    true on success, false if the element could not be unlocked
    
    Throws:
    
    java.io.IOException - if any file operation fail
  - unlock
```
public boolean unlock(java.lang.String name,
             boolean permissive)
               throws java.io.IOException
```
    Description copied from interface: Queue
    
    Unlock an element.
    
    Specified by:
    
    unlock in interface Queue
    
    Parameters:
    name - name of the element to be locked
    permissive - work in permissive mode
    
    Returns:
    true on success, false if the element could not be unlocked
    
    Throws:
    
    java.io.IOException - if any file operation fail
  - remove
```
public void remove(java.lang.String name)
```
    Description copied from interface: Queue
    
    Remove a locked element from the queue.
    
    Specified by:
    
    remove in interface Queue
    
    Parameters:
    name - name of the element to be removed
  - count
```
public int count()
```
    Description copied from interface: Queue
    
    Return the number of elements in the queue, locked or not (but not temporary).
    
    Specified by:
    
    count in interface Queue
    
    Returns:
    the number of elements in the queue
  - purge
```
public void purge()
           throws java.io.IOException
```
    Description copied from interface: Queue
    
    Purge the queue by removing unused intermediate directories, removing too old temporary elements and unlocking too old locked elements (aka staled locks); note: this can take a long time on queues with many elements.
    It uses default value for maxTemp and maxLock
    
    Specified by:
    
    purge in interface Queue
    
    Throws:
    
    java.io.IOException - if any file operation fail
  - purge
```
public void purge(java.util.Map<java.lang.String,java.lang.Integer> options)
           throws java.io.IOException
```
    Description copied from interface: Queue
    
    Purge the queue by removing unused intermediate directories, removing too old temporary elements and unlocking too old locked elements (aka staled locks); note: this can take a long time on queues with many elements.
    
    Specified by:
    
    purge in interface Queue
    
    Parameters:
    options - map containing purge options, only maxLock and maxTemp values are used, the others are ignored
    
    Throws:
    
    java.io.IOException - if any file operation fail
  - purge
```
public void purge(int maxLock)
           throws java.io.IOException
```
    Description copied from interface: Queue
    
    Purge the queue by removing unused intermediate directories, removing too old temporary elements and unlocking too old locked elements (aka staled locks); note: this can take a long time on queues with many elements.
    
    Specified by:
    
    purge in interface Queue
    
    Parameters:
    maxLock - maximum time for a locked element (in seconds, default 600); if set to 0, locked elements will not be unlocked
    
    Throws:
    
    java.io.IOException - if any file operation fail
  - purge
```
public void purge(int maxTemp,
         int maxLock)
           throws java.io.IOException
```
    Description copied from interface: Queue
    
    Purge the queue by removing unused intermediate directories, removing too old temporary elements and unlocking too old locked elements (aka staled locks); note: this can take a long time on queues with many elements.
    
    Specified by:
    
    purge in interface Queue
    
    Parameters:
    maxTemp - maximum time for a temporary element (in seconds, default 300); if set to 0, temporary elements will not be removed
    maxLock - maximum time for a locked element (in seconds, default 600); if set to 0, locked elements will not be unlocked
    
    Throws:
    
    java.io.IOException - if any file operation fail
  - iterator
```
public java.util.Iterator<java.lang.String> iterator()
```
    Specified by:
    
    iterator in interface java.lang.Iterable<java.lang.String>

Class QueueSimple

Usage

Description

Directory Structure

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

TEMPORARY_SUFFIX

LOCKED_SUFFIX

DIRECTORY_REGEXP

ELEMENT_REGEXP

Constructor Detail

QueueSimple

QueueSimple

QueueSimple

Method Detail

getGranularity

setGranularity

getId

getQueuePath

add

add

addPath

get

getAsByteArray

getPath

lock

lock

unlock

unlock

remove

count

purge

purge

purge

purge

iterator