Configuration crossover issues

This topic applies only to those upgrading from Together version 2.x. Users of Together 3.0 and above can safely skip it.

Together 3.x relied heavily on properties defined in its configuration files- much more than in previous versions. The 3.X configuration architecture, mostly carried over to version 4 and above greatly extends Together's customization capability. It is possible to customize almost every aspect of Together's appearance and functionality and you can effect the customizations at different levels. However, the implementation of this new architecture required extensive changes in the syntax of the definitions of the configuration properties as compared to the syntax used in Together 2.x.

Together 4.x changed the implementation of some subsystems, such as property Inspectors and the custom diagram capability, available in some products, from a basis on configuration properties to Java classes using the API.

Upgrading from version 2.x

The "bad news" for 2.x users is that it will be necessary to do your customizations again. The "good news" is that the kinds of customizations usually done in version 2.x can now be done much quicker and easier via the user interface.

Please note that not all changes in Together 2.x properties are described here because most of the changed properties can be now configured via the Options dialogs (Default, Project or Diagram Options dialogs). For example, the Together 2.x codegen.wrap_after property that controls source code line width is called autoformat.java.rightMargin in later versions. But it's not really necessary for you to know this. You simply set the desired line width in the source code formatting options in the Options dialog.

Some of the changes, such as changes in the inspector and codegen sections of the 2.x configuration file, are important to understand because many developers changed or added something to these and wish to transfer such changes to Together 3.x. This document will help familiarize you with changes in vital parts of the configuration system and where to find the same thing in the new architecture.

New structure of configuration files

Now Together has a set of configuration files contained in the ./config directory under your installation. These files contain properties relating to the same subsystem, or to the same aspect of functionality. For example, files inspector.config, print.config, diagram.config define properties for Inspector pane, Print page (Options dialog), and Diagram page(Options dialog).

Note, that this separation was made only for a practical reason - to group related properties together. You can create you own .config files in this directory, or add any properties to existing files. It does not matter in what file a property was defined.

Global changes in syntax

  1. "all" keyword used in Together 2.x to attach some property to all possible targets (languages, elements etc.) is now replaced with * (asterisk). For example,

    2.x: inspector.all.tag.all.Attribute.alias = String

    3.x: inspector.node.element.*.*.item.Properties.item.alias = StringField

  2. Multiline definitions: now it is possible to continue definition of a property on a new line if you place a backslash (\) at the beginning of the line. For example:

     
    inspector.node.element.java.Operation.item.Properties.item.visibility = ChoiceField(
    \   {
    \     values := { "public", "protected", "package local", "private" }
    \   }
    \ )

Changes in major properties sections from 2.x. Inspector (inspector.*) section in the Together 2.x config.properties file

In Together 4.x the $TOGETHER_HOME$/config/inspector.config file no longer exists. A new Inspector model is implemented through the API. For more information see Customizing property inspectors.

Note that names of some Together 2.x queries are changed:

In Together 3.x in these queries you must quote the name and the value of a property, so if in Together 2.x you wrote this:

then in Together 3.x you would write:

Codegen (codegen.*) section in the Together 2.x config.properties file

Codegen section is also considerably changed.

  1. Now the codegen definitions reside into several files corresponding to the language. So, the Java blueprints are defined in the java.config file, C++ blueprints - in the cpp.config etc.

  2. The syntax of blueprints is changed. For example, in Together 2.x the "aggregation as a Vector" blueprint was declared as following:

    codegen.java.blueprint.ClassDiagram.link.Aggregation as Vector.0 = "/**@shapeType AggregationLink"
    codegen.java.blueprint.ClassDiagram.link.Aggregation as Vector.1 = "@associates <b>%Dst%<b>"
    codegen.java.blueprint.ClassDiagram.link.Aggregation as Vector.2 = "@supplierCardinality 0..**/"
    codegen.java.blueprint.ClassDiagram.link.Aggregation as Vector.3 = "Vector %Name%;"

    In Together 3.x the definition is much more clear (note, the value is not quoted now):

    codegen.java.blueprint.link.Aggregation as Vector =
    /  /**@link aggregation
    \     @associates <b>%Dst%<b>*/
    \  private java.util.Vector %Name%;

    The general syntax for the blueprints is:

    codegen.<language>.blueprint.<blueprint_type>.<name>{.item.<item_name>} = <value>
  3. It is possible to group blueprints into a tree-like structure so that they will appear under the same expandable node in a pattern chooser dialog. To do that, create a blueprint whose value is group. For example:

     
    codegen.java.blueprint.link.Collections = group
    codegen.java.blueprint.link.Collections.name = "com.sun.java.util.collections (JDK 1.1x)"

    The .name parameter allows to specify the visible name of a group in a pattern chooser dialog. To populate the group, use the extended syntax described above:

     
    codegen.java.blueprint.link.Collections.item.Association as AbstractCollection =
    \  "/**@associates <b>%Dst%<b>*/
    \   private com.sun.java.util.collections.AbstractCollection %Name%;"

  4. The new feature of the codegen section is the ability to define a default pattern for some element by referencing an existing blueprint. This way, you can have several candidate blueprints for one default pattern (for example, for a default pattern for an attribute, you can define several blueprints with different types for an attribute), and can switch this default just by changing the referenced blueprint name:

    For example, the default pattern for constructors is defined as:

    codegen.java.default_pattern.member.Constructor = "Default Constructor"

    Here, the "Default Constructor" is the name of a blueprint defined in the java.config file:

    codegen.java.blueprint.member.Default Constructor = public %Class_Name%(){ }

    You can create your own constructor blueprint, for example, "My Constructor", and change the default pattern for constructors to use "My Constructor":

    codegen.java.default_pattern.member.Constructor = "My Constructor"
    codegen.java.blueprint.member.My Constructor = public %Class_Name%(boolean flag){ super(); System.out.println(flag); }

    After that, all constructors created by Together, will be created using your blueprint.

Locating other properties

If you didn't find information on some specific property here, try comparing the particular section of the version 2.x config.properties file with the corresponding *.config file in Together 3.x or greater. In most cases the visual comparison makes it quite clear how to change your settings so that they are now valid.

See also: