newPT

# Together - Persistence PowerTier Integration

## Introduction

The module generates .per files based on the information from diagrams. Presently, the "current" diagram option is only supported. Open a diagram, start Persistence PowerTier Integration module, check output directory and press ok.

The diagram maps to the PowerTier project file. All classes of the diagram with non-empty DistributionOption property defined become the members of the PowerTier project.

All properties are defined via javadoc style tags. All tags in use are defined in the source file PersistenceTags.java.

There's no need to remember the tags because they are listed in the PowerTier tab of the object inspector.

## 1. Working entities

### Diagrams

The class view diagrams only are used to generate *.per files for the PowerTier. We strongly discourage you to use the default diagram for designing a project. The default name for a *.per file is based on the diagram name, and "default" is not a really good name. It is also more convenient to use different diagrams for different files.

The module operates on the entire diagram or on the selected diagram elements. It is impossible to process all selected elements simultaneously if they are on different diagrams. Consider the class diagrams as the source of *.per files.

Class View Diagram properties are used to define PersistenceProperties block of a PowerTier project.

### Classes

Classes are the basic entities. Any class that has DistributionOption property defined is considered a PowerTier PersistenceClass. Other PowerTier properties of a class can be defined in the inspector pane, too.

### Attributes

All attributes defined in a persistent class are exported. The primitive types are converted according to the type conversion table, see configurable options section.

### Keys

Attributes can form a primary key. An attribute having primaryKey (Primary Key checkbox in PowerTier tab of the inspector) becomes the primary key. If several attributes have this property, they form a composite primary key, the order of its members follows the order of attributes in class.

### Links

Two types of links are used in the Persistence PowerTier Integration module. One is generalization link, which is directly translated into inheritance. The other one is association link. Association links are used to specify relationships and foreign keys.

Specifying foreign keys. An association link from one class to another, with Persistence Role defined as ForeignKey (see inspector), results in the generation of a foreign key. The destination (client) side class' primary key defines the names of attributes included in this foreign key. If this foreign key is the part of primary key, such link should have property identifying. It is recommended to leave FK links directed.

Specifying relationships. A relationship is defined as an undirected association link between two classes. A relationship record consists of two relation arcs. Relation arcs, cardinalities and delete actions for both arcs are specified in the inspector tab. By default, relation arc names are generated from class names if otherwise not specified.

## 2. Step-By-Step Howto

In this section we'll create a simple diagram and generate a .per file from it. First of all we need to activate PowerTier support module. Once the module is activated, the appropriate configuration file is loaded, PowerTier configuration options tab and PowerTier object inspector tab set up. The module needs to be activated only once, you do not need to do it every time you start Together. To activate PowerTier specific settings, run the module `Earlyaccess | Persistence PowerTier Integration | Activate PowerTier Support.`

1. Create a New Project. You wouldn't need any other classes, so you may remove classes.zip and swingall.jar from the project's search/classpath.
2. Create a New Diagram (Ctrl-N), select Class Diagram type, change the name of the diagram to `Demo`.
3. The next step is defining project's persistence properties. They will go to PersistenceProperties section of the generated project. The Together integration provides all the defaults. You may leave them intact for this time. To get to the properties, click on the diagram, then select PowerTier tab of the object inspector.
4. Add class named `Person`
5. Specify DistributionOption for the class `Person`, AllReadWrite using object inspector's PowerTier tab.
6. Add attribute `"age"`, type `"int"` (leave default). Check OptimisticControl checkbox in PowerTier tab of the object inspector.
7. Add attribute `"id"`, type {"int"} (leave default). Check Primary Key checkbox in PowerTier tab of the inspector pane.
8. Add attribute `"gender"`, type `"int"` (leave default).
9. Add class `Reference`, set Distribution option - AllReadWrite
10. Draw an association link from `Reference` to `Person` See object inspector, select PowerTier tab. Set Persistence Role to ForeignKey
11. Add class `Community`, set Distribution option - AllReadWrite
12. Drag an association link from `Person` to `Community`, set Persistence Role to Relationship. Make link undirected using object inspector.
13. Set client cardinality to "*" (0..n) Set supplier cardinality to "1" Specify DeleteActions for source and destination (choose any) You may choose relation arc names, they will be choosen based on class names if you leave them blank.
14. Now run the module. Go to the Modules tab of the navigator, open the `Earlyaccess | Persistence PowerTier Integration | Persistence PowerTier Integration`. Select Run . Now the output directory would be set by default to Together's installation folder <tj>/out/per/<your project name>. Select "current diagram" on the module dialog. Check the Options... dialog. Then press OK. The resulting file can now be found in the Together Installation Folder/out/per/<your_project>/Demo.per. You may check the result with your preferred text editor.

### Note

The module is distributed as open source. You're welcome to donate your own submissions. Send all suggestions, fixes and modifications to Alexander Aptus

## 3. Appendix A. Primitive types conversion table

PowerTier data type | Java type | Comment
`char` | `char` | character string
`Binary` | `int` | binary string
`short` | `short` | short integer
`int` | `int` | integer
`long` | `long` | long integer
`float` | `float` | floating point
`double` | `double` | longer floating point
`text` | `String` | large text object
`image` | `Object` | large binary object
`money` | `int` | money type
`datetime` | `Date` | date type
`OID` | `long` | PowerTier key type
`composite` | `int` | composite data type

Since many PowerTier data types have no matching primitive types in Java, it is recommended to explicitly specify PowertierType property for every attribute. You can alter conversion table in Options Editor by specifying which Java type matches every PowerTier type.

## 4. Appendix B. PowerTier-related Properties Used by the Integration Module

### Diagram Properties

All diagram properties are necessary to fill out the `PersistenceOptions` block of a generated .per file. All descriptions here refer only to PowerTier and not to the integration plugin.

Object Inspector Field | Property Type | Description
DomainName | string | specifies domain name.
DomainFileName | string | specifies an element for the names of files generated at the domain level
DomainOutputDir | string | specifies the directory where the code generator places generated files for this application
HeaderSuffix | string | ignored for PowerTier for Enterprise JavaBeans
SourceSuffix | string | ignored for PowerTier for Enterprise JavaBeans
RootFileName | string | specifies an element for the names of files generated at the project level.
ProjectInSubdir | boolean | indicates whether this project is generated into a directory below the domain output directory.
Package | string | when you choose EJBMapping for ProjGenerationOptions, specifies the fully-qualified Java package name for the project.
ProjRWClassIDBase | decimal or hexadecimal |
ProjGenerationOptions | List | specifies what kind of application to be generated.

### Class Properties

Object Inspector Field | Tag Name | Type | Description
TableName | `TableName` | string | specifies the name of database table or view that maps to this class.
ExistingTable | `ExistingTable` | boolean | if present, indicates that the table already exists in the database. This keyword must be present if ReadOnly property is also present.
ReadOnly | `ReadOnly` | boolean | if present, indicates that the application does not modify the database table or view.
FileNameRoot | `FileNameRoot` | string | specifies a root element for the names of generated files for this class.
DistributionOption | `DistributionOption` | List | specifies what parts of the class are available to the client tier.

### Attribute Properties

Object Inspector Field | Tag Name | Type | Description
PrimaryKey | `primaryKey` | boolean | if set, the attribute is primary key, or a member of composite primary key.
PowerTierType | `persistentType` | List | specifies PowerTier data type, it is recommended to specify this property regardless of mapping to avoid obscurity.
ColumnName | `columnName` | string | specifies column name associated with this attribute
ColumnNames | `columnNames` | string | specifies column names associated with this attribute; use comma separated list here
Queries | `queries` | string | specifies the query methods you would like to be generated for this attribute
DomainMin | `domainMin` | string | specifies the minimum value allowed for this attribute
DomainMax | `domainMax` | string | specifies the maximum value allowed for this attribute
OptimisticControl | `optimisticControl` | boolean | you can specify one attribute in each class to be an optimistic control attribute
DefaultValue | `defaultValue` | string | specifies default value for this attribute
Hooks | `hooks` | List | ignored for PowerTier for Enterprise JavaBeans

### Link Properties

There are two kinds of links that play role in Persistence PowerTier Integration module, association links and generalization links. Generalization links on diagram will produce inheritance in output files. There are no PowerTier-specific properties for that kind of links.

Association links are used to define Relationship and ForeignKey records. The role of an associatin link is defined by its PersistenceRole property. Whether PersistenceRole is set to ForeignKey or Relationship, different properties will be used.

Object Inspector Field | Tag Name | Type | Description
PersistenceRole | `persistenceRole` | `ForeignKey` or `Relationship` | Link role selector. Depending on its value, the properties marked with ForeignKey or Relationship prefixes in description will take effect.
Identifying | `identifying` | boolean | ForeignKey: specifies whether this FK should also be a part of the primary key.
Client relation arc | `clientRelationArc` | string | Relationship: the name of client relation arc, typically named after destination class
Client cardinality | `clientCardinality` | List | Relationship: client to supplier relationship cardinality
Supplier relation arc | `supplierRelationArc` | string | Relationship: the name of supplier relation arc, typically named after source class
Supplier cardinality | `supplierCardinality` | List | Relationship: supplier to client relationship cardinality
DeleteActionSrc | `deleteActionSrc` | List | Relationship: source side delete action
DeleteActionDst | `deleteActionDst` | List | Relationship: destination side delete action