com.vaadin.addon.jpacontainer.MutableEntityProvider Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jpacontainer-addon-agpl-3.0 Show documentation
Vaadin JPAContainer
The newest version!
/*
JPAContainer
Copyright (C) 2009-2011 Oy Vaadin Ltd

This program is available under GNU Affero General Public License (version
3 or later at your option).

See the file licensing.txt distributed with this software for more
information about licensing.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see .
 */
package com.vaadin.addon.jpacontainer;

/**
 * Entity provider that also supports adding, updating and removing entities.
 * Implementations should pay special attention to the usage of the
 * {@link #isEntitiesDetached() } property.
 * 
 * All the methods defined in this interface should run in their own transactions.
 * The implementation may either handle the transactions itself, or rely on
 * declarative transaction handling as provided by e.g. Spring or EJB.
 * If a method completes successfully, its transaction should be committed.
 * If an error occurs while accessing the persistence storage, the transaction
 * should be rolled back and a runtime exception should be thrown.
 * 
 * @author Petter Holmström (Vaadin Ltd)
 * @since 1.0
 */
public interface MutableEntityProvider extends EntityProvider {

	/**
	 * Adds entity to the persistence storage. This method returns
	 * the same entity after adding to make it possible for the client to access
	 * the entity identifier. Note, however, that depending on the
	 * implementation of the entity provider and the state of
	 * {@link #isEntitiesDetached() }, this may or may not be the same instance
	 * as entity. Therefore, if {@link #isEntitiesDetached() } is
	 * true, clients should always assume that
	 * entity != returnedEntity.
	 * 
	 * @param entity
	 *            the entity to add (must not be null).
	 * @return the added entity.
	 * @throws RuntimeException if an error occurs while adding the entity to the persistence storage.
	 */
	public T addEntity(T entity) throws RuntimeException;

	/**
	 * Saves the changes made to entity to the persistence storage.
	 * This method returns the same entity after saving the changes. Note,
	 * however, that depending on the implementation of the entity provider and
	 * the state of {@link #isEntitiesDetached() }, this may or may not be the
	 * same instance as entity. Therefore, if
	 * {@link #isEntitiesDetached() } is true, clients should always assume that
	 * entity != returnedEntity.
	 * 
	 * @param entity
	 *            the entity to update (must not be null).
	 * @return the updated entity.
	 * @throws RuntimeException if an error occurs while saving the changes to the persistence storage.
	 */
	public T updateEntity(T entity) throws RuntimeException;

	/**
	 * 
	 * Updates a single property value of a specific entity. If the entity is
	 * not found, nothing happens.
	 * 
	 * @param entityId
	 *            the identifier of the entity (must not be null).
	 * @param propertyName
	 *            the name of the property to update (must not be null).
	 * @param propertyValue
	 *            the new property value.
	 * @throws IllegalArgumentException
	 *             if propertyName is not a valid property name.
	 * @throws RuntimeException if an error occurs while saving the change to the persistence storage.
	 */
	public void updateEntityProperty(Object entityId, String propertyName,
			Object propertyValue) throws IllegalArgumentException, RuntimeException;

	/**
	 * Removes the entity identified by entityId. If no entity is
	 * found, nothing happens.
	 * 
	 * @param entityId
	 *            the identifier of the entity to remove.
	 * @throws RuntimeException if an error occurs while removing the entity from the persistence storage.
	 */
	public void removeEntity(Object entityId) throws RuntimeException;
}