NAME

        DYNAMO - Dynamic Assembly from Models

SYNOPSIS

        dynamo < <ocl constraint>


DESCRIPTION

	DYNAMO       

       	parses OCL constraints passed in as ASCII code and generates an
       	abstract syntax tree containing the information from the 
	constraints. Uses a symbol table to generate an intermediate
	representation of a structure that is walked by a Visitor
	design pattern to generate invariant maitenance code based on
	mixin layer templates.

	This particular version of DYNAMO does not use intermediate
	representation but has the output files hardcoded into it.


OPTIONS

        none


MAKEFILE OPTIONS
	
	make dynamo
		produces dynamo.exe from the provided files

	make clean
		removes all files generated


EXAMPLE

        ./dynamo < c2f.txt

              Parses the OCL constraints of file c2f.txt and generates
	      mixin layer templates


SYMBOL TABLE
	
	The Symbol Table for DYNAMO contains the name of the symbol as string,
	the OCL type of the symbol as string, the owner of the symbol
	as string, and an unisigned integer array of the location of
	the symbol in the AST. Global classes that are symbols
	have "Global Component" as the owner.  Variables inside
	of classes are owner by the class and have the name of
	the class as the owner


DATA FILE

	DYNAMO takes in UML data from the data file titled "data.txt".
	This file contains the names of all variables and classes included
	int the OCL constraint in the following format:

	Types:
  	  NameOfClass.NameOfVariable TypeOfVariable
          NameOfClass2.NameOfVariable2 TypeOfVariable2

	example:
	
		Types:
 		  F.f int
		  C.c int

		for constraints

		context F inv:
  			self.f = (C.c * 1.8) + 32
  

ERROR MESSAGES

	DYNAMO outputs an error if it cannot parse given input

	example:	

		1: syntax error, unexpected t_DIVIDE, expecting t_CONTEXT at /

	DYNAMO outputs errors if it cannot open the data file or of the data file
	is of incorrect format. For correct data file format please see above
	

STATUS

	Currently, DYNAMO is to generate a mode component template, status variable
	templates, and dependent variable wrapper based on an OCL invariant 
	constraint and input file.

FUTURE WORK

	Support for cosntraints needs to be added.
	UML data should come from a UML file.
	Possible implementation of alternative methods.


AUTHOR

        Written by Jonathan Gdalevich using the poclc OCL parser from Jude 
	Nagurney with changes by Jonathan Gdalevich (lordebon@cc.gatech.edu)
	Intermediate representation is written by Kurt Stirewalt 
	(stire@cse.msu.edu)


BUGS

        The parser only supports OCL 1.3

	The constraint itself must be inserted manually into the generate
	wrapper for the dependent varaible.


GLOSSARY

DYNAMO - Dynamic Assembly from Models, the project/process/system that deals 
with invariant constraint maintenance through employment of mixin layers 
and C++ templates.

Mixin layer - mixin classes that are scaled to a multiple-class granularity.

PWAN - Project Without A Name, the original name of the OCL parser 
currently used by DYNAMO.

OCL - Object Constraint Language, OMG specification that allows the 
representation of constraints within UML.

Invariant - a type of constraint that always holds true and never 
changes throughout the life of its owner.

Dependent variable - variable on the left side of a constraint and depends 
on the value of independent variables.  A separate wrapper is created 
for this variable as it is currently not part of the intermediate 
representation.

Independent variable - variable on the right side of a constraint and 
the dependent variable depends on it.  It is known as a Status Variable 
within the intermediate representation and has a special template generated 
for it.  Within the intermediate representation, it is stored within 
the StatusAPI which is itself stored in the Mode Component.

Mode Component - the central and most important object of the intermediate 
representation representing the class that contains the invariant.
All other objects are stored within it.  It is also the starting point 
of the Visitor.  Also is another name for the automatically generated 
component wrapper.

Intermediate Representation - a structure composed of various objects 
around the Mode Component.  It is build from data parsed out of the 
OCL constraint and UML class diagram.  The Visitor walks it generating 
source code to a stream.

Visitor Pattern - design pattern in which a Visitor object traverses 
a structure of objects where each object contains an accept() method.  
Depending on the object, the Visitor performs a certain operation.  
The developer does not need to know at run time the order or number 
of objects the Visitor will visit.  In DYNAMO, the visitor design pattern 
is used to generate code by having a visitor object visit every 
object in the intermediate representation.  See the following:
http://exciton.cs.oberlin.edu/javaresources/DesignPatterns/VisitorPattern.htm
http://www.dofactory.com/Patterns/PatternVisitor.aspx
http://en.wikipedia.org/wiki/Visitor_pattern

Visitor - an objects that visits specific objects within the 
framework of a visitor design pattern executing specific code 
depending on the type of the object being visited.

Symbol Table - a data structure used by DYNAMO to store 
data parsed out of OCL constraints and UML class diagrams.  
Each symbol is associated with a location and scope of the OCL constraint.

AST - Abstract Syntax Tree, a data structure that holds symbols 
and tokens parsed out of the OCL constraint.  It is arranges in a 
certain way to give specific meaning to each symbol within the scope of the 
constraint.

StatusVariable - representation of the independent variable within 
the intermediate representation.  Each contains a StatusType which 
is its OCL type and which in turn contains a CppType which is the 
C++ type of the variable.  See Independent Variable.

Copy-up Refinement - refinement that propagates information upwards 
from the independent variable to a dependent variable.  It is 
supported by the StatusUpdateService of the intermediate representation 
which also supports copy-down refinement.  Also known as constraint-trigger 
refinement.

Copy-down Refinement - refinement that propagates information downwards 
from the dependent variable to an independent variable.  It is supported 
by the StatusUpdateService and the StatusDeledateService of the 
intermediate representation which also supports copy-up refinement.  

ServiceInterface - object within the intermediate representation that 
allows non-constraint functions and variables to have code generated.  
They can be used within top or bottom ServiceAPIs.

ServiceAPI - object within the intermediate representation contained with 
in the Mode Component.  Each mode component can have up to two ServiceAPIs 
for top and bottom services (services from dependent and from independent 
objects).  ServiceAPIs contain Service Interfaces and can also contain 
StatusDelegate and StatusUpdate Services.

StatusDelegateService - see Copy-down Refinement.

StatusUpdateService - see Copy-up Refinement.

StatusAPI - object within the intermediate representation contained within 
the Mode Component that itself contains all Status Variables of the 
particular constraint.

StatusType - see StatusVariable.

CppType - see StatusVaraible.

Template - C++ template classes.  Special C++ classes that allow some 
evaluations to be performed at compile time instead of run time.  
DYNAMO uses them for mixin layers to improve performance of the 
generated code.  See
http://en.wikipedia.org/wiki/Template_metaprogramming

Lex - generator for lexical analyzers used by the PWAN parser.   
Flex is what actually being used.

Yacc - parser generator that uses a lex lexical analyzer to generate 
the PWAN parser within DYNAMO.  GNU bison is what actually being used.

PWAN PARSER

Advantages
-	Parser complete OCL
-	Easy to traverse the AST as example is provided
-	Relatively good syntax checking
Disadvantages
-	Supports only OCL 1.3
-	Produces an AST that is not in the best form for understanding 
constraints.  Primarily, OCL keywords and symbols are placed on a 
different level of the tree in comparison to variable names so that 
it is hard to figure out which symbol goes with which names.  This is 
especially complex for multiple keywords in a row or when OCL functions 
are used.
-	Hard to debug as some parts are not documented

Symbol Table and other structures used to generate the intermediate 
representation
Advantages
-	Correctly determine dependent and independent variables
-	Symbol Table is correctly filled
-	Supports multiple interdependent constraints through use of 
structures.
-	Retrieves all variable data needed for the correct implementation 
of the intermediate representation.
-	Well commented and documented.
Disadvantages
-	Does not retrieve the actual constraint formula from the AST.  
Only works with class and variable names.  The actual constraint has to 
be entered by hand into a generated file.
-	No support for any OCL functions.
-	Wrapper for the dependent variable is generated outside of the 
intermediate representation.
-	Some methods are too long and there is certain amount of code 
duplication.

Intermediate Representation and Code Generation
Advantages
-	Generally follows the schema as described in the documentation.
-	Correctly implements the visitor design pattern.
-	Conceptually easy to map the constraint to generated code.
-	Make adding new objects or changes in the output easier.
-	Allows for implementation of mode components with different 
parameters without the need for code changes.
-	Generates runnable code.
Disadvantages
-	No support for top or bottom refinements.
-	Little documentation within the code itself or documentation 
about the status of the code.
-	Very hard to debug.
-	Example is confusing as it uses two mode components, each with a 
single ServiceAPI, instead of a single mode component with two APIs that 
it should be able to support.
-	Prone to core dumps.
-	Has little or no error checking and will core dump upon incorrect 
input.
-	No support for multiple constraints that use same status variables.
-	Could possibly be easier implemented by functions that generate code 
depending on the input of variable names or number of constraints as 
demonstrated by an earlier version of the generator.
-	Does not use the same naming conventions as described in the 
documentation

       


/***********************************************************************
*
* DYNAMO, hereinafter (Software)
*
* Copyright 2005
* Georgia Tech Research Corporation
* Atlanta, Georgia  30332
* All Rights Reserved
*
* The following Software is posted on the Internet by the Georgia
* Tech Research Corporation (GTRC).  It was developed by students and
* faculty of the Georgia Institute of Technology.  GTRC hereby grants
* to the user a non-exclusive, royalty-free license to utilize such 
* Software for the user's own purposes pursuant to the following 
* conditions.
*
* THE SOFTWARE IS LICENSED ON AN "AS IS" BASIS.  GTRC MAKES NO
* WARRANTY THAT ALL ERRORS CAN BE OR HAVE BEEN ELIMINATED FROM THE
* SOFTWARE. GTRC SHALL NOT BE RESPONSIBLE FOR LOSSES OF ANY KIND
* RESULTING FROM THE USE OF THE SOFTWARE AND ITS ACCOMPANYING
* DOCUMENTATION, AND CAN IN NO WAY PROVIDE COMPENSATION FOR ANY
* LOSSES SUSTAINED, INCLUDING BUT NOT LIMITED TO ANY OBLIGATION,
* LIABILITY, RIGHT, CLAIM OR REMEDY FOR TORT, OR FOR ANY ACTUAL OR
* ALLEGED INFRINGEMENT OF PATENTS, COPYRIGHTS, TRADE SECRETS, OR
* SIMILAR RIGHTS OF THIRD PARTIES, NOR ANY BUSINESS EXPENSE, MACHINE
* DOWNTIME OR DAMAGES CAUSED LICENSEE BY ANY DEFICIENCY, DEFECT OR
* ERROR IN THE SOFTWARE OR MALFUNCTION THEREOF, NOR ANY INCIDENTAL
* OR CONSEQUENTIAL DAMAGES, HOWEVER CAUSED. GTRC DISCLAIMS ALL
* WARRANTIES, BOTH EXPRESS AND IMPLIED RESPECTING THE USE AND
* OPERATION OF THE SOFTWARE AND ANY ACCOMPANYING DOCUMENTATION,
* INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
* FOR PARTICULAR PURPOSE AND ANY IMPLIED WARRANTY ARISING FROM
* COURSE OF PERFORMANCE, COURSE OF DEALING OR USAGE OF TRADE.  GTRC
* MAKES NO WARRANTY THAT THE SOFTWARE IS ADEQUATELY OR COMPLETELY
* DESCRIBED IN, OR BEHAVES IN ACCORDANCE WITH ANY ACCOMPANYING
* DOCUMENTATION.  THE USER OF THE SOFTWARE IS EXPECTED TO MAKE THE
* FINAL EVALUATION OF THE SOFTWARE'S USEFULNESS IN USER'S OWN
* ENVIRONMENT.
*
*********************************************************************/

