com.helger.photon.basic.app.dao.impl

Class AbstractWALDAO<DATATYPE extends Serializable>

java.lang.Object

com.helger.photon.basic.app.dao.impl.AbstractDAO

com.helger.photon.basic.app.dao.impl.AbstractWALDAO<DATATYPE>

Type Parameters:

DATATYPE - The data type to be serialized

All Implemented Interfaces:

IAutoSaveAware, IChangeable, IDAO

Direct Known Subclasses:

AbstractMapBasedWALDAO, FavoriteManager, SimpleAuditManager

@ThreadSafe
public abstract class AbstractWALDAO<DATATYPE extends Serializable>
extends AbstractDAO

Base class for a simple DAO using write ahead logging (WAL).

Author:

Philip Helger

Nested Class Summary

Nested classes/interfaces inherited from interface com.helger.photon.basic.app.dao.IDAO

IDAO.EMode

Field Summary

Fields

Modifier and Type	Field and Description
static com.helger.commons.lang.TimeValue	DEFAULT_WAITING_TIME

Fields inherited from class com.helger.photon.basic.app.dao.impl.AbstractDAO

DEFAULT_AUTO_SAVE_ENABLED, m_aRWLock

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractWALDAO(Class<DATATYPE> aDataTypeClass, IDAOIO aDAOIO, IHasFilename aFilenameProvider)
protected	AbstractWALDAO(Class<DATATYPE> aDataTypeClass, IDAOIO aDAOIO, String sFilename)
protected	AbstractWALDAO(Class<DATATYPE> aDataTypeClass, IHasFilename aFilenameProvider)
protected	AbstractWALDAO(Class<DATATYPE> aDataTypeClass, String sFilename)

Method Summary

Modifier and Type	Method and Description
protected void	beforeWriteToFile(String sFilename, File aFile) Optional callback method that is invoked before the file handle gets opened.
protected DATATYPE	convertToNative(String sElement) This method is used upon recovery to convert a stored object to its native representation.
protected String	convertToString(DATATYPE aModifiedElement)
protected abstract com.helger.xml.microdom.IMicroDocument	createWriteData() Create the XML document that should be saved to the file.
IDAOIO	getDAOIO()
protected Class<DATATYPE>	getDataTypeClass()
IHasFilename	getFilenameProvider()
int	getInitCount()
String	getLastFilename()
LocalDateTime	getLastInitDateTime()
LocalDateTime	getLastReadDateTime()
LocalDateTime	getLastWriteDateTime()
int	getReadCount()
protected File	getSafeFile(String sFilename, IDAO.EMode eMode)
com.helger.commons.lang.TimeValue	getWaitingTime()
int	getWriteCount()
protected com.helger.xml.serialize.write.IXMLWriterSettings	getXMLWriterSettings()
protected void	initialRead() Call this method inside the constructor to read the file contents directly.
protected void	markAsChanged(DATATYPE aModifiedElement, EDAOActionType eActionType) This method must be called every time something changed in the DAO.
protected void	markAsChanged(List<DATATYPE> aModifiedElements, EDAOActionType eActionType)
protected void	modifyWriteData(com.helger.xml.microdom.IMicroDocument aDoc) Modify the created document by e.g. adding some comment or digital signature or whatsoever.
protected void	onFilenameChange(String sPreviousFilename, String sNewFilename) Called after a successful write of the file, if the filename is different from the previous filename.
protected com.helger.commons.state.EChange	onInit() Custom initialization routine.
protected abstract com.helger.commons.state.EChange	onRead(com.helger.xml.microdom.IMicroDocument aDoc) Fill the internal structures with from the passed XML document.
protected abstract void	onRecoveryCreate(DATATYPE aElement) Called when a recovery is needed to create a new item.
protected abstract void	onRecoveryDelete(DATATYPE aElement) Called when a recovery is needed to delete an existing item.
protected abstract void	onRecoveryUpdate(DATATYPE aElement) Called when a recovery is needed to update an existing item.
protected void	setWaitingTime(com.helger.commons.lang.TimeValue aWaitingTime) Set the waiting time used before the file is effectively written.
String	toString()
protected static void	triggerExceptionHandlersRead(Throwable t, boolean bIsInitialization, File aFile) Trigger the registered custom exception handlers for read errors.
protected static void	triggerExceptionHandlersWrite(Throwable t, String sErrorFilename, com.helger.xml.microdom.IMicroDocument aDoc) Trigger the registered custom exception handlers for read errors.
void	writeToFileOnPendingChanges() In case there are pending changes write them to the file.

Methods inherited from class com.helger.photon.basic.app.dao.impl.AbstractDAO

beginWithoutAutoSave, endWithoutAutoSave, getExceptionHandlersRead, getExceptionHandlersWrite, hasPendingChanges, internalHasPendingChanges, internalIsAutoSaveEnabled, internalSetPendingChanges, isAutoSaveEnabled, isDebugLogging, performWithoutAutoSave, performWithoutAutoSave, performWithoutAutoSaveThrowing, performWithoutAutoSaveThrowing

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_WAITING_TIME

public static final com.helger.commons.lang.TimeValue DEFAULT_WAITING_TIME

Constructor Detail

AbstractWALDAO

protected AbstractWALDAO(@Nonnull
                         Class<DATATYPE> aDataTypeClass,
                         @Nullable
                         String sFilename)

AbstractWALDAO

protected AbstractWALDAO(@Nonnull
                         Class<DATATYPE> aDataTypeClass,
                         @Nonnull
                         IHasFilename aFilenameProvider)

AbstractWALDAO

protected AbstractWALDAO(@Nonnull
                         Class<DATATYPE> aDataTypeClass,
                         @Nonnull
                         IDAOIO aDAOIO,
                         @Nullable
                         String sFilename)

AbstractWALDAO

protected AbstractWALDAO(@Nonnull
                         Class<DATATYPE> aDataTypeClass,
                         @Nonnull
                         IDAOIO aDAOIO,
                         @Nonnull
                         IHasFilename aFilenameProvider)

Method Detail

getDAOIO

@Nonnull
public final IDAOIO getDAOIO()

Returns:

The DAO IO object used by this instance.

getFilenameProvider

@Nonnull
public final IHasFilename getFilenameProvider()

Returns:

The filename provider used internally to build filenames. Never null.

onInit

@Nonnull
 @OverrideOnDemand
protected com.helger.commons.state.EChange onInit()

Custom initialization routine. Called only if the underlying file does not exist yet. This method is only called within a write lock!

Returns:

EChange.CHANGED if something was modified inside this method

onRead

@Nonnull
 @MustBeLocked(value=WRITE)
protected abstract com.helger.commons.state.EChange onRead(@Nonnull
                                                                                                  com.helger.xml.microdom.IMicroDocument aDoc)

Fill the internal structures with from the passed XML document. This method is only called within a write lock!

Parameters:

aDoc - The XML document to read from. Never null.

Returns:

EChange.CHANGED if reading the data changed something in the internal structures that requires a writing.

getSafeFile

@Nonnull
protected final File getSafeFile(@Nonnull
                                           String sFilename,
                                           @Nonnull
                                           IDAO.EMode eMode)
                                    throws DAOException

Throws:

DAOException

triggerExceptionHandlersRead

protected static void triggerExceptionHandlersRead(@Nonnull
                                                   Throwable t,
                                                   boolean bIsInitialization,
                                                   @Nullable
                                                   File aFile)

Trigger the registered custom exception handlers for read errors.

Parameters:

t - Thrown exception. Never null.

bIsInitialization - true if this happened during initialization of a new file, false if it happened during regular reading.

aFile - The file that was read. May be null for in-memory DAOs.

getDataTypeClass

@Nonnull
protected final Class<DATATYPE> getDataTypeClass()

Returns:

The implementation class as specified in the constructor. Never null.

convertToNative

@Nullable
 @OverrideOnDemand
 @IsLocked(value=WRITE)
protected DATATYPE convertToNative(@Nonnull
                                                                                           String sElement)

This method is used upon recovery to convert a stored object to its native representation. If you overwrite this method, you should consider overriding convertToString(Serializable) as well.

Parameters:

sElement - The string representation to be converted. Never null.

Returns:

The native representation of the object. If the return value is null, the recovery will fail with an exception!

onRecoveryCreate

@IsLocked(value=WRITE)
protected abstract void onRecoveryCreate(@Nonnull
                                                                 DATATYPE aElement)

Called when a recovery is needed to create a new item.

Parameters:

aElement - The element to be created. Never null.

onRecoveryUpdate

@IsLocked(value=WRITE)
protected abstract void onRecoveryUpdate(@Nonnull
                                                                 DATATYPE aElement)

Called when a recovery is needed to update an existing item.

Parameters:

aElement - The element to be updated. Never null.

onRecoveryDelete

@IsLocked(value=WRITE)
protected abstract void onRecoveryDelete(@Nonnull
                                                                 DATATYPE aElement)

Called when a recovery is needed to delete an existing item.

Parameters:

aElement - The element to be deleted. Never null.

initialRead

protected final void initialRead()
                          throws DAOException

Call this method inside the constructor to read the file contents directly. This method is write locked!

Throws:

DAOException - in case initialization or reading failed!

onFilenameChange

@OverrideOnDemand
 @MustBeLocked(value=WRITE)
protected void onFilenameChange(@Nullable
                                                                                String sPreviousFilename,
                                                                                @Nonnull
                                                                                String sNewFilename)

Called after a successful write of the file, if the filename is different from the previous filename. This can e.g. be used to clear old data.

Parameters:

sPreviousFilename - The previous filename. May be null.

sNewFilename - The new filename. Never null.

createWriteData

@Nonnull
 @MustBeLocked(value=WRITE)
protected abstract com.helger.xml.microdom.IMicroDocument createWriteData()

Create the XML document that should be saved to the file. This method is only called within a write lock!

Returns:

The non-null document to write to the file.

modifyWriteData

@OverrideOnDemand
 @MustBeLocked(value=WRITE)
protected void modifyWriteData(@Nonnull
                                                                               com.helger.xml.microdom.IMicroDocument aDoc)

Modify the created document by e.g. adding some comment or digital signature or whatsoever.

Parameters:

aDoc - The created non-null document.

beforeWriteToFile

@OverrideOnDemand
 @MustBeLocked(value=WRITE)
protected void beforeWriteToFile(@Nonnull
                                                                                 String sFilename,
                                                                                 @Nonnull
                                                                                 File aFile)

Optional callback method that is invoked before the file handle gets opened. This method can e.g. be used to create backups.

Parameters:

sFilename - The filename provided by the internal filename provider. Never null.

aFile - The resolved file. It is already consistency checked. Never null.

getXMLWriterSettings

@Nonnull
 @OverrideOnDemand
protected com.helger.xml.serialize.write.IXMLWriterSettings getXMLWriterSettings()

Returns:

The IXMLWriterSettings to be used to serialize the data.

getLastFilename

@Nullable
public final String getLastFilename()

Returns:

The filename to which was written last. May be null if no wrote action was performed yet.

triggerExceptionHandlersWrite

protected static void triggerExceptionHandlersWrite(@Nonnull
                                                    Throwable t,
                                                    @Nonnull
                                                    String sErrorFilename,
                                                    @Nullable
                                                    com.helger.xml.microdom.IMicroDocument aDoc)

Trigger the registered custom exception handlers for read errors.

Parameters:

t - Thrown exception. Never null.

sErrorFilename - The filename tried to write to. Never null.

aDoc - The XML content that should be written. May be null if the error occurred in XML creation.

convertToString

@Nonnull
 @OverrideOnDemand
protected String convertToString(@Nonnull
                                                               DATATYPE aModifiedElement)

getWaitingTime

@Nonnull
public com.helger.commons.lang.TimeValue getWaitingTime()

Returns:

The waiting time used before the file is effectively written. Never null. Default value is 10 seconds.

setWaitingTime

protected void setWaitingTime(@Nonnull
                              com.helger.commons.lang.TimeValue aWaitingTime)

Set the waiting time used before the file is effectively written. Default value is 10 seconds. Setting the value to a duration of 0 means that the write ahead is effectively disabled.

Parameters:

aWaitingTime - The waiting time to be used. May not be null.

markAsChanged

@MustBeLocked(value=WRITE)
 @OverridingMethodsMustInvokeSuper
protected void markAsChanged(@Nonnull
                                                                                             DATATYPE aModifiedElement,
                                                                                             @Nonnull
                                                                                             EDAOActionType eActionType)

This method must be called every time something changed in the DAO. It triggers the writing to a file if auto-save is active. This method must be called within a write-lock as it is not locked!

Parameters:

aModifiedElement - The modified data element. May not be null.

eActionType - The action that was performed. May not be null.

markAsChanged

@MustBeLocked(value=WRITE)
protected final void markAsChanged(@Nonnull
                                                               List<DATATYPE> aModifiedElements,
                                                               @Nonnull
                                                               EDAOActionType eActionType)

writeToFileOnPendingChanges

public final void writeToFileOnPendingChanges()

In case there are pending changes write them to the file. This method is write locked!

getInitCount

@Nonnegative
public int getInitCount()

Returns:

The number of times this DAO was initialized. Always ≥ 0. Usually this field is not persistent and only is valid until the application ends.

getLastInitDateTime

@Nullable
public final LocalDateTime getLastInitDateTime()

Returns:

The last time this DAO was initialized (without error). May be null if it wasn't read before. Usually this field is not persistent and only is valid until the application ends.

getReadCount

@Nonnegative
public int getReadCount()

Returns:

The number of times this DAO was initialized. Always ≥ 0. Usually this field is not persistent and only is valid until the application ends.

getLastReadDateTime

@Nullable
public final LocalDateTime getLastReadDateTime()

Returns:

The last time this DAO was read (without error). May be null if it wasn't read before. Usually this field is not persistent and only is valid until the application ends.

getWriteCount

@Nonnegative
public int getWriteCount()

Returns:

The number of times this DAO was initialized. Always ≥ 0. Usually this field is not persistent and only is valid until the application ends.

getLastWriteDateTime

@Nullable
public final LocalDateTime getLastWriteDateTime()

Returns:

The last time this DAO was written (without error). May be null if it wasn't written before. Usually this field is not persistent and only is valid until the application ends.

toString

public String toString()

Overrides:

toString in class AbstractDAO