ABLaUML is an Thomas Mercer-Hursh (thomas@cintegrity.com) ABL2UML (http://www.oehive.org/ABL2UML) derivative work.
We use ABLaUML to model legacy procedural systems. In order to do that we take the original code and convert it to object oriented code, changing the monolitic generation model into a model of discret succesive generation tasks.
We added xml file generation based on database content. This xml files are then used to build the UML model. We fill the database with information taken from an XREF compilation, due to that we call the database 'xrefsrc'.
In our case we are generation three xml files:
- for .p and .i, their relations and db access
- for .p notes
- for .p aliases
The generation of the data model (database structure) is made with an xml file too. This xml file (or files) contains the database structure definition.
UML repository manipulation logic was segregated from the generation logic, using an interface, wich allows the use of the same processing logic to build a repository for a different tool (other than Enterprise Architect - in theory).
So, the logic gets split in three layers:
- xml generation
- xml processing for UML generation
- uml repository manipulation
The full generation process is also divided in three basic steps:
- Information gathering and xrefsrc db filling
- xml generation based on xrefsrc data and databases structure
- xml processing and uml repository generation
This last step (UML generation) is splitted in several discrete steps, each of wich is implemented by a worker class. Each worker class is responsable for a piece, as smaller as possible, of the generation process. We use the following worker classes:
- Packages and components creation, to represent .p and .i
- Relations between components and packages (.p, .i)
- Packages moving, to locate child packages inside their parent
- Notes for components and packages
- Alias for components and packages
- Package diagram creation
- Diagram relations hidding
- Full data model building
- Data model cleaning, by eliminating non referenced tables
- Data model filling
There are depencies between workers, but that is no problem for the execution of any of them in any order, it will just affect the resulting UML.
An advantage of the new model is the capability of doing incremental builds.
To execute the UML generation process, an UMLBuilder object is needed. It get passed a list of worker classes to instantiate, and the xml file that each worker has to process. The UMLBuilder class uses IXMLParser (XMLParser), IUtils (EAUtils) and a StMapper object. The UMLBuilder object, instantiates each worker class (in the specified order), assigns it to the IXMLParser and process the xml file, then the worker generates the UML using IUtils (EAUtils) object.
Worker classes are a hierarchy that has a number of entry points (IWorker interface) that gets invoked through the xml processing. Each worker class expects a specific xml structure and makes a particular UML repository manipulation. XMLParser reads an xml file (using SAX) and invokes the appropied associated worker method. EAUtils implements all the Enterprise Architect UML repository generation, and manipulation, logic (most of this codes is taken from ABL2UML).
To generate xml files, XMLWriter derived classes are used. XMLWriter is a generic xml writing class. Each xml file to be generated, requires a class to generate it. In our case these classes are:
- XRefwriter
- Aliaswriter
- Notaswriter
- DDictwriter
UML generation uses fixed stereotypes for each model element, to be able to change the stereotypes of the UML model, an stereotype mapper is provided (StMapper). Care has to be taken when mapping stereotypes because they are used internally to identify model elements, this implies that if an internal stereotype is mapped to another internal stereotype, the ability to distinguish between this two elements is lost.
NOTES:
- so far we haven't found UML repository xref table use, and many times this table is the cause of a Repository to EAP transfer failure. Emptying this table usually solves the transfer problem, without negative effects on the model (we have seen no change in the model, whether this table has data or not).
- Enterprise Architect versions 7.5 and 8.0 have problems with connectors notes. They usually gets lost when transfering an EAP to a Repository (Repository to EAP has no problems with notes), this is not a constant problem.
ABLaUML es un trabajo derivado de ABL2UML (http://www.oehive.org/ABL2UML) de Thomas Mercer-Hursh (thomas@cintegrity.com).
Lo que se hizo fue tomar ABL2UML y utilizarlo para modelar sistemas procedimentales heredados. Para ello se modificó el código original convirtiéndolo a código orientado a objetos, cambiando el modelo de generación monolítico en uno de generación en etapas discretas secuenciales.
Se agregó la generación del xml que alimenta la generación, a partir de la información contenida en una base de datos. Como en nuestro caso tomamos toda la información de generación a partir de una compilacíón XREF, la base de datos la hemos llamdos xrefsrc. A partir de la información de la base de datos se generan uno o más archivos xml, que serán utilizados, posteriormente, para la generación del UML.
En nuestro caso generamos tres archivos xml:
- para los .p y .i, sus relaciones y acceso a bd
- para las notas de los .p
- para los alias de los .p
Para la generación del UML del modelo de datos (de las bases de datos), se comienza también por la generación de uno o más archivos xml con la estructura de las bases de datos. Luego se utilizan estos archivos para la generación del UML correspondiente.
Se separó la lógica de procesamiento, del manejo del repositorio, utilizando una interfaz, lo que posibilitaría el uso del mismo proceso de generación de UML para la generación en otra herramienta de modelado (en teoría).
De esta forma, la lógica queda separada en tres capas:
- Generación de xml
- Procesamiento del xml para generar UML
- Manipulación del repositorio
El proceso completo de generación del UML queda dividido en tres etapas básicas:
- Recopilación de información y llenado de base de datos xrefsrc
- Generación de xml a partir de xrefsrc y de la estructura de las bases de datos
- Procesamiento del xml y generación del repositorio UML
La última etapa (generación del UML) quedará dividida en múltiples etapas discretas, cada una implementada por una clase trabajadora (Worker). Cada clase trabajadora se encarga de una parte, lo más pequeña posible, del proceso de generación. Por ejemplo, nosotros utilizamos las siguientes clases:
- Para la creación de paquetes y componentes que representan los .p e .i
- Para relacionar los .p e .i entre si
- Para mover los paquetes dentro de otro paquete cuando hay una relación padre-hijo
- Para establecer las notas de los componentes y paquetes
- Para establecer los alias de los componentes y paquetes
- Para crear el diagrama de cada paquete
- Para eliminar las relaciones que no pertenecen al diagrama, en cada diagrama
- Para construir el modelo de datos completo
- Para eliminar del modelo de datos, las tablas que no tienen ninguna relación
- Para completar el modelo de datos
Como puede verse, hay dependencias entre las clases, pero ello no impide que cualquiera de ellas pueda ejecutarse en cualquier orden, independientemente de las demás (lo cual, sin duda, afecta el UML resultante).
Una ventaja del nuevo modelo es que permite la generación incremental del UML.
Para la ejecución de la etapa de generación del UML, se utiliza un objeto UMLBuilder, al que se la pasa una lista de nombres de clases trabajadoras a ejecutar, y el nombre del xml que éstas deben procesar. Esta clase utiliza objetos IXMLParser (XMLParser), IUtils (EAUtils) y un StMapper. El UMLBuilder instancia un objeto de cada clase trabajadora (en el orden especificado), lo asigna al IXMLParser y se procesa el xml, de forma que el objeto trabajador genere el UML utilizando IUtils (EAUtils).
Las clases trabajadoras son una jerarquía de clases que contienen un conjunto de puntos de entrada (interfaz IWorker) que se invocan a medida que se procesa un xml. Cada una de estas clases espera una estructura específica de xml y realiza una manipulación particular del repositorio UML. XMLParser lee un archivo xml (utilizando SAX) y va invocando el método apropiado del trabajador asociado. EAUtils implementa toda la lógica específica de Enterprise Architect para la generación y manipulación del repositorio UML (la mayor parte del código corresponde al código de ABL2UML).
Para la generación de los archivos xml se utilizan clases derivadas de XMLWriter, la cual es una clase genérica de generación de xml. Cada archivo xml que debe generarse requiere una clase que lo genere. En este caso pueden verse las clases:
- XRefwriter
- Aliaswriter
- Notaswriter
- DDictwriter
La generación del UML utiliza estereotipos fijos para cada elemento del modelo, por lo cual se provee de un mapeador de estereotipos (StMapper), que permite utilizar cualquier estereotipo, en lugar de los utilizados internamente. Hay que tener cuidado cuando se mapean estereotipos, ya que éstos se utilizan para diferenciar los elementos del modelo, lo que implica que si se mapea un estereotipo interno a otro estereotipo interno, se pierde la capacidad de distinguir entre estos dos tipos de elementos.
NOTAS:
- al día de hoy no hemos encontrado uso a la tabla xref del repositorio UML, y muchas veces la transferencia del repositorio a archivo EAP falla a causa de esta tabla. Vaciar la tabla soluciona el problema (en la mayoría de los casos), sin efectos adversos sobre el modelo.
- La versión 7.5 y 8.0 tienen un problema con las notas de los conectores, que hace que se pierdan al transferir un EAP al repositorio (la transferencia inversa funciona bien), este problema no es constante, algunas veces lo hace bien y otra mal.
English version
Se utilizan dos bases de datos (por lo menos), la base para los datos respecto del código ABL (xrefsrc) y la base para el repositorio UML (Repository).
Como archivos adjuntos se encuentra el archivo de definición de xrefsrc, la base del repositorio es un tema aparte (bastante complicado) que puede verse en la información de ABL2UML.
Para la base de repositorio, si se utiliza la estructura original provista, es necesario cambiar el tipo de FIXCHAR a CHARACTER para algunos campos en
algunas tablas. Dado que el asunto de la base de repositorio UML ya está detallado en el proyecto ABL2UML no se profundizará aquí.
La base xrefsrc tiene dos tablas:
- xrfdat
- xrfprg
xrfdat contiene el detalle de las relaciones entre componentes de código, es decir las inclusiones, invocaciones y acceso a datos. xrfprg contiene información que permite saber cuándo un componente (.p) es considerado una unidad funcional en sí mismo (el componente "inicial" de la unidad funcional correspondiente) o parte de una unidad funcional, y dos descripciones del componente que se utilizarán para generar las notas y los alias.
Adicionalmente a las anteriores, en nuestro caso utilizamos una tercer base de datos con la información de la estructura de menú (mapsissrc), se provee la estructura de tabla utilizada, para poder ejecutar el código provisto.
También se adjunta la definición sql modificada para el repositorio y el sql de creación de las secuencias necesarias (también en el repositorio).
En los archivos adjuntos se encuentran los datos correspondientes a las tablas de la base de datos xrefsrc, los xml generados a partir de estos datos y la exportación a EAP de cada etapa de la generación.
Two databases are used (at least), one for ABL code information (xrefsrc) and the UML repository database (Repository).
Attached are the xrefsrc database tables definitions, repository sql definition (modified) and sql sequences creation (for repository db). Repository database creation is somehow complicated, and out of scope, you can see details in ABL2UML.
If you use the original repository structure (ABL2UML or Sparx provided) you will need to change some fields type, or the code will fail (fixchar type unaccesible to ABL code).
xrefsrc database has two tables:
- xrfdat
- xrfprg
xrfdat holds relationship details between code components, this is include, run and data access information. xrfprg holds the information that lets you know when a component (.p) is a functional unit (actually the initial program of the functional unit) or part of another funcional unit, and two descriptions (optionals) that are used to generate notes and alias info.
We have also used a third database for storing menu structure information (mapsissrc), the structure is provided so distributed code can be run without modifications.
ejecutar ns_startup.p, luego de modificarlo
procesar XREF
correr ns_startup.p y generar xml
ejecutar ns_startup.p
Generalmente es más saludable una construcción incremental.
transferencia a EAP para poder trabajar
The attached files includes xrefsrc database tables data, xml files generated with this data and the EAP transfer of the generated UML (one for each generation step).