From 669b81e1de37a1523e48dfc67026677c996f2325 Mon Sep 17 00:00:00 2001
From: Dancovich <danilo.viana@serpro.gov.br>
Date: Thu, 7 Feb 2013 16:25:02 -0300
Subject: [PATCH] Alterando a interface Crud para permitir a implementação de mais abstrações.

---
 impl/core/src/main/java/br/gov/frameworkdemoiselle/template/Crud.java             | 41 +++++++++++++++++++++++++++++++++++++++--
 impl/extension/jpa/src/main/java/br/gov/frameworkdemoiselle/template/JPACrud.java | 34 +++++++++++++++++++++++++++++-----
 2 files changed, 68 insertions(+), 7 deletions(-)

diff --git a/impl/core/src/main/java/br/gov/frameworkdemoiselle/template/Crud.java b/impl/core/src/main/java/br/gov/frameworkdemoiselle/template/Crud.java
index f0720ef..9966e9b 100644
--- a/impl/core/src/main/java/br/gov/frameworkdemoiselle/template/Crud.java
+++ b/impl/core/src/main/java/br/gov/frameworkdemoiselle/template/Crud.java
@@ -39,16 +39,53 @@ package br.gov.frameworkdemoiselle.template;
 import java.io.Serializable;
 import java.util.List;
 
+/**
+ * Interface containing basic methods for creating, updating and deleting entities (the CRUD design pattern).
+ * 
+ * @author serpro
+ *
+ * @param <T> Type of the entity
+ * @param <I> Type of the identification attribute of the entity
+ */
 public interface Crud<T, I> extends Serializable {
 
+	/**
+	 * Find an entity by it's identification attribute and make it transient.
+	 * 
+	 * @param id The unique identification to find the entity to be deleted.
+	 */
 	void delete(I id);
 
+	/**
+	 * List all instances of the given entity.
+	 * 
+	 * @return The (possibly empty) list of all instances of the given entity.
+	 */
 	List<T> findAll();
 
-	void insert(T bean);
+	/**
+	 * Insert an entity and return the inserted instance of the entity
+	 * 
+	 * @param bean The bean to be inserted
+	 * @return The inserted instance of the entity
+	 */
+	T insert(T bean);
 
+	/**
+	 * Find an entity's instance by it's identification attribute and return it
+	 * @param id Value of the identification attribute of the desired entity's instance
+	 * @return The entity's instance whose identification attribute's value matches
+	 * the one passed as argument.
+	 */
 	T load(I id);
 
-	void update(T bean);
+	/**
+	 * Update an instance of the entity with the bean's attributes as new values. 
+	 * 
+	 * @param bean The bean instance containing both the identification value to find the old
+	 * instance and the new values for the instance's attributes.
+	 * @return The updated entity's instance
+	 */
+	T update(T bean);
 
 }
diff --git a/impl/extension/jpa/src/main/java/br/gov/frameworkdemoiselle/template/JPACrud.java b/impl/extension/jpa/src/main/java/br/gov/frameworkdemoiselle/template/JPACrud.java
index 65e26a4..fbb4b23 100644
--- a/impl/extension/jpa/src/main/java/br/gov/frameworkdemoiselle/template/JPACrud.java
+++ b/impl/extension/jpa/src/main/java/br/gov/frameworkdemoiselle/template/JPACrud.java
@@ -47,6 +47,7 @@ import javax.enterprise.inject.Instance;
 import javax.inject.Inject;
 import javax.persistence.Basic;
 import javax.persistence.Column;
+import javax.persistence.EntityExistsException;
 import javax.persistence.EntityManager;
 import javax.persistence.Enumerated;
 import javax.persistence.Query;
@@ -145,25 +146,48 @@ public class JPACrud<T, I> implements Crud<T, I> {
 		}
 	}
 
+	/**
+	 * Insert a new instance of the entity in the database. After insertion the entity becomes "managed"
+	 * as stated by the JPA specification.
+	 * 
+	 * @param entity A non-detached instance of an entity. If this instance is not managed, it will be after this method returns.
+	 * @return The same instance passed as argument.
+	 * @throws EntityExistsException if <code>entity</code> is an unmanaged instance
+	 * and the persistence provider already has a persisted instance that matches the <code>entity</code>'s primary key.
+	 * @throws IllegalArgumentException if the instance is not an entity
+	 * @see EntityManager#persist(Object entity)
+	 */
 	@Override
 	@Transactional
-	public void insert(final T entity) {
+	public T insert(final T entity) {
 		getEntityManager().persist(entity);
+		return entity;
 	}
 
+	/**
+	 * Finds an instance of this entity by it's primary ID and asks to the
+	 * persistence provider to remove this entity instance from the persistence
+	 * context.
+	 * 
+     * @see EntityManager#remove(Object entity)
+	 */
 	@Override
 	@Transactional
 	public void delete(final I id) {
 		T entity = getEntityManager().getReference(getBeanClass(), id);
 		getEntityManager().remove(entity);
 	}
-
+	
+	/**
+	 * Merge all changes made to the passed entity to a managed entity. The passed instance is not
+	 * modified nor becomes managed, instead the managed entity is returned by this method. 
+	 */
 	@Override
 	@Transactional
-	public void update(final T entity) {
-		getEntityManager().merge(entity);
+	public T update(T entity) {
+		return getEntityManager().merge(entity);
 	}
-
+	
 	@Override
 	public T load(final I id) {
 		return getEntityManager().find(getBeanClass(), id);
--
libgit2 0.21.2