org.xmlBlaster.engine.msgstore.cache
Class PersistenceCachePlugin

java.lang.Object
  org.xmlBlaster.engine.msgstore.cache.PersistenceCachePlugin

All Implemented Interfaces:

PersistenceCachePluginMBean, I_Map, I_AdminMap, I_AdminPlugin, I_AdminUsage, I_Plugin, I_Storage, I_StoragePlugin, I_StorageProblemListener, I_StorageProblemNotifier

public class PersistenceCachePlugin
extends java.lang.Object
implements I_StoragePlugin, I_StorageProblemListener, I_Map, PersistenceCachePluginMBean

Implements a random access message storage.

The implementation uses internally a RAM and a JDBC map and handles the caching between those two.

Author:

michele@laghi.eu, Marcel Ruff

See Also:

The engine.persistence requirement, I_MapTest

Field Summary

private ContextNode	contextNode
private ServerScope	glob
private boolean	isConnected
(package private) boolean	isDown
private static java.util.logging.Logger	log
private java.lang.Object	mbeanHandle My JMX registration
private java.lang.String	ME
private I_Map	persistentStore
private PluginInfo	pluginInfo
private QueuePropertyBase	property
private StorageId	storageId
private StorageSizeListenerHelper	storageSizeListenerHelper
private I_Map	transientStore

Fields inherited from interface org.xmlBlaster.util.queue.I_StorageProblemListener

AVAILABLE, UNAVAILABLE, UNDEF

Constructor Summary

PersistenceCachePlugin()

Method Summary

void	addStorageSizeListener(I_StorageSizeListener listener) Adds a storage size listener to the storage.
private void	assureTransientSpace(I_MapEntry mapEntry) Swap an entry away to hard disk.
I_MapEntry	change(I_MapEntry oldEntry, 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.
java.lang.String	checkConsistency(java.lang.String fixIt, java.lang.String reportFileName) Check if all messages in the storage are referenced by queue entries (history and callback queue).
long	clear() Clears everything and removes the queue (i.e.
private QueuePropertyBase	createRamCopy(QueuePropertyBase queuePropertyBase) We set the cache props to the real props for RAM queue running under a cacheQueue
void	destroy() destroys all the resources associated to this queue.
java.lang.String	dumpEmbeddedObjectsToFile(java.lang.String fileName) Dump all entries of this map to a file.
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) Access all entries.
PluginInfo	getInfo() Enforced by I_StoragePlugin
long	getMaxNumOfBytes() returns the capacity (maximum bytes) for this queue
long	getMaxNumOfBytesCache() returns the cache capacity (maximum bytes) for this storage
long	getMaxNumOfEntries() returns the maximum number of elements for this store
long	getMaxNumOfEntriesCache() returns the maximum number of cached elements for this store
long	getNumOfBytes() Returns the amount of bytes currently in the storage 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	getNumOfCachedBytes() Returns the amount of bytes currently in the RAM part of the storage
long	getNumOfCachedEntries() Returns the number of elements in the RAM part of this storage.
long	getNumOfEntries() It returns the size of the 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() It returns the size of persistent entries in the queue.
java.lang.Object	getProperties() Access the current queue configuration
java.lang.String	getPropertyStr() Access the current queue configuration.
java.lang.String	getQueueName() Returns the unique ID of this queue as found in the database XB_ENTRIES.queueName column.
StorageId	getStorageId() Returns the unique ID of this queue
I_StorageSizeListener[]	getStorageSizeListeners()
java.lang.String	getType() Enforced by I_Plugin
java.lang.String	getUsageUrl()
java.lang.String	getVersion() Enforced by I_Plugin
boolean	hasStorageSizeListener(I_StorageSizeListener listener) Checks wether the specified listener is registered.
void	init(Global glob, PluginInfo pluginInfo) Enforced by I_Plugin
void	initialize(StorageId uniqueQueueId, java.lang.Object userData) Is called after the instance is created.
boolean	isShutdown() Is the storage available?
boolean	isTransient()
private long	numSwapped()
int	put(I_MapEntry mapEntry) All entries are stored into the transient queue.
boolean	registerStorageProblemListener(I_StorageProblemListener listener) registers a new listener to be notified.
int	remove(I_MapEntry mapEntry)
int	remove(long uniqueId)
int	removeById(long uniqueId) Remove the specified storage entry.
private int	removeNoNotify(I_MapEntry mapEntry)
I_MapEntry	removeOldest() Remove the oldest entry.
java.lang.String	removeOldestEntry() Remove the oldest storage entry from cache.
void	removeStorageSizeListener(I_StorageSizeListener listener) Removes the specified listener from the queue.
int	removeTransient()
int	removeTransientEntries() Removes all the transient entries (the ones which have the flag 'persistent' set to false.
private java.lang.String	setMaxNum(boolean setBytes, boolean setCache, long max)
java.lang.String	setMaxNumOfBytes(long max) Increase the max number of bytes persistently.
java.lang.String	setMaxNumOfBytesCache(long max) Increase the max number of bytes of the cached part persistently.
java.lang.String	setMaxNumOfEntries(long max) Increase the max number of entries persistently.
java.lang.String	setMaxNumOfEntriesCache(long max) Increase the max number of entries of the cached part persistently.
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	setUsageUrl(java.lang.String url)
void	shutdown() Shutdown the implementation, sync with data store
private boolean	spaceLeft(I_MapEntry mapEntry, I_Map map) Check is storage is big enough for entry
private XmlBlasterException	spaceLeftException(I_MapEntry mapEntry, I_Map map) Check is storage is big enough for entry
void	storageAvailable(int oldStatus) Triggered by persistent store (JDBC) on reconnection
void	storageUnavailable(int oldStatus) Triggered by persistent store (JDBC) on lost connection
java.lang.String	toXml(java.lang.String extraOffset)
boolean	unRegisterStorageProblemListener(I_StorageProblemListener listener) unregisters a listener.
void	updateCounters(I_MapEntry entry)
java.lang.String	usage() JMX help

Methods inherited from class java.lang.Object

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

Field Detail

ME

private java.lang.String ME

contextNode

private ContextNode contextNode

glob

private ServerScope glob

log

private static java.util.logging.Logger log

property

private QueuePropertyBase property

isDown

boolean isDown

storageId

private StorageId storageId

transientStore

private I_Map transientStore

persistentStore

private I_Map persistentStore

isConnected

private boolean isConnected

pluginInfo

private PluginInfo pluginInfo

mbeanHandle

private java.lang.Object mbeanHandle

My JMX registration

storageSizeListenerHelper

private StorageSizeListenerHelper storageSizeListenerHelper

Constructor Detail

PersistenceCachePlugin

public PersistenceCachePlugin()

Method Detail

storageUnavailable

public void storageUnavailable(int oldStatus)

Triggered by persistent store (JDBC) on lost connection

Specified by:

storageUnavailable in interface I_StorageProblemListener

Parameters:

oldStatus - the status before the storage became unavailable.

See Also:

I_ConnectionListener.disconnected()

isTransient

public boolean isTransient()

Specified by:

isTransient in interface I_Storage

Returns:

true for RAM based queue, false for other types like CACHE and JDBC queues

storageAvailable

public void storageAvailable(int oldStatus)

Triggered by persistent store (JDBC) on reconnection

Specified by:

storageAvailable in interface I_StorageProblemListener

See Also:

I_StorageProblemListener.storageAvailable(int)

initialize

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

Is called after the instance is created.

Specified by:

initialize in interface I_Map

Parameters:

uniqueQueueId - A unique name, allowing to create a unique name for a persistent store (e.g. file name)

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

Throws:

XmlBlasterException

See Also:

I_Map.initialize(StorageId, Object)

getQueueName

public java.lang.String getQueueName()

Description copied from interface: I_AdminMap

Returns the unique ID of this queue as found in the database XB_ENTRIES.queueName column.

Specified by:

getQueueName in interface I_AdminMap

Returns:

For example "topicStore_heron"

removeById

public int removeById(long uniqueId)
               throws java.lang.Exception

Description copied from interface: I_AdminMap

Remove the specified storage entry.

Specified by:

removeById in interface I_AdminMap

Parameters:

uniqueId - The entry identifier

Returns:

the number of elements erased.

Throws:

java.lang.Exception

removeOldestEntry

public java.lang.String removeOldestEntry()
                                   throws java.lang.Exception

Description copied from interface: I_AdminMap

Remove the oldest storage entry from cache.

Specified by:

removeOldestEntry in interface I_AdminMap

Returns:

The entry removed

Throws:

java.lang.Exception

removeTransientEntries

public int removeTransientEntries()
                           throws java.lang.Exception

Description copied from interface: I_AdminMap

Removes all the transient entries (the ones which have the flag 'persistent' set to false.

Specified by:

removeTransientEntries in interface I_AdminMap

Returns:

Number of entries erased

Throws:

java.lang.Exception

createRamCopy

private QueuePropertyBase createRamCopy(QueuePropertyBase queuePropertyBase)

We set the cache props to the real props for RAM queue running under a cacheQueue

setProperties

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

Description copied from interface: I_Map

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

Specified by:

setProperties in interface I_Map

Throws:

XmlBlasterException

See Also:

I_Map.setProperties(Object)

getProperties

public java.lang.Object getProperties()

Access the current queue configuration

Specified by:

getProperties in interface I_Map

getPropertyStr

public java.lang.String getPropertyStr()

Description copied from interface: I_AdminMap

Access the current queue configuration.

Specified by:

getPropertyStr in interface I_AdminMap

put

public int put(I_MapEntry mapEntry)
        throws XmlBlasterException

All entries are stored into the transient queue. All persistent entries are stored also in the persistent queue. The exceeding size in the transient queue is calculated. If it is positive it means we need to swap. The overflowing entries are taken from the ram queue. The volatile between them are stored in the persistent storage (since the persistent ones have been previously stored).

Specified by:

put in interface I_Map

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).

See Also:

I_Map.put(I_MapEntry)

assureTransientSpace

private void assureTransientSpace(I_MapEntry mapEntry)
                           throws XmlBlasterException

Swap an entry away to hard disk. Call this method from synchronized code only.

Parameters:

mapEntry - The new entry which needs space for itself.

Throws:

XmlBlasterException

spaceLeftException

private XmlBlasterException spaceLeftException(I_MapEntry mapEntry,
                                               I_Map map)

Check is storage is big enough for entry

Parameters:

mapEntry - may not be null

Returns:

null There is space (otherwise the error text is returned)

spaceLeft

private boolean spaceLeft(I_MapEntry mapEntry,
                          I_Map map)

Check is storage is big enough for entry

Parameters:

mapEntry - may not be null

Returns:

true Space enough

getStorageId

public StorageId getStorageId()

Returns the unique ID of this queue

Specified by:

getStorageId in interface I_Storage

Returns:

For example "history_heronhello"

get

public I_MapEntry get(long uniqueId)
               throws XmlBlasterException

Description copied from interface: I_Map

Lookup entry without removing.

Specified by:

get in interface I_Map

Returns:

null if not found

Throws:

XmlBlasterException

See Also:

I_Map.get(long)

getAll

public I_MapEntry[] getAll(I_EntryFilter entryFilter)
                    throws XmlBlasterException

Access all entries.

TODO !!!: This method should be changed to an iterator approach as if we have swapped messages they won't fit to memory.

Specified by:

getAll in interface I_Map

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

See Also:

I_Map#getAll()

removeNoNotify

private int removeNoNotify(I_MapEntry mapEntry)
                    throws XmlBlasterException

Throws:

XmlBlasterException

See Also:

I_Map.remove(I_MapEntry)

remove

public int remove(I_MapEntry mapEntry)
           throws XmlBlasterException

Specified by:

remove in interface I_Map

Returns:

the number of elements erased.

Throws:

XmlBlasterException

See Also:

I_Map.remove(I_MapEntry)

remove

public int remove(long uniqueId)
           throws XmlBlasterException

Specified by:

remove in interface I_Map

Returns:

the number of elements erased.

Throws:

XmlBlasterException

See Also:

I_Map.remove(long)

removeOldest

public I_MapEntry removeOldest()
                        throws XmlBlasterException

Description copied from interface: I_Map

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.

Specified by:

removeOldest in interface I_Map

Returns:

the removed entry

Throws:

XmlBlasterException

See Also:

I_Map.removeOldest()

removeTransient

public int removeTransient()
                    throws XmlBlasterException

Throws:

XmlBlasterException

See Also:

I_Map#removeTransient()

numSwapped

private long numSwapped()

getNumOfEntries

public long getNumOfEntries()

It returns the size of the queue. Note that this call will return the size stored in cache, i.e. it will NOT make a call to the underlying DB.

Specified by:

getNumOfEntries in interface I_AdminMap

Specified by:

getNumOfEntries in interface I_Storage

Returns:

int the number of elements

See Also:

I_Storage.getNumOfEntries()

getNumOfCachedEntries

public long getNumOfCachedEntries()

Description copied from interface: I_AdminMap

Returns the number of elements in the RAM part of this storage. If no cache map is used and there is no RAM storage beneath we return -1

Specified by:

getNumOfCachedEntries in interface I_AdminMap

Returns:

int the number of elements or -1 if not applicable

See Also:

I_AdminMap.getNumOfCachedEntries()

getNumOfPersistentEntries

public long getNumOfPersistentEntries()

It returns the size of persistent entries in the queue. Note that this call will return the size stored in cache, i.e. it will NOT make a call to the underlying DB.

Specified by:

getNumOfPersistentEntries in interface I_Map

Specified by:

getNumOfPersistentEntries in interface I_AdminMap

Returns:

int the number of elements currently in the queue

See Also:

I_Map.getNumOfPersistentEntries()

getMaxNumOfEntries

public long getMaxNumOfEntries()

Description copied from interface: I_AdminMap

returns the maximum number of elements for this store

Specified by:

getMaxNumOfEntries in interface I_AdminMap

Specified by:

getMaxNumOfEntries in interface I_Storage

Returns:

int the maximum number of elements in the storage

See Also:

I_Storage.getMaxNumOfEntries()

getMaxNumOfEntriesCache

public long getMaxNumOfEntriesCache()

Description copied from interface: I_AdminMap

returns the maximum number of cached elements for this store

Specified by:

getMaxNumOfEntriesCache in interface I_AdminMap

Returns:

int the maximum number of elements in the storage

See Also:

I_Map#getMaxNumOfEntriesCache()

getNumOfBytes

public long getNumOfBytes()

Description copied from interface: I_AdminMap

Returns the amount of bytes currently in the storage 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.

Specified by:

getNumOfBytes in interface I_AdminMap

Specified by:

getNumOfBytes in interface I_Storage

Returns:

The number of elements currently in the storage

See Also:

I_Storage.getNumOfBytes()

getNumOfCachedBytes

public long getNumOfCachedBytes()

Description copied from interface: I_AdminMap

Returns the amount of bytes currently in the RAM part of the storage

Specified by:

getNumOfCachedBytes in interface I_AdminMap

Returns:

The number of elements currently in the storage or -1

See Also:

I_AdminMap.getNumOfCachedBytes()

getNumOfPersistentBytes

public long getNumOfPersistentBytes()

Description copied from interface: I_Map

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.

Specified by:

getNumOfPersistentBytes in interface I_Map

Specified by:

getNumOfPersistentBytes in interface I_AdminMap

Returns:

int the number of elements currently in the queue

See Also:

I_Map.getNumOfPersistentBytes()

setMaxNumOfBytes

public java.lang.String setMaxNumOfBytes(long max)

Description copied from interface: I_AdminMap

Increase the max number of bytes persistently.

Specified by:

setMaxNumOfBytes in interface I_AdminMap

Returns:

See Also:

I_AdminMap.setMaxNumOfBytes(long)

setMaxNumOfBytesCache

public java.lang.String setMaxNumOfBytesCache(long max)

Description copied from interface: I_AdminMap

Increase the max number of bytes of the cached part persistently.

Specified by:

setMaxNumOfBytesCache in interface I_AdminMap

Returns:

See Also:

I_AdminMap.setMaxNumOfBytesCache(long)

setMaxNumOfEntries

public java.lang.String setMaxNumOfEntries(long max)

Description copied from interface: I_AdminMap

Increase the max number of entries persistently.

Specified by:

setMaxNumOfEntries in interface I_AdminMap

Returns:

See Also:

I_AdminMap.setMaxNumOfEntries(long)

setMaxNumOfEntriesCache

public java.lang.String setMaxNumOfEntriesCache(long max)

Description copied from interface: I_AdminMap

Increase the max number of entries of the cached part persistently.

Specified by:

setMaxNumOfEntriesCache in interface I_AdminMap

Returns:

See Also:

I_AdminMap.setMaxNumOfEntriesCache(long)

setMaxNum

private java.lang.String setMaxNum(boolean setBytes,
                                   boolean setCache,
                                   long max)

getMaxNumOfBytes

public long getMaxNumOfBytes()

Description copied from interface: I_Map

returns the capacity (maximum bytes) for this queue

Specified by:

getMaxNumOfBytes in interface I_Map

Specified by:

getMaxNumOfBytes in interface I_AdminMap

Returns:

int the maximum number of elements in the queue

See Also:

I_Map.getMaxNumOfBytes()

getMaxNumOfBytesCache

public long getMaxNumOfBytesCache()

Description copied from interface: I_AdminMap

returns the cache capacity (maximum bytes) for this storage

Specified by:

getMaxNumOfBytesCache in interface I_AdminMap

Returns:

int the maximum number of elements in the storage

See Also:

I_Map#getMaxNumOfBytesCache()

clear

public long clear()

Clears everything and removes the queue (i.e. frees the associated table)

Specified by:

clear in interface I_Map

Specified by:

clear in interface I_AdminMap

Returns:

Number of entries removed

shutdown

public void shutdown()

Shutdown the implementation, sync with data store

Specified by:

shutdown in interface I_Map

Specified by:

shutdown in interface I_AdminMap

Specified by:

shutdown in interface I_AdminPlugin

Specified by:

shutdown in interface I_Plugin

isShutdown

public boolean isShutdown()

Description copied from interface: I_AdminMap

Is the storage available?

Specified by:

isShutdown in interface I_AdminMap

Specified by:

isShutdown in interface I_AdminPlugin

Specified by:

isShutdown in interface I_Storage

Returns:

true if shutdown

usage

public java.lang.String usage()

JMX help

Specified by:

usage in interface I_Map

Specified by:

usage in interface I_AdminMap

Specified by:

usage in interface I_AdminUsage

Returns:

a human readable usage help string

getUsageUrl

public java.lang.String getUsageUrl()

Specified by:

getUsageUrl in interface I_AdminUsage

Returns:

A link for JMX usage

setUsageUrl

public void setUsageUrl(java.lang.String url)

Specified by:

setUsageUrl in interface I_AdminUsage

toXml

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

Specified by:

toXml in interface I_Map

Parameters:

extraOffset - Indent the dump with given ASCII blanks

Returns:

Internal state as an XML ASCII string

init

public void init(Global glob,
                 PluginInfo pluginInfo)

Enforced by I_Plugin

Specified by:

init in interface I_Plugin

See Also:

I_Plugin.init(org.xmlBlaster.util.Global, PluginInfo)

getType

public java.lang.String getType()

Enforced by I_Plugin

Specified by:

getType in interface I_AdminPlugin

Specified by:

getType in interface I_Plugin

Returns:

"CACHE"

getVersion

public java.lang.String getVersion()

Enforced by I_Plugin

Specified by:

getVersion in interface I_AdminPlugin

Specified by:

getVersion in interface I_Plugin

Returns:

"1.0"

getInfo

public PluginInfo getInfo()

Enforced by I_StoragePlugin

Specified by:

getInfo in interface I_StoragePlugin

Returns:

the pluginInfo object.

checkConsistency

public java.lang.String checkConsistency(java.lang.String fixIt,
                                         java.lang.String reportFileName)

Description copied from interface: I_AdminMap

Check if all messages in the storage are referenced by queue entries (history and callback queue).
Caution: The check does not check queues from plugins which may reference the messageUnit, please set fixIt=true only if you know what you are doing!

Specified by:

checkConsistency in interface I_AdminMap

Parameters:

fixIt - "true": Unreferenced entries are deleted (ignoring case); else check is readonly,

reportFileName - The file name to dump the details

Returns:

The status report

destroy

public void destroy()
             throws XmlBlasterException

destroys all the resources associated to this queue. Even the persistent data is destroyed.

Specified by:

destroy in interface I_Map

Throws:

XmlBlasterException

registerStorageProblemListener

public boolean registerStorageProblemListener(I_StorageProblemListener listener)

Description copied from interface: I_StorageProblemNotifier

registers a new listener to be notified. If the registration was not done (for example if the implementation only allows one listener and there is already one), then a 'false' is returned, otherwise 'true' is returned.

Specified by:

registerStorageProblemListener in interface I_StorageProblemNotifier

See Also:

I_StorageProblemNotifier.registerStorageProblemListener(I_StorageProblemListener)

unRegisterStorageProblemListener

public boolean unRegisterStorageProblemListener(I_StorageProblemListener listener)

Description copied from interface: I_StorageProblemNotifier

unregisters a listener. If there is no such listener 'false' is returned, otherwise 'true' is returned.

Specified by:

unRegisterStorageProblemListener in interface I_StorageProblemNotifier

See Also:

I_StorageProblemNotifier.unRegisterStorageProblemListener(I_StorageProblemListener)

change

public I_MapEntry change(I_MapEntry oldEntry,
                         I_ChangeCallback callback)
                  throws XmlBlasterException

Specified by:

change in interface I_Map

Parameters:

oldEntry - 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.

See Also:

I_Map.change(I_MapEntry, I_ChangeCallback)

updateCounters

public void updateCounters(I_MapEntry entry)
                    throws XmlBlasterException

Specified by:

updateCounters in interface I_Map

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.

See Also:

I_Map.change(I_MapEntry, I_ChangeCallback)

change

public I_MapEntry change(long uniqueId,
                         I_ChangeCallback callback)
                  throws XmlBlasterException

Description copied from interface: I_Map

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

Specified by:

change in interface I_Map

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.

See Also:

I_Map.change(long, I_ChangeCallback)

embeddedObjectsToXml

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

Description copied from interface: I_Map

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

Specified by:

embeddedObjectsToXml in interface I_Map

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

See Also:

I_Map.embeddedObjectsToXml(OutputStream, Properties)

dumpEmbeddedObjectsToFile

public java.lang.String dumpEmbeddedObjectsToFile(java.lang.String fileName)
                                           throws java.lang.Exception

Description copied from interface: I_AdminMap

Dump all entries of this map to a file. The messages are XML formatted.

Specified by:

dumpEmbeddedObjectsToFile in interface I_AdminMap

Parameters:

fileName - The file name to dump, may contain a path.

Returns:

Status string

Throws:

java.lang.Exception

See Also:

I_AdminMap.dumpEmbeddedObjectsToFile(String)

addStorageSizeListener

public void addStorageSizeListener(I_StorageSizeListener listener)

Description copied from interface: I_Storage

Adds a storage size listener to the storage. Every time the number of storage entries changes we will fire a changed() event.

The changed() invocation is guaranteed to NOT be in any Queue specific synchronize

You can use this for example to add a threshold warning system.

Specified by:

addStorageSizeListener in interface I_Storage

Parameters:

listener - the listener to be added, adding the same listener multiple times will only remember one and fire once

See Also:

I_Storage.addStorageSizeListener(I_StorageSizeListener)

removeStorageSizeListener

public void removeStorageSizeListener(I_StorageSizeListener listener)

Description copied from interface: I_Storage

Removes the specified listener from the queue.

Specified by:

removeStorageSizeListener in interface I_Storage

Parameters:

listener - the listener to be removed. Currently only one. If you pass null, all queueSizeListeners are removed.

See Also:

I_Storage.removeStorageSizeListener(I_StorageSizeListener)

hasStorageSizeListener

public boolean hasStorageSizeListener(I_StorageSizeListener listener)

Description copied from interface: I_Storage

Checks wether the specified listener is registered.

Specified by:

hasStorageSizeListener in interface I_Storage

Parameters:

listener - the listener to check against. If you pass null it checks if at least one listener exists.

Returns:

true if the specified listener exists, false otherwise. If you passed null in the argument list it returns true if a listener exists.

See Also:

I_Storage.hasStorageSizeListener(I_StorageSizeListener)

getStorageSizeListeners

public I_StorageSizeListener[] getStorageSizeListeners()

Specified by:

getStorageSizeListeners in interface I_Storage

Returns:

the array of storage size listeners for this storage. It never returns null.

See Also:

I_Storage.getStorageSizeListeners()