P3: Class Diagram Visualization
and Model-to-Text Transformations

You are to modify your previous assignment (P1) a teeny bit, and write a new program P3 to (a) generate a Yuml specification using the VM2T tool.  When your program is invoked, a command-line parameter will specify whether a (a) Yuml spec or (b) Prolog tables is to be produced. 

You will need a program from CatLite from the last assignment.


Teeny Tiny Modification of P1

In P1, your program output the following standard header:
:- discontiguous bcClass/3, bcMembers/7.
:- dynamic bcClass/3, bcMembers/7.
Now, I want you to add the following extra lines that defines the schema of the tables you are outputting. Note that each table definition must start with %table:
:- discontiguous bcClass/3, bcMembers/7.
:- dynamic bcClass/3, bcMembers/7.
%table(bcClass,[id,"name","super"]).
%table(bcMember,[id,cid,static,field,"typeName","arrQual","signature"]).

That's it.


Yuml

Yuml is a free web service that draws UML class diagrams given a Yuml input specification.  As this is a for-profit company, the "free" service comes with some strings attached.  Namely, it will produce a pretty class diagram for you provided that your specification is not too complicated.  (I found other problems with Yuml, but this is a story for another day).

Familiarize yourself with Yuml:

[student|name]has-loves[course|name]


Yuml Specifications

A Yuml specification is elegant.  Here is a BNF of the portion of Yuml that we will use. Literals (a.k.a. tokens) are in single 'quotes'.

YumlSpec : Line+ ; // one or more lines

Line: Box | Connection ; // a line defines a box or connection

Box : '[' Class ']' ;

Connection : BoxName [End1] [Role1] DashType [Role2] [End2] BoxName ; // ignore subscripts

BoxName : '[' String ']' // class name
| '[ Interface;' String ']' // interface name
;

DashType : '-' // solid line
| '-.-' // dashed line
;

End : '<>' | '++' | '^' | '<' ; // aggregation, composition, inheritance, arrow

Role : String ; // String that has no ']' and quote chars

Class : Name // name only
| Name '|' String // name and methods only
| Name '|' String '|' String // name, fields, and methods
;

Name : String ; // String that has no ']' and quote chars

Note that a "String" token is mentioned above.  Well, this String isn't any Java String, but one that is devoid of the characters: "," comma,  "[" (left brace), "]" (right brace), "<" (less than), ">" (greater than), "-" (minus).  Further, a semicolon ";" means new line.  Some hints:

So, the following Yuml specification (a sentence in the above language):

[Interface;Closable|close()]
[Interface;NetworkChannel|bind();getLocalAddress();getOption();setOption();supportedOptions()]
[MyClass|_MyClass();close()]
[Interface;Closable]^-.-[MyClass]
[YourClass]<>-3>[MyClass]
[interface;Closable]^-[Interface;NetworkChannel]

Will produce this beauty:

 

Do not read the above specification too deeply!  "Interface;Closable" is a String.  The word "Interface" means nothing to Yuml.  It could just as well have been "George" (which also means nothing to Yuml).  What Yuml does understand is ";" (semicolon), which means add a new line.  So "Interface;Closable" produces a 2-line name in the above figure.  And the string "bind();getLocalAdddress()" means print strings "bind()" and "getLocalAddress()" on separate lines.

Note: Recall the BC database that you produced in P1.  Follow this link to see its tables and to refresh your memory.

Note: Here is a challenge of this project: You should observe that a BC database contains no associations, although it does contain "qualified name of superclass" and "qualified name of member's (return) type" fields.  You are to deduce from the data in a BC database what associations are present among classes of the given package.  Hint: if a referenced class is not in your database, then don't create a class diagram association.


Your Assignment

Start with your program of Project #1, retain its functionality, and add the extra functionality to produce a Yuml specification (sentence). You will  need to produce Yuml specs and Project#1 output later. The big picture is shown below as a category, which is read as:


Your P1 program maps Java class files to a BC Prolog database.  This assignment (P2) is to write a transformation that maps a BC Prolog database to a Yuml spec.  You will use the public Yuml web site to produce a beautiful Yuml figure (jpg or gif) for each Java package that was given to you in P1 (since you now know their database representation).

You are NOT to hack Java code to do this.  Instead, you are to translate your tables to
a Yuml specification using the VM2T (Velocity-Model-to-Text) tool.  The documentation for VM2T is in the _CatLiteDoc directory of CatLite and can be found here.

Getting Started

First, read the VM2T tutorial.  You'll get the idea quickly.

Second, here is a P3 zip file -- unzip it and this is the directory in which you will work.  In it, I provide a prolog database for the yparser package -- the file is named yparser.ypl.pl.  The VM2T script file is toYuml.vm -- right now it is a dummy file.  To translate yparser.ypl.pl into file myoutput.txt, you use two command line calls -- one to do the translation and the next to display the result ('type' is the 'cat' command in DOS):
C> java CatCore.vm2t.Main yparser.ypl.pl toYuml.pl myoutput.txt

C> type myoutput.txt
Now, look at the contents of myoutput.txt and you'll see the first few lines are:
   class yparser.connection extends Object;
class yparser.klass extends Object;
class yparser.Main extends Object;
Now, look at the toYuml.vm file:
#set($MARKER="//----")
${MARKER}${OutputFileName}

#foreach($class in $bcClassS)
class ${class.name} extends ${class.super};
#end

#foreach($m in $bcMemberS)
${m.typeName}${m.arrQual} ${m.signature};
#end

Basically, it says: route the output of a Velocity script to ${OutputFileName}, which in the above command line invocation was "myoutput.txt".  The first foreach loops through the bcClass table and outputs, for each class a line that gives the class name and its immediate superclass -- see above.  The next foreach does the same for the bcMembers table.

Your job is to:
Warning: there always remains the issue of whether your .vm and .pl files are readable to vm2t tool. If you don't get the output above, then you need to use the dos2unix or mac2unix or unix2mac etc. tools to give you a standard format.  The Cat tools were written for a DOS environment. You may have to fiddle with this to get it right for your environment.

Hints

Here is a PDF file that shows the Yuml pictures that I created long ago.  As Yuml changes periodically, the figures that you produce may not be identical, but should be obviously "equivalent".  Of course, you may list members etc or show associations that I didn't identify when I created these pictures.

What to Submit

All of the below in a zip file. The zip file must unzip into <yourName>/<YourFilesAndDirectories>.
  1. a short description that the Grader needs to know to run your program, other than the above.

  2. run your tool on all "test" programs given in P1.

  3. a short writeup showing the Yuml spec generated and its Yuml drawing for each "test" program.

  4. A PDF file (in the required format) that the Grader should read to provide any information that is not obvious.  The contents of the PDF file can be minimal.

A critical part of any design is clarity and understandability.   Hence, you will be graded on the clarity of your project and its ability to work correctly.  Sloppy code, documentation, or anything that makes grading or understanding your program difficult will cost you points.  Beware, some of these "beauty" points are subjective. 

Remember: No late assignments/submissions will be accepted.