ObjectScript Class Explorer - Exploración de clases ObjectScript con la notación UML

¡Hola a tod@s!

Este artículo es una pequeña descripción general de una herramienta que permitirá entender las clases y su estructura, dentro de los productos de InterSystems: desde IRIS hasta Caché, Ensemble y HealthShare.

En resumen, con esta herramienta se visualiza una clase o un paquete completo, se muestran las relaciones que existen entre las clases y proporciona toda la información que se encuentra disponible para los desarrolladores y líderes de equipos sin necesidad examinar el código, utilizando el Studio.

Si estás aprendiendo a utilizar los productos de InterSystems,  o simplemente estás interesado en aprender algo nuevo sobre las soluciones que ofrece la tecnología de InterSystems, ¡eres más que bienvenido a leer la descripción general de ObjectScript Class Explorer!

Introducción a los productos de InterSystems

IRIS (anteriormente conocido como Caché) es una DBMS Base de Datos Multi Modelo. Es posible  acceder a los datos mediante consultas SQL o al interactuar con los objetos y procedimientos almacenados por las interfaces que están disponibles para varios lenguajes de programación. Pero la primera opción siempre es desarrollar aplicaciones en el lenguaje nativo e integrado de la DBMS— ObjectScript (COS).

Caché es compatible con las clases que se encuentran en el nivel de la DBMS. Existen dos principales tipos de clases: Persistentes (pueden almacenarse en la base de datos) y registradas (no se almacenan en la base de datos y desempeñan el papel de programas y controladores). Además, existen varios tipos de clases especiales: Serial (son clases que pueden integrarse en clases persistentes para crear tipos de datos complejos, como por ejemplo direcciones), DataType (se utiliza para crear tipos de datos definidos por el usuario), Index, View y Stream.

Class Explorer

Caché Class Explorer es una herramienta que visualiza la estructura de las clases de Caché como un diagrama, muestra las dependencias que existen entre las clases y toda la información importante, incluido el código de los métodos, consultas, bloques xData, comentarios, documentos de apoyo y palabras clave de varios elementos de las clases.

Funcionalidad

Class Explorer utiliza una versión extendida del estándar UML para la visualización, debido a que Caché cuenta con un conjunto adicional de entidades que no son compatibles con el estándar UML , pero que son importantes para Caché: consultas, bloques xData, muchas de las palabras clave para los métodos y propiedades (como por ejemplo: System, ZenMethod, Hidden, ProcedureBlock), relaciones  padre/ hijo, de uno a muchos, tipos de clase, entre otras.

Caché Class Explorer (version 1.14.3) te permitirá hacer lo siguiente:

• Visualizar la jerarquía de los paquetes, un diagrama de clases o el paquete completo,

• Editar la apariencia de un diagrama después de visualizarlo,

• Guardar la imagen actual de un diagrama de clases,

• Guardar la apariencia actual de un diagrama y recuperarla en el futuro,

• Realizar búsquedas por cualquier palabra clave que se muestre en un diagrama o árbol de clases,

• Utilizar la información sobre las herramientas para obtener todos los detalles de las clases, sus propiedades, métodos, parámetros, consultas y bloques xData,

• Visualizar el código de los métodos, consultas o bloques xData,

• Activar o desactivar la visualización de cualquiera de los elementos del diagrama, incluidos los iconos gráficos

En la siguiente imagen se puede ver cómo se visualizan las clases en Class Explorer, y así comprender mejor los conceptos mencionados  en este artículo. Como ejemplo, veamos el paquete “Cinema” del namespace “SAMPLES”:

Descripción general de las funciones

La barra lateral izquierda contiene un árbol del paquete. Situando el cursor sobre el nombre del paquete y haciendo clic en un botón que aparece en el lado derecho se podrá visualizar el paquete completo. Si se selecciona la clase en el árbol del paquete se representará junto con sus clases vinculadas.

Class Explorer puede mostrar varios tipos de dependencias entre las clases:

1. Herencia. Se muestra con una flecha de color blanco que apunta hacia la dirección de la clase que se heredó;
2. “Asociación” o relación entre las clases. Si un campo de alguna de las clases contiene una clase de otro tipo, el generador de diagramas lo mostrará como una relación de asociación;
3. Relaciones padre-hijo y de uno a muchos: contienen las reglas para mantener la integridad de los datos.

Si se sitúa el cursor sobre la relación, se resaltarán las propiedades establecidas en ella:

Se debe tener en cuenta que Class Explorer no profundizará y no creará dependencias para las clases que se encuentran fuera del paquete actual. Únicamente mostrará las clases que se encuentran en el paquete actual, y si se necesita limitar la profundidad con que Class Explorer realice búsquedas para las clases, se debe utilizar la opción “Nivel de dependencia”:

La clase en sí,  se muestra como un recuadro que se divide en seis secciones:

1. Nombre de la clase: si posiciona el cursor sobre el nombre de la clase, se podrá saber cuándo fue creada, sus modificaciones, ver los comentarios y todas las palabras clave que se asignaron a la clase. Al hacer doble clic sobre el encabezado de la clase se abrirá su documentación,

2. Parámetros de la clase: todos los parámetros están asignados por tipo, palabras clave y comentarios. Los parámetros en cursivas, al igual que cualquier otra propiedad, contienen información sobre las herramientas y pueden desplazarse,

3. Las propiedades de las clases son similares a las de los parámetros,

4. Métodos: puede hacer clic sobre cualquiera de los métodos para ver su código fuente. La sintaxis de COS se resaltará,

5. Consultas: son similares a los métodos, al hacer clic sobre ellos, se podrá ver su código fuente,

6. Bloques xData: estos bloques contienen principalmente datos de tipo XML. Al hacer clic sobre ellos se mostrará el código fuente con formato en el bloque

De manera predeterminada, cada clase se visualiza mediante una serie de iconos gráficos. El significado de cada icono puede determinarse al hacer clic en el botón Help que se encuentra en la esquina superior derecha de la pantalla. Si necesita una notación UML más o menos estricta que se muestra de forma predeterminada, así como la visualización de cualquiera de las secciones de la clase, se puede desactivar desde la sección Configuraciones.

Si un diagrama es muy grande y no resulta familiar, se puede utilizar la función para buscar diagramas rápidamente. Se resaltarán las clases que contengan cualquier parte de la palabra clave introducida. Para avanzar  a la siguiente coincidencia, se presiona Enter o se hace clic nuevamente en el botón de búsqueda:

Finalmente, después de hacer todas las ediciones en el diagrama, se eliminarán todas las relaciones innecesarias y los elementos se colocarán en las posiciones correctas para lograr la apariencia deseada, se puede guardar al hacer clic en el botón "Download" que se encuentra en la esquina inferior izquierda: 

Cuando actives el botón del pin , se guardará la posición de los elementos que se encuentren en el diagrama del conjunto (o de un paquete) de clases actual. Por ejemplo, si selecciona las clases A y B, y después guarda la visualización con el botón del pin, verá exactamente la misma visualización cuando seleccione las clases A y B nuevamente, incluso después de reiniciar el navegador o el equipo. Pero si solamente selecciona la clase A, el diseño será el predeterminado.

Instalación

Para instalar Caché Class Explorer, solamente tendrás que importar la última versión XML del paquete en cualquier namespace. Cuando se complete la importación, notarás que aparece una nueva aplicación web llamada hostname/ClassExplorer/ (la barra que se encuentra al final de la ruta, es necesaria).

Instrucciones detalladas sobre la instalación

1. Descargar el archivo con la última versión de Caché Class Explorer,

2. Descomprimir el archivo XML llamado Cache/CacheClassExplorer-vX.X.X.xml,

3. Importar el paquete en cualquier namespace mediante alguna de las siguientes formas:

   1. Simplemente arrastrando el archivo XML hacia el Studio,

   2. Utilizando el Portal de administración del sistema: Explorador del sistema -> Clases -> Importar, y especifique la ruta hacia el archivo local,

   3. Utilizando el comando del terminal: do ##class(%Installer.Installer).InstallFromCommandLine(“Path/Installer.cls.xml”),

4. Consultar el registro de importación, si todo se realizó correctamente, se podrá abrir la aplicación web en http://hostname/ClassExplorer/. Si algo salió mal, revisar lo siguiente:

   1. Si se tienen los permisos correctos para importar clases hacia este namespace,

   2. Si el usuario de la aplicación web tiene suficientes privilegios para acceder a diferentes namespaces,

   3. Si aparece el error 404, comprobar si agregó una "/" barra al final de la URL.

Algunas capturas de pantalla adicionales

[Captura de pantalla 1] Paquete DSVRDemo, desplazamiento del cursor sobre el nombre de la clase.

[Captura de pantalla 2] Paquete DataMining, búsqueda de la palabra clave "TreeInput" en el diagrama.

[Captura de pantalla 3] Visualización del código del método en la clase JavaDemo.JavaListSample.

[Captura de pantalla 4] Visualización del contenido del bloque XData en la clase ClassExplorer.Router.

Probad cómo funciona Class Explorer en el namespace estándar SAMPLES: demostración. Y aquí se muestra una evaluación en video del proyecto.

Cualquier observación, sugerencia o comentario es bienvenido; podéis dejarlo aquí o en la sección Repositorio de GitHub.

¡Espero que os resulte útil!