About Scripts

Together offers means to access modeling information, prepare design and software documentation in the user-specified formats, export to various file formats, and develop patterns and wizards.
 
Together supports scripts in the 3 scripting languages: Java itself, TCL, and Python.

Java scripts in Together are simply Java classes. The scripts access model information using open Script API  that provides extensive customizations to support the individual needs of a wide variety of system modelers and developers. The script is as flexible as Java itself. A script in Java is a class implementing the oisoft.togetherx.scriptapi.Script interface.

You can create, edit, and run scripts within Together using intensively the model information from an open project. Scripts may generate documents and software presentations based on the project.

TCL and Python scripts are running by the corresponding subsystems of Together. Since these are interpreting scripts, no compilation is required.
For the information on TCL scripts and language refer to http://www.scriptics.com
For the information on Python scripts and language refer to http://www.python.org

Scripts feature availability

The extent to which you can work with scripts depends upon your license. Access has 3 levels: (1) no access to scripts, (2) access to run ready-made scripts, and (3) access to custom scripts development.

You can edit a Java script in the Together editor even if your product version does not have round-trip engineering for Java. You can run scripts when any project is open, or, if your script is not dependent on model information, when no project is open.

Note: Java scripts in source are DISABLED by default. To enable Java scripts in source, locate the following line in the ./lib/config.properties:

;script.loader.usescriptinsource = true

and uncomment this line by deleting the leading semi-colon (;) character. Reload properties if Together is already running.
 

Script API

Together (starting from version 2) offers the open API to allow the advanced user to develop scripts in Java accessing the Model information. Refer to Script API reference documentation located in the  ./doc/scriptapi directory.
 

Directory structure of Script processing system

 

$TOGETHER_HOME$/source

source base directory, created on installation

$TOGETHER_HOME$/source/oisoft/togetherx/scriptapi

sources of Script API interfaces: required for compilation, created on installation

$TOGETHER_HOME$/source/oisoft/togetherx/scripts

directory for script sources.  Created on installation, this directory contains source for a number of sample scripts.  Place your own script source here.

$TOGETHER_HOME$/scripts

directory for TCL and Python scripts.  Created on installation, this directory contains sample scripts.  Place your own TCL and Python scripts here.

$TOGETHER_HOME$/classes

compiled classes base directory, created on installation

$TOGETHER_HOME$/classes/oisoft/togetherx/scripts

directory for compiled scripts, created on installation  This directory contains ready-made precompiled scripts that can be invoked from the Tools menu.  These are scripts for COM IDL files generation, RTF documents generation and converting to Rose 98 files.  Place your own compiled scripts in this directory.

$TOGETHER_HOME$/out

default directory for scripts' output documents, created when necessary

Note: The $TOGETHER_HOME$ variable represents the root folder of your Together installation.

Working with compiled Java scripts

Some compiled scripts are established directly in the Tools menu. E.g. to run the script that generates IDL sources from the current model, call Tools | Generate IDL from the main menu.
All the compiled scripts (which files are located in ./classes/oisoft/togetherx/scripts) are accessible through the Open Script dialog. Choose Tools | Open Script to open it. Select the script name under "Compiled" tab and click Run.

The further concrete functionality depends on the script invoked. As a rule, a script writes some information to output stream. In this case the File dialog is opened enabling you to assign a file for output.

Output Document

If your script generates an output document and calls APIManager.getOutputStream() and/or APIManager.getOutputDirectory() methods, the Save As file dialog is displayed.

Enter the name for the document.
By default, the documents are written to $TOGETHER_HOME$/out directory, but you can choose another using the dialog.

Developing own Java scripts

If you have a full-rights license and if your config.properties file contains the line:
script.loader.usescriptinsource = true
then on calling Tools | Open script menu command, the extended Open Script dialog appears.
This dialog contains additional page, "Java", and two additional buttons, Create and Edit. In the "Java" page you will see the list of Java files found in ./source/oisoft/togetherx/scripts directory.

Creating Java scripts

To create a new script, click "Create" button. The Create script dialog appears.
For creating the simplest script you should just enter its name and press OK.
When you choose Tools | Open script next time, the new script is listed in the "Java" page. You can edit or run it.

With the Create script dialog you can also include some frequently used features in your script using checkboxes in the "Options" bottom left panel.
 

• Check "Extend UMLVisitor class", if you want to use "Visitor" pattern in your script;
• Check "Use output stream", if your script will write some output;
• Check "Open external viewer", if you want the output file to be opened automatically in the application associated with the file extension after the script finishes;
• Check "Customize script", if you want to customize some properties of your script before execution.
For customization of your script before execution, you can use properties.

    To make it:

1. Check "Customize script" checkbox;
2. Add properties you need clicking "Add property" button in the Create script dialog;
3. For each property, enter the name, the type and the initial value in the dialog displayed.

Editing Java scripts

To edit Java scripts in Together:
1. Open any project.
2. Select the script, you want to edit in the Open Script dialog.
3. Click Edit to open the script source code in the Text pane.
The script source file is automatically saved and closed when you select an element having parallel source code in the Diagram or Navigation panes.

Note: You must use a Together product with round-trip engineering support for Java to be able to edit Java scripts in the text pane. Use an external Java editor if necessary. You can run Java scripts from any Together edition with scripts support.

Compiling Java scripts

To compile Java scripts, you need to install a Java compiler (not included with Together). You can download a JDK free from www.javasoft.com. The compiler installation installs standard Java classes, usually in classes.zip.

Before compiling from Together,  you should specify the paths to your Java compiler and standard Java classes in the config.properties file:

script.loader.javac = <the full path to the compiler, including the name and extension>
script.loader.classes = <the full path to standard Java classes (usually in classes.zip)>
 
Example:
script.loader.javac   = "e:/jdk1.1.5/bin/javac.exe"
script.loader.classes = "e:/jdk1.1.5/lib/classes.zip"
You should specify the 'classes.zip' file for the compiler you use. For example if you have two versions of JDK, avoid specifying the compiler from one and classes.zip from another.

You can specify additional class paths and libraries to be passed to the compiler by adding these paths specification to the script.loader.classes property. Delimit each path with a semi-colon (;).
 

Example:
script.loader.classes = "e:/jdk1.1.5/lib/classes.zip;e:/jacl1.0/jacl.jar"
Once your config.properties file contains correct paths, you can compile scripts. Select the script name under the "Java" tab and click the "Run" button to start a console window for the Java compiler. If compilation succeeds, the compiled script class loads and runs. If compilation fails, a report is written to log.txt in $TOGETHER_HOME/source/oisoft/togetherx/scripts and Together opens that file in the application associated with .txt extension.

Script compilation output is written to: $TOGETHER_HOME/classes/oisoft/togetherx/scripts. When you choose Tools | Open script next time, the new script is listed in the Compiled page of the Open Script dialog.

You can edit your script in Together's text editor (see Editing Scripts above) or in your favorite editor and recompile and run it without restarting Together. When you complete script development, you can run it from the Compiled page of the Open Script dialog.
 

Developing Java scripts in your favorite IDE

You can develop your scripts in your favorite IDE, and just use Together to run them .
Set the output directory of your IDE to $TOGETHER_HOME$/classes/oisoft/togetherx/scripts and work as usual. (Note that $TOGETHER_HOME$ here should be resolved to the concrete installation path).

All scripts should be declared in package oisoft.togetherx.scripts.
After you've compiled your script, invoke the Open Script dialog in Together. The script's name appears in the Compiled page.

This way you can skip setting script.loader.javac and script.loader.classes properties in the config.properties file.
 

Customizing script with properties

If your script contains properties and calls...
    public boolean customize(Object customizableObject, String strTitle)
 
    ...method from APIManager where customizableObject is the object or customization, and strTitle is the title for dialog,
... then the customization dialog appears.

You can interactively change the values of any properties and they will be used in succeeding script operations. The method returns true if user clicks OK and false if Cancel is clicked.
 
Usually, "customize()" is the first executable operator in script. For example:
 

Example:
if (!customize(this, "Properties"))  {
   return;
}

Working with TCL scripts

For all information about TCL refer to http://www.scriptics.com
TCL scripts are text files with .tcl extension and they should be placed in ./scripts subdirectory to be available in Together. TCL scripts are listed in "Tcl" page of the Open script dialog. The scripts are interpreted by jacl.jar, working as a part of Together.
When developing own TCL scripts for Together you should get the pointer to APIManager, which in turn allows you to access all the model information. For getting the variable that refers APIManager in TCL use the following code:
 
set togetherapi [$this getAssocData "TogetherAPI"]
set apimanager  [$togetherapi       getAPIManager]
 

Working with Python scripts

For all information about Python refer to http://www.python.org
Python scripts are text files with .py extension and they should be placed in ./scripts subdirectory to be available in Together. Python scripts are listed in "Python" page of the Open script dialog. The scripts are interpreted by jpython.jar, working as a part of Together.
When developing own Python scripts for Together you should get the pointer to APIManager, which in turn allows you to access all the model information. For getting the variable that refers APIManager in Python use the following code:
 
apimanager = TogetherAPI.getAPIManager()
 

Chapter contents

About Scripts
Scripts feature availability
Script API
Directory structure of Script processing system
Working with compiled Java scripts
Output Document
Developing own Java scripts
Creating Java scripts
Editing Java scripts
Compilation and execution Java scripts
Developing Java scripts in your favorite IDE
Customizing script with properties
Working with TCL scripts
Working with Python scripts
 

 

GO TO TOP

CONTENTS

GETTING STARTED

HELP CONTENTS

© 1997-98