^Overview

This document provides build directions and a high-level architecture for the DB-UML Modeling Tool. The architecture requirements, overview and package structure are defined. The architecture is not complete and several sections need to be added. In particular the sections on Transformers need be completed.

^{Building DB-UML}

To build DB-UML you must be able to build ArgoUML first. For directions on building ArgoUML, see:

http://argouml-stats.tigris.org/documentation/defaulthtml/cookbook/ch02.html

To build DB-UML you will need an SVN client, the release 5 (or higher) Java JDK and Apache Ant.

To check out the latest version of DB-UML from SVN use:

svn checkout http://argouml-db.tigris.org/svn/argouml-db/trunk

Before building DB-UML you must set the location of your ArgoUML build in the module.properties file. For example:

argo.root.dir=C:/argosvn/argo

sets the ArgoUML root directory to “C:/argosvn/argo”. This is used to locate ArgoUML classes needed by DB-UML. Also, the build will place the dbuml.jar in ArgUML’s /ext folder so that ArgoUML will install it as a module.

To build DB-UML use the jar target:

Ant jar

You can use the run target but this will actually run ArgoUML defined by argo.root.dir.

^{Architecture Requirements}

The following are general requirements for the architecture. The general architecture of a UML modeling tool is shown in the following figure:

Text Box: Model

,Text Box: Transformation
Tools

Flowchart: Magnetic Disk: Database
Catalog Flowchart: Magnetic Disk: Model
Storage

The UML GUI component provides the GUI for the tool. The GUI is specific to the UML model. It uses the Model component to represent the elements of models and to store models. It also uses Transformation Tools. The tools accept transformation definitions for transforming one model into another. For database modeling tools the transformations need to access database catalogs.

UML GUI

The language used to model databases is a UML profile called DB-UML (see UML Database Modeling). As DB-UML is a UML profile it uses standard UML extension mechanisms. Existing UML modeling tools can be used to create DB-UML models. However to be easy to use, the GUI of the modeling tool needs to be specific to the DB-UML profile. Also the GUI needs to provide access to transformations that are relevant for database modeling.

Model

The model component should be based on the Meta Object Facility (MOF). Model storage should use the XML Metadata Interchange (XMI) language. This provides interoperability with other modeling tools and enables use of transformation tools

Transformation Tools

Transformation tools transform between models and implementations or between models. Currently there is no standard for a translation definition language. However, standards and tools supporting standards will be available in the future and the modeling tool should be structured so that new tools can be integrated.

^{Tool Architecture Overview}

ArgoUML is used as a basis for the DB-UML Modeling Tool. ArgoUML is an open source UML modeling tool (see http://ArgoUML.tigris.org/ ). The following diagram shows DB-UML and ArgoUML components:

Text Box: GUI,Text Box: Model,Text Box: GUI,Text Box: Model,Text Box: Trans-
formers
,Text Box: Model,Text Box: Catalog
Interface
,Text Box: Controllers

Flowchart: Magnetic Disk: Model
Storage

Flowchart: Magnetic Disk: Database
Catalog

ArgoUML

ArgoUML (package org.argouml.*) implements a UML GUI providing diagrams, explorer trees, property sheets and menus.

Argo implements a Model based on the Metadata Repository project (MDR). MDR is a Netbeans project that implements an MOF repository (see http://mdr.netbeans.org/ ). An implementation of the Java Metadata Interface is provided (JMI).

ArgoUML has a “module” architecture where modules can be added to extend behavior. Most of the database modeling tool has been developed as an ArgoUML module. This will allow future versions of ArgoUML to be utilized without large changes. However, some minor changes to ArgoUML are also necessary as there are areas of ArgoUML that can not be extended.

ArgoUML Facade

ArgoUML Façade components (package org.dbuml.argo.*) are implemented as an ArgoUML “module”. The GUI component implements GUI extensions for the DB-UML profile. The extensions add new diagrams, toolbars and menu items to facilitate models using the DBUML language.

The model component stands in front of the ArgoUML Model to insulate components from changes in ArgoUML. It also provides a view of the UML model that is specific to the DB-UML profile.

DB-UML

DB-UML components (package org.dbuml.base.*) implement Controllers for the actions needed by the tool. The Controllers implement particular actions using the other components of DB-UML

DB-UML components implement Transformers for the DB-UML profile. These provide transformations between models or between models and implementations. The Transformers utilize a Catalog Interface for database metadata and utilize a Model component to represent the model.

The Catalog Interface is generic and uses standard JDBC metadata. It allows the actual JDBC driver to be specified at runtime. A Database element defines the JDBC driver it will use.

The Model component in DBUML is an abstraction of the DB-UML profile. (the Model component in the ArgoUML Façade is the realization of the DB-UML profile using the ArgoUML Model)

DB-UML components have no dependencies on ArgoUML.

The above architecture can be extended to fit the needs of a particular database. The ArgoUML Façade components can be extended to provide additional ArgoUML GUI capabilities and additional model implementations. And DB-UML can be extended to provide additional model elements, controllers, transformers and database catalogs.

The above architecture implements several important goals:

1. Tools for the DB-UML profile must be “pluggable” into an existing UML tool. This leverages the functionality of an existing tool and allows integration with future versions of a tool.

2. The architecture must insulate controllers and transformers from a particular UML tool so that they be used with other tools.

3. The architecture must insulate controllers and transformers from the implementation of the model.

4. It should be possible to determine JDBC drivers at run-time.

5. It should be possible to extend the DB-UML GUI and the DB-UML model for additional database capabilities.

^{Package Structure}

The package structure of the modeling tool isw shown in the following diagram:

org.argouml

The org.argouml packages implement the ArgoUML tool providing a model implementation and a UML GUI.

uml.ui

The uml.ui package loads menu items defined in the org.dbuml.argo package at initialization time. These menu items added when the module is initialized. ArgoUML loads all “modules” in jars located in its “ext” folder during initialization and call an initialization method. The method adds menu items to create database deployment and schema diagrams.

The actual name of the module class to load is defined in the manifest of the module jar. For example:

Manifest-Version: 2.0
Created-By: 1.4.1 (Sun Microsystem Inc.)
Name: org/dbuml/argo/uml/ui/DBModule.class
Specification-Title: ArgoUML Dynamic Load Module
Implementation-Title: DBUML Module
Specification-Vendor: University of California
Specification-Version: 0.9.10
Extension-name: module.tools.test
Implementation-Version: 0.9.10
Implementation-Vendor: test In the above manifest the menu item to create is DBSchemaDiagramMenu.class.

model

Argo implements a Model based on the MOF. Access to the model is through the façade ModelFacade.

org.dbuml.argo

ui & diagram

The ui and diagram packages implement the GUI extensions for the DB-UML profile. Menu items are add during module initialization to create Database Schema diagrams and to create Database Deployment diagrams. The DBSchemaDiagram class pictures Schemas and their owned elements. It is the equivalent of a class diagram and extends the ArgoUML class diagram class The DBDeployment class pictures Database elements. It is the equivalent of a deployment diagrams and extends the ArgoUML deployment diagram class.

The diagrams define various actions to support the DB-UML profile. For example, a Database figure in a Database Deployment diagram has a “Connect to Catalog” action in its pop-up menu. Actions delegate the actual work to controllers in the org.dbuml.controller package. Actions can be defined as toolbars on diagrams and as popup menus in figures on diagrams.

Actions can also be defined as Popup menus on the ArgoUML Explorer. However, this in not part of the “plug-in” architecture and currently, ArgoUML code must be changed to call these actions.

model

org.dbuml.argo provides an implementation of the DB-UML profile using the ArgoUML model. ArgoDBModelFacade is the ArgoUML implementation of the interface DBModelFacadeInterface (defined in org.dbuml.model). ArgoDBModelFacade is the only class to interface with ArgoUML’s model. It actually only uses ArgoUML’s model façade classes and never directly uses ArgoUML’s model implementation.

org.dbuml.base

The org.dbuml.base packages implement the controllers, transformers and catalog interface needed by the modeling tool. It also contains an abstraction of the model. The packages are not dependent on the UML tool, the model implementation or the database implementation.

controller

DBUML components implement Controllers for the actions needed by the tool. The Controllers implement particular actions using the other components of DB-UML as in a “Model, View Controller” pattern.

NOTE: a review of the controller’s use of Swing is necessary.

transfom

The transform classes provide transformations between models or between models and implementations. They access the model via the model package and they access the catalog via the database package. Transformers are invoked by controllers.

The actual implementation of the transformers is defined by the implementation of the Factory interface. A database supplier provides an implementation of transformers or they can use the generic implementation.

DBMetadataToDBUML

The DBMetadataToDBUML transformer generates a DBUML model based on catalog metadata. Catalog metadata is retrieved using the database package and the model is generated using the model package. The transformer is used by the following actions:

1. Import Schemas action from a Model Element. The buildSchema method is used to build a Schema model element. No owned elements of the Schema are built. These can be built using other actions.

2. Import Tables action from a Schema Element. The buildTable method is used to build a Table model element. All owned Column elements of the Table are built. Index constrains are added to the Table corresponding to Index definitions. If the Table completes any associations (foreign key, reference, generalization, derivation) the associations are added.

3. Import Views action from a Schema Element. The buildView method is used to build a View model element. All owned Column elements of the View are built. If the View completes any derivation associations the associations are added.

DBUMLToSQL

The DBUMLToSQL provides methods for generating SQL statements from a DBUML model. It uses Velocity which is a Java-based template engine. We used DBUML model in Velocity context to produce DDL statements designed with a Velocity template. See Velocity User Guide and Velocity Developer’s Guide for information about Velocity Template Language (VTL).

To generate SQL DDL statements for tables we used a Velocity template similar to the following:

## SQL 92 source template

########################################################

## Create Table

########################################################

#set($colnum = $Table.getColumnsVector().size())

CREATE TABLE $Namespace.$Table.getFixedName()

(

#foreach ($col in $Table.getColumnsVector())

#set($colSize = $col.getLength())

#set($colScale = $col.getScale())

#set($colDefault = $col.getDefault())

$col.getFixedName() $col.getTypeName()#if($velocityCount < $colnum),

#end

);

The template generates the following DDL statement:

CREATE TABLE ord.orderfacts

(

order_k INT4,

orderstat_k INT4,

shiploc_k INT4,

part_k INT4,

product_k INT4,

cust_k INT4,

order_date_k INT4,

request_ship_date_k INT4,

last_ship_date_k INT4,

qty_ordered NUMERIC,

unit_price NUMERIC,

backorder_qty NUMERIC);

We followed Velocity’s fundamental pattern in GenericDBUMLToSQL.genCreateSQL() method (see Velocity Developer’s Guide for more information about the pattern).

That is, we performed the following:

1. Initialized the Velocity engine.

VelocityEngine engine = new VelocityEngine();

engine.init(Properties);

2. Created a velocity context.

VelocityContext context = new VelocityContext();

3. Added DBUML model to the context.

context.put("Table", (Table) dbe);

4. Chose a template.

Template templateCreateTables = engine.getTemplate("org/dbuml/base/transform/GenericCreateTables.vm");

5. Merged the template and DBUML model to produce the output.

StringWriter writer = new StringWriter();

templateCreateTables.merge(context, writer);

Generic DBUML Velocity templates are located in "org/dbuml/base/transform" folder.

UMLToDBUML

To be supplied.

DBUMLClassToProxy

To be supplied.

CDCMetadataToDBUML

To be supplied.

DBUMLToCacheControl

To be supplied.

XMLSchematoUML

To be supplied.

model

The model package represents the UML profile, DBUML. It “models” the database specific profile and it serves as a façade to the model implementation. The DBModelFacade class is an abstract class implementing DBModelFacadeInterface. All classes use DBModelFacade to access the model.

Information is exchanged between DBModelFacade and other components such as controllers or transformers is through DBElements. DBElements are contrainers for information about database entities. They are used only to pass data back and forth. They are not used as a complete model.

The actual implementation of DBModelFacade is defined by the implementation of DBSchemaDiagramMenu which is loaded by ArgoUML as a pluggable module. Only one implementation of DBModelFacade can be in place for an instance of ArgoUML.

database

The database package is the interface to a database catalog. The DBMetadata class keeps a database Connection and a DatabaseMetadata object for the metadata at connect time.

A DBMetadata object is created for a model element (representing a database) when the “Connect to Catalog” action is chosen from the element’s popup menu. The DBMetadata object is associated with the model element through the “database” attribute.

A database supplier provides an implementation of DBMetadata or they can use the generic implementation. The implementation is created by a database supplier’s implementation of the Factory interface.

DBMetadata objects are collected by the DBMetadataCache

DBMetadata uses Connectionfactory to connect to a catalog. The information needed to connect is in tagged values of the model element representing the database. For example, the following model element represents a Tiger database.

factory

The factory package creates the actual implementations of DBMetadata and the transform interfaces. The database supplier provides a Factory implementation or they can use the generic implementation. The name of the Factory implementation is defined as a tagged value of the model element representing the database (see previous section).

This provides the ability to use different types of catalogs (metadata implementations) and different types of transformers within the same instance of ArgoUML.