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

All Superinterfaces:

Serializable

All Known Subinterfaces:

BatchableEntityProvider<T>, CachingEntityProvider<T>, JndiJtaProvider<T>, MutableEntityProvider<T>

All Known Implementing Classes:

BatchableLocalEntityProvider, CachingBatchableEntityProvider, CachingBatchableLocalEntityProvider, CachingLocalEntityProvider, CachingMutableEntityProvider, CachingMutableLocalEntityProvider, EntityProvider, LocalEntityProvider, MutableEntityProvider, MutableLocalEntityProvider

public interface EntityProvider<T>
extends Serializable

Like the name suggests, the purpose of the EntityProvider is to provide entities to EntityContainers. It basically contains a subset of the methods found in the standard Container interface. Note, that most of the methods return entity IDs and not entity instances - only getEntity(EntityContainer, Object) actually returns instances.

Entity providers should at least implement this interface according to the contracts specified in the methods JavaDocs. Additional functionality may be added by also implementing e.g. MutableEntityProvider.

Once implemented, the entity provider can be plugged into an entity container by using the EntityContainer.setEntityProvider(com.vaadin.addon.jpacontainer.EntityProvider) method.

Please note the isEntitiesDetached() flag, as this may have weird consequences if used inproperly.

Since:

1.0

Author:

Petter Holmström (Vaadin Ltd)

See Also:

MutableEntityProvider, CachingEntityProvider, BatchableEntityProvider, EntityProviderChangeNotifier

Method Summary

boolean	containsEntity(EntityContainer<T> entityContainer, Object entityId, com.vaadin.data.Container.Filter filter) Checks if the persistence storage contains an entity identified by entityId that is also matched by filter.
List<Object>	getAllEntityIdentifiers(EntityContainer<T> entityContainer, com.vaadin.data.Container.Filter filter, List<SortBy> sortBy) Gets the identifiers of all items that match filter.
T	getEntity(EntityContainer<T> entityContainer, Object entityId) Loads the entity identified by entityId from the persistence storage.
int	getEntityCount(EntityContainer<T> entityContainer, com.vaadin.data.Container.Filter filter) Gets the number of entities that are matched by filter.
Object	getEntityIdentifierAt(EntityContainer<T> entityContainer, com.vaadin.data.Container.Filter filter, List<SortBy> sortBy, int index) Gets the identifier of the entity at position index in the result set determined from filter and sortBy.
javax.persistence.EntityManager	getEntityManager() Gets the entity manager.
EntityManagerProvider	getEntityManagerProvider() Gets the EntityManagerProvider that is used to find the current entity manager.
Object	getFirstEntityIdentifier(EntityContainer<T> entityContainer, com.vaadin.data.Container.Filter filter, List<SortBy> sortBy) Gets the identifier of the first item in the list of entities determined by filter and sortBy.
Object	getIdentifier(T entity) Returns identifier for given entity
Object	getLastEntityIdentifier(EntityContainer<T> entityContainer, com.vaadin.data.Container.Filter filter, List<SortBy> sortBy) Gets the identifier of the last item in the list of entities determined by filter and sortBy.
LazyLoadingDelegate	getLazyLoadingDelegate()
Object	getNextEntityIdentifier(EntityContainer<T> entityContainer, Object entityId, com.vaadin.data.Container.Filter filter, List<SortBy> sortBy) Gets the identifier of the item next to the item identified by entityId in the list of entities determined by filter and sortBy.
Object	getPreviousEntityIdentifier(EntityContainer<T> entityContainer, Object entityId, com.vaadin.data.Container.Filter filter, List<SortBy> sortBy) Gets the identifier of the item previous to the item identified by entityId in the list of entities determined by filter and sortBy.
QueryModifierDelegate	getQueryModifierDelegate()
boolean	isEntitiesDetached() 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.
void	refresh() Clears all caches and refreshes any loaded that cannot be discarded entities.
T	refreshEntity(T entity) Refreshes an entity from DB.
void	setEntitiesDetached(boolean detached) Specifies whether the entities returned by the entity provider should be explicitly detached or not.
void	setEntityManager(javax.persistence.EntityManager entityManager) Sets the entity manager.
void	setEntityManagerProvider(EntityManagerProvider entityManagerProvider) Sets the EntityManagerProvider that is used to find the current entity manager if none is set using setEntityManager(javax.persistence.EntityManager)
void	setLazyLoadingDelegate(LazyLoadingDelegate delegate) Set the delegate used for lazy loading.
void	setQueryModifierDelegate(QueryModifierDelegate delegate) Sets the QueryModifierDelegate, which is called in the different stages that the EntityProvider builds a criteria query.

Method Detail

getEntity

T getEntity(EntityContainer<T> entityContainer,
            Object entityId)

Loads the entity identified by entityId from the persistence storage.

Parameters:

entityId - the entity identifier (must not be null).

Returns:

the entity, or null if not found.

isEntitiesDetached

boolean isEntitiesDetached()

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.

Returns:

true if the entities are explicitly detached, false otherwise.

See Also:

setEntitiesDetached(boolean)

setEntitiesDetached

void setEntitiesDetached(boolean detached)
                         throws UnsupportedOperationException

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

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.

getEntityIdentifierAt

Object getEntityIdentifierAt(EntityContainer<T> entityContainer,
                             com.vaadin.data.Container.Filter filter,
                             List<SortBy> sortBy,
                             int index)

Gets the identifier of the entity at position index in the result set determined from filter and sortBy.

Parameters:

filter - the filter that should be used to filter the entities (may be null).

sortBy - the properties to sort by, if any (may be null).

index - the index of the entity to fetch.

Returns:

the entity identifier, or null if not found.

getFirstEntityIdentifier

Object getFirstEntityIdentifier(EntityContainer<T> entityContainer,
                                com.vaadin.data.Container.Filter filter,
                                List<SortBy> sortBy)

Gets the identifier of the first item in the list of entities determined by filter and sortBy.

Parameters:

filter - the filter that should be used to filter the entities (may be null).

sortBy - the properties to sort by, if any (may be null).

Returns:

the identifier of the first entity, or null if there are no entities matching filter.

getLastEntityIdentifier

Object getLastEntityIdentifier(EntityContainer<T> entityContainer,
                               com.vaadin.data.Container.Filter filter,
                               List<SortBy> sortBy)

Gets the identifier of the last item in the list of entities determined by filter and sortBy.

Parameters:

filter - the filter that should be used to filter the entities (may be null).

sortBy - the properties to sort by, if any (may be null).

Returns:

the identifier of the last entity, or null if there are no entities matching filter.

getNextEntityIdentifier

Object getNextEntityIdentifier(EntityContainer<T> entityContainer,
                               Object entityId,
                               com.vaadin.data.Container.Filter filter,
                               List<SortBy> sortBy)

Gets the identifier of the item next to the item identified by entityId in the list of entities determined by filter and sortBy.

Parameters:

filter - the filter that should be used to filter the entities (may be null).

sortBy - the properties to sort by, if any (may be null).

Returns:

the identifier of the next entity, or null if there are no entities matching filter or entityId is the last item.

getPreviousEntityIdentifier

Object getPreviousEntityIdentifier(EntityContainer<T> entityContainer,
                                   Object entityId,
                                   com.vaadin.data.Container.Filter filter,
                                   List<SortBy> sortBy)

Gets the identifier of the item previous to the item identified by entityId in the list of entities determined by filter and sortBy.

Parameters:

filter - the filter that should be used to filter the entities (may be null).

sortBy - the properties to sort by, if any (may be null).

Returns:

the identifier of the previous entity, or null if there are no entities matching filter or entityId is the first item.

getAllEntityIdentifiers

List<Object> getAllEntityIdentifiers(EntityContainer<T> entityContainer,
                                     com.vaadin.data.Container.Filter filter,
                                     List<SortBy> sortBy)

Gets the identifiers of all items that match filter. This method only exists to speed up Container.getItemIds(), which in turn is used by AbstractSelect and its subclasses (e.g. ComboBox). Using this method is not recommended, as it does not use lazy loading.

Parameters:

filter - the filter that should be used to filter the entities (may be null).

sortBy - the properties to sort by, if any (may be null).

Returns:

an unmodifiable list of entity identifiers (never null).

containsEntity

boolean containsEntity(EntityContainer<T> entityContainer,
                       Object entityId,
                       com.vaadin.data.Container.Filter filter)

Checks if the persistence storage contains an entity identified by entityId that is also matched by filter.

Parameters:

entityId - the entity identifier (must not be null).

filter - the filter that the entity should match (may be null).

Returns:

true if the entity exists, false if not.

getEntityCount

int getEntityCount(EntityContainer<T> entityContainer,
                   com.vaadin.data.Container.Filter filter)

Gets the number of entities that are matched by filter. If no filter has been specified, the total number of entities is returned.

Parameters:

filter - the filter that should be used to filter the entities (may be null).

Returns:

the number of matches.

setQueryModifierDelegate

void setQueryModifierDelegate(QueryModifierDelegate delegate)

Sets the QueryModifierDelegate, which is called in the different stages that the EntityProvider builds a criteria query.

Parameters:

delegate - the delegate.

getQueryModifierDelegate

QueryModifierDelegate getQueryModifierDelegate()

Returns:

the registered QueryModifierDelegate.

getIdentifier

Object getIdentifier(T entity)

Returns identifier for given entity

Parameters:

entity -

refreshEntity

T refreshEntity(T entity)

Refreshes an entity from DB. If entity no more exists, null is returned.

Parameters:

entity -

Returns:

the refreshed entity or null

setEntityManager

void setEntityManager(javax.persistence.EntityManager entityManager)

Sets the entity manager.

Parameters:

entityManager - the entity manager to set.

getEntityManager

javax.persistence.EntityManager getEntityManager()

Gets the entity manager.

Returns:

the entity manager, or null if none has been specified.

setEntityManagerProvider

void setEntityManagerProvider(EntityManagerProvider entityManagerProvider)

Sets the EntityManagerProvider that is used to find the current entity manager if none is set using setEntityManager(javax.persistence.EntityManager)

Parameters:

entityManagerProvider - The entity manager provider to set.

getEntityManagerProvider

EntityManagerProvider getEntityManagerProvider()

Gets the EntityManagerProvider that is used to find the current entity manager.

Returns:

the entity manager provider, or null if none specified.

setLazyLoadingDelegate

void setLazyLoadingDelegate(LazyLoadingDelegate delegate)

Set the delegate used for lazy loading.

Parameters:

delegate - the LazyLoadingDelegate to use.

getLazyLoadingDelegate

LazyLoadingDelegate getLazyLoadingDelegate()

Returns:

the LazyLoadingDelegate in use or null if none registered.

refresh

void refresh()

Clears all caches and refreshes any loaded that cannot be discarded entities.