OBCOM SQL Wizard

1. Introducción

OBCOM SQL Wizard es una herramienta que permite generar componentes para invocar a procedimientos almacenados en una base de datos DB2, PostgreSQL, Oracle, SQL Server y Sybase. Esta herramienta pueden generar: páginas ASP y JSP, clases Visual Basic 6, componentes EJB y Servicios Web (GlassFish, JBoss, WebLogic, WebSphere), componentes .NET y Servicios Web (Visual Basic y C-Sharp), y aplicaciones Adobe Flex para probar los Servicios web.

OBCOM SQL Wizard es una aplicación Java que se puede usar en cualquier estación de trabajo que tenga instalado Oracle Java 7 o superior. Su forma de uso es simple. Primero se conecta OBCOM SQL Wizard a una de base de datos. Luego se seleccionan los procedimientos almacenados que se desea invocar. Finalmente, se generan las componentes haciendo clic en un botón la barra de herramientas. Los detalles de estos pasos se explican en las próximas secciones de este documento.

OBCOM SQL Wizard genera sólo archivos de texto. No se requieren bibliotecas (run-time) adicionales, excepto por aquellas bibliotecas propias del ambiente de desarrollo y/o ejecución donde se utilizarán los archivos de texto generados.

2. Obtener o actualizar licencia de uso

Antes de poder utilizar OBCOM SQL Wizard, es necesario registrarse y obtener una licencia de uso. Al presionar el botón de la barra de herramientas, aparece una ventana como se observa en la siguiente figura. Los pasos necesarios para solicitar y obtener una licencia de uso están claramente explicados en esta ventana.

3. Conexión a la base de datos

El primer paso para usar OBCOM SQL Wizard es conecterse a una base de datos. Al presionar el botón de la barra de herramientas, aparece una ventana como la que se observa en la siguiente figura. Esta ventana solicita la siguiente información: (1) tipo del servidor de base de datos, (2) nombre o número IP del servidor, (3) nombre de la base de datos (SID en caso de Oracle), (4) nombre del usuario, y (5) contraseña del usuario.

4. Información de un procedimiento

La parte superior de la ventana de OBCOM SQL Wizard muestra la lista de los procedimientos almacenados disponibles en la base de datos (o esquema) seleccionado. Al hacer clic sobre uno de los procedimientos de esta lista, la parte inferior de la ventana permite ver (1) los parámetros de entrada/salida, y (2) el código fuente del procedimiento seleccionado. Las siguientes dos figuras muestran las dos pestañas que entregan esta información.

5. Filtro de procedimientos

La opción “Filtrar procedimientos…” del menú “Procedimientos” permite filtrar la lista de procedimientos almacenados usando (1) un patrón del nombre de los procedimientos, o (2) el nombre del esquema al que pertenecen los procedimientos. Una vez que se digitan los valores de estos filtros, hay que hacer clic en el botón “Aceptar”. El botón “Mostrar todos” cancela todos los filtros, y muestra todos los procedimientos almacenados.

Un patrón es una secuencia de uno o más caracteres, algunos de los cuales tienen significados especiales. En particular:

Carácter del Patrón	Carácter del nombre del Procedimiento Almacenado
?	Coincide con cualquier carácter
*	Coincide con una secuencia de cero o más caracteres
#	Coincide con un dígito cualquiera (0-9)
[lista-de-caracteres]	Coincide con un carácter incluido en la lista-de-caracteres
[!lista-de-caracteres]	Coincide con un carácter no incluido en la lista-de-caracteres
otro carácter	Coincide con el mismo carácter

Se puede especificar un intervalo de caracteres en lista-de-caracteres colocando un guión (–) para separar los límites inferior y superior del intervalo. Por ejemplo, la secuencia [A–Z] en patrón permite hallar una coincidencia si en la posición correspondiente de la cadena (String) hay un carácter en mayúsculas cualquiera, comprendido en el intervalo de la “A” a la “Z”. Se pueden incluir múltiples intervalos entre corchetes, sin necesidad de delimitadores, por ejemplo: [A–Za-z0-9].

6. Seleccionar procedimientos para generación

Para poder generar componentes con OBCOM SQL Wizard, es necesario seleccionar uno o más procedimientos almacenados. Para esto, se debe hacer clic en la caja asociada a cada procedimiento. Para seleccionar (o deseleccionar) varios procedimientos a la vez, se puede utilizar el menú “Procedimientos”. Alternativamente, el menú se puede activar haciendo clic con el botón derecho sobre la lista de procedimientos. En ambos casos, aparece una lista de opciones como se observa en la figura siguiente, la cual permite seleccionar o deseleccionar procedimientos en base a distintos criterios:

Las opciones “Incluir nombres…” y “Excluir nombres…” permiten seleccionar (o deseleccionar) procedimientos en base a una lista de nombres provistas en un archivo de texto. Cuando se utilizan estas opciones, OBCOM SQL Wizard muestra una ventana para que el usuario seleccione el archivo que contiene los nombres. Cada nombre de procedimiento debe estar en una línea separada.

7. Definir conjuntos de resultados en código fuente

Un conjunto de resultados (ResultSet) es una entidad dinámica, cuya estructura sólo se conoce en el momento que se ejecuta un procedimiento almacenado. No existe un mecanismo estándar que permita conocer, de antemano, el nombre y tipo de las columnas de componen los conjuntos de resultado que retorna por un procedimiento. Debido a esta falta de información, las estructuras que genera OBCOM SQL Wizard para representar conjuntos de resultado son genéricas, y sus campos (fields) están definidos sólo como “Object”, en vez de tener tipos más específicos. Estas estructuras genéricas (weakly-typed) tienen varios problemas: (1) el compilador no puede detectar mal uso de tipos de datos, (2) el código generado es menos eficiente, y (3) la representación XML de estas estructuras es grande.

OBCOM SQL Wizard es capaz de leer el código fuente de un procedimiento, y obtener la definición de los conjuntos de resultado (ResultSets) que el procedimiento retorna. Con esta información, OBCOM SQL Wizard puede generar estructuras específicas (strongly-typed) para cada uno de los conjuntos de resultado. Estas estructuras específicas son eficientes y generan representaciones XML muy compactas. Es decir, no tienen los problemas de las estructuras genéricas (weakly-typed) antes mencionadas.

Para que esto pueda ocurrir, se necesita que el programador defina los conjuntos de resultados (ResultSets) usando comentarios especiales en el código fuente del procedimiento. Cada definición debe comenzar con la marca “#ResultSet” y debe terminar con la marca “#EndResultSet”. Entre estas dos marcas deben existir una o más marcas “#Column” que definen el nombre y el tipo de cada una de las columnas del conjunto de resultados.

El siguiente cuadro muestra un ejemplo con el código fuente de un procedimiento Microsoft SQL Server que contiene la definición de un conjunto de resultados denominado “EMPLEADO”, cuyo nombre en plural es “EMPLEADOS”:

CREATE PROCEDURE EMP$BUSCAR_POR_RUT
    @RUT VARCHAR(10)
AS
BEGIN
    -- #ResultSet EMPLEADO EMPLEADOS
    --   #Column ID         DECIMAL
    --   #Column DEPT_ID    DECIMAL
    --   #Column NOMBRE     VARCHAR
    --   #Column PATERNO    VARCHAR
    --   #Column MATERNO    VARCHAR
    --   #Column RUT        VARCHAR
    --   #Column NACIMIENTO DATE
    --   #Column SUELDO     DECIMAL
    -- #EndResultSet
      SELECT E.ID            AS ID,
            E.DEPT_ID       AS DEPT_ID,
            RTRIM(E.NOMBRE) AS NOMBRE,
            RTRIM(E.PATERNO) AS PATERNO,
            RTRIM(E.MATERNO) AS MATERNO,
            E.RUT           AS RUT,
            E.NACIMIENTO    AS NACIMIENTO,
            E.SUELDO        AS SUELDO
      FROM EMPLEADOS E
      WHERE E.RUT = @RUT
END

El siguiente cuadro muestra el mismo ejemplo anterior, pero con código fuente de un procedimiento Oracle:

CREATE OR REPLACE PROCEDURE EMP$BUSCAR_POR_RUT
(
    RUT$       IN VARCHAR2,
    EMPLEADOS$ OUT SYS_REFCURSOR
)
AS
BEGIN
    -- #ResultSet EMPLEADO EMPLEADOS
    --   #Column ID         NUMBER
    --   #Column DEPT_ID    NUMBER
    --   #Column NOMBRE     VARCHAR
    --   #Column PATERNO    VARCHAR
    --   #Column MATERNO    VARCHAR
    --   #Column RUT        VARCHAR
    --   #Column NACIMIENTO DATE
    --   #Column SUELDO     NUMBER
    -- #EndResultSet
    OPEN EMPLEADOS$ FOR
        SELECT E.ID            AS ID,
               E.DEPT_ID       AS DEPT_ID,
               RTRIM(E.NOMBRE) AS NOMBRE,
               RTRIM(E.PATERNO) AS PATERNO,
               RTRIM(E.MATERNO) AS MATERNO,
               E.RUT           AS RUT,
               E.NACIMIENTO    AS NACIMIENTO,
               E.SUELDO        AS SUELDO
        FROM EMPLEADOS E
        WHERE E.RUT = RUT$;
END

Importante: los nombres de las columnas definidas con la marca “#Column” deben coincidir exactamente con los nombres de las columnas (alias) especificados en la sentencia “SELECT”.

8. Generar componente EJB y Servicio Web

La opción “Componentes JEE…” del menú “Generar” permite generar componentes EJB (Stateless Session Beans) para invocar a procedimientos almacenados desde servidores GlassFish, JBoss, WebLogic y WebSphere. Adicionalmente, puede generar un servicio web para invocar a los procedimientos mediante protocolo SOAP estándar. Al seleccionar esta opción de menú, aparece una ventana como se observa en la siguiente figura:

Las componentes EJB que genera el OBCOM SQL Wizard son de tipo sesión sin estado (Stateless Session Beans). Cada método de la clase principal del EJB (SessionBean) implementa un llamado a un procedimiento almacenado, y los argumentos de este método corresponden a los parámetros de entrada (input) del procedimiento. Los valores de salida (output) del procedimiento, así como los conjuntos de resultado (ResultSets), son retornados en una clase serializable basada en el patrón “Data Transfer Object” (DTO).

Si ocurre un error durante la ejecución del procedimiento, se dispara una excepción Java que incluye un mensaje explicativo y la excepción base (SQLException). Estas excepciones pueden ser generadas por el programador dentro de los procedimientos almacenados utilizando funciones estándar tales como “RAISE_APPLICATION_ERROR” en Oracle o “RAISERROR” en MS-SQL.

Cuando la opción “Generar usando definiciones #ResultSet contenidas en código fuente” no se selecciona, OBCOM SQL Wizard genera código que toma la data contenida en clases javax.sql.ResultSet y la almacena en otras clases que implementan las interfaces javax.sql.RowSet y javax.sql.rowset.CachedRowSet. Esto permite utilizar esta data sin necesidad de mantener una conexión abierta con la base de datos. En aquellos servidores que no posean clases que implementen estas interfaces (por ejemplo, IBM WebSphere 6.01), es necesario utilizar alguna biblioteca que provea esta funcionalidad (por ejemplo, la biblioteca gratuita JDBC Rowset Implementations 1.0.1).

9. Generar componente y Servicio Web .NET

La opción “Componentes .NET…” del menú “Generar” permite generar componentes .NET de Microsoft (Visual Basic o C-Sharp) para invocar los procedimientos almacenados seleccionados. Adicionalmente, puede generar un Servicio Web (Web Service) ASMX para invocar a los procedimientos mediante protocolo SOAP estándar. Al seleccionar esta opción de menú, aparece una ventana como se observa en la siguiente figura:

10. Generar páginas JSP

La opción “Páginas JSP…” del menú “Generar” permite generar una página JSP por cada procedimiento almacenado seleccionado. Las páginas JSP generadas por OBCOM SQL Wizard implementan servicios de tipo REST (Representational State Transfer). Al seleccionar esta opción de menú, aparece una ventana como se observa en la figura siguiente:

Una vez seleccionadas las opciones de generación, OBCOM SQL Wizard genera una página JSP con el mismo nombre del procedimiento. La página JSP obtiene los valores de los parámetros de entrada (input) del procedimiento de los parámetros GET o POST suministrados. Por ejemplo, la siguiente URL ejecuta un procedimiento llamado “GetUserData”, que tiene dos parámetros de entrada “UserID” y “FromDate”. Los valores de estos parámetros son “106035” y “2004-10-24”, respectivamente:

http://www.foo.cl/dbas/GetUserData.jsp?UserID=106035&FromDate=2004-10-24

Una vez ejecutado el procedimiento, la página JSP retorna los valores de los parámetros de salida (output), incluyendo el/los conjuntos de resultado (ResultSets) devueltos por el procedimiento. La página JSP también está preparada para atrapar y retornar cualquier error que ocurra durante la ejecución del procedimiento. Los valores de salida, los conjuntos de resultado (ResultSets), y los posibles errores se retornan siempre en formato XML.

11. Generar páginas ASP

La opción “Páginas ASP…” del menú “Generar” permite generar una página ASP de Microsoft por cada procedimiento almacenado seleccionado. Al presionar el botón de la barra de herramientas, aparece una ventana como se observa en la figura siguiente:

La modalidad “adCmdStoreProc” invoca directamente al procedimiento, en cambio la modalidad adCmdText invoca al procedimiento utilizando un comando de la forma “{?=call proc(?,?)}”. La modalidad adCmdText es más estándar, pero menos eficiente. La modalidad adCmdStoreProc es más eficiente, pero no está disponible en todas las bibliotecas OLEDB. Si está disponible, se recomienda utilizar la modalidad adCmdStoreProc.

Por cada procedimiento seleccionado, se genera una página ASP con el mismo nombre del procedimiento. La página ASP obtiene los valores de los parámetros de entrada (input) del procedimiento de los parámetros GET o POST suministrados. Por ejemplo, la siguiente URL ejecuta un procedimiento llamado “GetUserData”, que tiene dos parámetros de entrada “UserID” y “FromDate”. Los valores de estos parámetros son “106035” y “2004-10-24”, respectivamente:

http://www.foo.cl/dbas/GetUserData.asp?UserID=106035&FromDate=2004-10-24

Una vez ejecutado el procedimiento, la página ASP retorna los valores de los parámetros de salida (output), incluyendo el/los conjuntos de resultado (ResultSets) devueltos por el procedimiento. La página ASP también está preparada para atrapar y retornar cualquier error que ocurra durante la ejecución del procedimiento.

Los valores de salida, los conjuntos de resultado (ResultSets), y los posibles errores se pueden retornan en formato ADTG (binario compacto) o en formato XML. Por defecto, el formato utilizado es ADTG. Para obtener un resultado en formato XML, se debe invocar al procedimiento con un parámetro adicional de nombre “EcuFormat” con valor “XML”:

http://www.foo.cl/dbas/GetUserData.asp?EcuFormat=XML&UserID=106035&...

12. Generar clases Visual Basic 6

La opción “Visual Basic 6…” del menú “Generar” permite generar clases Visual Basic 6 de Microsoft para invocar a procedimientos almacenados. Al presionar el botón de la barra de herramientas, aparece una ventana como se observa en la siguiente figura: