The purpose of this document.

Together delivers a unique capability to extend its functionality externally by using scripts and patterns. Scripts are discussed in the main documentation. The purpose of this document is to help you get an idea of the structure of patterns and to help you deploy your own patterns.

What are Together patterns?

Together patterns are public Java classes implementing an interface called com.togethersoft.openapi.sci.pattern.SciPattern.

What can Together patterns do?

Patterns are intended to create new frequently used elements, to modify existing elements, or to implement useful source code constructions or solutions in your model. For example, Together ships with a set of GoF patterns including Visitor, Observer, Singleton etc.

Are patterns model language dependent or not?

Some patterns work only with a specific language (for example, Enterprise Java Bean pattern can work only with the Java language), and some can be applied to any language (for example, `com.togethersoft.modules.patterns.UNIVERSAL.MEMBER.Stub_implementation` pattern). Together determines the target language for a pattern automatically based its location in the installation. See details below.

How do patterns work?

Behavior of a pattern is defined by its properties set. The `getProperties` method returns a com.togethersoft.util.propertyMap.`PropertyMap` instance containing a set of all the properties for the pattern.

SciPattern interface defines those methods you must implement in your pattern:

- `apply` method makes the pattern perform desired actions
- `canApply` method checks whether the pattern can be applied to the target object (objects) with the current values of pattern's properties.
- `prepare` method checks if it is possible to apply this pattern to the target object (objects) at all, and makes some startup preparations for the pattern. It returns `true` if everything is okay, and `false` if the pattern cannot be applied to the target object (objects) at all.
- `getProperties` method returns a `PropertyMap` instance containing a set of all the properties for the pattern.

Other information about pattern-related interfaces and pattern properties can be found in the main API documentation (\doc\api folder in your Together installation).

Where should I place my patterns?

Here is the simplest pattern which does nothing. Nevertheless, it will help us to explain the key point of pattern deployment:

`

    package com.togethersoft.modules.patterns.JAVA.CLASS.Pattern;

    import com.togethersoft.openapi.sci.pattern.SciPattern;
    import com.togethersoft.util.propertyMap.PropertyMap;
    import com.togethersoft.util.propertyMap.DefaultPropertyMap;

    public class Pattern implements SciPattern {
      public boolean prepare () {
        return true;
      }
      public boolean canApply() {
        return true;
      }
      public void apply() {
      }
      public PropertyMap getProperties(){
        return myProperties;
      }
      private PropertyMap myProperties = new DefaultPropertyMap();
    }

`

The pattern package defines the target language and the target elements for the pattern (or elements produced by the pattern):

1. Target language:

- `com.togethersoft.modules.patterns.JAVA` package in its subpackages contains patterns intended to work only with Java language
- `com.togethersoft.modules.patterns.UNIVERSAL` package in its subpackages contains patterns intended to work with any language.

1. Elements:

- `com.togethersoft.modules.patterns.JAVA.CLASS, com.togethersoft.modules.patterns.UNIVERSAL.CLASS` packages in their subpackages contain patterns which work with or produce classes
- `com.togethersoft.modules.patterns.JAVA.LINK, com.togethersoft.modules.patterns.UNIVERSAL.LINK` packages in their subpackages contain patterns which work with or produce links
- `com.togethersoft.modules.patterns.JAVA.MEMBER, com.togethersoft.modules.patterns.UNIVERSAL.MEMBER` packages in their subpackages contain patterns which work with or produce members

In our example, we have defined a pattern working with Java classes.

It is possible to create a pattern hierarchy within the packages described above. In this case Together will use a name of a subpackage as a name for a group of patterns defined in this package. For example, a pattern defined in a package com.togethersoft.modules.patterns.JAVA.CLASS.my_Set_Of_Patterns; in class pattern chooser dialog will be displayed in a separate group called "my Set Of Patterns" (Together automatically replaces an underscore sign with a space).

I see some patterns have a description in a pattern chooser dialog. How can I insert a description for my pattern?

To do that you have to place a file named "Description.html" in a directory with your pattern. The contents of this file will be displayed in a dialog in the "Description" section.

Where to go from here?

Together patterns are written using the SCI API, so you need to refer to the API documentation before starting to 'roll your own'.

You can find examples of mature patters in togetherx\pattern directory in your installation.