Integration into UML-modeling tool
The UML-integration is done on top of the UML-modeling tool Poseidon for UML, which is a commercial product shown in the screenshot below.
A free-of-charge “Community Edition” of Poseidon is available for non-commercial use. It will be necessary to register the Community Edition with a real email-address in order to receive long-term license key. However, the registration procedure can be skipped manually every time the program starts, which allows testing for at least some time without registration.
Download
- poseidonCE-3_0_1_03.zip from http://www.gentleware.de/index.php?id=114.
- sc-templates.zip from this page
Installation
- Make sure you have Java 1.4 installed to run Poseidon (1.5 is untested).
- Download poseidonCE-3_0_1_03.zip (other versions may work, but are not tested). The following steps have been tested with the „ZIP for any platform“-version on Linux.
- Install the software. When using the „ZIP for any platform“, just unzip it in a common place like e.g. “/opt”. The following assumes that the software is finally installed in /opt/poseidonCE3.0.1/, and that subdirectories like “/opt/poseidonCE3.0.1/lib” exist after installation.
- It may be necessary to set the start-script's executable-permission using “cd /opt/poseidonCE3.0.1/bin” and “chmod a+x poseidon.sh”.
- Try “./poseidon.sh”. If Poseidon does not yet start, it may be necessary to set the JAVA_HOME variable. If this cannot be done globally, edit the file poseidon.sh and add as one of the first lines: “JAVA_HOME=/path/to/java” (e.g. “/usr/java/j2sdk1.4.2_04”).
- Start “./poseidon.sh”. Test if everything runs with the built-in code-generation templates. Play around and create some dummy Java-classes.
- Exit Poseidon.
- Unzip the file “sc-templates.zip” inside the installation's “/lib”-directory (“/opt/poseidonCE3.0.1/lib” in the example). This will create a subfolder “/templates” in the “/lib”-directory (thus, “/opt/poseidonCE3.0.1/lib/templates” in the example).
- Start “./poseidon.sh” again. The editor of the "Source Code" tab should now show SuperCollider code skeletons, and the code-generation process (menu "Generation/Java...") will create SuperCollider source-files with the suffix '.sc'.
The free-of-charge Community Edition of Poseidon knows about Java code generation only. Installing additional languages besides Java is possible with the commercial editions only. In order to let the Community Edition generate SuperCollider code, the original Java code generation templates have to be replaced with new ones. The application will still label all items related to code generation with "Java", and even the template files to install are still called "JavaClass.vm", "JavaOperation.vm" etc. But despite the "Java"-labels everywhere: with the new templates, SuperCollider source-code will be generated. (Note that this method of customizing Poseidon's code generation process is not as hacky as it sounds. It is officially documented under http://www.gentleware.com/index.php?id=174.)
A little more on templates...
To create the "/templates"-subfolder in the "/lib"-directory, either unpack the archive "sc-templates.zip" into the "/lib"-folder (inside the archive, the files are stored in a "/templates"-subfolder, so "/templates" will be created on unpacking). Alternatively, unpack the archive anywhere you like, and create a filesystem soft-link to the "/templates"-directory inside ../lib (using "ln -s /here/is/my/location/templates" inside the "/lib"-folder).
The original installation reads its templates from the compressed archive file "templates.jar" in the "/lib"-folder. This file needs not to be removed, it will be ignored once a "/lib/templates"-folder exists.
Developing SuperCollider classes
The general sequence of steps is as follows (of course, each step will be repeated over and over to change something or add more, this is not a fixed sequence!):
- Create classes by adding class symbols to a class-diagram.
- Add attributes (“variables”) and methods (“functions”) to the classes.
- Add relationships between classes, if wanted (will appear as variables in the SuperCollider-classes).
- Select a class, or a single method to edit the source-code for.
- Change to the “Source code” tab in the edit-pane below the diagram. Now there's a text editor which displays some pre-generated parts of the source-code, and some space to edit the implementation. The pre-generated parts of the code are displayed on green background, to indicate that they cannot be edited when the cursor is above them. The editable parts of the code are displayed on white background.
- Finally, generate ordinary source-files from your model, so that your program can be run by SuperCollider. Chose the menu item “Generate / Java...”. This will open a dialog which allows to individually chose which classes or which packages are to be generated (and especially which not, so e.g. a package “sc-lang” can be ignored. See below on “Handling SuperCollider's own classes”). Don't be worried about the name “Java” appearing everywhere! As the original Java-templates had been changed when installing the sc-templates, Poseidon will generate SuperCollider code.
The figure below shows the code generation dialog.
The code generation dialog. (Again, don't be worried about the label “Java” appearing everwhere.)
- When getting errors on language-startup (the usual case during developing), do not correct mistakes in the generated source-files! These modifications will not be persistent, because they are not made in the model. Next time you generate the source-files from the model, any changes you have made directly to the generated source files would be overwritten. So always edit the source-code in the Poseidon's “Source code” tab below the diagram and then generate the source-files again from the model. The generated source-files loaded by sclang are only “materialized snapshots” of the model and should never be changed directly. (In the area of model-based development, this way of developing is called “forward-engineering”, in contrast to “roundtrip-engineering”, which would allow to make changes in the source-files, too.)
Mapping from UML elements to SuperCollider constructs
| - UML - | - SC - |
| Class | Class |
| Package | None, UML-packages are ignored for SuperCollider code-generation. They can be useful inside the UML model to organize classes. |
| Attribute | Variable |
| Static Attributes | Class-Variables |
| Methods | Methods ('messages'/'functions') |
| Static Methods | Class-Methods |
| 0..1 / 1..1 - Relationships | Variable (to be used as reference to one instance) |
| 0..* / 1..* - Relationships | Variable (to be used as List, continaing references to instances). (User-code must take care of initialization with an empty list.) |
| Type decalarations of attributes, function-arguments and return-values. | None except comments, the SuperCollider language in untyped. But including type declarations in the UML model will automatically generate comments in the code-skeletons which strongly increase readability of the code. |
| Public (+) visibility of attributes | Variable plus automatic getter and setter declaration (“”). |
| Package (~), Protected (#), Private (-) visibility of attributes | None, normal variable is used. Although visibility is not reflected in the SuperCollider language, it may be useful to distinguigh different levels of visibility in the model. |
| Public (+), Package (~), Protected (#), Private (-) visibility of functions | None. Although visibility is not reflected in the SuperCollider language, it may be useful to distinguigh different levels of visibility in the model. |
Handling SuperCollider's built-in classes
When using language-internal classes or datatypes, such as 'Object', 'List' or 'int', Poseidon will at first automatically sort those classes into the corresponding packages known from Java. E.g., when using 'List' in a new, previously empty, UML model, the Java packages 'java' and 'java.util' will automatically be created and 'List' will be sorted into there. This does not do much harm, because classes in the 'java.*'-packages will be excluded from code generation anyway.
However, other SuperCollider-classes do not coincidentally match in name with Java classes. As with any class completely new to Poseidon, those classes will automatially be created in the current package when used for the first time. E.g., if a method gets declared, and one parameter is marked as being of type 'Dictionary', a new entry “Dictionary” will show up in the current package. Of course, this class should not be there.
In those cases, DO NOT DELETE the automatically created class which appears to be there in error. (Your declarations in the model would lose their references to this class, too.) Instead, MOVE the class to a "neutral" package which does not belong to the model you are working on. Later, when generating the code, disable code generation for this "neutral" package.
It would be possible to just use the 'java.lang'-package as neutral package, because it gets excluded from code genration anyway. However, it is ugly to keep a 'java'-package in the model. Instead, create a package 'sc-lang' and move the declarations of used SuperCollider-classes like 'Dictionary' there (this is done by selecting the class to move in the element-tree on the left (or somewhere in a diagram), and then change the “Namespace”-entry in the “Properties”-panel to the target package where to move the class). Move also those classes to the 'sc-lang'-package that had automatically been sorted into a 'java.*'-package because of coincidentally Java-like names. Afterwards the 'java'-package of the model can be deleted.
Example
An example of model-based development with SuperCollider is the class-library for XML parsing and formatting, an implementation of the Document Object Model (DOM) DOM-Level-1. The file 'sc-xml-dom.zuml' from XML parsing and formatting - Download contains the parser classes loadable as a UML-model in Poseidon.
See also Unified Modeling Language (UML), XML parsing and formatting, Document Object Model (DOM).
jg
sc-templates.zip
