org.xmlBlaster.engine.msgstore
Interface I_Map

All Superinterfaces:

I_Storage, I_StorageProblemNotifier

All Known Implementing Classes:

JdbcQueue, JdbcQueueCommonTablePlugin, MapPlugin, PersistenceCachePlugin

public interface I_Map
extends I_Storage, I_StorageProblemNotifier

The Interface which our persistent map and cache map must implement.

All methods are reentrant and thread safe

Author:

xmlBlaster@marcelruff.info

Method Summary

I_MapEntry	change(I_MapEntry entry, I_ChangeCallback callback)
I_MapEntry	change(long uniqueId, I_ChangeCallback callback) This method is threadsafe because it makes a lookup for the updated entry within the synchronization point.
long	clear() Delete all entries
void	destroy() destroys all the resources associated to this queue.
long	embeddedObjectsToXml(java.io.OutputStream out, java.util.Properties props) Dump all entries of this map to the given output stream.
I_MapEntry	get(long uniqueId) Lookup entry without removing.
I_MapEntry[]	getAll(I_EntryFilter entryFilter) Retrieve all entries in the storage, please take care on memory consumption.
long	getMaxNumOfBytes() returns the capacity (maximum bytes) for this queue
long	getNumOfPersistentBytes() Returns the amount of bytes used by the persistent entries in the queue If the implementation of this interface is not able to return the correct number of entries (for example if the implementation must make a remote call to a DB which is temporarly not available) it will return -1.
long	getNumOfPersistentEntries() Returns the number of elements having the persistent flag set in this queue.
java.lang.Object	getProperties() Access the current queue configuration
void	initialize(StorageId uniqueMapId, java.lang.Object userData) Is called after the instance is created.
int	put(I_MapEntry mapEntry) Adds one entry and automatically increments the reference counter.
int	remove(I_MapEntry mapEntry)
int	remove(long uniqueId)
I_MapEntry	removeOldest() Remove the oldest entry.
void	setProperties(java.lang.Object userData) Allows to overwrite properties which where passed on initialize() The properties which support hot configuration are depending on the used implementation
void	shutdown() Shutdown the implementation, sync with data store, free resources
java.lang.String	toXml(java.lang.String extraOffset)
void	updateCounters(I_MapEntry entry)
java.lang.String	usage()

Methods inherited from interface org.xmlBlaster.util.queue.I_Storage

addStorageSizeListener, getMaxNumOfEntries, getNumOfBytes, getNumOfEntries, getStorageId, getStorageSizeListeners, hasStorageSizeListener, isShutdown, isTransient, removeStorageSizeListener

Methods inherited from interface org.xmlBlaster.util.queue.I_StorageProblemNotifier

registerStorageProblemListener, unRegisterStorageProblemListener

Method Detail

initialize

void initialize(StorageId uniqueMapId,
                java.lang.Object userData)
                throws XmlBlasterException

Is called after the instance is created.

Parameters:

uniqueMapId - A unique name, allowing to create a unique name for a persistent store (e.g. file name) "history:/node/heron/topic/"

userData - For example a Properties object or a String[] args object passing the configuration data

Throws:

XmlBlasterException

setProperties

void setProperties(java.lang.Object userData)
                   throws XmlBlasterException

Allows to overwrite properties which where passed on initialize() The properties which support hot configuration are depending on the used implementation

Throws:

XmlBlasterException

getProperties

java.lang.Object getProperties()

Access the current queue configuration

get

I_MapEntry get(long uniqueId)
               throws XmlBlasterException

Lookup entry without removing.

Returns:

null if not found

Throws:

XmlBlasterException

getAll

I_MapEntry[] getAll(I_EntryFilter entryFilter)
                    throws XmlBlasterException

Retrieve all entries in the storage, please take care on memory consumption.

Parameters:

entryFilter - null to get everything. If specified you can filter by this callback the wanted entries.

Returns:

A current snapshot of all entries

Throws:

XmlBlasterException

put

int put(I_MapEntry mapEntry)
        throws XmlBlasterException

Adds one entry and automatically increments the reference counter. Note: If an entry existed already (0 is returned), it is NOT updated in storage

Parameters:

msgMapEntry - the entry

Returns:

Number of new entries added: 0 if entry existed, 1 if new entry added

Throws:

XmlBlasterException - in case an error occurs. Possible causes of error can be a communication exception of the underlying implementation (jdbc, file system etc).

remove

int remove(I_MapEntry mapEntry)
           throws XmlBlasterException

Returns:

the number of elements erased.

Throws:

XmlBlasterException

remove

int remove(long uniqueId)
           throws XmlBlasterException

Returns:

the number of elements erased.

Throws:

XmlBlasterException

removeOldest

I_MapEntry removeOldest()
                        throws XmlBlasterException

Remove the oldest entry. 'Oldest' is defined in the context of the implementation to support an efficient cache, typically it is the LRU (last recent used) entry.

Returns:

the removed entry

Throws:

XmlBlasterException

clear

long clear()
           throws XmlBlasterException

Delete all entries

Returns:

Number of entries removed

Throws:

XmlBlasterException

getNumOfPersistentEntries

long getNumOfPersistentEntries()

Returns the number of elements having the persistent flag set in this queue. If the implementation of this interface is not able to return the correct number of entries (for example if the implementation must make a remote call to a DB which is temporarly not available) it will return -1.

Returns:

int the number of elements currently in the queue

getNumOfPersistentBytes

long getNumOfPersistentBytes()

Returns the amount of bytes used by the persistent entries in the queue If the implementation of this interface is not able to return the correct number of entries (for example if the implementation must make a remote call to a DB which is temporarly not available) it will return -1.

Returns:

int the number of elements currently in the queue

getMaxNumOfBytes

long getMaxNumOfBytes()

returns the capacity (maximum bytes) for this queue

Returns:

int the maximum number of elements in the queue

shutdown

void shutdown()

Shutdown the implementation, sync with data store, free resources

destroy

void destroy()
             throws XmlBlasterException

destroys all the resources associated to this queue. This means that all temporary and persistent resources are removed.

Throws:

XmlBlasterException

usage

java.lang.String usage()

Returns:

a human readable usage help string

toXml

java.lang.String toXml(java.lang.String extraOffset)

Parameters:

extraOffset - Indent the dump with given ASCII blanks

Returns:

An xml encoded dump

embeddedObjectsToXml

long embeddedObjectsToXml(java.io.OutputStream out,
                          java.util.Properties props)
                          throws java.lang.Exception

Dump all entries of this map to the given output stream. The messages are XML formatted.

Parameters:

out - The output stream to dump the entries

props - Configuration properties, not yet specified, just pass null

Returns:

Number of entries dumped

Throws:

java.lang.Exception

change

I_MapEntry change(I_MapEntry entry,
                  I_ChangeCallback callback)
                  throws XmlBlasterException

Parameters:

entry - the entry to change. This is the old entry, i.e. the entry on which the modification has to take place by callback. Or it is the new entry and you can pass null for callback. IMPORTANT: This method is not threadsafe since it does not make a lookup to get the actual entry. The specified entry could be a dirty read, in which case the current entry would be overwritten with this dirty value. If you want to work threadsafe you should invoke change(long, callback). That method makes a lookup within the same synchronization point.

callback - the object on which the callback method 'changeEntry' is invoked. The modification of the object is done in that method. If you pass null, then the changeEntry is not invoked and the processing continues with entry.

Returns:

I_MapEntry the modified entry.

Throws:

XmlBlasterException - if something goes wrong when making the change (for example if the entry is not in the map) or if the callback throws an exception.

change

I_MapEntry change(long uniqueId,
                  I_ChangeCallback callback)
                  throws XmlBlasterException

This method is threadsafe because it makes a lookup for the updated entry within the synchronization point.

Parameters:

uniqueId - the uniqueId of the entry to change. This is the old entry, i.e. the entry on which the modification has to take place.

callback - the object on which the callback method 'changeEntry' is invoked. The modification of the object is done in that method. If you pass null, then the changeEntry is not invoked and the processing continues with entry.

Returns:

I_Entry the modified entry.

Throws:

XmlBlasterException - if something goes wrong when making the change (for example if the entry is not in the map) or if the callback throws an exception.

updateCounters

void updateCounters(I_MapEntry entry)
                    throws XmlBlasterException

Parameters:

entry - the entry to change. This is the old entry, i.e. the entry on which the modification has to take place by callback. Or it is the new entry and you can pass null for callback. IMPORTANT: This method is not threadsafe since it does not make a lookup to get the actual entry. The specified entry could be a dirty read, in which case the current entry would be overwritten with this dirty value. If you want to work threadsafe you should invoke change(long, callback). That method makes a lookup within the same synchronization point.

Throws:

XmlBlasterException - if something goes wrong when making the change (for example if the entry is not in the map) or if the callback throws an exception.