The Together-Bolero Plug-In enables you to use Unified Modeling Language (UML) modeling in Bolero development projects. Bolero projects can be visually analyzed, designed and maintained with the help of the Together UML CASE software, which makes the complete set of UML features available.

Since Bolero is a repository-based development suite, all information should be stored in the internal database. To allow external tools like Together to use Bolero project information, export/import procedures are provided in Bolero. Export/import facilities have also been implemented in Together.

There is no master-slave relationship between Bolero and Together. New projects can be created using either Bolero or Together, and then the information can be transferred from one application to the other using the export/import facilities. Nevertheless, it is possible to identify the relative strengths of Bolero and Together as follows and allocate tasks for project design and implementation accordingly:

Bolero:

- Is the only tool for complete development of Bolero objects, including

o Creation/modification/removal of existing Bolero objects (classes, interfaces, adapters, features, patterns and much more)

o Implementation of Bolero method bodies (writing Bolero implementation source code using the internal text editor, with syntax highlighting, syntax checking and more)

o Compilation of Bolero sources and building deliverable application

- Should be used as the primary information store, i.e. projects should be stored in the Bolero repository, so that sources can be compiled there and objects can be shared with other projects

Together:

- Is the only tool[1] for analysis and design modeling, including

o Creation/modification of UML diagrams, including Class, UseCase, StateChart, Sequence and others

o Complete development of Java classes, which can be reused by Bolero classes, including design, implementation, compilation, and maintenance of Java files in third-party RCS[2]

o Bolero-specific features are implemented as additions to Together. The standard behavior of Together is unchanged, and no features that apply to Java objects have been changed. For example, the user can calculate metrics for Java classes or apply Design Patterns

o Development of Java classes that are related to Bolero classes (for example, inherited from a Bolero class, or associated with it)

- Generation of complete documentation in Microsoft Word or HTML formats, including diagram pictures, design information and so on.

Note: In the documentation you may find some screenshots and feature names, a little bit different than in the version you have on your computer. Every build of Together may have improvements of the User Interface, new modules and new features. We hope it would not be a problem for you to find the correspondences.

2 How it works

Additional features have been implemented in Bolero and Together. This chapter describes how the two tools interchange information and how they manage projects.

2.1 Bolero side

Bolero provides a general facility for communicating with external tools by exporting and importing BAR files (Bolero archive files). When a project is exported, Bolero generates a set of files in XML format and packs them together into a BAR file. This file can be read by an external application. Similarly, an external application can generate a BAR file that Bolero can import, using the contents of the file to update repository objects or create new ones.

To make the interchange procedure with Together easier for the user, special tools “Together export” and “Together import” have been introduced. You can easily start these from the tools menu. When “Together export” is started, Bolero generates a file called BoleroTJ.bar in a special exchange directory[3]. When “Together import” is started, Bolero looks for a file called TJBolero.bar in the same directory and reads its contents into the repository.

2.2 Together side

In Together, the Bolero integration features have been implemented as a plug-in. This means that all parts of the product are modular and can be enabled or disabled by using of according Activation/Deactivation module [NE1] [4].

The plug-in is implemented as a set of Together’s modules and additional configuration files, which allow the visualization, creation and modification of Bolero objects.

By calling the “Bolero import” module, you can import the contents of the prepared Bolero project (see above) into the current Together project. After performing all necessary modifications, you must run the “Bolero export” module, which exports all information into the TJBolero.bar file, ready to be imported into the Bolero repository.

You can also create a Bolero project from scratch. In this case, the “import from Bolero” step is not necessary and you can start creating new Bolero classes and filling the methods with implementation code in Together. The next step is to export the project to Bolero, where the objects can be compiled and deployed.

Together’s extensive customizability allowsplug-in to configure the 'Object Inspector pane' so thatTogether can view Bolero objects in a completely different way than, for example, Java objects. It defined another view representation for Bolero objects on diagrams that has no impact on Together’s behavior when it is working on standard objects with plug-ins deactivated[5]. The design aim for the Together plug-in was to make the Together working environment as familiar as possible for the experienced Bolero user. Terms and names in Together have been chosen to be as similar as possible to the terms and names used in the Bolero Component Studio. On the other hand, a new user of Together should not become disorientated because of the sudden appearance of many new IDE elements when the plug-in is activated. Therefore, plug-ins do not modify standard elements of Together’s IDE, like toolbars and diagram panes. All Bolero-specific items (for example, “New Bolero Class”) are available through context menus of appropriate elements (a new Bolero class can be created from a context menu of a class diagram, and a Bolero Method can be created from a context menu of BoleroClass/BoleroInterface, but this would not be available for a Java class).

2.3 Description of the internal representation

Together is based on the “single source” concept. This means that it is not repository based, but keeps all model information directly in the source code. For example, if a class is defined in the source files, then Together will visualize that class in a diagram. If the class has methods, then the diagram object will also show a list of the methods. For more detailed information, see the Together documentation Together\help\Welcome.htm .

Standard Together supports Java, C++ (Together/C++ ) and other languages, but does not offer integrated support for Bolero. This means that it cannot parse Bolero source files and retrieve class declarations etc. from them. However, this is not absolutely necessary, firstly because the Bolero language is very similar to Java, and secondly because the Together plug-in imports information from BAR files into Java files, mapping Bolero features to Java features as it does so.

The creation of Java sources instead of Bolero sources is transparent for the user. Information defined in the Bolero Component Studio is available in the Together Object Inspector and/or on the diagram, so the user does not need to modify anything in the source code. All editing is performed in the Object Inspector. Users familiar with the Bolero Component Studio and with the Together IDE will only need a short time to learn how to manage Bolero projects in Together.

A typical Bolero class might be generated in Together as follows:

/**

* @Bolero

* @Class com.softwareag.repository.infomodel.bolero.BoleroClass

* @InfoModel com.softwareag.repository.infomodel.bolero.BoleroInfoModel

* @language 0

* @kind 0

* @classProperty 0

* @withPopulation true

* …

public class MyClass extends Object {

// List of methods

// List of fields

}

Together keeps additional information in design comments. All features that cannot be mapped from Bolero to Java can easily be stored in such comments.

As an example, the checkbox for the property “withPopulation” is shown in the Object Inspector. To modify the value of this property, simply change the state of the check box.

On import, the plug-in creates classes, representing Bolero objects, and marks them with the property “@Bolero”. This property is used by the Object Inspector to visualize Bolero properties, and by the export facility to generate corresponding XML elements for the objects.

Similarly, when you choose the “New Bolero class” command, a Java class is created, but the elements of the class are already prepared for storing Bolero information.

You will find additional information about the internal representation below.

3 Installation

3.1 Requirements

- Both Bolero and Together or greater must be installed on the user's computer[6]. Versions are: Bolero v 2.1.1Fix level 03 or greater, Together or Together/Enterprise.

- JDK1.2 (1.2.2 or greater is recommended) must be installed to run plug-in modules.

- The Together-Bolero plug-in does not require a lot of disk space (its size is approximately 200KB. The plug-in version 1.1 is delivered with Together 3.1 and greater and version of the plug-in 1.0 could be obtained separately for versions 3.0x). However, you should take into consideration disk space requirements for BAR files that are exchanged between Together and Bolero, which may require several megabytes, and also temporary files, which are subsequently compressed to form BAR files.

- System requirements for tools: see documentation.

3.2 Installing the Together-Bolero Plug-in for Together

There is no special installation required. The plug-in is delivered within Together/Enterprise edition

3.3 Installing the Together-Bolero Plug-In for Together [7]

The plug-in is installed into the top-level directory of the Together installation. This adds a few compiled Java classes into the module directory[8] (implementation of plug-in modules), and a few configuration files into the config directory[9]:

- Updates for the Object Inspector to visualize additional properties of Bolero objects

- Updates for View maps (allows visualizing Bolero objects with other colors, another set of compartments and so on)

- Updates for CodeGeneration rules (allows additional properties to be defined for new Bolero objects)

- Updates for menu (add s context-sensitive menu items for diagrams)

- Updates of tools definition (adds Delete Bolero Objects tool)

- Updates of general configuration (adds BoleroExchange directory name to list of ignored directories for parsing process).

Installation also creates an additional launcher file (TJBolero.bat). This file is a copy of the Tg_jre12.bat file delivered with Together with added –DBOL_ROOT=%BOL_ROOT% statement of Together launcher[10].

3.4 Uninstalling of the plug-in version 1.0 for Together

To uninstall the plug-in from Together you need to remove all Bolero-specific config files from the <Together_Installation_dir>/modules/com/togethersoft/modules/Bolero subdirectory: “zzz_BoleroXXX.config” files, where XXX are all suffixes like “Inspector”, “View”, etc. You may also remove implementation classes from the module subdirectory: <Together_Installation_dir>/modules/com/togethersoft/modules/Bolero – you need to remove all files from the directory and restart Together[11].

3.5 Uninstalling of the plug-in version 1.1 for Together

There is no uninstallation procedure for the plug-in delivered with Together 3.1x. Use deactivation facility of the plug-in to disable all extensions provided by the plug-in.

4 Work scenarios

4.1 Activation of the plug-in v1.0 in Together

The plug-in version 1.0 is separate product and has to be installed separately. After installation of that Together will run always with Bolero additions, until user will uninstall the plug-in. See Installing the Together-Bolero Plug-In for Together 3.0x for details.

4.2 Plug-in activation in Together

In Together and over Bolero plug-in is integral part of the product. To enable or to disable Bolero-specific extensions, Activation modules should be used.

There is module: “Bolero Integration”. When Activate command is used, it loads set of additional config files and allows starting Import/Export modules. The mode is remembered till deactivation will be used. I.e. after restart of Together Bolero-mode would be kept.

When “Bolero Integration” module is started mode is changed immediately (all related files are loaded by the module), but you need to update open views to see changes on them (just select in diagram context menu “Update” and you’ll see the changes).

4.3 Plug-in activation in Together

To deactivate Bolero plug-in you have to start “Bolero Integration” module with Deactivate command (see picture above). This will unload Bolero-specific configuration files. After launching of the module you have to update diagram (or switch to another object to update Object inspector table) to see changes immediately.

4.4 Bolero èTogether

This section describes the steps necessary to export a Bolero project to Together.

To export a project prepared in the Bolero Component Studio to Together, select the project (the project is now active) and choose the Tool/Together Export feature to export the project. The file BoleroTJ.bar is now created in the exchange directory[12].

You can now switch to the Together IDE and import the BAR file that you have just created:

- Create a new project

- Specify project properties (select Java language as project default language)

-After clicking OK and project creation, select the module navigation pane and launch the "Bolero import" module:

(Note: To start the module, click the right-mouse button on the module name. The context menu “Run” will appear.)

For Together version 4.1 and plug-in version 1.1 the picture would be:

- Before running the module, you may open Together’s message window in order to see information messages from the process[13]. Also, a progress indicator appears in the status bar area.

- When the hourglass cursor disappears (the message “Import finished” appears in the message window if it is open), the imported information is available for use.

Any items that were not recognized by Together during import (for example, database specific information is not managed by Together) are stored in special subdirectory of the project (<project_dir>/BoleroExchange)[14]. This information is therefore available for export. Each time an import is started, the BoleroExchange directory is cleared, so that mixing of “unknown information” from different Bolero projects is prevented.

4.5 Together session (designing Bolero projects in Together IDE)

You can modify projects imported from the Bolero Component Studio by modifying Bolero classes, their features and the relationships between them and introducing new objects. You can also design new Bolero projects from scratch.

The second method is very similar to the first, except that it is obviously not necessary to import information from Bolero, so that the process starts with the creation of new classes or analysis diagrams.

A unique feature of the integration of Together and Bolero is that it is possible to develop projects in mixed mode, using Bolero classes and Java classes together in one project. For example, you can create a Java class inherited from a Bolero class.

New Java objects can be created in Together using the normal techniques, for example via toolbar buttons, or via the context menu on the diagram background. In contrast, new Bolero objects can only be created via the context menu of the class diagram:

Bolero method in a Bolero class is created in the same way:

4.5.1 Storing design information

You can use Together features such as assigning cardinalities to association links, changing association relations to aggregation, and so on. Bolero does not allow this information to be stored separately in its repository, although it is possible to keep this information in the description of the Bolero object. After importing a project from Together into Bolero, you may see that the description information has been augmented by design information from Together, as shown in the following example:

Of course, the description field can be modified in the Bolero Component Studio. You may modify Together design properties, but this is not recommended, in order to ensure the integrity of the information[15].

4.6 Together è Bolero

This section describes how to export a Bolero project from Together to the Bolero Component Studio.

When you wish to continue work in the Bolero Component Studio, run the Export to Bolero module:

For Together 4.1 the picture will look like:

During the export procedure, a TJBolero.bar file is created in Bolero’s exchange directory. It contains the following information:

All objects (both previously-imported objects and newly-created objects) represented in the Together IDE.

Any objects that were not recognized during import process to Together (these objects, for example database specific objects, are retained during importing and exported unchanged).

4.7 Features of round-trip processing

This section describes special features of the round-trip (export/import cycle) procedure. Any information that cannot be interpreted by one of the products (either Together or Bolero) might be lost. In this case the tool prompts the user; however, you should be aware that loss of information can occur. For example, it is required that all objects (both classes and text documents) located in one package must have unique names. It is preferable to introduce new diagrams with unique names, rather than resolving names after an error message during the export procedure.

4.7.1 Multiple imports

It is possible to initiate several imports from Bolero without an intervening export. This may cause problems when the project is exported to Bolero for the following reason:

On import, Together stores all unrecognized object declarations in a specific intermediate directory (<Together_project_dir>/BoleroExchange). When the export procedure is initiated, Together generates declarations for all known objects, and adds to them the information from the BoleroExchange directory. This enables all the information to be kept together, and ensures that nothing is lost during the round trip. Note, however, that the BoleroExchange directory is purged when the import procedure starts. This means that “unknown” information from any previous imports is deleted whenever a subsequent import is performed.

The import module first checks for the existence of Bolero objects in the Together project. If no objects with a @Bolero tag are found, import is enabled (this allows Bolero projects to be imported into pure-Java projects to extend the first one). Otherwise, the import procedure prompts the user about the impossibility of importing the two Bolero projects into one Together project.

Importing different Bolero projects into different Together projects is enabled.

Importing one Bolero project into several Together projects is also possible. In this case synchronization would be done on the Bolero side: the most recently imported project (i.e., the project most recently exported from Together) updates any previously imported project.

4.7.2 Multiple exports

It is possible to initiate several exports for one Together project. This is allowed, and Together keeps all necessary information ready for exporting, however many exports actions are initiated.

If a new class is created between runs of the export procedure, the class declaration is added to the BAR file[16]. This allows the user to fix errors, if any, which appear during export. For example, the syntax of Bolero method parameters is not checked on the fly, but is only checked on export. If an error is detected, a message appears during export, the user can solve the problem and run the export procedure once again.

An additional feature of the export procedure is synchronization of the sequence diagram with associated sources. If a new object in the sequence diagram is associated with a Bolero class (a new one, created by the user in the Together session), sometimes the properties of operation assigned to a message trace will be shown on the diagram incorrectly[17]. The export procedure synchronizes Bolero method declarations with their Java equivalents. After the application of export name and parameters of the Bolero method on the sequence diagrams, everything will be correct[18].

Note: Bolero supports only one import file from Together. Each export from Together creates (or overwrites) TJBolero.bar file in the Bolero exchange directory. It is not possible to initiate multiple Bolero exports from different Together projects without importing each project in turn into the Bolero Component Studio.

5 Troubleshooting

A list of possible problems and their solutions.

1. Cloning Bolero objects can cause errors when the project is imported into Bolero. Each imported Bolero object has a unique OID (object identifier). This allows the maintenance of relationships from other Bolero objects to this one (for example, a database field might be associated with a Bolero Class Field). When the object is cloned, it is copied completely – i.e. with all properties[19], including its OID. This causes problems when the object is imported into the Bolero Component Studio, because two different objects have the same OID.

2. Manual merging of projects. Together is a single-source technology CASE tool. This means that all information for class diagrams is kept in the source code. Suppose the user has two Bolero projects and two corresponding Together projects. Copying files from one Together project to another allows the user to see merged information (i.e. merged classes/packages/diagram list; the method lists of two classes that have the same name are not merged). However, this project will not be correctly exported to the Bolero Component Studio for two reasons:
- Objects in different projects may have the same OIDs (see above)
- If additional information of the import (database-related information, Bolero Patterns, external documents, etc.) was available, the information would be lost or exported incorrectly (relationships between these objects and classes could be broken).

3. Selection of Bolero methods in the Sequence diagram is not correct if the method was created in Together (not imported from a BAR file). When a Bolero method is created in Together, the information about its name and parameters is stored as design comments of the newly created Java method (the physical Java methods are created with names NewMethod1, NewMethod2, etc.). When trying to select the method as associated for the message trace at the sequence diagram, the user sees a list of physical methods. To see which Bolero method is associated with a particular physical method, choose the “More…” menu topic, and then enter the 'Properties'. In the Object Inspector pane, all information is displayed correctly.

You can now start the export procedure, which synchronizes the Bolero and Java specifications of the methods[20].

4. Selection of Bolero operators in Sequence diagram. When trying to associate Bolero operators with the message trace at the sequence diagram, the names of the operators “*”, “/” and others are not displayed correctly even after starting the export procedure. Unfortunately, the operators are not mapped to Java at all and the synchronization of their names could be lost. It is recommended to specify a text description for the message trace instead of selecting the method from the list.

5. Get/Set methods of Bolero attribute are not accessible in selection list when assigning operation to the message trace in the Sequence diagram. The get and set methods do not exist as separate objects in the Bolero language, therefore they are not defined separately in the Java representation. Specify a text description for the message trace instead of selecting the method from the list.

6. Projects with several design diagrams are imported to Bolero with exceptions. The Bolero Component Studio has a limitation that all objects in one package must have unique names (the namespace includes both classes and text documents). Diagram files of Together are stored as text documents in the Bolero repository, so they should have unique names. By default Together creates diagrams with names “Untitled1”, “Untitled2”, etc. for every type of diagram. The files have different extensions, but this is ignored by Bolero. To create a named diagram, specify the name in the “New diagram” dialog:

If a diagram has already been created, it can be renamed in the Object Inspector area (click on the navigation tree on the diagram; the appropriate ObjectInspector appears and the diagram can be renamed).

7. Several features of Together are not applicable to Bolero classes (or to projects containing such classes):

- Generation of Sequence Diagram from Bolero sources

- QA features are limited in usage (some metrics, for example, calculating percentage of commented source code, would return incorrect results)

- Cloning of imported Bolero classes/class members is not supported

- Patterns, which requires method body implementation changes, are not applicable to Bolero classes

- “Add linked” feature will be unavailable for ‘Association’, ‘Dependencies’ and ‘Other’ for classes, which have parameterized associations/parameters of methods and other non-Java features used[21].

- Tools, registered for Java objects (Compile, Debug, etc.) will not work correct for Bolero classes (this will NOT start Bolero compiler or debugger). Opening of external text editor for Bolero objects is not recommended. Switch to Bolero Component Studio when you like to implement Bolero source code in more fashion way.

- Generate HTML Documentation may show in result some specific tags, usually hidden from the user. Also some other tags would be shown in the form as they represented internally in Bolero repository. For example “featureKind 0” would mean “FeatureKind concrete”.

8. If you will create some design objects on default class diagrams (the diagrams, which are creating automatically and representing physical packages (directories) - *.dfPackage files) the objects would be lost after round-trip. Create additional notes and other design objects on Class diagram (via New Diagram – ClassDiagram) or on diagrams of other types.

[1] In contrast to Bolero, Together has competitors in the UML CASE tools area, but it uses unique technologies (patents pending) which allow particularly tight integration with Bolero.

[2] Together does not have its own compiler or RCS, but is delivered with public domain ones and has powerful configuration facilities which allow your favorite tools to be used for these purposes.

[3] Bolero specifies the system environment variable BOL_ROOT, which usually accords to the root directory of the Bolero installation. Under the subdirectory exchange/together of this location the BoleroTJ.bar file will be stored.

[4] The set of available plug-ins for a user is defined by Together license key of the user. If the user doesn’t have an appropriate license to activate a plug-in he has to obtain a new license key.

[5] Bolero classes are shown with a blue background.

[6] It is also possible that the user will implement only the design part of a Bolero project without compilation of Bolero classes. In this case he only needs to have Together installed and should copy the resulting BAR file to another computer, where Bolero is installed to continue work with the classes.

[7] The separate installation of the plug-in is ONLY required for Together 3.0 and 3.0x, but the plug-in version 1.1 is already preinstalled in Together 3.1 and greater. Together 4.1 not requires installation of the plug-in, it is enough to install Together 4.1 itself.

[8]Together extensions hierarchy is changed a little in Together 4.1 – since this version the plug-in classes are located at modules/com/togethersoft/modules/bolero subdirectory of Together installation.

[9] In Together 4.1 config files reside in the same directory where classes are placed, the files are not mixed with standard ones.

[10] This allowed to path value of system variable, specifying location of Bolero installation.

[11] In fact, you may keep implementation classes without removal, if you will not start the modules, Together will run absolutely the same way as it before the plug-in installation.

[12] The directory name and files there are not important for the user because the exchange procedure is completely automatic (user should just activate it)

[13] If the user did not open the window it will automatically open if any errors occur during the import process.

[14] The directory name BoleroExchange is included into the list of ignored names. In the project using of packages with this name is disabled.

[15] If the user makes any errors like misprints when correcting Together staff, the relevant property will disappear from the diagram pane in Together session, but it will not be deleted from the sources. So it would be possible to fix the problem later, but anyway it is better to prevent problems than to resolve them.

[16] .bar file is overwritten every time and contents of that are: declarations of all objects represented in Together session + all objects stored from import (“unknown objects”).

[17] Sequence diagram elements are associated to Java constructions, but Bolero methods are not directly mapped to Java (types of parameters could be parameterized and information about them is kept in design comments (so the signature of the Java method does not accord to the Bolero method).

[18] Actually as close, as possible, for example for the bolero method: “Object myMethod (Array {String} a)” on the message trace “myMethod (Array__String_)” will be shown, because it shows the signature of the Java method. Another exception is for the Bolero operators (“+”, “*”, etc. method names are allowed in Bolero), which are completely not mapped to Java, for such methods synchronization is not possible, and it’s recommended not to associate the message trace with such operators (just assign the method name textually or look to the properties of the associated method to see the Bolero name)

[19] On cloning names are usually changed (like clone of MyClass will create new class with name MyClass1 etc.)

[20] Unfortunately, even in this case the selection would be possible with some limitations: instead of “foo (int, float, Array {String})” user will see “foo (int, float, Array__String_)”

[21] This means, for example, if one class has a parameterized attribute of type of another class, the relationship would not be recognized by “Add linked” module. Though if the class has another attribute, defined without template, the relationship between classes will be found by the second attribute.