Skip to content

Architecture

Jump to bottom Edit New page
Rui Cai edited this page Feb 17, 2022 · 9 revisions

Architecture

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.umple.org/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 https://cruise.umple.org/umple/umple-compiler-javadoc/. Ideally every Umple class and method would have a comment, and hence this javadoc would have a comment too.

Main programs

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

Parsing is accomplished in class Parser cruise.umple/src/Parser.ump cruise.umple/src/Parser_Code.ump

key method:

  • `parse(String ruleName, TextParser inputParser, Token parentToken, int level, String... stopAts)``

and class UmpleInternalParser cruise.umple/src/UmpleInternalParser.ump cruise.umple/src/UmpleInternalParser_Code.ump

key methods:

  • 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

Messages have various levels of severity. Warnings allow compilation to continue, errors do not.

Metamodel

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:

  • run()
  • generate()

Code generation

Core code generation for Java takes place in cruise.umple/src/generators/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.umple/* and cruise/vml and test data under data/. Note that the project uses test-driven development, so tests should always be developed in advance of any work on src/

Key contents of src/

  • 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.
  • *.ump paired with *_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 UmpleTo* packages.
  • Json*, Umlet*, 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

Processing view

Diagrams will be placed here showing the flow among the various components: What is consumed and produced by what.

Testing view

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

Add a custom footer

General

Developers

Server maintenance

External

Other

Clone this wiki locally