ext/OGDF/ogdf/fileformats/DinoUmlToGraphConverter.h

   1 /*
   2  * $Revision: 2564 $
   3  *
   4  * last checkin:
   5  *   $Author: gutwenger $
   6  *   $Date: 2012-07-07 00:03:48 +0200 (Sa, 07. Jul 2012) $
   7  ***************************************************************/
   8
   9 /** \file
  10  * \brief Contains the class DinoUmlToGraphConverter...
  11  *
  12  * ...which performs all necessary steps to obtain a model graph
  13  * and a set of diagram graphs from the input file.
  14  *
  15  * \author Dino Ahr
  16  *
  17  * \par License:
  18  * This file is part of the Open Graph Drawing Framework (OGDF).
  19  *
  20  * \par
  21  * Copyright (C)<br>
  22  * See README.txt in the root directory of the OGDF installation for details.
  23  *
  24  * \par
  25  * This program is free software; you can redistribute it and/or
  26  * modify it under the terms of the GNU General Public License
  27  * Version 2 or 3 as published by the Free Software Foundation;
  28  * see the file LICENSE.txt included in the packaging of this file
  29  * for details.
  30  *
  31  * \par
  32  * This program is distributed in the hope that it will be useful,
  33  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  34  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  35  * GNU General Public License for more details.
  36  *
  37  * \par
  38  * You should have received a copy of the GNU General Public
  39  * License along with this program; if not, write to the Free
  40  * Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  41  * Boston, MA 02110-1301, USA.
  42  *
  43  * \see  http://www.gnu.org/copyleft/gpl.html
  44  ***************************************************************/
  45
  46 #ifdef _MSC_VER
  47 #pragma once
  48 #endif
  49
  50 #ifndef OGDF_DINO_UML_TO_GRAPH_CONVERTER_H
  51 #define OGDF_DINO_UML_TO_GRAPH_CONVERTER_H
  52
  53 #include <ogdf/fileformats/DinoXmlParser.h>
  54 #include <ogdf/fileformats/DinoUmlModelGraph.h>
  55 #include <ogdf/fileformats/DinoUmlDiagramGraph.h>
  56 #include <ogdf/basic/UMLGraph.h>
  57
  58 namespace ogdf {
  59
  60         //---------------------------------------------------------
  61         // D i n o U m l T o G r a p h C o n v e r t e r
  62         //---------------------------------------------------------
  63         /** This class performs all necessary steps to obtain a model
  64          *  graph and diagram graphs from the input file which contains
  65          *  an UML model in XML format.
  66          *  In particular the following is done:
  67          *  - Given the input file a class DinoXmlParser is created which
  68          *    accomplishes the parsing of the XML file; as result of the
  69          *    parsing procedure a parse tree representing the xml document
  70          *    is accessible.
  71          *  - The parse tree is used to extract the model graph of the contained
  72          *    uml model as well as a set of diagram graphs which are part of the
  73          *    uml model.
  74          *
  75          *  The graphs can be accessed via the functions getModelGraph() and
  76          *  getDiagramGraphs().
  77          *
  78          *  In debug mode warnings and the content of the model graph and the diagram
  79          *  graphs are written into the log file named \e umlToGraphConversionLog.txt.
  80          */
  81         class OGDF_EXPORT DinoUmlToGraphConverter {
  82
  83         private:
  84
  85                 /** The parser used for parsing the input file. */
  86                 DinoXmlParser *m_xmlParser;
  87
  88                 /** The graph which represents the complete UML model. */
  89                 DinoUmlModelGraph *m_modelGraph;
  90
  91                 /** The set of graphs which represent special diagrams
  92                  *  contained in the model.
  93                  */
  94                 SList<DinoUmlDiagramGraph*> m_diagramGraphs;
  95
  96                 /** This list contains the set of graphs of the list #m_diagramGraphs
  97                  *  in UMLGraph format. The transformation is performed in the constructor
  98                  *  #DinoUmlToGraphConverter().
  99                  */
 100                 SList<UMLGraph*> m_diagramGraphsInUMLGraphFormat;
 101
 102                 /** Predefined info indices for known tag and attribute names. */
 103                 enum PredefinedInfoIndex {
 104                         xmi = 0,
 105                         xmiContent,
 106                         xmiId,
 107                         umlModel,
 108                         umlNamespaceOwnedElement,
 109                         umlClass,
 110                         name,
 111                         umlGeneralization,
 112                         child,
 113                         parent,
 114                         umlAssociation,
 115                         umlAssociationConnection,
 116                         umlAssociationEnd,
 117                         type,
 118                         umlDiagram,
 119                         rootUmlDiagramElement,
 120                         umlDiagramElement,
 121                         geometry,
 122                         subject,
 123                         umlPackage,
 124                         umlInterface,
 125                         umlDependency,
 126                         client,
 127                         supplier,
 128                         diagramType,
 129                         classDiagram,
 130                         moduleDiagram,
 131
 132                         nextPredefinedInfoIndex
 133                 };
 134
 135                 /** Maps string info to node.
 136                  *  We need this hash table for fast access to nodes corresponding
 137                  *  to UML elements. For each UML Element in XMI format we have an
 138                  *  unique identifier via the xmi.id attribute. The xmi.id attribute
 139                  *  is saved as string in the hash table of the parser, hence we can
 140                  *  use the info index of it. While scanning for relations between nodes
 141                  *  we encounter the xmi.id attribute values of the involved elements referenced
 142                  *  as type attribute in the relation. Now we can use the hash table to
 143                  *  access the corresponding node.
 144                  */
 145                 Hashing<int,NodeElement*> m_idToNode;
 146
 147                 /** Maps string info to edge.
 148                  *  The functionality is the same as for #m_idToNode.
 149                  */
 150                 Hashing<int,EdgeElement*> m_idToEdge;
 151
 152                 /** The log file.
 153                  *  The log file is named \e umlToGraphConversionLog.txt and contains
 154                  *  warnings and errors ocurred during the conversion process. Furthermore
 155                  *  it contains the content of the model graph #m_modelGraph and of the
 156                  *  diagram graphs #m_diagramGraphs.
 157                  */
 158                 ofstream *m_logFile;
 159
 160         public:
 161
 162                 /** Constructor.
 163                  *  The constructor performs the following:
 164                  *  - A parser object of class DinoXmlParser is created and
 165                  *    the parse process is started via DinoXmlParser::createParseTree().
 166                  *  - The variable #m_modelGraph is initialized with an empty object
 167                  *    of type DinoUmlModelGraph. Then the model graph is build up with
 168                  *    createModelGraph().
 169                  *  - The list of diagram graphs #m_diagramGraphs is given to
 170                  *    createDiagramGraphs() to build them up.
 171                  *
 172                  *  @param fileName The file name of the xml file which contains the data
 173                  *                  of the uml model to be converted into the graph format.
 174                  */
 175                 DinoUmlToGraphConverter(const char *fileName);
 176
 177                 /** Destructor.
 178                  *  The destructor destroys:
 179                  *  - the diagram graphs contained in #m_diagramGraphs,
 180                  *  - the model graph contained in #m_modelGraph,
 181                  *  - the parser contained in #m_xmlParser.
 182                  */
 183                 ~DinoUmlToGraphConverter();
 184
 185                 /** Access to model graph.
 186                  *  @return A const reference to the model graph.
 187                  */
 188                 const DinoUmlModelGraph &getModelGraph() const {
 189                         return *m_modelGraph;
 190                 }
 191
 192                 /** Access to diagram graphs.
 193                  *  @return A const reference to the list of diagram graphs.
 194                  */
 195                 const SList<DinoUmlDiagramGraph*> & getDiagramGraphs () const {
 196                         return m_diagramGraphs;
 197                 }
 198
 199                 /** Access to the diagrams graphs in UMLGraph format.
 200                  *  @return A const reference to a list of diagram graphs in UMLGraph format.
 201                  */
 202                 const SList<UMLGraph*> & getDiagramGraphsInUMLGraphFormat () const {
 203                         return m_diagramGraphsInUMLGraphFormat;
 204                 }
 205
 206                 /** Prints the content of each diagram to \a os.
 207                  *  @param os The output stream where to direct the output to.
 208                  */
 209                 void printDiagramsInUMLGraphFormat(ofstream &os);
 210
 211                 /** Print hash table which maps the ids to the NodeElements.
 212                  *  @param os The output stream where to direct the output to.
 213                  */
 214                 void printIdToNodeMappingTable(ofstream &os);
 215
 216         private:
 217
 218                 /** Inserts known strings for tags and attributes into the hashtable
 219                  *  of the parser. The info elements for the hashtable are taken from
 220                  *  enum #PredefinedInfoIndex.
 221                  */
 222                 void initializePredefinedInfoIndices();
 223
 224                 /** Converts the relevant information contained in the parse tree
 225                  *  into the data structure of DinoUmlModelGraph. Error messages are
 226                  *  reported in #m_logFile.
 227                  *  @param modelGraph The model graph into which the nodes and edges
 228                  *  corresponding to uml elements and uml relations should be inserted.
 229                  *  @return Returns true if conversion was succesful, false otherwise.
 230                  */
 231                 bool createModelGraph(DinoUmlModelGraph &modelGraph);
 232
 233                 /** Traverses the package structure and identifies classifiers inside
 234                  *  the parse tree (starting at \a currentRootTag) and inserts a new node
 235                  *  for each classifier. This function will call itself recursively while
 236                  *  traversing nested packages.
 237                  *
 238                  *  Valid classifiers are currently: \c class and \c interface.
 239                  *  @param currentRootTag The tag where to start the search for classifiers.
 240                  *  @param currentPackageName This string should contain the name of the package
 241                  *  path corresponding to \a currentRootTag.
 242                  *  @param modelGraph The model graph into which nodes are inserted.
 243                  *  @return False if something went wrong, true otherwise.
 244                  */
 245                 bool traversePackagesAndInsertClassifierNodes(
 246                         const XmlTagObject &currentRootTag,
 247                         String currentPackageName,
 248                         DinoUmlModelGraph &modelGraph);
 249
 250                 /** Tries to find all classifiers of type \a desiredClassifier inside the parse
 251                  *  tree (starting at \a currentRootTag). Inserts a new node into \a modelGraph
 252                  *  for each classifier found.
 253                  *  @param currentRootTag The tag where to start the search for the desired
 254                  *  classifier.
 255                  *  @param currentPackageName This string should contain the name of the package
 256                  *  path corresponding to \a currentRootTag.
 257                  *  @param desiredClassifier The info index of the desired class
 258                  *  (see enum #PredefinedInfoIndex).
 259                  *  @param modelGraph The model graph into which nodes are inserted.
 260                  *  @return False if something went wrong, true otherwise.
 261                  */
 262                 bool insertSpecificClassifierNodes(
 263                         const XmlTagObject &currentRootTag,
 264                         String currentPackageName,
 265                         int desiredClassifier,
 266                         DinoUmlModelGraph &modelGraph);
 267
 268                 /** Traverses the package structure and identifies associations inside
 269                  *  the parse tree and inserts a new edge between the corresponding
 270                  *  nodes of the involved classifiers.
 271                  *
 272                  *  Note that it is not possible to include this function into
 273                  *  traversePackagesAndInsertClassifierNodes(). The reason is that it
 274                  *  is possible that edges are specified prior to that one or both nodes
 275                  *  have been created.
 276                  *  @param currentRootTag The tag where to start the search for associations.
 277                  *  @param modelGraph The model graph into which edges are inserted.
 278                  *  @return False if something went wrong, true otherwise.
 279                  */
 280                 bool traversePackagesAndInsertAssociationEdges(
 281                         const XmlTagObject &currentRootTag,
 282                         DinoUmlModelGraph &modelGraph);
 283
 284                 /** Traverses the package structure and identifies generalization inside
 285                  *  the parse tree and inserts a new edge between the corresponding
 286                  *  nodes of the involved classifiers.
 287                  *
 288                  *  It does not make sense to put this function and
 289                  *  traversePackagesAndInsertAssociationEdges() together since the generalization
 290                  *  tags are inside the class tags, so first the classes have to be identified
 291                  *  again in contrast to traversePackagesAndInsertAssociationEdges().
 292                  *  @param currentRootTag The tag where to start the search for generalizations.
 293                  *  @param modelGraph The model graph into which edges are inserted.
 294                  *  @return False if something went wrong, true otherwise.
 295                  */
 296                 bool traversePackagesAndInsertGeneralizationEdges(
 297                         const XmlTagObject &currentRootTag,
 298                         DinoUmlModelGraph &modelGraph);
 299
 300
 301                 /** Identifies dependency tags inside the parse tree and inserts a
 302                  *  new edge between the corresponding nodes of the involved elements.
 303                  *  @param currentRootTag The tag where to start the search for dependencies.
 304                  *  @param modelGraph The model graph into which edges are inserted.
 305                  *  @return False if something went wrong, true otherwise.
 306                  */
 307                 bool insertDependencyEdges(
 308                         const XmlTagObject &currentRootTag,
 309                         DinoUmlModelGraph &modelGraph);
 310
 311                 /** For each diagram converts the relevant information contained in the parse tree
 312                  *  into the data structure of DinoUmlDiagramGraph. Error messages are
 313                  *  reported in #m_logFile.
 314                  *  @return Returns true if conversion was succesful, false otherwise.
 315                  *  \todo Currently only class diagrams are handled. Must be extended to handle
 316                  *  other kinds of uml diagrams.
 317                  */
 318                 bool createDiagramGraphs();
 319
 320                 /** Transforms each diagram graph contained in #m_diagramGraphs into an equivalent
 321                  *  Error messages are reported in #m_logFile.
 322                  *  @param diagramGraphsInUMLGraphFormat The list of diagram graphs in UMLGraph
 323                  *  format which have been obtained from the diagram graphs.
 324                  *  @return Returns true if conversion was successful, false otherwise.
 325                  */
 326                 bool createDiagramGraphsInUMLGraphFormat(SList<UMLGraph*> &diagramGraphsInUMLGraphFormat);
 327
 328
 329         }; // class DinoUmlToGraphConverter
 330
 331
 332 } // end namespace ogdf
 333
 334 #endif