com.vaadin.addon.jpacontainer
Interface CachingEntityProvider<T>

All Superinterfaces:

EntityProvider<T>, Serializable

All Known Implementing Classes:

CachingBatchableEntityProvider, CachingBatchableLocalEntityProvider, CachingLocalEntityProvider, CachingMutableEntityProvider, CachingMutableLocalEntityProvider

public interface CachingEntityProvider<T>
extends EntityProvider<T>

Interface to be implemented by all EntityProviders that perform some kind of internal caching.

Since:

1.0

Author:

Petter Holmström (Vaadin Ltd)

Method Summary

void	flush() Flushes the cache, forcing all entities to be loaded from the persistence storage upon next request.
int	getEntityCacheMaxSize() Gets the maximum number of entity instances to store in the cache.
boolean	isCacheEnabled() Returns whether the entity provider currently has the internal cache enabled.
boolean	isCloneCachedEntities() Returns whether entities found in the cache should be cloned before they are returned or not.
boolean	isEntitiesDetached() If the cache is in use, all entities are automatically detached regardless of the state of this flag.
void	setCacheEnabled(boolean cacheEnabled) Turns the cache on or off.
void	setCloneCachedEntities(boolean clone) Changes the value of the isCloneCachedEntities() flag.
void	setEntitiesDetached(boolean detached) If the cache is in use, all entities are automatically detached regardless of the state of this flag.
void	setEntityCacheMaxSize(int maxSize) Sets the maximum number of entity instances to store in the cache.
boolean	usesCache() Returns whether the entity provider is currently using the internal cache, which will be the case if both the caching is enabled ( setCacheEnabled(boolean) and there is no filter modifiying QueryModifierDelegate in use.

Methods inherited from interface com.vaadin.addon.jpacontainer.EntityProvider

containsEntity, getAllEntityIdentifiers, getEntity, getEntityCount, getEntityIdentifierAt, getEntityManager, getEntityManagerProvider, getFirstEntityIdentifier, getIdentifier, getLastEntityIdentifier, getLazyLoadingDelegate, getNextEntityIdentifier, getPreviousEntityIdentifier, getQueryModifierDelegate, refresh, refreshEntity, setEntityManager, setEntityManagerProvider, setLazyLoadingDelegate, setQueryModifierDelegate

Method Detail

getEntityCacheMaxSize

int getEntityCacheMaxSize()

Gets the maximum number of entity instances to store in the cache. The default value is implementation specific.

Returns:

the max size, or -1 for unlimited size.

setEntityCacheMaxSize

void setEntityCacheMaxSize(int maxSize)
                           throws UnsupportedOperationException

Sets the maximum number of entity instances to store in the cache. The implementation may decide what to do when the cache is full, but a full cache may never cause an exception. This feature is optional.

Parameters:

maxSize - the new maximum size, or -1 for unlimited size.

Throws:

UnsupportedOperationException - if this implementation does not support configuring the maximum cache size.

flush

void flush()

Flushes the cache, forcing all entities to be loaded from the persistence storage upon next request. This feature should be implemented by all caching entity providers.

isCacheEnabled

boolean isCacheEnabled()

Returns whether the entity provider currently has the internal cache enabled. By default, caching should be enabled.

NOTE! If a QueryModifierDelegate is in use and it modifies the filters through the QueryModifierDelegate.filtersWillBeAdded(javax.persistence.criteria.CriteriaBuilder, javax.persistence.criteria.CriteriaQuery, java.util.List) method, caching will NOT be enabled.

Returns:

true if the cache is in use, false otherwise.

setCacheEnabled

void setCacheEnabled(boolean cacheEnabled)
                     throws UnsupportedOperationException

Turns the cache on or off. When the cache is turned off, it is automatically flushed.

NOTE! If a QueryModifierDelegate is in use and it modifies the filters through the QueryModifierDelegate.filtersWillBeAdded(javax.persistence.criteria.CriteriaBuilder, javax.persistence.criteria.CriteriaQuery, java.util.List) method, caching will NOT be enabled.

Parameters:

cacheEnabled - true to turn the cache on, false to turn it off.

Throws:

UnsupportedOperationException - if the cache cannot be turned on or off programmatically.

usesCache

boolean usesCache()

Returns whether the entity provider is currently using the internal cache, which will be the case if both the caching is enabled ( setCacheEnabled(boolean) and there is no filter modifiying QueryModifierDelegate in use.

Returns:

true if the cache is actually in use, false otherwise.

isEntitiesDetached

boolean isEntitiesDetached()

If the cache is in use, all entities are automatically detached regardless of the state of this flag.

If this method returns true, all entities returned from this entity provider are explicitly detached from the persistence context before returned, regardless of whether the persistence context is extended or transaction-scoped. Thus, no lazy-loaded associations will work and any changes made to the entities will not be reflected in the persistence context unless the entity is merged.

If this method returns false, the entities returned may be managed or detached, depending on the scope of the persistence context.

The default value is implementation specific.

Specified by:

isEntitiesDetached in interface EntityProvider<T>

Returns:

true if the entities are explicitly detached, false otherwise.

See Also:

isCacheEnabled()

setEntitiesDetached

void setEntitiesDetached(boolean detached)
                         throws UnsupportedOperationException

If the cache is in use, all entities are automatically detached regardless of the state of this flag.

Specifies whether the entities returned by the entity provider should be explicitly detached or not. See EntityProvider.isEntitiesDetached() for a more detailed description of the consequences.

Specified by:

setEntitiesDetached in interface EntityProvider<T>

Parameters:

detached - true to request explicitly detached entities, false otherwise.

Throws:

UnsupportedOperationException - if the implementation does not allow the user to change the way entities are returned.

See Also:

isCacheEnabled()

isCloneCachedEntities

boolean isCloneCachedEntities()

Returns whether entities found in the cache should be cloned before they are returned or not. If this flag is false, two subsequent calls to #getEntity(java.lang.Object) with the same entity ID and without flushing the cache in between may return the same entity instance. This could be a problem if the instance is modified, as the cache would then contain the locally modified entity instance and not the one that was fetched from the persistence storage.

If the entity instances are serialized and deserialized before they reach the container, or the container is read-only, entities need not be cloned.

It is undefined what happens if this flag is true and the entities are not cloneable.

The default value of this flag is implementation dependent.

Returns:

true if cached entities should be cloned before they are returned, false to return them directly.

See Also:

setCloneCachedEntities(boolean)

setCloneCachedEntities

void setCloneCachedEntities(boolean clone)
                            throws UnsupportedOperationException

Changes the value of the isCloneCachedEntities() flag.

Parameters:

clone - true to clone cached entities before returning them, false to return them directly.

Throws:

UnsupportedOperationException - if the implementation does not support changing the state of this flag.