Persistir una entidad

Para persistir una entidad se requiere crear una nueva clase. Para este ejemplo persistiremos la entidad denominada CityEntity, por tanto creamos la clase CityPersistence. Esta clase se agrega en el paquete persistence.

Toda clase de persistencia debe definirse como un EJB si estado (Stateless). Esto es importante, ya que estos Beans (clases) "no mantienen un estado de conversación con el cliente. Cuando un cliente invoca los métodos de un bean sin estado, las variables de instancia del bean pueden contener un estado específico para ese cliente, pero solo durante la invocación. Cuando el método finaliza, el estado específico del cliente no debe mantenerse. Sin embargo, los clientes pueden cambiar el estado de las variables de instancia en beans sin estado agrupados, y este estado se mantiene en la siguiente invocación del bean sin estado agrupado". [1]

Un EJB si estado se define con la anotación @Stateless

@Stateless
public class CityPersistence {

Luego definimos un Logger para llevar un registro de todos los eventos que ocurren cuando se ejecutan las diferentes operaciones en la persistencia.

private static final Logger LOGGER = Logger.getLogger(CityPersistence.class.getName());

A continuación se define un atributo de tipo EntityManager el cual se encargará de realizar todas las operaciones de persistencia. Este atributo se anota con @PersistenceContext. El valor del atributo unitName en la anotación se puede validar en Netbeans en la ruta proyecto back > Other Sources > src/main/resources > META-INF > persistence.xml.

@PersistenceContext(unitName = "ejemploPU")
protected EntityManager em;

Luego, se documentan los parámetros para cada método. El siguiente es el método create, el cual recibe como parámetro un CityEntity, lo persiste en la base de datos, y retona el mismo objeto que ahora tendrá un ID que ha sido definido por la base de datos.

/**
    * Crea una ciudad en la base de datos
    *
    * @param cityEntity objeto city que se creará en la base de datos
    * @return devuelve la entidad creada con un id dado por la base de datos.
*/
public CityEntity create(CityEntity cityEntity) {
    LOGGER.log(Level.INFO, "Creando una ciudad nueva");
    /* Note que hacemos uso de un método propio de EntityManager para persistir la ciudad en la base de datos.
        Es similar a "INSERT INTO table_name (column1, column2, column3, ...) VALUES (value1, value2, value3, ...);" en SQL.
    */
    em.persist(cityEntity);
    LOGGER.log(Level.INFO, "Ciudad creada");
    return cityEntity;
}

El siguiente método se encaga de devolver todos las ciudades que existen en la base de datos. Dado que en la base de datos pueden existir varias ciudades, se retornará una lista de ciudades.

/**
    * Devuelve todas las ciudades de la base de datos.
    *
    * @return una lista con todas las ciudades que encuentre en la base de
    * datos. "select u from CityEntity u" es como un "select * from
     * CityEntity;" - "SELECT * FROM table_name" en SQL
*/

public List<CityEntity> findAll() {
    LOGGER.log(Level.INFO, "Consultando todas las ciudades");
    // Se crea un query para buscar todas las ciudades en la base de datos.
    TypedQuery query = em.createQuery("select u from CityEntity u", CityEntity.class);
    // Note que en el query se hace uso del método getResultList() que obtiene una lista de ciudades.
    return query.getResultList();
}

El siguiente método se encaga de buscar la ciudad con el id que se envía de argumento.

/**
    * Busca si hay alguna ciudad con el id que se envía de argumento
    *
    * @param cityId: id correspondiente a la ciudad buscada.
    * @return una ciudad.
    */
public CityEntity find(Long cityId) {
    LOGGER.log(Level.INFO, "Consultando la ciudad con id={0}", cityId);
    /* Note que se hace uso del metodo "find" propio del EntityManager, el cual recibe como argumento 
    el tipo de la clase y el objeto que nos hara el filtro en la base de datos en este caso el "id"
    Suponga que es algo similar a "select * from CityEntity where id=id;" - "SELECT * FROM table_name WHERE condition;" en SQL.
    */
    return em.find(CityEntity.class, cityId);
}

El siguiente método se encaga de actualizar la información de una ciudad.

/**
    * Actualiza una ciudad.
    *
    * @param cityEntity: la ciudad que viene con los nuevos cambios. Por
    * ejemplo el nombre pudo cambiar. En ese caso, se haria uso del método
    * update.
    * @return una ciudad con los cambios aplicados.
*/
public CityEntity update(CityEntity cityEntity) {
    LOGGER.log(Level.INFO, "Actualizando la ciudad con id={0}", cityEntity.getId());
    /* Note que hacemos uso de un método propio del EntityManager llamado merge() que recibe como argumento
    la ciudad con los cambios. Esto es similar a 
    "UPDATE table_name SET column1 = value1, column2 = value2, ... WHERE condition;" en SQL.
    */
    return em.merge(cityEntity);
}

El siguiente método se encaga de borrar una ciudad de la base de datos:

/**
    * Borra una ciudad de la base de datos recibiendo como argumento el id de
    * la ciudad
    *
    * @param cityId: id correspondiente a la ciudad a borrar.
*/

public void delete(Long cityId) {
    LOGGER.log(Level.INFO, "Borrando la ciudad con id={0}", cityId);
    // Se hace uso de mismo método que esta explicado en public CityEntity find(Long id) para obtener la ciudad a borrar.
    CityEntity cityEntity = em.find(CityEntity.class, cityId);
    /* Note que una vez obtenido el objeto desde la base de datos llamado "cityEntity", volvemos hacer uso de un método propio del
    EntityManager para eliminar de la base de datos el objeto que encontramos y queremos borrar.
    Es similar a "delete from CityEntity where id=id;" - "DELETE FROM table_name WHERE condition;" en SQL.*/
    em.remove(cityEntity);
}

El siguiente método se encaga de buscar una ciudad por nombre:

/**
    * Busca una ciudad en la base de datos recibiendo como argumento el nombre de
    * la ciudad
    *
    * @param name: el nombre de la ciudad a buscar.
*/

public CityEntity findByName(String name) {
    LOGGER.log(Level.INFO, "Consultando ciudades por nombre ", name);
    // Se crea un query para buscar ciudades con el nombre que recibe el método como argumento. ":name" es un placeholder que debe ser remplazado
    TypedQuery query = em.createQuery("Select e From CityEntity e where e.name = :name", CityEntity.class);
    // Se remplaza el placeholder ":isbn" con el valor del argumento 
    query = query.setParameter("name", name);
    // Se invoca el query se obtiene la lista resultado
    List<CityEntity> sameName = query.getResultList();
    CityEntity result;
    if (sameName == null) {
        result = null;
    } else if (sameName.isEmpty()) {
        result = null;
    } else {
        result = sameName.get(0);
    }
    LOGGER.log(Level.INFO, "Saliendo de consultar ciudades por nombre ", name);
    return result;
}

Un video con el paso a paso de la explicación puede consultarse en este link

Referencias:

[1]. https://docs.oracle.com/cd/E19798-01/821-1841/gipin/index.html