net.sourceforge.domian.repository
Class XStreamXmlFilePerEntityRepository<T extends Entity>

java.lang.Object
  net.sourceforge.domian.repository.AbstractRepository<T>
      net.sourceforge.domian.repository.AbstractDomianCoreRepository<T>
          net.sourceforge.domian.repository.XStreamXmlFilePerEntityRepository<T>

All Implemented Interfaces:

HumanReadableFormatRepository<T>, PersistentRepository<T>, Repository<T>, TextualFormatRepository<T>

public class XStreamXmlFilePerEntityRepository<T extends Entity>
extends AbstractDomianCoreRepository<T>

A persistent repository backed by XStream functionality.

The only persistence definition supported by this repository is PersistenceDefinition.FILE. All repository operations are executed in an exclusive fashion, applying pessimistic locking. Translated into ACID terms, this corresponds to isolation level SERIALIZABLE.

All entities in this repository are persisted into individual XML files. The typical disc footprint is 1KB per entity. The persistence format is human readable XStream XML. The file encoding is UTF-8.

File-based stores counts as persistent storage media, although the nature of the synchronous writings to disc obviously depends on the file system implementations involved.

NB! When used as a partition repository, this repository implementation does not reflect altered state between partitions. When changing state in entities residing in more han one partition, for which at least one of them is a XStreamXmlFilePerEntityRepository, explicit updates for all partitions involved are needed.

Since:

0.4

Author:

Eirik Torske

See Also:

XStream, PersistenceDefinition.FILE

Nested Class Summary

protected static class

AbstractXStreamXmlFilePerEntityRepository.EntityId_NamedXStreamFilePersistenceStrategy Custom FilePersistenceStrategy class.

Field Summary

protected static java.lang.String	DEFAULT_REPOSITORY_ROOT_DIR_NAME
protected static java.lang.String	DEFAULT_REPOSITORY_ROOT_PATH
protected java.lang.String	repositoryId The repository-ID the name of the repository.
protected java.lang.String	repositoryRootPath For file-based repositories the repositoryRootPath is the absolute path for all repositories of the same type.
protected static java.lang.String	XSTREAM_XML_FILE_SUFFIX

Fields inherited from class net.sourceforge.domian.repository.AbstractDomianCoreRepository

DEFAULT_DOMIAN_ROOT_DIR_NAME, DEFAULT_DOMIAN_ROOT_PATH, log, synchronizer

Fields inherited from class net.sourceforge.domian.repository.AbstractRepository

supportsRecursiveIndexing, usesNativePartitioningSupport

Constructor Summary

XStreamXmlFilePerEntityRepository(java.lang.String repositoryId)

XStreamXmlFilePerEntityRepository(java.lang.String repositoryRootPath, java.lang.String repositoryId)

XStreamXmlFilePerEntityRepository(java.lang.String repositoryRootPath, java.lang.String repositoryId, Synchronizer synchronizer)

XStreamXmlFilePerEntityRepository(java.lang.String repositoryId, Synchronizer synchronizer)

Method Summary

protected void	call(java.util.concurrent.Callable<T> callable) Added for completeness.
protected <T> T	callConcurrently(java.util.concurrent.Callable<T> callable) Convenience method for running a Callable in a concurrent manner.
protected <T> T	callConcurrentlyInNewThread(java.util.concurrent.Callable<T> callable)
protected <T> T	callConcurrentlyWithRetry(java.util.concurrent.Callable<T> callable) Convenience method for running a Callable in a concurrent manner.
protected <T> T	callExclusively(java.util.concurrent.Callable<T> callable) Convenience method for running a Callable in an exclusively manner.
protected <T> T	callExclusivelyInNewThread(java.util.concurrent.Callable<T> callable)
protected <T> T	callExclusivelyWithRetry(java.util.concurrent.Callable<T> callable) Convenience method for running a Callable in an exclusively manner.
void	close() Closes the repository and releases all resources.
java.lang.Long	countAllEntities()
protected void	createRepositoryFilesIfNotExist()
<V extends T> java.util.Collection<V>	findAllEntitiesSpecifiedBy(Specification<V> specification) Finds and returns all entities approved by the given specification.
java.lang.String	getEncoding()
protected static java.lang.String	getEntityIdBasedFilenameFrom(Entity entity) A naming scheme for file-per-entity Domian XStream persistence.
java.lang.String	getFormat()
java.lang.Integer	getMaxNumberOfRetries()
EntityMetaData	getMetaDataFor(T entity)
PersistenceDefinition	getPersistenceDefinition()
java.io.File	getRepositoryDirectory() The unique file directory in which the repository data files resides.
java.lang.String	getRepositoryId() The repository-ID the name of the repository.
protected java.lang.String	getRepositoryPath(java.lang.String repositoryRootPath, PersistentRepository<T> repository)
java.lang.String	getRepositoryPathString()
java.lang.String	getRepositoryRootPath()
java.lang.Integer	getRetryTimeoutInMilliseconds()
<V extends T> java.util.Iterator<V>	iterateAllEntitiesSpecifiedBy(Specification<V> specification) Finds and returns all entities approved by the given specification.
void	load() The semantics of this operation depends on the Repository's PersistenceDefinition.
void	persist() The semantics of this operation depends on the Repository's PersistenceDefinition.
<V extends T> void	put(V entity) Puts the given entity into this repository.
<V extends T> java.lang.Boolean	remove(V entity) Removes the given entity from this repository.
<V extends T> java.lang.Long	removeAllEntitiesSpecifiedBy(Specification<V> specification) Removes all entities approved by the given specification.
protected void	run(java.lang.Runnable runnable) Added for completeness.
protected void	runAsynchronously(java.lang.Runnable runnable) Executes the given Runnable in a fresh and independent thread.
protected void	runConcurrently(java.lang.Runnable runnable) Convenience method for running a Runnable in a concurrent manner.
void	setMaxNumberOfRetries(java.lang.Integer maxNumberOfRetries)
void	setRetryTimeoutInMilliseconds(java.lang.Integer retryTimeoutInMilliseconds)
<V extends T> void	update(V entity) Updates an entity.

Methods inherited from class net.sourceforge.domian.repository.AbstractDomianCoreRepository

createUniqueSpecificationFor, getSynchronizer, makePartition, onMakePartition, setSynchronizer

Methods inherited from class net.sourceforge.domian.repository.AbstractRepository

contains, count, countAll, countAllEntitiesSpecifiedBy, find, findAll, findSingle, findSingleEntitySpecifiedBy, isIndexingEntitiesRecursively, isPartitioningNatively, iterate, iterateAll, putAll, remove, removeAll, update

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sourceforge.domian.repository.Repository

count, countAll, countAllEntitiesSpecifiedBy, find, findAll, findSingle, findSingleEntitySpecifiedBy, isIndexingEntitiesRecursively, isPartitioningNatively, iterate, iterateAll, makePartition, putAll, remove, removeAll, update

Field Detail

DEFAULT_REPOSITORY_ROOT_DIR_NAME

protected static final java.lang.String DEFAULT_REPOSITORY_ROOT_DIR_NAME

See Also:

Constant Field Values

DEFAULT_REPOSITORY_ROOT_PATH

protected static final java.lang.String DEFAULT_REPOSITORY_ROOT_PATH

XSTREAM_XML_FILE_SUFFIX

protected static final java.lang.String XSTREAM_XML_FILE_SUFFIX

See Also:

Constant Field Values

repositoryRootPath

protected java.lang.String repositoryRootPath

For file-based repositories the repositoryRootPath is the absolute path for all repositories of the same type.

repositoryId

protected java.lang.String repositoryId

The repository-ID the name of the repository. It should be unique within a running system.

For file-based repositories the ${repositoryRootPath}/${repositoryId} forms the absolute folder path in which the repository data resides.

Constructor Detail

XStreamXmlFilePerEntityRepository

public XStreamXmlFilePerEntityRepository(java.lang.String repositoryId)

XStreamXmlFilePerEntityRepository

public XStreamXmlFilePerEntityRepository(java.lang.String repositoryId,
                                         Synchronizer synchronizer)

XStreamXmlFilePerEntityRepository

public XStreamXmlFilePerEntityRepository(java.lang.String repositoryRootPath,
                                         java.lang.String repositoryId)

XStreamXmlFilePerEntityRepository

public XStreamXmlFilePerEntityRepository(java.lang.String repositoryRootPath,
                                         java.lang.String repositoryId,
                                         Synchronizer synchronizer)

Method Detail

countAllEntities

public java.lang.Long countAllEntities()

Returns:

the total number of entities residing in this particular repository (partition)

iterateAllEntitiesSpecifiedBy

public <V extends T> java.util.Iterator<V> iterateAllEntitiesSpecifiedBy(Specification<V> specification)

Description copied from interface: Repository

Finds and returns all entities approved by the given specification. An iterator is returned for lazy retrieval of the entities.

Parameters:

specification - the entity specification

Returns:

an iterator with all entities approved by the specification argument

findAllEntitiesSpecifiedBy

public <V extends T> java.util.Collection<V> findAllEntitiesSpecifiedBy(Specification<V> specification)

Description copied from interface: Repository

Finds and returns all entities approved by the given specification.

Parameters:

specification - the entity specification

Returns:

a collection of all entities approved by the specification argument, or an empty set if no entities are found and approved

put

public <V extends T> void put(V entity)

Description copied from interface: Repository

Puts the given entity into this repository.

Parameters:

entity - the entity to be stored

removeAllEntitiesSpecifiedBy

public <V extends T> java.lang.Long removeAllEntitiesSpecifiedBy(Specification<V> specification)

Description copied from interface: Repository

Removes all entities approved by the given specification.

Parameters:

specification - the entity specification

Returns:

the number of removed entities

remove

public <V extends T> java.lang.Boolean remove(V entity)

Description copied from interface: Repository

Removes the given entity from this repository.

Parameters:

entity - the entity to be removed

Returns:

true if the entity is found and removed, otherwise false

getPersistenceDefinition

public PersistenceDefinition getPersistenceDefinition()

getFormat

public java.lang.String getFormat()

load

public void load()

Description copied from interface: PersistentRepository

The semantics of this operation depends on the Repository's PersistenceDefinition.

persist

public void persist()

Description copied from interface: PersistentRepository

The semantics of this operation depends on the Repository's PersistenceDefinition.

update

public <V extends T> void update(V entity)

Description copied from interface: Repository

Updates an entity. When an entity is (re)-retrieved, all state changes will be visible, no matter what kinds of repository implementations being involved. Do notice that for all memory-based repositories (and possibly some delegated ones), entity updates are of course immediately visible.

(Only applicable for persistent repositories doing explicit data writes, like PersistenceDefinition.FILE, and possibly PersistenceDefinition.DELEGATED... For all other persistence definitions, this method is redundant/not applicable. Anyway, by applying this method in a consistent manner, an eventual repository migration will not need any code changes.

getMetaDataFor

public EntityMetaData getMetaDataFor(T entity)

Returns:

persistence meta data for given entity

close

public void close()

Description copied from interface: PersistentRepository

Closes the repository and releases all resources.

This method is redundant for certain repository implementations, but by using this method in a consistent manner, an eventual repository migration will not need any code changes.

getEntityIdBasedFilenameFrom

protected static java.lang.String getEntityIdBasedFilenameFrom(Entity entity)

A naming scheme for file-per-entity Domian XStream persistence. This particular naming scheme is based on the entities' IDs.

Returns:

the file name for this entity based on its entity-ID

createRepositoryFilesIfNotExist

protected void createRepositoryFilesIfNotExist()

getRepositoryRootPath

public java.lang.String getRepositoryRootPath()

getRepositoryId

public java.lang.String getRepositoryId()

Description copied from interface: PersistentRepository

The repository-ID the name of the repository. It should be unique within a running system.

For file-based repositories, the repository-ID should constitute the last directory element of the repository directory.

Specified by:

getRepositoryId in interface PersistentRepository<T extends Entity>

Returns:

the repository id

getRepositoryPathString

public java.lang.String getRepositoryPathString()

getRepositoryDirectory

public java.io.File getRepositoryDirectory()

Description copied from interface: PersistentRepository

The unique file directory in which the repository data files resides.

Specified by:

getRepositoryDirectory in interface PersistentRepository<T extends Entity>

Returns:

the repository directory, if applicable

getMaxNumberOfRetries

public java.lang.Integer getMaxNumberOfRetries()

setMaxNumberOfRetries

public void setMaxNumberOfRetries(java.lang.Integer maxNumberOfRetries)

getRetryTimeoutInMilliseconds

public java.lang.Integer getRetryTimeoutInMilliseconds()

setRetryTimeoutInMilliseconds

public void setRetryTimeoutInMilliseconds(java.lang.Integer retryTimeoutInMilliseconds)

getEncoding

public java.lang.String getEncoding()

Specified by:

getEncoding in interface TextualFormatRepository<T extends Entity>

getRepositoryPath

protected java.lang.String getRepositoryPath(java.lang.String repositoryRootPath,
                                             PersistentRepository<T> repository)

Returns:

the absolute path to the repository location based on root path and the repository ID

run

protected void run(java.lang.Runnable runnable)

Added for completeness.

call

protected void call(java.util.concurrent.Callable<T> callable)
             throws java.lang.Exception

Added for completeness.

Throws:

java.lang.Exception

runConcurrently

protected void runConcurrently(java.lang.Runnable runnable)

Convenience method for running a Runnable in a concurrent manner.

See Also:

Synchronizer

callConcurrently

protected <T> T callConcurrently(java.util.concurrent.Callable<T> callable)

Convenience method for running a Callable in a concurrent manner.

See Also:

Synchronizer

callExclusively

protected <T> T callExclusively(java.util.concurrent.Callable<T> callable)

Convenience method for running a Callable in an exclusively manner.

See Also:

Synchronizer

callConcurrentlyWithRetry

protected <T> T callConcurrentlyWithRetry(java.util.concurrent.Callable<T> callable)

Convenience method for running a Callable in a concurrent manner. If an exception is thrown, the Callable will be immediately retried. The nature of the retries are further defined by the maxNumberOfRetries and retryTimeoutInMilliseconds member values.

callExclusivelyWithRetry

protected <T> T callExclusivelyWithRetry(java.util.concurrent.Callable<T> callable)

Convenience method for running a Callable in an exclusively manner. If an exception is thrown, the Callable will be immediately queued for retrial. The nature of the retries are further defined by the maxNumberOfRetries and retryTimeoutInMilliseconds member values.

callConcurrentlyInNewThread

protected <T> T callConcurrentlyInNewThread(java.util.concurrent.Callable<T> callable)
                                 throws java.util.concurrent.ExecutionException,
                                        java.util.concurrent.TimeoutException,
                                        java.lang.InterruptedException

Throws:

java.util.concurrent.ExecutionException

java.util.concurrent.TimeoutException

java.lang.InterruptedException

callExclusivelyInNewThread

protected <T> T callExclusivelyInNewThread(java.util.concurrent.Callable<T> callable)
                                throws java.util.concurrent.ExecutionException,
                                       java.util.concurrent.TimeoutException,
                                       java.lang.InterruptedException

Throws:

java.util.concurrent.ExecutionException

java.util.concurrent.TimeoutException

java.lang.InterruptedException

runAsynchronously

protected void runAsynchronously(java.lang.Runnable runnable)

Executes the given Runnable in a fresh and independent thread. This method does not block the original thread. The Synchronizer mode is concurrent. (An asynchronous version of Synchronizer in exclusive mode has no meaning, as it is a "stop-the-world" kind of mode.)