Merge branch '2.4.0' of git@github.com:demoiselle/framework.git into 2.4.0

Ednara Oliveira
2 parents 68efc05f e3e1da17
Showing 3 changed files with 95 additions and 21 deletions Show diff stats
impl/core/src/main/java/br/gov/frameworkdemoiselle/template/Crud.java
impl/core/src/main/java/br/gov/frameworkdemoiselle/template/DelegateCrud.java
impl/extension/jpa/src/main/java/br/gov/frameworkdemoiselle/template/JPACrud.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);
 }
@@ -46,6 +46,19 @@ import br.gov.frameworkdemoiselle.transaction.Transactional;
 import br.gov.frameworkdemoiselle.util.Beans;
 import br.gov.frameworkdemoiselle.util.Reflections;
+/**
+ * An implementation of the {@link Crud} interface that delegates it's operations
+ * to another {@link Crud} implementation.
+ * 
+ * @author serpro
+ *
+ * @param <T> 
+ *            bean object type
+ * @param <I>
+ *            bean id type
+ * @param <C>
+ *            type of {@link Crud} implementation this class will delegate to
+ */
 public class DelegateCrud<T, I, C extends Crud<T, I>> implements Crud<T, I> {
 	private static final long serialVersionUID = 1L;
@@ -137,21 +150,21 @@ public class DelegateCrud&lt;T, I, C extends Crud&lt;T, I&gt;&gt; implements Crud&lt;T, I&gt; {
 	 *            A entity to be inserted by the delegate
 	 */
 	@Override
-	public void insert(final T bean) {
+	public T insert(final T bean) {
 		if (isRunningTransactionalOperations()) {
-			transactionalInsert(bean);
+			return transactionalInsert(bean);
 		} else {
-			nonTransactionalInsert(bean);
+			return nonTransactionalInsert(bean);
 		}
 	}
 	@Transactional
-	private void transactionalInsert(final T bean) {
-		nonTransactionalInsert(bean);
+	private T transactionalInsert(final T bean) {
+		return nonTransactionalInsert(bean);
 	}
-	private void nonTransactionalInsert(final T bean) {
-		getDelegate().insert(bean);
+	private T nonTransactionalInsert(final T bean) {
+		return getDelegate().insert(bean);
 	}
 	/**
@@ -171,21 +184,21 @@ public class DelegateCrud&lt;T, I, C extends Crud&lt;T, I&gt;&gt; implements Crud&lt;T, I&gt; {
 	 *            The instance containing the updated state.
 	 */
 	@Override
-	public void update(final T bean) {
+	public T update(final T bean) {
 		if (isRunningTransactionalOperations()) {
-			transactionalUpdate(bean);
+			return transactionalUpdate(bean);
 		} else {
-			nonTransactionalUpdate(bean);
+			return nonTransactionalUpdate(bean);
 		}
 	}
 	@Transactional
-	private void transactionalUpdate(final T bean) {
-		nonTransactionalUpdate(bean);
+	private T transactionalUpdate(final T bean) {
+		return nonTransactionalUpdate(bean);
 	}
-	private void nonTransactionalUpdate(final T bean) {
-		getDelegate().update(bean);
+	private T nonTransactionalUpdate(final T bean) {
+		return getDelegate().update(bean);
 	}
 	private boolean isRunningTransactionalOperations() {
@@ -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&lt;T, I&gt; implements Crud&lt;T, I&gt; {
 		}
 	}
+	/**
+	 * 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);
	@@ -39,16 +39,53 @@ package br.gov.frameworkdemoiselle.template;		@@ -39,16 +39,53 @@ package br.gov.frameworkdemoiselle.template;
39	import java.io.Serializable;	39	import java.io.Serializable;
40	import java.util.List;	40	import java.util.List;
41		41
		42	+/**
		43	+ * Interface containing basic methods for creating, updating and deleting entities (the CRUD design pattern).
		44	+ *
		45	+ * @author serpro
		46	+ *
		47	+ * @param <T> Type of the entity
		48	+ * @param <I> Type of the identification attribute of the entity
		49	+ */
42	public interface Crud<T, I> extends Serializable {	50	public interface Crud<T, I> extends Serializable {
43		51
		52	+ /**
		53	+ * Find an entity by it's identification attribute and make it transient.
		54	+ *
		55	+ * @param id The unique identification to find the entity to be deleted.
		56	+ */
44	void delete(I id);	57	void delete(I id);
45		58
		59	+ /**
		60	+ * List all instances of the given entity.
		61	+ *
		62	+ * @return The (possibly empty) list of all instances of the given entity.
		63	+ */
46	List<T> findAll();	64	List<T> findAll();
47		65
48	- void insert(T bean);	66	+ /**
		67	+ * Insert an entity and return the inserted instance of the entity
		68	+ *
		69	+ * @param bean The bean to be inserted
		70	+ * @return The inserted instance of the entity
		71	+ */
		72	+ T insert(T bean);
49		73
		74	+ /**
		75	+ * Find an entity's instance by it's identification attribute and return it
		76	+ * @param id Value of the identification attribute of the desired entity's instance
		77	+ * @return The entity's instance whose identification attribute's value matches
		78	+ * the one passed as argument.
		79	+ */
50	T load(I id);	80	T load(I id);
51		81
52	- void update(T bean);	82	+ /**
		83	+ * Update an instance of the entity with the bean's attributes as new values.
		84	+ *
		85	+ * @param bean The bean instance containing both the identification value to find the old
		86	+ * instance and the new values for the instance's attributes.
		87	+ * @return The updated entity's instance
		88	+ */
		89	+ T update(T bean);
53		90
54	}	91	}