Documentación

Descripción:
Cuando se realizan programas para gestionar una base de datos, hay tareas que son frecuentes como: la introducción, edición y borrado de registros de tablas, realizar búsquedas, obtener resultados y mostrarlos en controles tipo regillas (gridviews). Crear la codificación de estas tareas, es bastante tediosa y repetiva, y más cuando tiene un gran número de tablas y vistas (algo que es muy frecuente, aunque sean bases de datos pequeñas).

El uso de este “framework” facilita esta tarea, creando para ellos una serie de clases especificas para cada tabla y vistas, para poder gestionar los registros la base de datos.

Se basa en la implementación del patrón de diseño DAO y VO, y cada tabla y vista, va a tener su propia clase VO y clase DAO
Las clases VO son clases que nos sirven para “transportar” los datos de los registros, para ello usamos sus propiedades. Estas propiedades equivalen al nombre del campo.
Las clases DAO son clases que nos facilitan la gestión de los registros de la tabla: insertar, editar, borrar, buscar, obtener el resultado de una consultas, conversiones de datos, relleno de gridviews asignados, creación de formularios para añadir registros y editarlos, etc.

El programa MapBD realiza las siguiente tareas:
- Va a analizar la base de datos, obteniendo las tablas y vistas con sus respectivos campos y tipos de datos.
- Creará unos archivos, los archivos de clases del tipo DAO y VO, necesarios para manipular los datos.
- Copiará los archivos necesarios a la carpeta del usuario /temporal.


Se creará la siguiente estructura de directorios en la carpeta user.home /temporal


























Esta estructura de directorios la copiamos a nuestro proyecto de Gambas3, en la carpeta oculta “.src”. Al hacer esto, en directorio “fuentes” aparece la estructura de directorios y en ellos las clases que se crean.
Hacer notar que en Gambas3, para usar las clases que están en los directorios de fuentes, aunque estén en subdirectorios de directorios, se usa el nombre y no hace falta indicar la ruta donde se encuentra.


Nota:
En el caso de que queramos “personalizar” estas clases, añadiendo o modificando métodos existentes, por ejemplo la presentación de los formularios), recomiendo la creación de otro directorio, yo lo denomino “Adaptadas”, donde os creeis la clases que “heredan” de la que queremos modificar. En estas clases añadimos o modificados los métodos y son las que realmente se usarán en la aplicación.
El hecho de crearlas en otra carpeta, es una ventaja, ya que si necesitamos generar de nuevo las clases DAO / VO (Data Access Object / Value Object) con la aplicación mapbd-vistas, no podremos modificarlas ya que están en otro directorio y no se “machacarán”.


Ejemplo:
Queremos añadir a una clase ViviendaDAO, una nueva propiedad “tag”, que sea para contener información extra, para el programador.

Pasos a seguir:
- Nos iríamos a la carpeta “Adaptadas”
- Pulsamos con el botón derecho para ir al menu popup, elegimos la opción de crear una nueva clase
- En el formulario, le indicamos su nombre “AdaptadaViviendaDAO”, y que hereda de la clase “ViviendaDAO”
- Añadimos el código de la propiedad

Podemos observar, al ver el arbol de proyecto, la clase nueva se muestra nueva clase se indica que esta por debajo de “ViviendaDAO”. Aunque fisicamente el archivo esta en la carpeta “Adaptadas”

Nota:
Puedes ver que si borro la linea “inherits ViviendaDAO” de la case “AdaptadaViviendaDAO”, se muestra en al directorio “Adaptadas”, donde realmente esta.

Vamos a describir uno por uno lo que nos encontramos en los directorios que se crean y como usarlo.



1. Ficheros en el directorio .scr
Se crean 4 ficheros:
estructural.html
Es una plantilla en html, que usa el programa para crear los informes.
Está codificada en utf-8, para que no de problemas con los acentos y letras especiales (ñÑ) a la hora de crear los informes (es de uso interno para las clases DAO)
FormAutomaticoDinamico.class y FormAutomaticoDinamico.form
Es un formulario el cual tiene métodos especiales para la creación de formularios automáticamente. (es de uso interno para las clases DAO)
{nombreBaseDatos}.tar.gz
Es una copia de la base .sqlite comprimida de la que se ha generado las clases.




2. Ficheros del directorio conexión.
Contiene la variables públicas:
hconn: es un objeto connection que guarda los datos de base de datos y la responsable de acceder a ella. (es de uso interno para las clases DAO)

NombreBaseDatos: contiene la ruta “de trabajo y el nombre de la base de datos, que usa la aplicación.

Métodos:
conexión(): se encarga de la conexión a la base de datos sqlite. Incluso si no existe el fichero de base de datos en el la ruta indicada por NombreBaseDatos, la copia del directorio .src al directorio de trabajo

desconectar(): se encarga de cerrar la base de datos.


3. Carpeta ModeloTabla.
En esta carpeta se encuentras las clases referidas a cada tabla de la base de datos.
Se organizan en dos subcarpetas:
  • DAO: (Data Access Object) las que gestionan los registros de las tablas: inserción, edición, borrado, filtrado, etc..
  • VO: (Value Object), son clases que representan los registros de las distinta tablas. Nos facilitan la transmisión de los datos entre las distintas funciones de las clases DAO


3.1 Directorio VO.
El directorio VO de la carpeta ModeloTabla, contiene las clases VO, una por cada tabla existente.
Describo a continuación el esquema de una clase VO:
Nombre: {nombreTabla}VO.class

Esta clase va a tener tantas propiedades como campos tenga la tabla.
Ademas tiene dos métodos:
PUBLIC FUNCTION ConvertirVOaColeccion(dato as {nombreTabla}VO) AS collection
  • En esta función le pasamos una clase VO de tabla y devuelve una colección (las keys, coinciden con el nombre de los campo).

PUBLIC FUNCTION ConvertirColeccionaVO(dato as collection) AS {nombreTabla}VO
  • Esta función hace lo inverso de la anterior, le pasamos una colección y devuelve un objeto de la clase VO de la tabla


3.2 Directorio DAO
El directorio DAO de la carpeta ModeloTabla, contiene las clases que trabajan con las tablas de la base de dato,una por cada tabla existente.
Describo a continuación el esquema de una clase DAO:
Nombre: {nombreTabla}DAO.class

Nota:
{idprincipal}: Todas las tablas tienen que tener un campo que identifique univoca mente los registros. Por ejemplo para una tabla que contengan datos de personas, su numero NIF, seria el idprincipal de esta tabla


Propiedades:
gridviewPropio: es el gridview que usamos para mostrar los datos de la tabla

Métodos Generales:
PUBLIC SUB contenido() as result
Devuelve el result de todos los registros de la tabla. Internamente se ejecuta la sentencia: “SELECT * FROM {nombreTabla}”


PUBLIC FUNCTION Total() AS integer
Devuelve el numero de registro que tiene una tabla.
Internamente se ejecuta la sentencia: “SELECT {idprincipal} FROM {nombreTabla}”


PUBLIC function sql( consulta AS string) As result
Devuelve un result de una sentencia sql realizada a la base de datos.

PUBLIC Function informe() as string
Devuelve (y escribe en la consola) información referida de la tabla: nombre, nombre de los campos y tipos.

Public function NombreCampos() as Collection
Devuelve una colección que contiene con la key:
“traducidos”: los nombre traducidos de los campos separados por “|”
“sintraducidos”: los nombre de los campos separados por “|”

Métodos: Operaciones de Agregar, Editar, Borrar:
PUBLIC function registrar( Nueva{nombreTabla} as {nombreTabla}VO) as boolean
Se encarga de registra (añadir) un objeto VO del nombre de la tabla indicada a la base de datos. Devolviendo un valor True o False, dependiendo de como ha ido la operación de insersión del registro.


PUBLIC FUNCTION Modificar{idprincipal}(editado as Integer, Nueva{nombreTabla} as {nombreTabla}VO) as boolean
Modifica un registro. El registro modificado es indicado por el parámetro “editado” que es su id. La información de la modificación lo contiene el objeto Nueva{nombreTabla} que es del tipo {nombreTabla}VO


PUBLIC function Borrar{idprincipal}( valor AS Integer ) as boolean
Borra el registro que tenga de {idprincipal} igual al valor indicado





Métodos: Operaciones de Busquedas:


PUBLIC function BuscarIgual( valor AS integer,campoId as string, optional CampoOrden as string,optional restosql as string ) as result
Devuelve el resultado de la consulta donde:
- campoId: es el nombre del campo que usamos que debe de cumplir el criterio de la busqueda
- valor: valor numerico a usar en la busqueda
Opcionalmente hay dos parámetros más:
CampoOrden: Valor opcional que sirve para la ordenación de los resultados.
Valores posibles: nombre del campo para usar en la ordenación mas  "ASC" o "DES"
Ejemplo:
campoOrden="fecharecibo DESC"  
ordenara los resultado por el campo "fecharecibo" en forma "Descendiente"
Para más detalles: http://www.tutorialspoint.com/sqlite/sqlite_order_by.htm
restossql: se usa para añadir alguna condición más que se deba de cumplir. Se escribe en lenguaje SQL


PUBLIC function BuscarIgual{nombreCampo}( valor AS integer,optional CampoOrden as string ) as result
Se crea tantas funciones de este tipo, como campos haya. Hace lo mismo que la función anterior (exceptuando que no tiene el parámetro restossql), pero aplicado al nombre del campo indicado en el nombre de la función. Se mantiene por compatibilidad a otras versiones de mapbd anteriores.

PUBLIC function BuscarContenido{nombreCampo}( valor AS String,optional CampoOrden as string ) as result
Devuelve el resultado de la búsqueda de los registros que contengan en el campo indicado por el nombre de la función el valor. Opcionalmente los datos se pueden devolver ordenados de forma ascendente, o descendente.
Equivale a la sentencia sql:
Select * From {nombreTabla} WHERE {nombreCampo] like '%valor%'



Métodos especiales para campos tipo DATE:
Las siguientes funciones que se crean si el campo es del tipo DATE:

PUBLIC function BuscarMenor{campoTipoFecha}( valor AS Date,optional CampoOrden as string ) as result
Devuelve el resultado de buscar los registros que sean de fecha menor al indicado “valor”

PUBLIC function BuscarMayorQue{campoTipoFecha}( valor AS Date,optional CampoOrden as string ) as result
Devuelve el resultado de buscar los registros que sean de fecha mayores al indicado “valor”


PUBLIC function BuscarEntre{campoTipoFecha}( valorMin AS Date, valorMax AS Date,optional CampoOrden as string ) as result
Devuelve el resultado de buscar los registros que sean de fecha entre valorMin y valorMax.


Funciones para formateo de Gridview:

PUBLIC Function gridFormatearColumnas(grid AS GridView) as gridview
Formatea el gridview pasado como parámetro, los títulos en las columnas igual al nombre del campo. Es la forma habitual de mostrar los datos.

PUBLIC FUNCTION gridFormatearFilas(grid AS GridView) AS gridview
Formatea el gridview pasado como parámetro , la primera columna, con el nombre de los campos. Útil para mostrar un solo registro.

PUBLIC FUNCTION mostrarRegistro(numero AS Integer, grid AS GridView, OPTIONAL sqlcadena AS String) AS Result
Sirve para mostrar un registro, en un gridviews que esté formateado por filas (usando la función gridFormatearFilas).
Ese registro es indicado por un número:
Los resultados de la consulta “SELECT * FROM {nombreTabla}” o el de la ejecución de la sentencia “sqlcadena”, se enumeran (0,1,2,3...) y ese es el numero que tenemos que indicar.

PUBLIC FUNCTION GridResultanteSQL(res AS result, grid AS GridView) AS gridview
Esta función formatea un grid que recibe como parámetro. El formateo de grid se realiza según un result que se le pasa como parámetro. Pone como títulos a las columnas el nombre de los campos del result, y crea tantas filas como resultados haya.


Public Sub MostrarGridView(gridviewtrabajo As GridView, Optional cadenaSQL As String, optional resultado as result)
Es una “macro” función, que realiza las siguientes tareas:
- Formatea el gridview “gridviewtrabajo”
- Asigna internamente el gridview (propiedad gridviewPropio) que es usado por el resto de funciones.
- Asigna a la propiedad tag del gridviewPropio, los nombre de los campos.
- Asigna un Observador interno al gridviewPropio.
- Realiza la consulta tipo “SELECT * FROM {nombreTabla}” o la indicada en el parámetro cadenaSQL
- Muestra los resultados de la consulta

Public Sub Observar_Data(row As Integer, column As Integer)
Función interna para actualizar los datos del gridview, cada vez que se modifica.


Métodos de Conversión:
PUBLIC FUNCTION ConvertirResult(hr as result) AS {nombreTabla}VO[]
Esta función se encarga de convertir un result en un array de objetos {nombreTabla}VO


PUBLIC FUNCTION filaSeleccionadaVO() AS {nombreTabla}VO
Función que devuelve un objeto {nombreTabla}VO según la fila selecciona del gridviewPropio. En el caso de que no haya nada seleccionado, muestra un mensaje de error y devuelve NULL

Public Function extraeColumnaArray(datos As {nombreTabla}VO[], nombrecampo As String) As String
Función que devuelve una cadena de texto, que contiene la lista de valores (separada por “,”) extraído del array de clases {nombre}TablaVO, cuya propiedad sea igual del campo indicado por “nombrecampo”.


Métodos relacionados con Formulario:
Public Sub FormularioRegistrar(numeropaneles as integer)
Crea un formulario para registrar un registro de la tabla y los datos que recibe del formulario los inserta en la tabla. El parámetro de numeropaneles sirve para indicar cuantos subdivisiones en el formulario. Por ejemplo si tenemos 20 campos, lo ideal seria usar 3 subdivisiones en el formulario para que se muestre 10 en cada panel





















Public function FormularioModificarRegistro{nombreTabla}(identificador as integer, datosEditar as {nombreTabla}VO, numeropaneles as integer) as boolean
Crea un formulario para editar un registro de la tabla {nombreTabla}, pasandole el “identificador” que es el del campo {idprincipal}, los datos del registro a modificar (en el formato {nombreTablaVO}) y guarda las modificaciones realizadas en la tabla.

Public function GeneradorCodigoFormulario(tipo as string,optional datosEditar as ContratoVO) as string
Es la función que se encarga de generar el código del formulario, para mostrar los campos, controles, y valores por defecto. Normalmente este método se hereda en otra clase “Adaptada” y se modifica para personalizar los formularios, por ejemplo inserción de etiquetas tipo “label”.

Métodos para imprimir:
Public Sub ImprimirRapidoTablaHorizontal()
Crea un archivo html y lo muestra. Crea un tabla en formato html, que contiene como cabecera de títulos los nombres de los campos y tantas filas como registros haya en el gridviewPropio. Este código en html, lo inserta en la plantilla “estructura.html”, creando un fichero en “/tmp/informe.html” y lo abre con el navegador.

Public Sub ImprimirRapidoTablaVertical()
Crea un archivo html y lo muestra. Crea un tabla con el registro seleccionado en el gridviewPropio, mostrándolo en formato de filas. Al igual que la función anterior crea un fichero en “/tmp/informe.html” y lo abre con el navegador.


4. Carpeta ModeloVista.

En esta carpeta se encuentras las clases referidas a cada Vistas creada en la base de datos.
Se organizan en dos subcarpetas:
  • DAO: (Data Access Object) las que gestionan los registros de las vistas. En este caso, en las vistas no podemos ni insertar, ni editar ni borrar registros.
  • VO: (Value Object), son clases que representan los registros de las distinta vista. Nos facilitan la transmisión de los datos entre las distintas funciones de las clases DAO

Nota:
El uso de vistas en la base de datos, simplifica enormemente el trabajo a la hora de programar, ya que nos evita usar sentencias muy complejas (por ejemplo de mezcla de resultados de distintas tablas y aplicando distintos criterios) que son muy propensas a tener errores al transcribirlas.
Estas vistas al estar integrada en la base de datos, simplemente las tenemos que leer desde nuestro programa.


4.1 Directorio VO.
El directorio VO de la carpeta ModeloVista, contiene las clases VO, una por cada vista existente.
Describo a continuación el esquema de una clase VO:
Nombre: {nombreVista}VO.class

Esta clase va a tener tantas propiedades como campos tenga la vista,
Ademas tiene dos métodos:
PUBLIC FUNCTION ConvertirVOaColeccion(dato as {nombreVista}VO) AS collection
En esta función le pasamos una clase VO de vista y devuelve una colección (las keys, coinciden con el nombre de los campo).

PUBLIC FUNCTION ConvertirColeccionaVO(dato as collection) AS {nombreVista}VO
Esta función hace lo inverso de la anterior, le pasamos una colección y devuelve un objeto de la clase VO de la vista.

4.2 Directorio DAO
El directorio DAO de la carpeta ModeloVista, contiene las clases que trabajan con las vistas de la base de dato, una por cada vista existente.
Describo a continuación el esquema de una clase DAO:
Nombre: {nombreVista}DAO.class

Nota:
1) {idprincipal}: Todas las vistas tienen que tener un campo que identifique univoca mente los registros. Por ejemplo para una tabla que contengan datos de personas, su numero NIF, seria el idprincipal de esta tabla

2) El número de métodos con respecto a las clases DAO de las tablas en senciblemente menor ya que no se pueden editar/modificar/borrar registros de las vistas.


Propiedades:
gridviewPropio: es el gridview que usamos para mostrar los datos de la tabla

Métodos Generales:
PUBLIC SUB contenido() as result
Devuelve el result de todos los registros de la tabla. Internamente se ejecuta la sentencia: “SELECT * FROM {nombreVista}”


PUBLIC FUNCTION Total() AS integer
Devuelve el numero de registro que tiene una tabla.
Internamente se ejecuta la sentencia: “SELECT {idprincipal} FROM {nombreVista}”


PUBLIC function sql( consulta AS string) As result
Devuelve un result de una sentencia sql realizada a la base de datos.

Public function NombreCampos() as Collection
Devuelve una colección que contiene con la key:
“traducidos”: los nombre traducidos de los campos separados por “|”
“sintraducidos”: los nombre de los campos separados por “|”


Métodos: Operaciones de Busquedas:

PUBLIC function BuscarIgual( valor AS integer,campoId as string, optional CampoOrden as string,optional restosql as string ) as result
Devuelve el resultado de la consulta donde:
- campoId: es el nombre del campo que usamos que debe de cumplir el criterio de la busqueda
- valor: valor numerico a usar en la busqueda
Opcionalmente hay dos parámetros más:
CampoOrden: Valor opcional que sirve para la ordenación de los resultados.
Valores posibles: nombre del campo para usar en la ordenación mas  "ASC" o "DES"
Ejemplo:
campoOrden="fecharecibo DESC"  
ordenara los resultado por el campo "fecharecibo" en forma "Descendiente"
restossql: se usa para añadir alguna condición más que se deba de cumplir. Se escribe en lenguaje SQL

Funciones para formateo de Gridview:

PUBLIC Function gridFormatearColumnas(grid AS GridView) as gridview
Formatea el gridview pasado como parámetro, los títulos en las columnas igual al nombre del campo. Es la forma habitual de mostrar los datos.

PUBLIC FUNCTION gridFormatearFilas(grid AS GridView) AS gridview
Formatea el gridview pasado como parámetro , la primera columna, con el nombre de los campos. Útil para mostrar un solo registro.

PUBLIC FUNCTION mostrarRegistro(numero AS Integer, grid AS GridView, OPTIONAL sqlcadena AS String) AS Result
Sirve para mostrar un registro, en un gridviews que esté formateado por filas (usando la función gridFormatearFilas).
Ese registro es indicado por un número:
Los resultados de la consulta “SELECT * FROM {nombreTabla}” o el de la ejecución de la sentencia “sqlcadena”, se enumeran (0,1,2,3...) y ese es el numero que tenemos que indicar.

PUBLIC FUNCTION GridResultanteSQL(res AS result, grid AS GridView) AS gridview
Esta función formatea un grid que recibe como parámetro. El formateo de grid se realiza según un result que se le pasa como parámetro. Pone como títulos a las columnas el nombre de los campos del result, y crea tantas filas como resultados haya.


Public Sub MostrarGridView(gridviewtrabajo As GridView, Optional cadenaSQL As String, optional resultado as result)
Es una “macro” función, que realiza las siguientes tareas:
- Formatea el gridview “gridviewtrabajo”
- Asigna internamente el gridview (propiedad gridviewPropio) que es usado por el resto de funciones.
- Asigna a la propiedad tag del gridviewPropio, los nombre de los campos.
- Asigna un Observador interno al gridviewPropio.
- Realiza la consulta tipo “SELECT * FROM {nombreTabla}” o la indicada en el parámetro cadenaSQL
- Muestra los resultados de la consulta

Public Sub Observar_Data(row As Integer, column As Integer)
Función interna para actualizar los datos del gridview, cada vez que se modifica.


Métodos de Conversión:
PUBLIC FUNCTION ConvertirResult(hr as result) AS {nombreVista}VO[]
Esta función se encarga de convertir un result en un array de objetos {nombreTabla}VO


PUBLIC FUNCTION filaSeleccionadaVO() AS {nombreVista}VO
Función que devuelve un objeto {nombreVista}VO según la fila selecciona del gridviewPropio. En el caso de que no haya nada seleccionado, muestra un mensaje de error y devuelve NULL

Public Function extraeColumnaArray(datos As {nombreVista}VO[], nombrecampo As String) As String
Función que devuelve una cadena de texto, que contiene la lista de valores (separada por “,”) extraído del array de clases {nombre}VistaVO, cuya propiedad sea igual del campo indicado por “nombrecampo”.



Métodos para imprimir:
Public Sub ImprimirRapidoTablaHorizontal()
Crea un archivo html y lo muestra. Crea un tabla en formato html, que contiene como cabecera de títulos los nombres de los campos y tantas filas como registros haya en el gridviewPropio. Este código en html, lo inserta en la plantilla “estructura.html”, creando un fichero en “/tmp/informe.html” y lo abre con el navegador.

Public Sub ImprimirRapidoTablaVertical()
Crea un archivo html y lo muestra. Crea un tabla con el registro seleccionado en el gridviewPropio, mostrándolo en formato de filas. Al igual que la función anterior crea un fichero en “/tmp/informe.html” y lo abre con el navegador.


No hay comentarios:

Publicar un comentario