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

All Superinterfaces:

com.vaadin.data.Buffered, com.vaadin.data.Item, com.vaadin.data.Property.ValueChangeNotifier, Serializable

All Known Implementing Classes:

JPAContainerItem

public interface EntityItem<T>
extends com.vaadin.data.Item, com.vaadin.data.Buffered, com.vaadin.data.Property.ValueChangeNotifier

Interface defining the Items that are contained in a EntityContainer. Each item is always backed by an underlying Entity instance that normally is a POJO. EntityItems are always linked to a specific EntityContainer instance and cannot be added to other Containers.

By default, whenever a Property of the item is changed, the corresponding property of the Entity is updated accordingly. However, it is also possible to buffer all the changes by setting #setWriteThrough(boolean) to false. In this mode, the underlying Entity will remain untouched until Buffered.commit() is called. Please note, that this has nothing to do with the buffering of the EntityContainer.

Since:

1.0

Author:

Petter Holmström (Vaadin Ltd)

Nested Class Summary

Nested classes/interfaces inherited from interface com.vaadin.data.Item

com.vaadin.data.Item.Editor, com.vaadin.data.Item.PropertySetChangeEvent, com.vaadin.data.Item.PropertySetChangeListener, com.vaadin.data.Item.PropertySetChangeNotifier, com.vaadin.data.Item.Viewer

Nested classes/interfaces inherited from interface com.vaadin.data.Buffered

com.vaadin.data.Buffered.SourceException

Method Summary

boolean	addItemProperty(Object id, com.vaadin.data.Property property) This functionality is not supported.
void	addListener(com.vaadin.data.Property.ValueChangeListener listener) Registers a new value change listener for all the properties of this item.
void	addNestedContainerProperty(String nestedProperty) Originally, all nested properties are inherited from the EntityContainer.
EntityContainer<T>	getContainer() Gets the container that contains this item.
T	getEntity() Gets the underlying entity instance that contains the actual data being accessed by this item.
Object	getItemId() Gets the item ID of the item.
EntityItemProperty	getItemProperty(Object id)
Collection<?>	getItemPropertyIds()
boolean	isDeleted() Checks whether this item has been marked for deletion.
boolean	isDirty() Checks whether the underlying entity (returned by getEntity()) has been modified after it was fetched from the entity provider.
boolean	isModified() When using item-level buffering, this method tests whether there are changes made to the EntityItem that have not yet been committed to the underlying Entity (getEntity()).
boolean	isPersistent() Checks if the underlying entity (getEntity()) is persistent (i.e.
void	refresh() This method refreshes persisted entity from EntityProvider and calls value change listeners for all properties.
boolean	removeItemProperty(Object propertyId) Removes a nested property added with addNestedContainerProperty(java.lang.String).
void	removeListener(com.vaadin.data.Property.ValueChangeListener listener) Removes a previously registered value change listener.

Methods inherited from interface com.vaadin.data.Buffered

commit, discard, isBuffered, setBuffered

Methods inherited from interface com.vaadin.data.Property.ValueChangeNotifier

addValueChangeListener, removeValueChangeListener

Method Detail

getItemId

Object getItemId()

Gets the item ID of the item. This ID can be used to uniquely identify the item inside the container. It may not necessarily be the same as the entity ID.

If the item ID is null, the entity item was created by a container, but not yet added to it.

Returns:

the item ID or null if the item is not yet inside a container.

See Also:

EntityContainer.createEntityItem(java.lang.Object)

getEntity

T getEntity()

Gets the underlying entity instance that contains the actual data being accessed by this item.

Returns:

the entity (never null).

isPersistent

boolean isPersistent()

Checks if the underlying entity (getEntity()) is persistent (i.e. fetched from a persistence storage) or transient (created and buffered by the container). This method always returns false if getItemId() is null, even if the underlying entity actually is persistent.

Returns:

true if the underlying entity is persistent, false if it is transient.

isDirty

boolean isDirty()

Checks whether the underlying entity (returned by getEntity()) has been modified after it was fetched from the entity provider. When the changes have been persisted, this flag will be reset.

This flag is only of relevance when container buffering is used. If the container is in write-through mode, any changes made to the entity will automatically be propagated back to the entity provider and hence, this method will always return false as there are no dirty entities.

However, if container write-through mode is turned off, any changes made to the entity will not be propagated back until explicitly committed. Modified entities that have not yet been propagated back to the entity provider are considered dirty.

Please note, that this is not the same as the isModified() flag, which is of relevance when item buffering is used.

If the item is not persistent, this method always returns false.

Returns:

true if the underlying entity has been modified, false if not.

isModified

boolean isModified()

When using item-level buffering, this method tests whether there are changes made to the EntityItem that have not yet been committed to the underlying Entity (getEntity()). If item-level buffering is not used, this method always returns false.

Specified by:

isModified in interface com.vaadin.data.Buffered

Returns:

true if #isWriteThrough() returns false and there are changes that have not yet been commited to the underlying Entity, false otherwise.

See Also:

isDirty()

isDeleted

boolean isDeleted()

Checks whether this item has been marked for deletion. This method can only return true if isPersistent() is true and the container is running in buffered mode.

Returns:

true if the item has been deleted, false otherwise.

getContainer

EntityContainer<T> getContainer()

Gets the container that contains this item. If getItemId() is null, the container created the item but does not yet contain it.

Returns:

the container (never null).

addListener

void addListener(com.vaadin.data.Property.ValueChangeListener listener)

Registers a new value change listener for all the properties of this item.

Specified by:

addListener in interface com.vaadin.data.Property.ValueChangeNotifier

Parameters:

listener - the new listener to be registered.

removeListener

void removeListener(com.vaadin.data.Property.ValueChangeListener listener)

Removes a previously registered value change listener. The listener will be unregistered from all the properties of this item.

Specified by:

removeListener in interface com.vaadin.data.Property.ValueChangeNotifier

Parameters:

listener - listener to be removed.

getItemProperty

EntityItemProperty getItemProperty(Object id)

Specified by:

getItemProperty in interface com.vaadin.data.Item

addNestedContainerProperty

void addNestedContainerProperty(String nestedProperty)
                                throws UnsupportedOperationException,
                                       IllegalArgumentException

Originally, all nested properties are inherited from the EntityContainer. However, if additional properties are needed, this method can be used to add the nested property nestedProperty to the set of properties for this particular item.

Otherwise, this method behaves just like EntityContainer.addNestedContainerProperty(java.lang.String).

Parameters:

nestedProperty - the nested property to add (must not be null).

Throws:

UnsupportedOperationException - if nested properties are not supported by the container.

IllegalArgumentException - if nestedProperty is illegal.

removeItemProperty

boolean removeItemProperty(Object propertyId)
                           throws UnsupportedOperationException

Removes a nested property added with addNestedContainerProperty(java.lang.String). This method cannot be used to remove any other properties.

Specified by:

removeItemProperty in interface com.vaadin.data.Item

Parameters:

propertyId - the ID (name) of the nested property.

Returns:

true if a nested property was removed by this method, false otherwise.

Throws:

UnsupportedOperationException - if the implementation does not support removing nested properties.

addItemProperty

boolean addItemProperty(Object id,
                        com.vaadin.data.Property property)
                        throws UnsupportedOperationException

This functionality is not supported.

Specified by:

addItemProperty in interface com.vaadin.data.Item

Throws:

UnsupportedOperationException - always thrown.

getItemPropertyIds

Collection<?> getItemPropertyIds()

In practice, this means all the properties of the underlying entity class, any nested properties defined in the container and any nested properties added using addNestedContainerProperty(java.lang.String). Any non-nested properties that have been removed from the container will still show up in this collection.

Specified by:

getItemPropertyIds in interface com.vaadin.data.Item

refresh

void refresh()

This method refreshes persisted entity from EntityProvider and calls value change listeners for all properties.

The method can be used to update one item if developer know it has been changed either straight to the entity object or to backend.

Note, that in case the write buffering and isDirty() flag is on, all changes will be lost and property values are overridden from the backend.

Also note that the entire container might get reloaded when calling this method when e.g. the entity has been deleted from the database.