[jboss-cvs] jboss-seam/src/main/org/jboss/seam/framework ...
Peter Muir
peter at bleepbleep.org.uk
Sun Nov 18 08:12:59 EST 2007
User: pmuir
Date: 07/11/18 08:12:59
Modified: src/main/org/jboss/seam/framework EntityHome.java
Home.java
Log:
JBSEAM-1842 and fix bad formatting
Revision Changes Path
1.24 +104 -19 jboss-seam/src/main/org/jboss/seam/framework/EntityHome.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: EntityHome.java
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/src/main/org/jboss/seam/framework/EntityHome.java,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -b -r1.23 -r1.24
--- EntityHome.java 13 Nov 2007 19:29:24 -0000 1.23
+++ EntityHome.java 18 Nov 2007 13:12:59 -0000 1.24
@@ -17,6 +17,13 @@
{
private static final long serialVersionUID = -3140094990727574632L;
+ /**
+ * Run on {@link EntityHome} instantiation.
+ * <br />
+ * Validates that an {@link EntityManager} is available.
+ *
+ * @see Home#create()
+ */
@Override
public void create()
{
@@ -27,6 +34,9 @@
}
}
+ /**
+ * Returns true if the entity instance is managed
+ */
@Transactional
public boolean isManaged()
{
@@ -34,6 +44,19 @@
getEntityManager().contains( getInstance() );
}
+ /**
+ * Flush any changes made to the managed entity instance to the underlying
+ * database.
+ * <br />
+ * If the update is successful, a log message is printed, a
+ * {@link javax.faces.application.FacesMessage} is added and a transaction
+ * success event raised.
+ *
+ * @see Home#updatedMessage()
+ * @see Home#raiseAfterTransactionSuccessEvent()
+ *
+ * @return "updated" if the update is successful
+ */
@Transactional
public String update()
{
@@ -44,6 +67,17 @@
return "updated";
}
+ /**
+ * Persist unmanaged entity instance to the underlying database.
+ * If the persist is successful, a log message is printed, a
+ * {@link javax.faces.application.FacesMessage } is added and a transaction
+ * success event raised.
+ *
+ * @see Home#createdMessage()
+ * @see Home#raiseAfterTransactionSuccessEvent()
+ *
+ * @return "persisted" if the persist is successful
+ */
@Transactional
public String persist()
{
@@ -55,6 +89,18 @@
return "persisted";
}
+ /**
+ * Remove managed entity instance from the Persistence Context and the
+ * underlying database.
+ * If the remove is successful, a log message is printed, a
+ * {@link javax.faces.application.FacesMessage} is added and a transaction
+ * success event raised.
+ *
+ * @see Home#deletedMessage()
+ * @see Home#raiseAfterTransactionSuccessEvent()
+ *
+ * @return "removed" if the remove is successful
+ */
@Transactional
public String remove()
{
@@ -65,26 +111,48 @@
return "removed";
}
+ /**
+ * Implementation of {@link Home#find() find()} for JPA
+ *
+ * @see Home#find()
+ */
@Transactional
@Override
public E find()
{
- if (getEntityManager().isOpen()) {
+ if (getEntityManager().isOpen())
+ {
E result = loadInstance();
- if (result==null) {
+ if (result==null)
+ {
result = handleNotFound();
}
return result;
- } else {
+ }
+ else
+ {
return null;
}
}
+ /**
+ * Utility method to load entity instance from the {@link EntityManager}.
+ * Called by {@link #find()}.
+ * <br />
+ * Can be overridden to support eager fetching of associations.
+ *
+ * @return The entity identified by {@link Home#getEntityClass() getEntityClass()},
+ * {@link Home#getId() getId()}
+ */
protected E loadInstance()
{
return getEntityManager().find(getEntityClass(), getId());
}
+ /**
+ * Implementation of {@link Home#joinTransaction() joinTransaction()} for
+ * JPA.
+ */
@Override
protected void joinTransaction()
{
@@ -101,22 +169,39 @@
}
}
+ /**
+ * The Seam Managed Persistence Context used by this Home component
+ */
public EntityManager getEntityManager()
{
return getPersistenceContext();
}
+ /**
+ * The Seam Managed Persistence Context used by this Home component.
+ */
public void setEntityManager(EntityManager entityManager)
{
setPersistenceContext(entityManager);
}
+ /**
+ * The name the Seam component managing the Persistence Context.
+ * <br />
+ * Override this or {@link #getEntityManager()} if your persistence context
+ * is not named <code>entityManager</code>.
+ */
@Override
protected String getPersistenceContextName()
{
return "entityManager";
}
+ /**
+ * Implementation of {@link Home#getEntityName() getEntityName()} for JPA
+ *
+ * @see Home#getEntityName()
+ */
@Override
protected String getEntityName()
{
1.28 +183 -1 jboss-seam/src/main/org/jboss/seam/framework/Home.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: Home.java
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/src/main/org/jboss/seam/framework/Home.java,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -b -r1.27 -r1.28
--- Home.java 13 Nov 2007 19:29:24 -0000 1.27
+++ Home.java 18 Nov 2007 13:12:59 -0000 1.28
@@ -35,24 +35,66 @@
private String createdMessage = "Successfully created";
private String updatedMessage = "Successfully updated";
+ /**
+ * Add a {@link javax.faces.application.FacesMessage} and log a message when
+ * the entity instance is updated.
+ *
+ * Utility method to add a {@link javax.faces.application.FacesMessage} from
+ * the Seam managed resource bundle or, if not specified in the resource
+ * bundle, from {@link #getUpdatedMessage()} and log the entity when the
+ * managed entity is updated.
+ *
+ * @see #getUpdatedMessage()
+ * @see #getUpdatedMessageKey()
+ */
protected void updatedMessage()
{
debug("updated entity #0 #1", getEntityClass().getName(), getId());
getFacesMessages().addFromResourceBundleOrDefault( SEVERITY_INFO, getUpdatedMessageKey(), getUpdatedMessage() );
}
+ /**
+ * Add a {@link javax.faces.application.FacesMessage} and log a message when
+ * the entity instance is deleted.
+ *
+ * Utility method to add a {@link javax.faces.application.FacesMessage} from
+ * the Seam managed resource bundle or, if not specified in the resource
+ * bundle, from {@link #getDeletedMessage()} and log the entity when the
+ * managed entity is deleted.
+ *
+ * @see #getDeletedMessage()
+ * @see #getDeletedMessageKey()
+ */
protected void deletedMessage()
{
debug("deleted entity #0 #1", getEntityClass().getName(), getId());
getFacesMessages().addFromResourceBundleOrDefault( SEVERITY_INFO, getDeletedMessageKey(), getDeletedMessage() );
}
+ /**
+ * Add a {@link javax.faces.application.FacesMessage} and log a message when
+ * the entity instance is created.
+ *
+ * Utility method to add a {@link javax.faces.application.FacesMessage} from
+ * the Seam managed resource bundle or, if not specified in the resource
+ * bundle, from {@link #getUpdatedMessage()} and log the entity when the
+ * managed entity is updated.
+ *
+ * @see #getCreatedMessage()
+ * @see #getCreatedMessageKey()
+ */
protected void createdMessage()
{
debug("created entity #0 #1", getEntityClass().getName(), getId());
getFacesMessages().addFromResourceBundleOrDefault( SEVERITY_INFO, getCreatedMessageKey(), getCreatedMessage() );
}
+ /**
+ * Run on {@link Home} instantiation to check the Home component is in a
+ * valid state.
+ * <br />
+ * Validates that the class of the entity to be managed has been specified.
+ */
@Create
public void create()
{
@@ -62,6 +104,13 @@
}
}
+ /**
+ * Get the managed entity, using the id from {@link #getId()} to load it from
+ * the Persistence Context or creating a new instance if the id is not
+ * defined.
+ *
+ * @see #getId()
+ */
@Transactional
public E getInstance()
{
@@ -73,12 +122,26 @@
return instance;
}
+ /**
+ * Clear the managed entity (and id), allowing the {@link EntityHome} to be
+ * reused.
+ */
public void clearInstance()
{
setInstance(null);
setId(null);
}
+ /**
+ * Load the instance if the id is defined otherwise create a new instance
+ * <br />
+ * Utility method called by {@link #getInstance()} to load the instance from
+ * the Persistence Context if the id is defined. Otherwise a new instance is
+ * created.
+ *
+ * @see #find()
+ * @see #createInstance()
+ */
protected void initInstance()
{
if ( isIdDefined() )
@@ -97,18 +160,36 @@
}
}
+ /**
+ * Hook method called to allow the implementation to join the current
+ * transaction when necessary.
+ */
protected void joinTransaction() {}
+ /**
+ * Hook method called by {@link #initInstance()} to allow the implementation
+ * to load the entity from the Persistence Context.
+ */
protected E find()
{
return null;
}
+ /**
+ * Utility method called by the framework when no entity is found in the
+ * Persistence Context.
+ */
protected E handleNotFound()
{
throw new EntityNotFoundException( getId(), getEntityClass() );
}
+ /**
+ * Create a new instance of the entity.
+ * <br />
+ * Utility method called by {@link #initInstance()} to create a new instance
+ * of the entity.
+ */
protected E createInstance()
{
if (newInstance!=null)
@@ -132,6 +213,11 @@
}
}
+ /**
+ * Get the class of the entity being managed.
+ * <br />
+ * If not explicitly specified, the generic type of implementation is used.
+ */
public Class<E> getEntityClass()
{
if (entityClass==null)
@@ -150,100 +236,190 @@
return entityClass;
}
+ /**
+ * Set the class of the entity being managed.
+ * <br />
+ * Useful for configuring {@link Home} components from
+ * <code>components.xml</code>.
+ */
public void setEntityClass(Class<E> entityClass)
{
this.entityClass = entityClass;
}
+ /**
+ * Get the id of the object being managed.
+ */
public Object getId()
{
return id;
}
+ /**
+ * Set/change the entity being managed by id.
+ *
+ * @see #assignId(Object)
+ */
public void setId(Object id)
{
if ( setDirty(this.id, id) ) setInstance(null);
this.id = id;
}
+ /**
+ * Set the id of entity being managed.
+ * <br />
+ * Does not alter the instance so used if the id of the managed object is
+ * changed.
+ *
+ * @see #setId(Object)
+ */
protected void assignId(Object id)
{
setDirty(this.id, id);
this.id = id;
}
+ /**
+ * Returns true if the id of the object managed is known.
+ */
public boolean isIdDefined()
{
return getId()!=null && !"".equals( getId() );
}
+ /**
+ * Set/change the entity being managed.
+ */
public void setInstance(E instance)
{
setDirty(this.instance, instance);
this.instance = instance;
}
+ /**
+ * {@link javax.el.ValueExpression} to execute to load a new instance.
+ * <br />
+ * Mainly used when configuring the {@link Home} components in
+ * <code>components.xml</code>.
+ */
public ValueExpression getNewInstance()
{
return newInstance;
}
+ /**
+ * {@link javax.el.ValueExpression} to execute to load a new instance.
+ * <br />
+ * Mainly used when configuring the {@link Home} components in
+ * <code>components.xml</code>.
+ */
public void setNewInstance(ValueExpression newInstance)
{
this.newInstance = newInstance;
}
+ /**
+ * Message displayed to user when the managed entity is created.
+ */
public String getCreatedMessage()
{
return createdMessage;
}
+ /**
+ * Message displayed to user when the managed entity is created.
+ */
public void setCreatedMessage(String createdMessage)
{
this.createdMessage = createdMessage;
}
+ /**
+ * Message displayed to user when the managed entity is deleted.
+ */
public String getDeletedMessage()
{
return deletedMessage;
}
+ /**
+ * Message displayed to user when the managed entity is deleted.
+ */
public void setDeletedMessage(String deletedMessage)
{
this.deletedMessage = deletedMessage;
}
+ /**
+ * Message displayed to user when the managed entity is updated.
+ */
public String getUpdatedMessage()
{
return updatedMessage;
}
+ /**
+ * Message displayed to user when the managed entity is updated.
+ */
public void setUpdatedMessage(String updatedMessage)
{
this.updatedMessage = updatedMessage;
}
+ /**
+ * The prefix of the key to look up messages in the Seam managed resource
+ * bundle.
+ * <br />
+ * By default the simple name of the class suffixed with an underscore.
+ */
protected String getMessageKeyPrefix()
{
String className = getEntityClass().getName();
return className.substring( className.lastIndexOf('.') + 1 ) + '_';
}
+ /**
+ * The key to look up in the Seam managed resource bundle the message
+ * displayed when the managed entity is created.
+ * <br />
+ * By default the {@link #getMessageKeyPrefix()} suffixed with created.
+ */
protected String getCreatedMessageKey()
{
return getMessageKeyPrefix() + "created";
}
+ /**
+ * The key to look up in the Seam managed resource bundle the message
+ * displayed when the managed entity is updated.
+ * <br />
+ * By default the {@link #getMessageKeyPrefix()} suffixed with updated.
+ */
protected String getUpdatedMessageKey()
{
return getMessageKeyPrefix() + "updated";
}
+ /**
+ * The key to look up in the Seam managed resource bundle the message
+ * displayed when the managed entity is deleted.
+ * <br />
+ * By default the {@link #getMessageKeyPrefix()} suffixed with deleted.
+ */
protected String getDeletedMessageKey()
{
return getMessageKeyPrefix() + "deleted";
}
+ /**
+ * Raise events when a CRUD operation succeeds.
+ * <br />
+ * Utility method to raise two events: an event of type
+ * <code>org.jboss.seam.afterTransactionSuccess</code> is raised, along with
+ * an event of type
+ * <code>org.jboss.seam.afterTransactionSuccess.<entityName></code>.
+ */
protected void raiseAfterTransactionSuccessEvent()
{
raiseTransactionSuccessEvent("org.jboss.seam.afterTransactionSuccess");
@@ -254,6 +430,9 @@
}
}
+ /**
+ * The simple name of the managed entity
+ */
protected String getSimpleEntityName()
{
String name = getEntityName();
@@ -267,6 +446,9 @@
}
}
+ /**
+ * Hook method to get the name of the managed entity
+ */
protected abstract String getEntityName();
}
More information about the jboss-cvs-commits
mailing list