Readme
File
 
Together 2.2
ABOUT PORTABILITY INSTALLATION STARTUP GETTING HELP VERSION HISTORY

Thank you for your interest in the Together® family of object modeling tools. The readme files provide late-breaking information and things you should know before installing the product. You may also want to have a look at the Frequently Asked Questions (FAQ) file before you proceed to installation or using the product. Information in this file is applicable to all Together products unless otherwise noted. Platform-specific readme files are provided. 

About Together

Together is the first platform-independent UML™ modeler that delivers simultaneous round-trip engineering.

Together includes the following features (new features in version 2.2 are marked with **; new features in versions 2.x are marked with *):
 

  • Simultaneous roundtrip engineering based on the source code
  • UML™: use-case, package, class, sequence, collaboration*, and state. Plus Coad: object models and scenario views* 
  • More deep integration between diagrams**: importing physical and logical packages mutually, exchange of UML diagrams' elements
  • Fully customizable* code construction and round-trip engineering 
  • Large project support: display control (by element, by category), view management with autoupdate (physical and logical package content), source and diagram-layout files (as scalable as your file system itself) 
  • Server mode support: multi-platform, multi-user installation in a shared directory**
  • Documentation generation (HTML doc. gen. Framed document and image maps of all diagrams.* Clicking on a class or member in the image displays the corresponding text documentation.) 
  • Generic documentation generation in customizable format (RTF and HTML included)**
  • External tools access* (invoke your favorite Editor, IDE, or version control system directly from within Together)
  • Import from and export to Rational™ Rose™* 
  • Extensive configurability* (key system properties are now modifiable in configuration file, including: text editor tab size, highlighting of diagram elements, code generation and parser blueprints, file templates, default stereotype list, stereotypes in color); customizable Text Editor**
  • Versatile in-place diagram editing (Full-declaration editing of attributes and operations.* In-place editing of link labels, roles, and cardinalities.* Optional auto-detection and display of dependencies.*) 
  • Together scripts: open Script API for user's development.*
  • Tested on the most popular operating systems and Java™ Virtual machines (refer to Portability topic for the last information about supported platforms)

Portability

Together has been tested* on most popular OS + JavaVM combinations.
The information specific to operating systems is organized in separate readme files. There you can find the information about the Java versions, under which Together has been tested. However, you can run Together under other Java Virtual Machines, but we cannot predict the results. We would appreciate any reports from you about the experience of that kind.

Windows NT and Windows 95/98 users:

Proceed with readme_windows.html

OS/2 users:

Proceed with readme_os2.html

UNIX users:

Proceed with readme_unix.html
This covers different UNIX systems, Linux, Sun Solaris, and different hardware platforms, Intel-x86, SPARC.
Mac is still being tested

However, this file continues with the information applicable to all the operating systems.

*"Write once, run anywhere" Java apps still require testing (no surprise). As Java application developers, we sometimes find the need to write some additional code to work around defects exhibited by one or more VMs. No big deal.


Together Installation

Together has a pure-Java installer as well as platform-specific installers. The installation process varies depending upon which product version and which variant of the installer you have obtained. All installers for all products provide a wizard to guide you throught the installation.

License installation

The Together installer first looks for a license file in the setup directory. If none is present, it checks the destination directory and preserves any existing license file found there. If no license file is present in either location, the product installs to the specified destination directory with Whiteboard Edition feature set and license. In this case the installer offers a choice of the supported source language. Together in Whiteboard Edition will only work with the projects of the selected language.

Installing over previous versions

Since 356 build, Together installer preserves user's configuration properties and lisence file. The upgrade to the next version of Together would be easy if you choose the same destination directory in the installator. CAUTION: However, some previous builds can cause missing of your files. Observe buildnum.txt file in the installation set and conclude which recommendations you should follow. Or follow them all, if you are not sure.
    1. Always back up your existing license file (./bin/license.tg)
    2. Back up your configuration properties (./lib/config.properties), if you have modified them manually, e.g. to alter code-generation blueprints, tune script loader, etc.
    3. Back up your Together properties (./lib/together.properties), if you wish to keep Global Options settings, made from the Global Options dialog.
    4. After backing up your files, either completely uninstall the previous version, or install the new version to another folder.
    5. If you install to a different folder and you find you have a different product version or edition than you had previously, copy your backed-up license file to the new installaiton's ./bin directory, overwriting any existing license.tg file.
    6. Then either insert your changes from your backed-up config.properties and together.properties to the new ones, or copy them to your project directory. The last hint enables automatic merging of the property files. In addition you can use command line options to specify additional directories for properties files.

Using the pure-Java installer:

You can use the pure-Java installer with all supported operating systems and Java VMs. The Java installer ships as a compiled Java class.
You must already have a supported Java VM installed on your computer in order to use the pure-Java installer. For information on supported operating systems see the Portability section above and check the corresponding readme file for your OS.

To install Together using the Java installer:

  1. Run together.class in your Java virtual machine and follow the JShield Wizard's instructions.
  2. Choose the destination directory where Together is to be installed.
  3. Choose the supported language for round-trip engineering. This choice is skipped, if you have already a license file either in the installation fileset or destination directory.
  4. Afterwards, optionally copy your license file to the bin subdirectory and accompanying files (e.g. this readme file) to the top product directory.
Should you experience installation problems, please check the  FAQ file  (faq.html) where you'll find answers to many questions including known installation issues.
 

Server installation 

During installation you will be prompted to choose between Workstation or Server installation variant. The variants differ by fileset and by processing with property files.
The server installation installs all the platform-specific runnable files (Together.exe, Together.bat, Together.cmd, and Together.sh) and creates in addition three subdirectories under %TOGETHER_HOME%/bin directory for three platform-specific oistart tools: The properties are loaded first from the host.properties, together.properties and config.ptoperties files from %TOGETHER_HOME%/lib directory.
Next, the properties are loaded from together.properties file in the current working directory, if present, and this file serves to store changes in Global properties. The properties are written on exit and on pressing OK in the Global Options dialog.
This policy allows to provide to a number of users with corporate set of properties, e.g. with styled code-generation, and leaves freedom to have own user's properies.


Start-up

To start Together in any Java machine

  1. Start command line (console, DOS prompt, etc.)
  2. Change working directory to /Together/bin (assuming you've installed the product to /Together)
  3. Find the command-line file (script, batch, etc.), which has the name Together and the extension appropriate to your OS (.bat, .cmd, .sh)
  4. Execute this file.

  5. The command-line file is configured by the installer, however, it may require additional corrections according to your environment and Java VM installation.
    Note that the only command in it should call the Java VM on your computer, pass to it the proper classpath with both Together classes and standard classes, and specify oisoft.together.Main as class to execute.

After startup:

For more information, see the Getting Started part of the Help.

Opening a project file on start-up

The first parameter in a call of Together (the concrete file name varies depending on OS and JVM) specifies the name of the project to be automatically opened. If you start Together manually from the command line you can specify the existing project name. (Together project files have a .tpr extension.)
See also: Command line parameters topic of the Help.

Remote access for system properties 


Getting Help

To open Together included documentation in your HTML browser, choose commands on the Together Help menu or simply press Ctrl+Shift+H key in any of Together's windows. Since you are already reading this text in the browser after installation, just click this hyperlink to open the Help contents.

You can find answers to a number of frequently asked questions in the FAQ document: faq.html. This document includes general information and troubleshooting sections. If you have questions that are not covered in FAQ, information and support are available from:
 
North and South America:  Object International, Inc.
1720 Leigh Drive, Raleigh, NC 27603-5159, USA
World Wide Web: http://www.oi.com
 E-mail for info: info@oi.com
E-mail for support: support@oi.com
Tech Support Hotline: 1-919-773-1063
Phone: 1-919-772-9350
Fax: 1-919-772-9389
UK and Ireland: Object UK Ltd.
PO Box 64, Southampton SO15 5TG, UK
World Wide Web: http://www.objectuk.co.uk
 E-mail for info: info@objectuk.co.uk
E-mail for support: support@objectuk.co.uk
Phone: +44-1703-399990
Fax: +44-1703-399991
Rest of the World: Object International Software Ltd.
Schulze-Delitzsch-Str. 16, D-70565 Stuttgart, Germany
World Wide Web: http://www.oisoft.com/
 E-mail for info: info@oisoft.com
E-mail for support: support@oisoft.com
Phone: +49-711-787-100
Fax: +49-711-787-1017


Version History 

(This is the last section in this file)
Changes made to product since the official release of Together 2.1 (build 352):
  1. Server mode support.

  2. For more information about installation and operating see Server installation in this document.
  3. Command line options / remote properties.

  4. See new topic "Command line parameters" of User Reference and Remote access for system properties in this document.
  5. Together can run documentation generation and scripts in command line mode.

  6. New command line parameters added: Each of these should be used with the project name parameter.
    For more information refer to the Help, User Reference, Command line parameters.
  7. Tags (in design comments) can have optionally multiple instances.

  8.     The tag should be declared as multiple in the config.properties by adding the property:
        inspector.<language>.tag.<diagram>.<tag_name>.<name>.multiple = true
        By default the property is added for the "see" and "param" tags.
    For such a property the extended editor dialog is invoked with the ellipsis button of the tag field in the inspector. The editor look and functionality differs for tag of String and Multistring types.
  9. Static members are displayed underlined in Analysis mode also.
  10. The order of design tags in code generation can be configured. See the details in the section of config.properties file for codegen.all.tag_order.* options.
  11. Symbol @ can be used in Java-doc tag values. See parser.javadoc.tag_starts_line option in config.properties.
  12. Code generation of Java-doc comments are cutomizable allowing to create box-comments. See description for codegen.javadoc.line_prefix and codegen.javadoc.content_indent options in the config.properties.
  13. 'Unlink' command for imported classes is renamed to 'Delete from view' (in the popup menu).
  14. Code generation is now configurable for members and classes created in diagrams.

  15. Code for attribute/operation is generated accordingly to a pattern.
    See comments before codegen.cpp.blueprints.* in config.properties for more info.
    Default blueprints are also provided in config.properties.
  16. Code generation for Aggregation links is changed to vector by default (Java)
  17. The cardinality tags are removed from Aggregation links generated by default
  18. The generated cardinality "zero-to-many" is changed from * to 0..*
  19. Choose pattern is enabled for operations.

  20. Note : choose pattern dialog is enabled only for operations with empty body, because applying a pattern removes the existing body.
  21. Pure links (attributes-as-comments) created with Together/Pro are recognized. On change, they are rewritten in the new form.
  22. Import in non-class diagrams.

  23. Import command is provided in the Use Case and State diagrams popup menu.
    The Import dialog invoked shows the Use Case / State diagrams (correspondingly) on the project tree.
    It allows importing of top-level (not nested) Use Cases (Actors) / States into the current diagram.
  24. Clone diagram functionality is implemented.

  25. Clone diagram command is added to the popup menu of diagram items in the Navigation pane,
    that allows to create copy of non-class diagram with another name/in the another package.
  26. Clone class is implemented - new command in class popup menu.

  27. Note: currently it is implemented for Java only.
  28. Text Editor colors are customizable.

  29. New page in Global Options dialog. Invoke help from that page.
  30. New tools macro added: $CLASS_NAME$

  31. It returns class name when target is a class or a class member.
    For Java projects the macro expands to the fully qualified (dot-separated) name;
    For C++ - just into the class name identifier.
  32. Order of commands in Tools menu is changed to follow the importance-for-user order
  33. Tool filters for parsing tools output and producing navigatable messages in the Message window.

  34. They can be defined in config.properties and then assigned to tools in the Tools Options dialog.
    See description for "tools.filter.*" options in config.properties.
  35. Option to Generate documentation for the current diagram and all contained subdiagrams. See Generate documentation dialog.
  36. Import dialog : multi-selection a group of items with Shift-clicking is added.
  37. Option dialog :

  38. Options | Classes | Associations | "Association as label" is renamed to "Association as attribute".
  39. User config.properties and together.properties are backup'ed on the installation above the previous version.
  40. Bug fixing :
  41. New MS VM for Java  5.00.2924 from SKD for Java 3.1 is bundled with the corresponding installation.
  42. Installation of C++ samples for Whiteboard edition (depending on language choice during the installation).
  43. Samples:
  44. Scripts:
  45. Choose pattern dialog for links is divided into two parts: Link patterns and and Attribute patterns.

  46. If a selected attribute is recognized as a link, the link tab is activated; otherwise attribute's tab.
  47. Language choice is removed in Together/C++ only edition (previously it have been just disabled).
  48. Use Case diagram: extends link between actors are optionally allowed.

  49. It is available optionally - config.propreties:
    model.allow_actors_generalization
  50. Together launcher (Windows) functionality improved :

  51. it can optionaly start with specified VM (if it is found) :
        -sun command line option should be passed to the launcher to make it look for Sun JVM first .
  52. Changes to the Companion :
Changes made to product since the official release of Together/J 2.0 (build 338):
  1. C++ functionality improved (including bug fixing)
  2. Java scripts in source and Script API sources added to installation. See Chapter 6 in the help/UserGuide/Scripts.html about script support and script.loader.* options in config.properties
  3. JPython scripts support. See script.loader.usepythonscript option in config.properties
  4. IDL™ for COM and CORBA™ generating scripts is now supplied
  5. Blueprints groups for link implementation as JGL 2.x, JGL 3.x and JDK 1.2 containers are designed. The groups are selectable in the Global Options dialog, Code Editor page. The blueprints can be used with the “Choose pattern” dialog. See help/UserGuide/DiagramOptions.html, "Code Editor tab", and help/UserGuide/ChoosePattern.html, "Choose pattern dialog"
  6. [C++]  ./lib/preinclude.inc  now includes macro definitions for Borland C++ 5.0 and Borland C++ Builder in addition to MS Foundation Classes. See comments at the head of preinclude.inc for further information.
  7. [C++] ./lib/preinclude.inc is now being merged with the one from project
  8. [C++] processing list declarations
  9. Indentation of automatically inserted text on code generation is customizable. See codegen.indent option in config.properties
  10. Working with Rose comments and Together/Pro (previous generation of Together) comments is supplied. Old comments are rewritten in the new form if they or their corresponding element change
  11. View commands for resize the panes are changed to High pane, Wide pane, and Maximized pane. Their shortcuts are changed correspondingly: Ctrl+H, Ctrl+W, Ctrl+M. The hot key invoking the Help (previously Ctrl+H) now is Ctrl+Shift+H. See Help, User Reference, "Basic Shortcuts"
  12. The Import dialog is modified and importing itself is expanded. Major points are:
  13. See ./help/UserGuide/Import.html/Import.html for more information.
     
  14. Blueprints for classes feature is implemented with a choose pattern field in the Inspector.
  15. It is now possible to print on continuous rolls of paper- arbitrary paper size can be set in Print options.
  16. Default options changes :
  17. You can now enter a command line option at start-up that specifies a remote directory to search for together. properties and host.properties files. See Startup section above.
  18. Product under Windows is started with new launcher together.exe, which checks for installed VM and then either launches jview or jre.
  19. Auto-dependency links appearance changed - they are shown in blue color and dashed (like manual dependencies).
  20. Scripts support: