Class JESpace<K,V>

java.lang.Object

org.jpos.util.Log

org.jpos.space.JESpace<K,V>

Type Parameters:

K - the key type

V - the value type

All Implemented Interfaces:

AutoCloseable, Runnable, LocalSpace<K,V>, PersistentSpace, Space<K,V>, Loggeable, LogSource

public class JESpace<K,V>
extends Log
implements LocalSpace<K,V>, PersistentSpace, Loggeable, Runnable

BerkeleyDB Jave Edition based persistent space implementation

Since:

1.6.5

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	JESpace.GCRef	Persistent entity used by the garbage collector to track expiring Ref entries.
static class	JESpace.Ref	Persistent entity representing a single space entry (key/value with optional expiration).

Field Summary

Fields

Modifier and Type	Field	Description
static final long	DEFAULT_LOCK_TIMEOUT	Default lock timeout in milliseconds.
static final long	DEFAULT_TXN_TIMEOUT	Default transaction timeout in milliseconds.
static final long	GC_DELAY	Delay in milliseconds between GC runs.

Fields inherited from class Log

DEBUG, defaultTags, ERROR, FATAL, INFO, logger, realm, TRACE, WARN

Modifier and Type	Field	Description
static final String	DEBUG	Level constant for debug events.
protected final Map<String,String>	defaultTags	Default tags applied to every LogEvent created by this Log.
static final String	ERROR	Level constant for error events.
static final String	FATAL	Level constant for fatal events.
static final String	INFO	Level constant for informational events.
protected Logger	logger	Logger receiving the events produced by this Log.
protected String	realm	Realm associated with events emitted through this Log.
static final String	TRACE	Level constant for trace events.
static final String	WARN	Level constant for warning events.

Constructor Summary

Constructors

Constructor	Description
JESpace(String name, String params)	Constructs a JESpace with the given name and path/parameter string.

Method Summary

Modifier and Type	Method	Description
void	addListener(Object key, SpaceListener listener)	add a SpaceListener associated with a given key
void	addListener(Object key, SpaceListener listener, long timeout)	add a SpaceListener associated with a given key for a given period of time.
void	close()
void	dump(PrintStream p, String indent)	Dumps a human-readable representation of this object to the print stream.
boolean	existAny(Object[] keys)	Returns true if any of the given keys are present in the space.
boolean	existAny(Object[] keys, long timeout)	Returns true if any of the given keys become available within the timeout.
void	gc()	Runs a garbage-collection pass removing expired entries from the BDB JE store.
Set	getKeySet()	Returns the set of all keys currently present in the space.
static JESpace	getSpace(String name)	Returns (or creates) the named JESpace using the name as the storage path.
static JESpace	getSpace(String name, String path)	Returns (or creates) the named JESpace stored at the given path.
V	in(Object key)	Take an entry from the space, waiting forever until one exists.
V	in(Object key, long timeout)	Take an entry from the space, waiting a limited amount of time until one exists.
V	inp(Object key)	In probe takes an entry from the space if one exists, return null otherwise.
void	nrd(Object key)	Nrd (not read) waits forever until Key is not present in space. Resolution for expiring entries is implementation dependant, but a minimum one-second is suggested.
V	nrd(Object key, long timeout)	Nrd (not read) waits up to timeout until Key is not present in space. Resolution for expiring entries is implementation dependant, but a minimum one-second is suggested.
void	out(K key, V value)	Write a new entry into the Space
void	out(K key, V value, long timeout)	Write a new entry into the Space, with an timeout value
void	push(K key, V value)	Write a new entry at the head of a queue.
void	push(K key, V value, long timeout)	Write a new entry at the head of the queue with a timeout value
void	put(K key, V value)	Removes all existing entries for the key then writes a single entry (head-of-queue replacement).
void	put(K key, V value, long timeout)	Write a single entry at the head of the queue discarding the other entries, with timeout.
V	rd(Object key)	Read an entry from the space, waiting forever until one exists.
V	rd(Object key, long timeout)	Read an entry from the space, waiting a limited amount of time until one exists.
V	rdp(Object key)	Read probe reads an entry from the space if one exists, return null otherwise.
void	removeListener(Object key, SpaceListener listener)	removes a SpaceListener associated with a given key
void	run()
int	size(Object key)	Returns the number of entries queued under the given key.

Methods inherited from class Log

applyDefaultTags, createDebug, createDebug, createError, createError, createFatal, createFatal, createInfo, createInfo, createLogEvent, createLogEvent, createTrace, createTrace, createWarn, createWarn, debug, debug, error, error, fatal, fatal, getDefaultTags, getLog, getLogger, getRealm, info, info, removeDefaultTag, setDefaultTag, setDefaultTags, setLogger, setLogger, setRealm, trace, trace, warn, warn

Modifier and Type	Method	Description
protected LogEvent	applyDefaultTags(LogEvent evt)	Decorates evt with this Log's default tags, if any.
LogEvent	createDebug()	Creates an empty debug-level event.
LogEvent	createDebug(Object detail)	Creates a debug-level event with the given payload.
LogEvent	createError()	Creates an empty error-level event.
LogEvent	createError(Object detail)	Creates an error-level event with the given payload.
LogEvent	createFatal()	Creates an empty fatal-level event.
LogEvent	createFatal(Object detail)	Creates a fatal-level event with the given payload.
LogEvent	createInfo()	Creates an empty info-level event.
LogEvent	createInfo(Object detail)	Creates an info-level event with the given payload.
LogEvent	createLogEvent(String level)	Creates a new LogEvent at the given level decorated with this Log's default tags.
LogEvent	createLogEvent(String level, Object detail)	Creates a new LogEvent at the given level with an initial payload.
LogEvent	createTrace()	Creates an empty trace-level event.
LogEvent	createTrace(Object detail)	Creates a trace-level event with the given payload.
LogEvent	createWarn()	Creates an empty warning-level event.
LogEvent	createWarn(Object detail)	Creates a warning-level event with the given payload.
void	debug(Object detail)	Logs a debug event with the given detail.
void	debug(Object detail, Object obj)	Logs a debug event with the given detail and an additional payload.
void	error(Object detail)	Logs an error event with the given detail.
void	error(Object detail, Object obj)	Logs an error event with the given detail and an additional payload.
void	fatal(Object detail)	Logs a fatal event with the given detail.
void	fatal(Object detail, Object obj)	Logs a fatal event with the given detail and an additional payload.
Map<String,String>	getDefaultTags()	Returns an unmodifiable snapshot of the current default tags.
static Log	getLog(String logName, String realm)	Convenience factory returning a Log bound to the given logger name and realm.
Logger	getLogger()	Returns the underlying logger.
String	getRealm()	Returns the realm associated with events emitted through this Log.
void	info(Object detail)	Logs an info event with the given detail.
void	info(Object detail, Object obj)	Logs an info event with the given detail and an additional payload.
void	removeDefaultTag(String key)	Removes a previously-registered default tag.
void	setDefaultTag(String key, String value)	Sets a default tag on every event produced by this Log; a null value removes the entry.
void	setDefaultTags(Map<String,String> tags)	Replaces the entire set of default tags.
void	setLogger(Logger logger)	Replaces the underlying logger, leaving the realm unchanged.
void	setLogger(Logger logger, String realm)	Replaces the underlying logger and realm.
void	setRealm(String realm)	Replaces the realm associated with emitted events.
void	trace(Object detail)	Logs a trace event with the given detail.
void	trace(Object detail, Object obj)	Logs a trace event with the given detail and an additional payload.
void	warn(Object detail)	Logs a warning event with the given detail.
void	warn(Object detail, Object obj)	Logs a warning event with the given detail and an additional payload.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface Loggeable

dump

Modifier and Type	Method	Description
default void	dump(PrintStream p, String indent, LogRenderer.Type type)	Dumps a representation of this object using the specified renderer type.

Field Details

GC_DELAY

public static final long GC_DELAY

Delay in milliseconds between GC runs.

See Also:

• Constant Field Values

DEFAULT_TXN_TIMEOUT

public static final long DEFAULT_TXN_TIMEOUT

Default transaction timeout in milliseconds.

See Also:

• Constant Field Values

DEFAULT_LOCK_TIMEOUT

public static final long DEFAULT_LOCK_TIMEOUT

Default lock timeout in milliseconds.

See Also:

• Constant Field Values

Constructor Details

JESpace

public JESpace(String name,
 String params)
        throws SpaceError

Constructs a JESpace with the given name and path/parameter string.

Parameters:

name - the space name (also used as the entity store name)

params - comma-separated parameters; first element is the directory path

Throws:

SpaceError - if the BerkeleyDB environment or store cannot be opened

Method Details

out

public void out(K key,
 V value)

Description copied from interface: Space

Write a new entry into the Space

Specified by:

out in interface Space<K,V>

Parameters:

key - Entry's key

value - Object value

out

public void out(K key,
 V value,
 long timeout)

Description copied from interface: Space

Write a new entry into the Space, with an timeout value

Specified by:

out in interface Space<K,V>

Parameters:

key - Entry's key

value - Object value

timeout - timeout value in millis

push

public void push(K key,
 V value,
 long timeout)

Description copied from interface: Space

Write a new entry at the head of the queue with a timeout value

Specified by:

push in interface Space<K,V>

Parameters:

key - Entry's key

value - Object value

timeout - timeout value in millis

push

public void push(K key,
 V value)

Description copied from interface: Space

Write a new entry at the head of a queue.

Specified by:

push in interface Space<K,V>

Parameters:

key - Entry's key

value - Object value

rdp

public V rdp(Object key)

Description copied from interface: Space

Read probe reads an entry from the space if one exists, return null otherwise.

Specified by:

rdp in interface Space<K,V>

Parameters:

key - Entry's key

Returns:

value or null

in

public V in(Object key)

Description copied from interface: Space

Take an entry from the space, waiting forever until one exists.

Specified by:

in in interface Space<K,V>

Parameters:

key - Entry's key

Returns:

value

in

public V in(Object key,
 long timeout)

Description copied from interface: Space

Take an entry from the space, waiting a limited amount of time until one exists.

Specified by:

in in interface Space<K,V>

Parameters:

key - Entry's key

timeout - millis to wait

Returns:

value or null

rd

public V rd(Object key)

Description copied from interface: Space

Read an entry from the space, waiting forever until one exists.

Specified by:

rd in interface Space<K,V>

Parameters:

key - Entry's key

Returns:

value

rd

public V rd(Object key,
 long timeout)

Description copied from interface: Space

Read an entry from the space, waiting a limited amount of time until one exists.

Specified by:

rd in interface Space<K,V>

Parameters:

key - Entry's key

timeout - millis to wait

Returns:

value or null

nrd

public void nrd(Object key)

Description copied from interface: Space

Nrd (not read) waits forever until Key is not present in space.
Resolution for expiring entries is implementation dependant, but a minimum one-second is suggested.

Specified by:

nrd in interface Space<K,V>

Parameters:

key - Entry's key

nrd

public V nrd(Object key,
 long timeout)

Description copied from interface: Space

Nrd (not read) waits up to timeout until Key is not present in space.
Resolution for expiring entries is implementation dependant, but a minimum one-second is suggested.

Specified by:

nrd in interface Space<K,V>

Parameters:

key - Entry's key

timeout - millis to wait

Returns:

value or null

inp

public V inp(Object key)

Description copied from interface: Space

In probe takes an entry from the space if one exists, return null otherwise.

Specified by:

inp in interface Space<K,V>

Parameters:

key - Entry's key

Returns:

value or null

existAny

public boolean existAny(Object[] keys)

Description copied from interface: Space

Returns true if any of the given keys are present in the space.

Specified by:

existAny in interface Space<K,V>

Parameters:

keys - array of keys to check

Returns:

true if one or more keys are available in the space

existAny

public boolean existAny(Object[] keys,
 long timeout)

Description copied from interface: Space

Returns true if any of the given keys become available within the timeout.

Specified by:

existAny in interface Space<K,V>

Parameters:

keys - array of keys to check

timeout - to wait for any of the entries to become available in millis

Returns:

true if one or more keys are available in the space

put

public void put(K key,
 V value,
 long timeout)

Description copied from interface: Space

Write a single entry at the head of the queue discarding the other entries, with timeout.

Specified by:

put in interface Space<K,V>

Parameters:

key - Entry's key

value - Object value

timeout - timeout value in millis

put

public void put(K key,
 V value)

Removes all existing entries for the key then writes a single entry (head-of-queue replacement).

Specified by:

put in interface Space<K,V>

Parameters:

key - the entry key

value - the new value

gc

public void gc()
        throws com.sleepycat.je.DatabaseException

Runs a garbage-collection pass removing expired entries from the BDB JE store.

Throws:

com.sleepycat.je.DatabaseException - on BDB error

run

public void run()

Specified by:

run in interface Runnable

close

public void close()
           throws com.sleepycat.je.DatabaseException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Space<K,V>

Throws:

com.sleepycat.je.DatabaseException

getSpace

public static JESpace getSpace(String name,
 String path)

Returns (or creates) the named JESpace stored at the given path.

Parameters:

name - space name

path - filesystem path for BDB JE environment

Returns:

the JESpace instance

getSpace

public static JESpace getSpace(String name)

Returns (or creates) the named JESpace using the name as the storage path.

Parameters:

name - space name and storage path

Returns:

the JESpace instance

addListener

public void addListener(Object key,
 SpaceListener listener)

Description copied from interface: LocalSpace

add a SpaceListener associated with a given key

Specified by:

addListener in interface LocalSpace<K,V>

Parameters:

key - Entry's key

listener - a SpaceListener

addListener

public void addListener(Object key,
 SpaceListener listener,
 long timeout)

Description copied from interface: LocalSpace

add a SpaceListener associated with a given key for a given period of time. Warning: not supported by all space implementations.

Specified by:

addListener in interface LocalSpace<K,V>

Parameters:

key - Entry's key

listener - a SpaceListener

timeout - listener registration timeout in millis

removeListener

public void removeListener(Object key,
 SpaceListener listener)

Description copied from interface: LocalSpace

removes a SpaceListener associated with a given key

Specified by:

removeListener in interface LocalSpace<K,V>

Parameters:

key - Entry's key

listener - the SpaceListener

getKeySet

public Set getKeySet()

Description copied from interface: LocalSpace

Returns the set of all keys currently present in the space.

Specified by:

getKeySet in interface LocalSpace<K,V>

Returns:

Set containing all keys in Space

size

public int size(Object key)

Description copied from interface: LocalSpace

Returns the number of entries queued under the given key.

Specified by:

size in interface LocalSpace<K,V>

Parameters:

key - the key to query

Returns:

number of entries in a given key

dump

public void dump(PrintStream p,
 String indent)

Description copied from interface: Loggeable

Dumps a human-readable representation of this object to the print stream.

Specified by:

dump in interface Loggeable

Parameters:

p - the output stream

indent - indentation prefix