Class MultiReferenceStorage

java.lang.Object

org.apache.james.mime4j.storage.MultiReferenceStorage

All Implemented Interfaces:

Storage

public class MultiReferenceStorage
extends Object
implements Storage

A wrapper around another Storage that also maintains a reference counter. The inner storage gets deleted only if the reference counter reaches zero.

Reference counting is used to delete the storage when it is no longer needed. So, any users of this class should note:

• The reference count is set up one on construction. In all other cases, addReference() should be called when the storage is shared.
• The caller of addReference() should ensure that delete() is called once and only once.
• Sharing the Storage instance passed into MultiReferenceStorage(Storage) may lead to miscounting and premature deletion

Field Summary

Fields

Modifier and Type	Field	Description
private int	referenceCounter
private final Storage	storage

Constructor Summary

Constructors

Constructor	Description
MultiReferenceStorage(Storage storage)	Creates a new MultiReferenceStorage instance for the given back-end.

Method Summary

Modifier and Type	Method	Description
void	addReference()	Increments the reference counter.
private boolean	decrementCounter()	Synchronized decrement of reference count.
void	delete()	Decrements the reference counter and deletes the inner Storage object if the reference counter reaches zero.
InputStream	getInputStream()	Returns the input stream of the inner Storage object.
private void	incrementCounter()	Synchronized increment of reference count.

Methods inherited from class Object

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

Field Details

storage

private final Storage storage

referenceCounter

private int referenceCounter

Constructor Details

MultiReferenceStorage

public MultiReferenceStorage(Storage storage)

Creates a new MultiReferenceStorage instance for the given back-end. The reference counter is initially set to one so the caller does not have to call addReference() after this constructor.

Parameters:

storage - storage back-end that should be reference counted.

Throws:

IllegalArgumentException - when storage is null

Method Details

addReference

public void addReference()

Increments the reference counter.

Throws:

IllegalStateException - if the reference counter is zero which implies that the backing storage has already been deleted.

delete

public void delete()

Decrements the reference counter and deletes the inner Storage object if the reference counter reaches zero.

A client that holds a reference to this object must make sure not to invoke this method a second time.

Specified by:

delete in interface Storage

Throws:

IllegalStateException - if the reference counter is zero which implies that the backing storage has already been deleted.

getInputStream

public InputStream getInputStream()
                           throws IOException

Returns the input stream of the inner Storage object.

Specified by:

getInputStream in interface Storage

Returns:

an input stream.

Throws:

IOException - if an I/O error occurs.

incrementCounter

private void incrementCounter()

Synchronized increment of reference count.

Throws:

IllegalStateException - when counter is already zero

decrementCounter

private boolean decrementCounter()

Synchronized decrement of reference count.

Returns:

true when counter has reached zero, false otherwise

Throws:

IllegalStateException - when counter is already zero