Introduction to Module development

Together is highly extensible by means of an open Java API that enables you to write Java programs that use model information from Together and/or interact with Together itself to extend its native capabilities. Such pograms are called modules. Many of Together's own features as implemented this way, and the architecture makes it possible for Togethersoft to include modules developed by strategic partners or other third parties.

Module development can take two forms:

Compiled: Written in Java and compiled using a Java compiler. Such modules use the same JVM as Together at runtime.
Written in TCL (or JPython): Such modules, referred to as scripts are interpreted by appropriate Together subsystems at runtime.

Compiled modules deliver better performance and more depth becase you have the full capabilities of the Java langage at your disposal. This topic addresses the basic concepts of module development.

Types of modules

All modules are defined by their language, invokation time and type of deployment. By the time of invokation the module are categorized into the following groups : User, User with pre-initialization, Startup, Activatable (OnDemand).

User module is added to the modules tree as an icon and can be invoked later from a popup menu (Run) of this icon.

User with pre-initialization is the same as "User", but differs with an additional feature that initialization method of such module executes before the first run of the module. This type makes sense for JAVA modules only and is assigned by default.

Startup modules are not added to the modules tree and always run on Together startup.

Activatable (OnDemand) module combines the advantages of both User and Startup types. Activatable modules are added both to the modules tree and to the list in Options|Activatable Modules menu.

To change Activatable module state, one can use main menu instead of browsing modules tree. Main menu item Options->Activatable Modules contains submenu where all existing Activatable modules are presented as checkbox menu items. State of a checkbox reflects the current state of an Activatable module. Checking a box activates a module, unchecking makes it deactivated.

State of an activatable module is persistent between Together sessions. Being activated, such module behaves as a startup module. By default activatable modules are deactivated.

Modules are Java classes that implement the IdeScript, IdeStartup,or IdeActivatable interfaces.

Modules of the User type should implement IdeScript interface that provides the method run(). Startup modules implement the interface IdeStartup that provides autorun() method. The modules that should provide the possibility of on-demand invokation and deactivation, implement the interface IdeActivatable that extends IdeStartup with shutdown method. If a module is supposed to be used both as startup and user module, it should implement IdeScript and IdeStartup interfaces, while startup module with the possibility of on-demand invocation, should implement both IdeScript and IdeActivatable interfaces.

All these interfaces are provided in the Together API. This powerful API delivers the capability to externally use Together's internal functionality.

The three main groups composing API are :

com.togethersoft.openapi.ide package and its subpackages
com.togethersoft.openapi.rwi package and its subpackages
com.togethersoft.openapi.sci package and its subpackages

The API is composed of a three-tier interface that enables varying degrees of access to the native infrastructure. The top tier represents the highest degree of constraint and the lowest tier the least degree of constraint. The interfaces are very simply named:

IDE
Read-Write Interface (RWI)
Source Code Interface (SCI)

Basic Together API architecture

IDE

This is the API you need in order to generate custom outputs based on information contained in a Together model. It is a read-only interface, meaning that you can extract information from the model but not change the model (accidentally or otherwise). IDE group provides the functionality related to the model's representation in Together's IDE and interaction with the user. Each package composing the IDE group has a description highlighting the areas of applicability of this concrete package.

RWI

This API enables you to go deeper into the Together architecture. You can both extract information from, and write information to your models, and you can do some extensions of Together's capabilities. RwiElements can represent more than packages, classes and members. In a RWI model they may represent different diagrams (class diagrams, use case diagrams, sequence diagrams and others), links, notes, use cases, actors, states etc.

SCI

As the name implies, the Source Code Interface takes you down to the source code level. This API is the most granular enabling even manipulation of single bytes. An SCI model is a set of sources (for Java, .class files are allowed) organized into packages. The SCI packages represent the Java packages (which can be stored even in .zip or .jar files) or directories for other languages. SCI model can contain parts written in different languages.

SCI allows you to work with the source code almost independently of the language being used. For example, a SciClass object can represent a class in both Java and C++.

API Technical reference

Complete HTML technical reference documentation for the API is provided separately from this Help documentation. Refer to the file index.html in the $TOGETHER_HOME$/doc/api/ .

View API documentation now
View multi-framed version of the API documentation.

Naming conventions

Together's modules are classes implementing either IdeScript or IdeStartup interfaces, or both. The names of modules use mixed case: GenerateDocumentaion, ImportFiles etc.

Naming methods

Methods should be named using a full English description, using mixed case with the first letter of any non-initial word capitalized. It is also common practice for the first word of a method name to be a strong, active verb. Examples:

processModel()
printCurrentDiagram()
recheckAllNames()
iterateCurrentNode()

This convention results in methods whose purpose can often be determined just by looking at the name. Although this convention results in a little extra typing by the developer, because it often results in longer names, this is more than made up for by the increased understandability of your code.

Getters

Getters are methods that return the value of an attribute. You should prefix the word 'get' to the name of the attribute, unless it's a Boolean attribute and then you prefix 'is' to the name of the attribute instead of 'get.' Examples:

 
getFirstName()
getAccountNumber()
getLostEh()
isPersistent()
isAtEnd()

By following this naming convention you make it obvious that a method returns an attribute of an object, and for boolean getters you make it obvious that it returns true or false.

Setters

Setters are methods that modify the values of an attribute. You should prefix the word 'set' to the name of the attribute, regardless of the attribute type. Examples:

 
setFirstName(String aName)
setAccountNumber(int anAccountNumber)
setReasonableGoals(Vector newGoals)
setPersistent(boolean isPersistent)
setAtEnd(boolean isAtEnd)

Following this naming convention you make it obvious that a method sets the value of an attribute of an object.

Naming attributes

You should use a full English descriptor to name your attributes to make it obvious what the attribute represents. Attributes that are collections, such as arrays or vectors, should be given names that are plural to indicate that they represent multiple values.

Documenting the module

Okay to use phrases instead of complete sentences, in the interests of brevity. This holds especially in the initial summary and in @param tag descriptions.
Use 3rd person (descriptive) not 2nd person (prescriptive). The description is in 3rd person declarative rather than 2nd person imperative.
```
Gets the label.        (preferred)
Get the label.         (avoid)
```
Method descriptions begin with a verb phrase. A method implements an operation, so it usually starts with a verb phrase:
```
Gets the label of this button.                  (preferred)
This method gets the label of this button.      (avoid)
```
Add description beyond the name. The best names are "self-documenting", meaning they tell you basically what the method does. If the doc comment merely repeats the mehtod's name in sentence form, it is not providing more information. For example, if method description uses only the words that appear in the method name, then it is adding nothing at all to what you could infer. The ideal comment goes beyond those words and should always reward you with some bit of information that was not immediately obvious from the name. Avoid - The description below says nothing beyond what you know from reading the method name. The words "set", "tool", "tip", and "text" are simply repeated in a sentence.
```
 
    /**
     * Sets the tool tip text.
     *
     * @param text  The text of the tool tip.
     */
    public void setToolTipText(String text) {
```
Preferred - This description more completely defines what a tool tip is, in the larger context of registering and being displayed in response to the cursor.
```
 
    /**
     * Registers the text to display in a tool tip.   The text
     * displays when the cursor lingers over the component.
     *
     * @param text  The string to display.  If the text is null,
     *              the tool tip is turned off for this component.
     */
    public void setToolTipText(String text) {
```

Order of Tags

Include tags in the following order:

 
* @author       (classes and interfaces only, required)
* @version      (classes and interfaces only, required)
* @param        (methods and constructors only)
* @return       (methods only)
* @exception    (@throws is a synonym added in Javadoc 1.2)
* @see
* @since
* @deprecated

Deploying modules

For now, a module defines its own subpackage with the name matching to name of the module, located in the modules package For example:

  package modules.InsertTags;

  import com.togethersoft.openapi.ide.IdeContext;
  import com.togethersoft.openapi.ide.IdeScript;

  public class InsertTags implements IdeScript{
    public void run(IdeContext context){
    }
  }