This entry gives highlights of the architecture of the Umple technology. Umple contributors who wish to better understand Umple should work their way through the files and directories described here.
Umple Architecture: Core files to understand the Umple Compiler
Master Umple file for Umple
The following file is compiled to produce Umple itself. It includes or 'uses' the other files that comprise the Umple compiler. cruise.umple/src/Master.ump This will compile not only the code for the main compiler, but also for various other parts of the Umple technology such as the documenter (for generating the user manual). Compiling this using Umple will generate Java (placed in cruise.umple.src-gen-java), which is then compiled to produce various jar files such as umple.jar, vml.jar and umplsync.jar. Note that it is not recommended to directly compile Master.ump; it is best to do a full build instead by going to the build directory and running ant -Dmyenv=local
For a class diagram of all the Umple classes see: http://cruise.eecs.uottawa.ca/umple/umple-compiler-classDiagram.shtml
API of the generated Java files
Umple code compiled from the Umple not only generates java files but also calls many of the generated methods. As a result, a complete javadoc of all public methods within the Umple compiler is at http://umple.org/umple-compiler-javadoc/. Ideally every Umple class and method would have a comment, and hence this javadoc would have a comment too.
There are two important 'main' methods for the command-line version of the compiler, both found in cruise.umple/src/Main_Code.ump
- PlaygroundMain(): Used by UmpleOnline when it invokes the compiler. The main program in umplesync.jar
- UmpleConsoleMain(): The normal command-line compiler main method. The main program in umple.jar This is the main program you would want to call when you are compiling from the command line or using the build scripts.
Grammar and Parsing
The source for the Umple grammar is divided into several files with the extension .grammar, including cruise.umple/src/umple_core.grammar A nicely pretty-printed view of the grammar is available in the Umple User Manual; this is automatically generated from the .grammar files. It is available as: http://grammar.umple.org
- `parse(String ruleName, TextParser inputParser, Token parentToken, int level, String... stopAts)``
private void addNecessaryFiles()
private void parseAllFiles()
public ParseResult analyze(boolean shouldGenerate)
Note that UmpleInternalParser at the end includes several other parser components for parsing such special elements as classes, tracing, state machines, etc.
Error and Warning Messages
When parsing, error messages may be generated. All error messages are placed in file cruise.umple/src/en.error
Error messages are emitted by using one of the following methods
addErrorMessage, which takes as arguments the message number, the location in the parse results and any positional parameters to substitute into the error message. It is in cruise.umple/src/Parser_Code.ump
setFailedPosition(this calls the above), and takes similar arguments. It is in cruise.umple/src/UmpleInternalParser_Code.ump
Messages have various levels of severity. Warnings allow compilation to continue, errors do not.
The metamodel describes the classes and other entities present in a program that the Umple compiler is compiling. There are two main files:
- Umple.ump contains the raw 'UML' view of the metamodel
- Umple_Code.ump contains the java methods that are mixed into the classes defined in Umple.ump
Key methods in these files in class UmpleModel are:
Core code generation for Java takes place in cruise.umple/src/Generator_CodeJava.ump
Key methods are:
private void prepare(UmpleClass aClass)
public void generate()
Similarly named files are used to generate other languages.
Generated code for many languages is specified using UmpleTL files found in the UmpleToX directories, such as UmpleToJava/UmpleTLTemplates These are compiled by the Umple compiler, generating Java source using the codegen ant target, which is then copied into cruise.umple/src-gen-UmpleTL and invoked by files such as Generator_CodeJava.umpGenerator_CodeJava.ump, mentioned previously.
Generation for 'specialty' outputs such as Ecore and YUML can be found in files of the pattern Generator_CodeX.ump such as cruise.umple/src/Generator_CodeEcore.ump
Umple Architecture: Pages for specific features or subsystems
Umple Architecture: Package View
The packages in the trunk are described below. Note that within each package there are many *.java files. As a rule, never edit these. Java files are always generated, usually by Umple itself. Always look for the corresponding .ump file.
cruise.umple/: The main compiler
Key packages and files in cruise.umple
- src/: Contains the umple files. Also contains Java files generated from these in its subdirectory 'cruise'. More details of the contents of src are below.
- src-gen-umple and src-gen-umpletl: files generated from Umple and UmpleTL, related to code generation. Should not be edited (not version controlled).
test/: Testcases, under
cruise/vmland test data under
data/. Note that the project uses test-driven development, so tests should always be developed in advance of any work on
- Master.ump: The main file that is compiled to build the Umple compiler. This has a large number of 'use' statements that simply describe the other files that must be compiled together to build the compiler.
*_Code.ump: Pairs of files separating pure model from methods for the classes described in the model.
*.grammar: files implementing the Umple grammar as described for Umple's internal parser
*Parser*: Files related to parsing.
- Main_Code.ump: The console (command-line) main program for the Umple compiler.
Documenter*: A System for building the documentation found at: http://manual.umple.org.
Generator*: Code generation of code in Java, PHP, Ruby, etc. See also below where we describe the
Violet*: Additional outputs the compiler can generate
VML*: Variability modeling language extension
cruise.umple.eclipse/: The Eclipse plugin
cruise.umple.xtext.ui/: Code for the XText UI
UmpleTo*: Code for generating code in the various languages
testbed/: More extensive tests than those found in the above packages
sandbox/: This is for testing Umple infrastructure
dist/: Outputs to be deployed
examples/: Larger, fully functional examples
Systems with Umple at their core. They serve as additional testing for Umple
externalexamples/: Examples contributed by others
This is for people who have used Umple, and have agreed to have the examples open-sourced here, so that we can compile them whenever we update the compiler, as extra test cases.
umpleonline/: The website found at http://try.umple.org
Diagrams will be placed here showing the flow among the various components: What is consumed and produced by what.
Umple uses several levels of tests. It tests the tokenization in the parser, it tests that the metamodel is properly instantiated, and it tests that the resulting systems have code that looks correct and works correctly. In all cases, the tests are set up before the code is written. Umple testing architecture