generación automática de documentación a través de un archivo xml
TRANSCRIPT
Generación Automática de Documentación
Página 0
GENERACIÓN AUTOMÁTICA DE
DOCUMENTACIÓN A TRAVÉS DE
UN ARCHIVO XML
Mikel Belausteguigoitia
Oihane Crucelaegui
Maialen Magalhaes
Imanol Vellón
Generación Automática de Documentación
Índice
Página 1
Índice
1 Introducción ....................................................................................................... 2
2 Objetivo ............................................................................................................. 4
3 Lenguaje de Modelado UML ............................................................................. 5
4 Metodología de Trabajo ..................................................................................... 7
5 Formato de la Documentación ........................................................................... 8
5.1 Lista de Componentes Hardware ................................................................ 8
5.2 Lista de la Arquitectura Hardware de los Nodos ........................................ 8
5.2.1 Nodo Procesador ........................................................................................ 8
5.2.2 Nodos Entrada/Salida ............................................................................... 10
5.2.3 Segmentos de Bus ..................................................................................... 12
6 Implementación ............................................................................................... 14
7 Resultados Obtenidos ...................................................................................... 18
8 Conclusiones .................................................................................................... 19
Generación Automática de Documentación
Grupo 2
Página 2
1 Introducción
En el proceso de diseño de sistemas de control industrial no solo se deben tener en
cuenta las especificaciones funcionales, qué hace el sistema, sino también las no funcionales,
cómo lo hace y qué restricciones existen.
Cuando se diseña un sistema de control una de las mayores dificultades es
precisamente definir correctamente las especificaciones en todos los niveles, conocer las
restricciones y gestionar la relación entre ellas. Como solución a este problema, cuya
complejidad se deriva principalmente del tamaño del sistema, surge la idea de realizar el
diseño basado en modelos.
Lo que se hace es definir distintos puntos de vista, llamados dominios: dominio
funcional, dominio de la arquitectura software y dominio de la arquitectura hardware. Una vez
definidos los dominios se realiza un modelo1 del sistema para cada dominio, para lo cual se
define un lenguaje o metamodelo2 especifico de cada dominio.
El modelo completo del sistema está compuesto por el modelo de cada dominio más
las relaciones entre los dominios.
En este proyecto se ha realizado el modelado de un sistema de control a través de los
modelos funcional, hardware y software.
El diseño basado en modelos además de ayudar en la gestión de la complejidad en el
diseño de un sistema conlleva otras ventajas entre las que destacan la trazabilidad de los
requisitos y la generación de código.
1Modelo: representación parcial o simplificada de la realidad que recoge aquellos aspectos de relevancia
para las intenciones del modelador, y de la que se pretende extraer conclusiones de tipo predictivo. Se
modela para comprender mejor o explicar mejor un proceso o unas observaciones. Un mismo objeto
puede ser modelado con distintas técnicas y distintas intenciones, de forma que cada modelo resalta sólo
ciertos aspectos del objeto.
2Metamodelado: es el análisis, construcción y desarrollo de los marcos, las reglas, las limitaciones, los
modelos y teorías aplicables y útiles para el modelado de una clase predefinida de los problemas.
Generación Automática de Documentación
Grupo 2
Página 3
El objetivo de este proyecto es la generación automática de documentación a partir de
un modelo. Esto es posible porque un modelo realizado en UML puede ser exportado a un
fichero de texto en XML y se ha definido el estándar XMI (XML Metada Interchange) que
especifica la forma en la que es posible intercambiar modelos UML entre distintas
herramientas de modelado. En definitiva, el objetivo es extraer la información referente al
modelo contenido en el XMI y generar la documentación requerida.
Generación Automática de Documentación
Grupo 2
Página 4
2 Objetivo
El objetivo del presente proyecto es generar de forma automática la documentación de
la Estación 1- Ubicación Base. Concretamente, se trata de generar la siguiente
documentación:
• La lista general de componentes hardware por la que está compuesta la
estación.
• La lista de la arquitectura hardware de los nodos, distinguiendo entre:
� Nodo Procesador.
� Nodos Entrada/Salida.
� Segmentos de bus.
Para la consecución de dicho objetivo, vamos a partir del modelo de la Estación 1, que
se ha realizado con el lenguaje de modelado UML.
Generación Automática de Documentación
Grupo 2
Página 5
3 Lenguaje de Modelado UML
Tal y como se ha comentado en el punto 2, objetivo del proyecto, tenemos que partir
del modelo de la Estación 1. Para ello, vamos a utilizar el lenguaje de modelado UML.
El Lenguaje Unificado de Modelado (UML) es un lenguaje gráfico para visualizar,
especificar, construir y documentar un sistema. Es decir, es un lenguaje de modelado que
permite la representación conceptual y física de un sistema.
Hay que resaltar que UML es un "lenguaje de modelado" para especificar o para
describir métodos o procesos. Se utiliza para definir un sistema, para detallar los artefactos en
el sistema y para documentar y construir. En otras palabras, es el lenguaje en el que está
descrito el modelo.
UML cuenta con varios tipos de diagramas, los cuales muestran diferentes aspectos de
las entidades representadas. En nuestro caso, los más importantes son los siguientes.
• Diagrama de clases: es un tipo de diagrama estático que describe la estructura del
sistema mostrando sus clases, atributos y las relaciones entre ellos. Se utilizan durante
el proceso de diseño, donde se crea el diseño conceptual de la información que se
manejará en el sistema, y los componentes que se encargaran del funcionamiento y la
relación entre uno y otro.
• Diagrama de componentes: representa cómo un sistema de software es dividido en
componentes y muestra las dependencias entre estos componentes. Pueden ser usados
para modelar y documentar cualquier arquitectura de sistema.
• Diagramas de objetos: se puede considerar un caso especial de un diagrama de clases
en el que se muestran instancias específicas de clases (objetos) en un momento
particular del sistema. Los diagramas de objetos utilizan un subconjunto de los
elementos de un diagrama de clase. Los diagramas de objetos no muestran la
multiplicidad ni los roles, aunque su notación es similar a los diagramas de clase.
• Diagrama de Despliegue: es un tipo de diagrama que se utiliza para modelar el
hardware utilizado en las implementaciones de sistemas y las relaciones entre sus
componentes. Los elementos usados por este tipo de diagrama son nodos,
componentes y asociaciones.
Generación Automática de Documentación
Grupo 2
Página 6
Es indudable que el modelo de la estación va a contener particularidades que ningún
lenguaje, va a poder describirlas todos a la vez. Es por esto que parte de la especificación del
UML se dedica a definir mecanismos de extensión con miras a incrementar el campo de
aplicación del lenguaje. El mecanismo de extensión, que hemos utilizado nosotros, es el
llamado estereotipo; Un estereotipo representa una distinción de uso. Se trata de pequeñas
etiquetas que aplicadas a los elementos o relaciones de un diagrama indican significado
adicional.
Una vez que tenemos el modelo completo estereotipado de la Estación 1, generamos el
archivo XML que es el documento de base sobre el que realizaremos la búsqueda de
información. Notar que es posible ampliar el modelo de la estación, pero gracias a la ventaja
de que XML es extensible, solo hay que extenderlo con la adicción de nuevas etiquetas, de
modo que se puede continuar utilizando sin mayor complicación.
A continuación se muestra un ejemplo para ver la estructura del documento XML generado:
<nestedNode xmi:type="uml:Device" xmi:id="Ue9cfb082-bc42-4930-b20d-a41fe088a3de" xmi:uuid="e9cfb082-bc42-4930-b20d-a41fe088a3de" name="S1_PowerSupply">
<xmi:Extension extender="UModel"> <appliedStereotype xmi:type="uml:StereotypeApplication" xmi:id="U04213ff2-6f9b-40ad-8f3a-ae2bbffa7bc8" xmi:uuid="04213ff2-6f9b-40ad-8f3a-ae2bbffa7bc8" visibility="unspecified" classifier="U44640d98-4882-42fd-8bf5-47ab398ee58d"> <slot xmi:type="uml:Slot" xmi:id="U3c8c722f-6f28-4c54-a0ee-ab65a5c9ecca" xmi:uuid="3c8c722f-6f28-4c54-a0ee-ab65a5c9ecca" definingFeature="U00c24948-68a6-4ba2-9f1c-17628f21de84"> <value xmi:type="uml:LiteralString" xmi:id="U7a4620ea-a7fc-4f5c-b13b-ad93a052d2bf" xmi:uuid="7a4620ea-a7fc-4f5c-b13b-ad93a052d2bf" value="S1_PowerSupply"/>
El motivo de usar la tecnología XML es porque expresa la información de forma
estructurada, esto es, la información se compone de partes bien definidas, y esas partes se
componen a su vez de otras partes. . Entonces se tiene un árbol de trozos de información.
Estas partes se denominan elementos, y se las señala mediante etiquetas. Los elementos XML
pueden tener contenido, o bien ser elementos vacíos. A su vez, los elementos pueden tener
atributos, que son una manera de incorporar características o propiedades a dichos elementos.
Por otra parte, los documentos XML sólo permiten un elemento raíz del que todos los demás
sean parte, es decir, solo pueden tener un elemento inicial.
En base a esta estructura, construiremos un algoritmo iterativo que recorra el
documento XML para encontrar la información que nos interesa y mostrarla por pantalla.
Generación Automática de Documentación
Grupo 2
Página 7
4 Metodología de Trabajo
El proceso de trabajo que seguimos, consta de las siguientes etapas:
- Modelado de la Estación 1.
- Generación de código XML a partir del modelo creado.
- Construcción de un algoritmo iterativo que nos proporcione la información que
requerimos para generar la documentación.
- Por último, generación de un archivo para presentar la información filtrada.
Generación Automática de Documentación
Grupo 2
Página 8
5 Formato de la Documentación
A continuación se muestra el formato que queremos generar para documentar la
información. El objetivo es resumir toda la información disponible en una tabla que refleje y
resuma dicha información, para que en un solo vistazo nos hagamos una idea de la
composición Hardware de la Estación 1.
5.1 Lista de Componentes Hardware
Esta lista refleja todos los dispositivos que contiene el modelo de la estación, los
cuales se resumen a continuación:
Unit Description Serial Number
3 Fuente de Alimentación S1_PS
1 Procesador S1_P
5 Digital Input S1_DI
5 Digital Output S1_DO
3 Enlace Ethernet S1_ETHERNET
5.2 Lista de la Arquitectura Hardware de los Nodos
El objetivo de esta lista es obtener las características principales tales como nombre,
número de serie, posición y descripción de todos los dispositivos que componen cada nodo. A
su vez, también vamos a obtener una tabla resumen que nos va a indicar los nodos que une el
segmento de bus.
5.2.1 Nodo Procesador
El Autómata programable de la estación 1 (S1_PLC) es nuestro Nodo Procesador,
que va estar compuesto por los siguientes dispositivos (ver figura nº1):
- Un procesador
- Una fuente de alimentación
- Cuatro tarjetas de Entradas/Salidas
- Una tarjeta Ethernet
Generación Automática de Documentación
Grupo 2
Página 9
La documentación que habría que generar, tendría el siguiente aspecto:
Name Serial Number Position Description
Power Supply S1_PowerSupply S1_PS 1 Fuente de
Alimentación
Proccesor S1_P 2222 2 Procesador
IO Board
S1_DI_1 S1_DI 3 Digital Input
S1_DI_2 S1_DI 4 Digital Input
S1_DO_1 S1_DO 5 Digital Output
S1_DO_2 S1_DO 6 Digital Output
Communication
Board S1_ETHERNET S1_ETHERNET 7 Enlace Ethernet
Figura Nº1. Nodo Procesador (S1_PLC) de la estación 1- Ubicación Base.
Generación Automática de Documentación
Grupo 2
Página 10
5.2.2 Nodos Entrada/Salida
Se trata de los nodos que hemos denominado Esclavo_profibus_1 y
Esclavo_profibus_2. La característica que hace que se diferencien del nodo procesador, es
que no disponen del dispositivo procesador. A continuación, se enumeran los dispositivos que
los componen:
- Una fuente de alimentación
- Una tarjeta Ethernet
- Cuatro tarjetas de Entradas/Salidas para el Esclavo_Profibus_1 (ver figura nº3)
- Dos tarjetas de Entradas/Salidas para el Esclavo_Profibus_2 (ver figura nº4)
Figura Nº2. Nodo Esclavo_Profibus_1 de la estación 1- Ubicación Base.
Generación Automática de Documentación
Grupo 2
Página 11
La tabla resumen que contiene la información de dichos nodos, se presenta a
continuación:
• Esclavo_Profibus_1
Name Serial Number Position Description
Power Supply S1_PowerSupply S1_PS 1 Fuente de
Alimentación
IO Board
S1_DI_1 S1_DI 3 Digital Input
S1_DI_2 S1_DI 4 Digital Input
S1_DO_1 S1_DO 5 Digital Output
S1_DO_2 S1_DO 6 Digital Output
Communication
Board S1_ETHERNET S1_ETHERNET 7 Enlace Ethernet
Figura Nº3. Nodo Esclavo_Profibus_2 de la estación 1- Ubicación Base.
Generación Automática de Documentación
Grupo 2
Página 12
• Esclavo_Profibus_2
Name Serial Number Position Description
Power Supply S1_PowerSupply S1_PS 1 Fuente de
Alimentación
IO Board
S1_DI_1 S1_DI 3 Digital Input
S1_DO_1 S1_DO 5 Digital Output
Communication
Board S1_ETHERNET S1_ETHERNET 7 Enlace Ethernet
5.2.3 Segmentos de Bus
Es el elemento que realiza la conexión entre los nodos que hemos generado. Para
obtener información de este elemento y poder generar la documentación, partimos de las
asociaciones que hemos creado para unir dichos nodos (ver figura nº4).
Figura Nº4. Bus Profibus_DP1.
Generación Automática de Documentación
Grupo 2
Página 13
La información resumida queda de la siguiente manera:
Node Serial Number
S1_PLC Processing Node
Esclavo_Profibus_1 IO Node
Esclavo_Profibus_2 IO Node
Generación Automática de Documentación
Grupo 2
Página 14
6 Implementación
A continuación, se explica el algoritmo implementado para obtener la tabla de los
componentes Hardware. Para generar el resto de documentación se reutilizara la mayor parte
del código, indicando puntualmente las diferencias encontradas.
El primer paso, consiste en decirle al programa donde se encuentra el fichero .xmi,
para ello utilizamos la instrucción Load y le indicamos el path donde se encuentra el fichero.
A continuación, nos situamos en el elemento raíz del documento .xmi (NodoRaíz) y
generamos MiLista, que contiene los nestedNode.
MiXml->Load("..\\docxmi\\Celula 1_v1.xmi"); XmlElement^ NodoRaiz = MiXml->DocumentElement XmlNodeList^ MiLista = NodoRaiz->GetElementsByTagName("nestedNode");
El siguiente paso, es hallar los identificadores serialNumber y description, que genera
el .xmi que por defecto se asocia al perfil que hemos aplicado en el modelo de la Estación.
Para lograr dicho objetivo se crea MiLista2, que contiene los ownedAttribute y MiLista3, que
contiene los packagedElement y se recorren ambas listas para guardar en SerialId y el
descrptionId.
//Para hallar el identificador del SerialNumber XmlNodeList^ MiLista2 = NodoRaiz->GetElementsByTagName("ownedAttribute");
for(int i = 0; i<MiLista2->Count; i++) {if(((XmlElement^)MiLista2[i])->GetAttribute("name")->Equals("serialNumber"))
{SerialId = ((XmlElement^)MiLista2[i])->GetAttribute("xmi:id");} } //Para hallar el identificador de Description
XmlNodeList^ MiLista3 = NodoRaiz->GetElementsByTagName("packagedElement"); for(int i = 0; i<MiLista3->Count; i++)
{if(((XmlElement^)MiLista3[i])->GetAttribute("name")->Equals("GenericComponent"))
{lista_gc->Add(MiLista3[i]); XmlNodeList^ lista_gc1 = lista_gc[0]->ChildNodes; for(int j = 0; j<lista_gc1->Count; j++) {if(((XmlElement^)lista_gc1[j])->GetAttribute("name")->Equals("description")) {descriptionId = ((XmlElement^)lista_gc1[j])->GetAttribute("xmi:id");}}}}
Generación Automática de Documentación
Grupo 2
Página 15
A continuación, se genera una lista de dispositivos, lista_device, a partir de MiLista
que contiene todos los dispositivos que cuelgan de los nodos.
for(int i = 0; i<MiLista->Count; i++) { if(((XmlElement^)MiLista[i])->GetAttribute("xmi:type")->Equals("uml:Device")) { lista_device->Add(MiLista[i]); Prueba = ((XmlElement^)lista_device[0])->GetAttribute("name");}}
En las siguientes líneas, se muestra la creación de la lista_slot, que contiene los
atributos de los dispositivos. Se identifican los slots del serialNumber y description y se
guardan dichos valores en serial_value y en description. También se comprueban aquellos
dispositivos que tienen el mismo serialNumber, para realizar su suma.
for (int j=0; j<lista_device->Count; j++) { XmlNodeList^ lista_slot = lista_device[j]->ChildNodes[0]->ChildNodes[0]->ChildNodes; for(int i=0; i<lista_slot->Count; i++) { if(((XmlElement^)lista_slot[i])->GetAttribute("definingFeature")==SerialId) {for(int k=0; k<a; k++) { if(serial_value[k]==((XmlElement^)((XmlElement^)lista_slot[i])->ChildNodes[0])->GetAttribute("value")) { contador[k]++; salto=1;}} if (salto==0){ serial_value[a] = ((XmlElement^)((XmlElement^)lista_slot[i])->ChildNodes[0])->GetAttribute("value"); for(int l=0; l<lista_slot->Count; l++) {if(((XmlElement^)lista_slot[l])->GetAttribute("definingFeature")==descriptionId) {description[a] = ((XmlElement^)((XmlElement^)lista_slot[l])->ChildNodes[0])->GetAttribute("value"); }} contador[a]++; a++;} else salto=0;}}}
Generación Automática de Documentación
Grupo 2
Página 16
Por último, se muestra por pantalla, los resultados obtenidos.
if (myfile.is_open()) { myfile<<"<table border=1>\n"; myfile<<"<tr><th>Unit</th>"; myfile<<"<th>Description</th>"; myfile<<"<th>Serial Number</th></tr>\n"; for(int fil = 0; fil<devices_max; fil++) { myfile<<"<tr><td align=center>"; myfile<<devDoc[fil].contador; myfile<<"</td><td align=center>"; myfile<<devDoc[fil].Description; myfile<<"</td><td align=center>"; myfile<<devDoc[fil].Serial_ID; myfile<<"</td></tr>\n"; } myfile<<"</table>"; myfile.close(); }
Para obtener la tabla de la arquitectura Hardware de los Nodos, la primera apreciación
que hay que tener en cuenta, es la de poder diferenciar entre Nodo Procesador y Nodo
Entrada/Salida. Debido a la imposibilidad de realizar esta distinción y con objeto de poder
generar la documentación de acuerdo a los requisitos demandados, optamos por declarar el
atributo serialNumber del estereotipo aplicado Nodo (ver figura nº 4). De esta manera,
tenemos nuestro punto de partida para distinguir ambos nodos.
for(int i = 0; i<lista_nodos->Count; i++) { for(int j = 0; j<lista_nodos[i]->ChildNodes->Count; j++) {if(lista_nodos[i]->ChildNodes[j]->HasChildNodes) {AppliedStereotypeSlots = ((XmlElement^)lista_nodos[i]->ChildNodes[j]->ChildNodes[0])->GetElementsByTagName("slot"); for(int k = 0; k<AppliedStereotypeSlots->Count; k++) {if(((XmlElement^)AppliedStereotypeSlots[k])->GetAttribute("definingFeature")->Equals(SerialId)) {if(((XmlElement^)((XmlElement^)AppliedStereotypeSlots[k])->ChildNodes[0])->GetAttribute("value")->Equals("Processing Node")) {lista_nodos_procesador->Add(lista_nodos[i]); }
if(((XmlElement^)((XmlElement^)AppliedStereotypeSlots[k])->ChildNodes[0])->GetAttribute("value")->Equals("IO Node")) {lista_nodos_IO->Add(lista_nodos[i]); }}}}}}
Generación Automática de Documentación
Grupo 2
Página 17
Con el propósito de identificar a que nodo corresponde cada dispositivo, se añaden los
dispositivos como elementos nuevos creados directamente a partir del nodo en cuestión (ver
figura nº 5).
En este caso, necesitamos hallar la lista de los identificadores (classifier) Processor,
PowerSupply, IOBoard y CommunicationBoard. Dichos identificadores se almacenaran en las
variables ProccesorClassifier, PowSupplyClassifier, IOBoardClassifier y
ComBoardClassifier respectivamente, que utilizaremos para conocer qué tipo de dispositivo
cuelga de cada nodo.
for(int i = 0; i<lista_classifiers->Count; i++) {if(((XmlElement^)lista_classifiers[i])->GetAttribute("name")->Equals("Processor")) {ProcessorClassifier = ((XmlElement^)lista_classifiers[i])->GetAttribute("xmi:id");} if(((XmlElement^)lista_classifiers[i])->GetAttribute("name")->Equals("PowerSupply")) {PowSupplyClassifier = ((XmlElement^)lista_classifiers[i])->GetAttribute("xmi:id");} if(((XmlElement^)lista_classifiers[i])->GetAttribute("name")->Equals("IOBoard")) {IOBoardClassifier = ((XmlElement^)lista_classifiers[i])->GetAttribute("xmi:id");} if(((XmlElement^)lista_classifiers[i])->GetAttribute("name")->Equals("CommunicationBoard")) {ComBoardClassifier = ((XmlElement^)lista_classifiers[i])->GetAttribute("xmi:id");}}
Una vez conocido el tipo de dispositivo que es, se obtienen los valores de los atributos
que tiene definido. Y por último, al igual que el caso anterior, se muestra por pantalla la tabla
generada.
//El codigo es similar al caso de la lista de los dispositivos
Figura Nº5. Ventana Model Tree del programa Altova U-Model
Generación Automática de Documentación
Grupo 2
Página 18
7 Resultados Obtenidos
Las siguientes imágenes, muestran el contenido de la documentación generada.
Figura Nº6. Tabla de Componentes Hardware.
Figura Nº7. Tabla de Arquitectura Hardware de los Nodos.
Generación Automática de Documentación
Grupo 2
Página 19
8 Conclusiones
El algoritmo que hemos generado nos permitiría obtener de forma automática la
documentación de cualquier estación que se modele, siempre y cuando se apliquen los
mismos perfiles que se han utilizado a la hora de modelar esta estación. Por lo tanto, la mayor
ventaja que nos proporciona este código es la posibilidad de reutilización que nos brinda.
Esto se debe gracias al lenguaje de esquema que utiliza XML, donde la estructura y las
restricciones de los contenidos de los documentos se describen de una forma muy precisa.
Otra característica importante es que se trata de un código robusto y confiable,
entendiendo como tal, aquel código donde se minimizan los errores de compilación.