Getting Started Guide

How to install Rebel?

The Rebel is distributed through the official StarUML extension registry. To install it, follow these steps:

1. Download and install StarUML
2. Start the StarUML
3. Open StarUML's Extension Manager by selecting Tools -> Extension Manager
4. Type 'Rebel' in the Search field, as shown in the picture below
5. Press install button of the extension

After installation is completed, you should see Rebel menu, as shown in the picture below:

For more information about managing StarUML extensions, please see the official guide.

Modeling Prerequisites

If you are already familiar with StarUML, you may skip this section.

However, if you do not have prior experience with StarUML and do not know the difference between a UML model and its view, it is important to understand its basic concepts.

Code Generation Setup

We have prepared a short screencast that presents the creation of a simple project, used in the example below. You can watch it on our youtube channel.

In order to generate Java code from your UML model, you need to configure the project root package. This chapter will guide you step by step through the code generation setup.

For the sake of simplicity, we will use the example from the picture below.

Step 1: Using StarUML Property editor, set the stereotype of the project main package to 'root'.

Code generation always starts from the package having stereotype root. All contents below this package will be processed during the code generation. In other words: the UML package having stereotype root is the starting point of the code generation process.

Looking at our example project, you can see in the StarUML Model Explorer that the contacts is our root package. In the Properties panel below, you can see the name of the package (contacts) and the value of its stereotype attribute (root).

Step 2 (optional): define the base package for your project.

Rebel allows you to set a custom base package for your project, using the Rebel Property Editor.

In our example, you can see in the Rebel Property Editor that we have defined com.archetype to be a prefix of our root package. Thus, the full name of our root package will be com.archetype.contacts.

Step 3 (optional): Define a destination folder for the generated sources.

A destination folder for the generated Java code is set by using Rebel -> Configure -> Project Codebase. If not set, the Rebel will prompt you to choose destination folder by opening file select dialog.

For more information about project configuration you can further explore Rebel Preferences.

As an example, our destination folder may be c:/sample-project/src/main/java

Having in mind that the base package is com.archetype and the name of the root package is rebel, the code generator will place generated sources in the c:/sample-project/src/main/java/com/archetype/contacts directory.

Step 4: Select Rebel -> Generate from the menu to generate code

Finally, to generate Java code, use Rebel -> Generate from the StarUML menu or use the shortcut key F5 instead.

Preserved Sections

Rebel generates preserved sections to make it possible for the developer to customize generated code. Customization may include annotating method or attribute, adding a new method to the class, implementing method defined within the model, etc. In other words, preserved sections represent special code comments that remain intact between two code generations.

A Rebel user should take care to do all his customisations of the code within the preserved section blocks. Each preserved section block has three parts:

• Starting comment
• Preserve section block body, that contain usefull contents
and
• Ending comment

An example is displayed below.

public String getMarketPlaceName() {
// ----------- << AAAAAAFeHg5Vxvz2sM0="">method
return getMarketplace().getName();
// ----------- >>
}

No matter how simple the concept of preserve section is, it enables developer to customize generated code and introduce additional value to the generated sources. Also, it enables separation between model and the overall project implementation: model remains abstracted from the code that contains all implementation details.

Rebel Preferences

Rebel code generation preferences are available either through StarUML menu File -> Preferences -> Rebel or through menu Rebel -> Configure.

In order to be understood and used effectively, all Rebel preferences are divided into several categories:

• General Settings, that includes several fundamental code generation preferences;
• Project Settings, covering some basic project-level settings;
• Additional Settings, introducing some additional customization of generated Java code;
• Mapping of built-in (Rebel) types to Java types. For more information on built-in types and their meaning, see their explanation;
• Persistence Settings. This section contains some project-level settings for Java Persistence API (JPA) annotation generation;
• Jackson Settings. This section contains some project-level settings for Jackson annotation generation;
• Spring, that includes possibility to enable/disable Spring modeling and code generation;
• Custom Annotations, where you can enable or disable usage of custom annotations while modeling.

For more details, please see the table below.

Preference	Description	Note
General Settings
Use local Rebel settings	Use project-specific instead of global Rebel configuration.	If set, the Rebel will store its settings per project basis.
Use Tab for indentation	If set, Tab will be used for indentation.	Otherwise, spaces will be used for indentation of generated files.
Indent Spaces	Number of blank spaces to be used if spaces are used for line indentation.	Used only if option 'Use Tab for indentation' is disabled.
Use Diamond Operator <>	If set, generated code will use Java 7 diamond operator when creating collection objects.	As an example, if 'Use Diamond Operator <>' is on, Rebel will use new HashSet<>() when creating a new HashSet.
Project Settings
Project Codebase	Directory to contain generated Java source files.	If empty, the Rebel will prompt you to select directory by opening 'Select Directory' dialog.
Generate Accessors	If set, Rebel will generate getters and setters for class attributes.	If you decide to use utility like Lombok for your classes, you may decide to unset this option.
Generate Documentation	If enabled, Rebel will structure model documentation into javadoc format and store it in the generated code.
Generate Package Info	Generate package-info.java file for every generated Java package.	False by default.
Copyright Text	Copyright text to be applied to all generated files.	The Rebel will emulate multi-line text by replacing '\n' characters from the copyright text with the new line.
Additional Settings
Standard imports	Imports to be used in all generated files.	Rebel imports java.util.* and java.time.* packages by default.
Generate fluent setters	Generate setters returning this, that enables method chaining.	This preference enables method chaining, like in this example: new Person() .setName("John").setLastName("Doe").toString();
Generate fluent link/unlink methods	Generate link/unlink methods returning this, that enables method chaining.	This preference enables method chaining when dealing with association link/unlink methods belonging to objects of generated classes.
Unordered Collection Interface	Java collection interface to be used for unordered associations.	Java interface Set is used as a default value.
Unordered Collection Implementation	Java collection implementation to be used for unordered associations.	Java collection HashSet is used as a default implementation. An example of generated code could be like this: Set<Person> persons = new HashSet<>();
Ordered Collection Interface	Java collection interface to be used for ordered associations.	Java interface List is used by default.
Ordered Collection Implementation	Java collection implementation to be used for ordered associations.	ArrayList is used as a default implementation. An example of generated code could be like this: List<Address> addresses = new ArrayList<>();
Built-in Type Mapping
string	Built-in type for modeling textual information.	Mapped to String by default.
integer	Built-in type for modeling whole numbers.	Mapped to primitive type int by default.
bool	Built-in type for modeling boolean values.	Mapped to primitive type boolean by default.
float	Built-in type for modeling floating point numbers.	Mapped to primitive type float by default.
double	Built-in type for modeling floating point numbers.	Mapped to primitive type double by default.
dateTime	One of built-in date-time data types, intended for modeling date with time information.	By default, dateTime attribute type is mapped to LocalDateTime.
date	One of built-in date-time data types, intended for modeling date without time information.	By default, date attribute type is mapped to LocalDate.
time	One of built-in date-time data types, intended for modeling time without date information.	By default, time attribute type is mapped to LocalTime.
binary	Built-in type for modeling binary information, such as blobs, images, etc.	By default, binary attribute type is mapped to byte[].
Persistence Settings
Generate persistence meta-data	If set, persistence aspect will be enabled in the project.	Custom persistence attributes can be defined using the Rebel Property Editor.
Java type for entity id	The Rebel will automatically add id and version attributes of a configured type to all persistent classes.	Defaults to Long.
Persistent classes are serializable	If set, persistent classes will implement Serializable interface.	Default value is false.
Generate equals()	If set, Rebel will override equals() and hashCode() methods for all persistent classes, based on the value of the @Id attribute.	Default value is true.
Persist enums as strings	If set, enum attributes will be persisted as string values in the database.	Default value is true.
Use @Temporal annotation	If set, @Temporal annotation will be applied to date attributes.	Default value is true.
Use @NotNull annotation	If set, Rebel will add @NotNull annotation to required attributes and association fields.	Default value is true.
Jackson Settings
Enable Jackson	If set, generation of Jackson annotations from the model will be enabled.	Jackson annotation generation is enabled by default.
Spring
Enable Spring	If set, Spring aspect will be enabled in the project. Using Rebel Property Editor, you will be able to specify whether a class is a Spring component, service, repository, etc.	Default value is false.
Spring Data
Common Repository Interface	Common interface for all generated Spring Data Repositories.	Default value is CrudRepository.
Custom Annotations
Enable custom annotations	If set, user will be able to put arbitrary Java annotations on any model element, through Rebel Property Editor.	User defined annotations will be a part of generated Java code.

User Interface

Rebel introduces additional GUI elements to StarUML. However, for the sake of clarity, some important built-in elements of the StarUML user interface will also be explained here shortly.

Extensions: stereotypes and profiles

When it comes to generating concrete software artifacts, like Java code or database schema from the abstract UML model, there is a gap that need to be overcomed. For instance, using only standard UML, there is no option to turn off code generation for a model element. Or, you cannot say: this class is immutable and persistent.

To bridge this gap, Rebel uses stereotypes and custom Rebel profiles.

Stereotypes may be imagined as labels or tags for UML model elements.

While their values may be anything, stereotypes as a concept are part of UML standard. Thus, you can edit element's stereotype using StarUML Properties Editor.

A profile is a set of Rebel-defined attributes that describe a particular aspect of the model.

For instance, the persistence profile defines a set of attributes to describe persistent aspect of domain classes. Within the persistence profile, there are different sets of attributes for persistent classes, attributes and associations. On the other hand, the Java profile provides additional customizations for Java code generation.

These, custom profile attributes are edited using the Rebel Property Editor.

At the moment of writing, the Rebel supports following profiles:

• Java Profile
• Persistence Profile
• Spring Profile
• Jackson Profile
• Documentation Profile

Each one of them is described in more details below.

Built-in types

When modeling attributes, method parameter types or return value types, always use Rebel built-in types. These types include:

• string,
• integer,
• bool,
• float,
• double,
• date,
• dateTime,
• time and
• binary.

By using these, meta-types, model will be independent of the particular implementation of its types. Mapping of Rebel built-in types into particular (Java) types is defined using Preferences.
For instance, (model type) date can be mapped into java.util.Date, Java 8 LocalDate, or something different, depending on the user preferences.

However, in case that you decide to use, while modeling, types different than the built-in ones, Rebel will generate them just as they are declared. For instance, if you declare an attribute to be String or Runnable, types not recognized by the Rebel, they will be used just as you have defined them. In the generated code, you will see String or Runnable as the attribute type.

Modeling Conventions

Whenever introducing an association, specify both association name, as well as both association end names, cardinality and navigability. It is important to define all these basic pieces of information, because they may be used by code generator under different circumnstances. For instance, the name of association may be used as a name for joining database table. Names of the association ends are used to create association fields in the related classes. Picture below demonstrates proper naming of classes, their attributes and associations.

Modeling Tips & Tricks

Suppress Properties Display

All Rebel defined extended model properties are stored as StarUML tags.

The default behavior of the StarUML is to display tag values in all class diagrams. While there is a clear motivation for that decision, when it comes to using Rebel, things could change quickly.

Having in mind that Rebel automatically creates model tags, in a matter of seconds class diagrams become too verbose to be useful, as shown in the picture below.

Solution for this problem is to select (all) model elements shown in the diagram and switch "Show Property" option to off, as displayed in the image above.

You can also select model elements whose display you want to customize and use keyboard shortcuts Ctrl + Shift + P (Windows/Linux) or ⌘ + ⇧ + P (OS X) to toggle display of properties (tags) on or off.