Documentación Componente Historial 

1.  Documentación Componente Historial
1.  Prerequisitos
1.  Dependencias backend
2.  Configuración de freemaker
3.  Configuración de Spring
4.  Modificacion del archivo ehcache.xml
5.  Modificacion del archivo osde­framework.properties
6.  @Audited
7.  Formatos
2.  Invocar al caso de uso historial como dialogo
1.  Importar el script del componente
3.  Problemas conocidos

Prerequisitos
Dependencias backend

Agregar las siguientes entradas en el archivo pom.xml del proyecto backend.

<dependency>
    <groupId>ar.com.osde.framework</groupId>
    <version>${osde.framework.version}</version>
    <artifactId>osde­framework­historial­auditoria­backend</artifactId>
</dependency>

<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate­annotations</artifactId>
    <version>3.4.0.GA</version>    
    <exclusions>
        <exclusion>
            <groupId>org.hibernate</groupId>
            <artifactId>ejb3­persistence</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate­commons­annotations</artifactId>
    <version>3.3.0.ga</version>    
    <exclusions>
        <exclusion>
            <groupId>org.hibernate</groupId>
            <artifactId>ejb3­persistence</artifactId>
        </exclusion>
        <exclusion>
            <groupId>javax.persistence</groupId>
            <artifactId>persistence­api</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate­validator</artifactId>
    <version>3.1.0.CR2</version>    
</dependency>

Dependencias frontend

Agregar las siguiente entrada en el archivo pom.xml del proyecto frontend.

<dependency>

    <groupId>ar.com.osde.framework</groupId>
    <artifactId>osde­framework­historial­auditoria­frontend</artifactId>
    <version>${osde.framework.version}</version>
</dependency>

Configuración sitemesh

Para evitar que sitemesh interfiera con la actualización dinámica de las páginas de este componente es necesario asegurarse que en
en archivo decorators.xml exista la siguiente exclusión: <pattern>*/ajax/*</pattern>

<decorators defaultdir="some/path">

......
    <excludes>
........
        <pattern>*/ajax/*</pattern>
.......
    </excludes>
......
</decorators>

Nota: El archivo decorators.xml se debería encontrar en la carpeta WEB­INF del proyecto frontend. /xxx­
frontend/src/main/webapp/WEB­INF/decorators.xml

Configuración de freemaker

Este componente utiliza templates de freemaker, para lo cual se debe asegurar que esté configurado en el web.xml de la aplicación
frontend el servlet que permite este tipo de vistas. 

<servlet>

   <servlet­name>JspSupportServlet</servlet­name>
   <servlet­class>org.apache.struts2.views.JspSupportServlet</servlet­class>
   <load­on­startup>1</load­on­startup>
</servlet>
Nota: Esto debería estar configurado en el arquetipo, pero no está de mas verificar.

Configuración de Spring
Nota: No hay que agregar ninguna configuración a spring, esta sección solo esta de manera informativa.

Este ejemplo muestra una de las formas de agregar los EventListeners al SessionFactory de Hibernate con Spring 
Para más información sobre Envers, consulte: http://docs.jboss.org/envers/docs/index.html 

< bean id="auditEventListener" class="org.hibernate.envers.event.AuditEventListener">

        
<bean id="spring.hibernate.session.factory" 
class="org.springframework.orm.hibernate3.annotation.AnnotationSessionFactoryBean">
        <property name="dataSource" ref="controlFacturacion.spring.datasource"/>
        <property name="hibernateProperties" 
ref="controlFacturacion.spring.hibernate.properties" />
        <property name="eventListeners">
          <map>
            <entry key="post­insert" value­ref="auditEventListener" />
            <entry key="post­update" value­ref="auditEventListener" />
            <entry key="post­delete" value­ref="auditEventListener" />
            <entry key="post­collection­recreate" value­ref="auditEventListener" />
            <entry key="pre­collection­remove" value­ref="auditEventListener" />        
            <entry key="pre­collection­update" value­ref="auditEventListener" />
          </map>
        </property>
        
        <property name="mappingLocations">
          <list>
                <value>classpath:**/*.hbm.xml</value>
          </list>
        </property>
        <property name="lobHandler" ref="controlFacturacion.spring.lobHandler"/>
</bean/>

Modificacion del archivo ehcache.xml

<cache  name="OSDE_FRAMEWORK_HISTORIAL" maxElementsInMemory="300"
        eternal="false" timeToIdleSeconds="360"
        timeToLiveSeconds="360" overflowToDisk="false"/>

Modificacion del archivo de FrontEnd osde­framework.properties

osde.framework.historial.urlHost = http://local.intranet.osde:8081
osde.framework.historial.urlContext = /templateApp/
osde.framework.historial.endPoint = webservices/OsdeFrameworkHistorialService

Configurar una entidad como auditable
Para cada entidad sobre la que se desea realizar auditoria se deben realizar los siguientes pasos

@Audited

Se debe indicar que la entidad será auditada, para ello se debe anotar la clase con la anotación
@audited. 

package ar.com.osde.templateApp.common.entities.libreria;

import org.hibernate.envers.Audited;

import ar.com.osde.framework.entities.FrameworkEntity;

@Audited
public class Autor implements FrameworkEntity {

    private static final long serialVersionUID = ­7752151846535575091L;
    private long id;
    private String nombre;
    private String apellido;
    private Boolean baja;
..... resto de la clase ...
}

Generar descriptor de entidad

Por defecto este componente solo conoce los atributos fecha, proceso, usuario y operación. Para mostrar información adicional de la
clase es necesario crear un archivo descriptor de la entidad por cada clase con el nombre: NombreClase.his.xml en el mismo package
que la clase, ya que utiliza getResourceAsStream para abrirlo.

<?xml version="1.0" encoding="UTF­8"?>

<entity name="Libros">

    <column name="Nombre" property="nombre"/>
    <column name="Descripción" property="descripcion" />
    <column name="Fecha de Edición" property="fechaEdicion"
    format­pattern="dd/MM/yyyy hh:mm"/>
    <column name="Stock Mínimo" property="stockMinimo"/>
    <column name="Precio" property="precio" format­pattern="¤#.00"/>
    <column name="Categoría">
  <property name="categoria.descripcion" />    
        <property name="categoria.id" format­pattern="###"/>
    </column>
</entity>

Nota: Respetar el encoding UTF­8

Donde la propiedad name del elemento entity se utiliza para armar el título del caso de uso.
Cada elemento column representa una columna en la tabla de historial, el atributo nombre será el título de la columna.

Por otra parte cada columna puede tener una o mas propiedades que se muestren, se puede especificar una propiedad como atributo,
o bien una lista de propiedades.

Relacionar Entidades

Es posible vincular dos entidades para poder filtrar todos los cambios de una entidad relacionada. Para el caso de la entidad Libro
esta tiene relacionada una entidad categoria. La entidad categoria entre sus atributos debe contar con el id del libro.

Al ejemplo anterior hay que agregar lo siguiente al mismo nivel que los tags column:

    <relatedEntity name="Categoria" 
className="ar.com.osde.templateApp.common.entities.libreria.Categoria" field="libroId"/>
   

Por el momento el componente no soporta más de un nivel de relación. Se debe evitar tener mas de un nivel.

Formatos

Los format­pattern que se pueden especificar corresponden a los patterns según el tipo de dato:

Numbers: DecimalFormat
Date: SimpleDateFormat

En los otros tipos de datos, se ignoran. 
Los boolean se muestran como si / no.
  

Invocar al caso de uso historial como dialogo
Importar el script del componente

El componente provee un componente javascript para simplificar la tarea de incluir el caso de uso . No se necesita mas que importar
el archivo y abrir el dialogo. No se necesita tener creado un div donde abrir el dialogo.

En el head de la página que requiera mostrar un dialogo con el historial de la entidad se debe agregar el siguiente script.

<script type="text/javascript" 
src="contextPath/static/osde/framework/historial/js/historial_dialog.js"/>
Se debe reemplazar el contextPath (en rojo) con el path en el nombre de contexto de la aplicación que utiliza el componente, por
ejemplo utilizando request.getContextPath();

Abrir el dialogo

Para abrir el dialog, utilizando jquery, se puede agregar el siguiente código en el document.ready

$("#btnHistorial").click ( function () {
 var id = document.getElementsByName('id')[0].value;
 var contextPath = '/templateApp­frontend/';
 var entityName = 'ar.com.osde.templateApp.common.entities.libreria.Libro';
 var dialog = new OsdeFrameworkHistorialDialogBox(contextPath,
    {entity:entityName, entityId: id, field:'null', decorator:'ajax'});
 dialog.showDialog();
 return false;
} );

Problemas conocidos

HH3854

Se encontró un defecto de envers, cuando se utiliza la configuración default­lazy, y lazy en false en los mapeos hbm. Para mas
información del defecto aqui

Para evitar el mismo, se cambiaron los archivos hbm recibidos indicando en las colecciones y objetos relacionados la propiedad lazy
en true para las colecciones y en proxy para los objetos

En principio si las colecciones y los objetos relacionados no tienen la propiedad lazy en true, envers falla.

HH3895

Este error de envers provoca que la entidad versionada no sea inicializada cuando se consulta la propiedad primary key. No tiene
gran impacto en el componente ya por lo general no se muestra el id de las entidades, si se desea hacer esto, la propiedad primary
key de la entidad no debe ser la primera en la lista. ej ver el descriptor del punto generar descriptor de la entidad, en la columna
categoria.
En la última versión del componente de historial se realizó un fix sobre este punto. Ahora es posible poner primero el campo id.

Para mas información del defecto aqui
=