Different Encodings of Class Diagrams

Meta4 uses 3 different representations of class diagrams, all useful to end programmers. Each is documented below:

Representation	Utility
Class Diagram Specs	The primary way class diagrams are defined manually
Class Diagram Databases	This is the respresentation on which constraints are defined and executed
PlantUML Specs and Conversion to PNG Files	One way to depict class diagrams visually
Yuml Class Diagram Specs and Manual Conversion to PNG Files	Another way to depict class diagrams visually

Big Picture

The picture below left is a flowchart (or category) that shows how different representations of programs (cdspec, CD databases, etc) are related by programs (labeled arrows). Generally speaking, a cdspec defines a class diagram and is hand-written by a user. Different tools convert a cdspec into various forms. The program CDSpec2CD translates a cdspec file to a CD database that is populated with tuples that encode the cdspec. Such a database, in turn can be converted into a PNG file by two distinct paths, using PlantUML or Yuml shown below; their graphics are not the same and not all arrows can be performed automatically. (I would have to buy a Yuml server for automatic translation -- such is life on the free side).

In the following, I illustrate a pets class diagram, and how to invoke programs to transform its cdspec into PNG images. One sequence of command-line invocations that can do this is shown in the middle figure below with commentary to the right.

sequence of program calls

Commentary

// start with a pets cdspec file, 
// pets.cdspec.pl

C>java M4.CDSpec2CD pets 


C>java M4.CD2PlantUML pets 



C>java M4.PlantUML2Png pets 
(5 entities)



// ends with pets.class.png




converts pets.cdspec.pl -> pet.cd.pl


converts pets.cd.pl to pets.class.plantuml
(a PlantUML specification of pet.cdspec.pl)


converts pets.class.plantuml to pets.class.png
(a graphical image of pets.cdspec.pl)

The next sections explain each representation (a.k.a. MDE MetaModels) and the model-to-model or model-to-text transformations needed to compute other representations of a class diagram.

Class Diagram Specs

Programmers specify a class diagram textually in a cdspec file. A cdspec file has name "X.cdspec.pl", where "X" is the name of its Meta4 application. Below is a cdspec for pets (stored in pets.cdspec.pl). Its PlantUML graphics is in the middle and its Yuml counterpart is to the right:

#1

#2
#3
#4



#5

#6
#7

classDiagram pets. 

table(Pet,[name,age:int]). 
table(Dog,[]).
table(Cat,[friendly:bool]).
table(DogBreed,[name]).
table(Person,[name,"city"]).

subtable(Pet,[Dog,Cat]). 

assoc(db,DogBreed,breed,BLACK_DIAMOND,Dog,examples,BLANK).
assoc(po,Person,ownedby,1,1,Pet,owns,0,5).

The cdspec is a series of declarations, where each declaration occurs on a single and separate line:

a class diagram declaration whose name must match that of its filename,
then table declarations,
then subtable declarations, and
then association declarations.

Note that types of attributes (or fields) are "str" for string, "qstr" for quoted string, "int" for integer, "dbl" for double, "float" for float, and "bool" for boolean. If an attribute is specified without a type, "str" is assumed. The difference between the "str" and "qstr" type is simple: a "str" is essentially a Java Identifier -- no fancy characters, blanks, or commas, like Austin (no quotes). A "qstr" is literally that "New York", a quoted string. Values for bool are true and false (no caps).

In the above case:

Line #1 declares the name of a class diagram as 'pets'. The name of the file containing this specification must be pets.cdspec.pl.
Line #2 declares a Pet class or table to have attributes "id" (added by default to all classes), "name" and "age", where "age" is declared an integer, and the other fields are by default "str".
Line #3 declares a Dog class or table to have no attributes -- actually we'll see that Dog is a subclass or subtable of Pet in line #5, so it does inherit Pet attributes.
Line #4 declares a Cat class or table to have one attribute, "friendly" of type boolean. We'll see next that Cat is a subclass or subtable of Pet.
Line #5 declares the subclasses or subtable of Pet are Dog and Cat.
Line #6 declares an association (with name "db") between table DogBreed and Dog. The BLACK_DIAMOND means composition: each Dog belongs to precisely 1 DogBreed. BLANK means each DogBreed can be connected to any number of Dogs.
Line #7 declares an association (with name "po") that each Person owns 0..5 Pets, and each Pet is owned by precisely one Person.

More details are explained as we go along. There are constraints you should be aware of, but are not yet enforced:

Classes that root inheritance hierarchies (DogBreed, Pet, Person), the first attribute must be "id" (for identifier).
Identifier fields "id" are added automatically, so this shouldn't be a problem.
The order in which classes are defined in an association matters: the strongest association end must be listed first. The ordering of association strength is:
BLACK_DIAMOND > DIAMOND > ONEPLUS > BLANK = NM = CUSTOM

When a cdspec is parsed syntactic errors are reported, halting computation.

Class Diagram Databases

A CD database file has name "X.cd.pl", where "X" is the name of the Meta4 application. Below left is the schema of a CD database and to the right is the CD database for pets (stored in pets.cd.pl):


dbase(cd,[tab,attr,assoc,sub,cons]).

table(tab,[id,name,abs:bool]).

table(attr,[id,name,ptype,attrof:tab]).
#ptype = primitive type int, float, bool, dbl, str, qstr

table(assoc,[id,name,class1:tab,role1,atype1,min1:int,max1:int,class2:tab,role2,atype2,min2:int,max2:int]).
#atype1, atype2 = DIAMOND(0,1), BLACK_DIAMOND(1,1), ONEPLUS (1,-1), BLANK(0,32000), CUSTOM(0,0)
#class1, role1 = primary table, primary role
#class2, role2 = secondary table, secondary role
#name = association table name (needed only for NM associations)

table(sub,[id,suptab:tab,subtab:tab]).
#suptab, subtab = supertable, subtable

table(cons,[id,name,"constraint"]).


dbase(cd,[tab,attr,assoc,sub,cons]).

table(tab,[id,name,abs:bool]).

table(attr,[id,name,ptype,attrof:tab]).
#ptype = primitive type int, float, bool, dbl, str, qstr

table(assoc,[id,name,class1:tab,role1,atype1,min1:int,max1:int,class2:tab,role2,atype2,min2:int,max2:int]).
#atype1, atype2 = DIAMOND(0,1), BLACK_DIAMOND(1,1), ONEPLUS (1,-1), BLANK(0,32000), CUSTOM(0,0)
#class1, role1 = primary table, primary role
#class2, role2 = secondary table, secondary role
#name = association table name (needed only for NM associations)

table(sub,[id,suptab:tab,subtab:tab]).
#suptab, subtab = supertable, subtable

table(cons,[id,name,"constraint"]).

A PNG file of a cdspec is produced by converting a cdspec file to a CD database, the database to a PlantUML spec, the spce to a PNG file:

C>java M4.cdspec2CD pets 


C>java M4.CD2PlantUML pets 


C>java M4.PlantUML2Png pets 
(5 entities)

Standard constraints are evaluated on the resultant CD database:

The first column of every table must be named "id".
All tuple ids must be unique per table.
All tuple "name"s in table tab and assoc must be unique.
For each table, the union of its attributes and the association ends that might become fields is formed. If duplicate names are discovered, they are reported.
A foreign key in a table is a column whose type is not primitive. Foreign keys are pointers to (a.k.a. ids of) tuples in another table; these pointers are validated to ensure database consistency. Examples in the CD schema above are:

the attrof column in table attr contains legal ids of tab(le) tuples
the class1 and class2 columns in table assoc contain legal ids of tab(le) tuples.
the suptab and subtab columns in table sub contain legal ids of tab(le) tuples.

min and max fields of associations are checked to ensure that they contain integer values, and that 0<min<max.

If errors are detected, they are reported and computations halt.

PlantUML Specs and Conversion to PNG Files

A PlantUML document of a class diagram is a file with name "X.class.plantuml", where "X" is the name of the application. Below left is the PlantUML document of the CD database for pets and to the right its PlantUML png file. Note that class id(entifiers) are not displayed as explicit fields, even though they are indeed present.


@startuml
class Pet {
  name
  age : int
}

class Dog {
}

class Cat {
  friendly : bool
}

class DogBreed {
  name
}

class Person {
  name
  "city"
}

Pet <|-- Dog
Pet <|-- Cat
DogBreed "breed" *-- "examples" Dog
Person "ownedby 1" -- "owns 0..5" Pet
@enduml

A Plantuml spec file (ex: pets.class.plantuml) is produced from a CD database (ex: pets.cd.pl) by the following command:

   C>java M4.CD2PlantUML pets

# reads pet.cd.pl
# produces pet.class.plantuml

A PlantUML file is converted to a PNG file by the following command:

   C>java M4.PlantUML2Png pets 
   (5 entities)

# reads pet.class.plantuml
# produces pet.class.png

The conversion uses the plantuml.jar file that invokes an installed (Windows) app Graphviz.

Yuml Class Diagram Specs and Manual Conversion to PNG Files

A Yuml spec of a class diagram is a file with name "X.class.yuml where "X" is the name of the MDELite application. Below left is the Yuml file of the CD database for pets and to the right its Yuml png file:


[Pet|name;age|]

[Cat|friendly|]

[DogBreed|name|]

[Person|name;city|]

[DogBreed]++breed-examples[Dog]

[Person]ownedby-owns[Pet]

[Pet]^-[Dog]

[Pet]^-[Cat]

A Yuml file (ex: pets.class.yuml) is produced from a CD database (ex: pets.cd.pl) by the following command:

C>java M4.CD2Yuml pets

# reads pet.class.yuml
# produces pet.png

A Yuml file is converted to a PNG file by copying the generated yuml file (ex: pet.class.yuml) and entering it onto this Yuml web page for graphic production.

Warning: You must manually save the produced image (recommended name pet.png).