Rebel for StarUML

Faster prototyping, easier software maintenance.

Getting Started Guide

The Rebel is designed to be very intuitive and easy to use. This getting started guide will take you through all you need to know to use it.

It will take you less than a minute to start generating Java code and some more time to truly adopt its concepts and vocabulary. If you have any questions or suggestions, please do not hesitate to contact us. We would love to hear from you!

The guide is divided into the following sections:

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

How to install Rebel
Using Extension Manager to install Rebel

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

Rebel Menu
Rebel menu - after plugin has been installed

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

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

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.

How to setup code generation
An example project setup

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 rebel is our root package. In the Properties panel below, you can see the name of the package (rebel) 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 Extended Model Properties editor.

In our example, you can see in the Rebel's Extended Model Properties 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.rebel.

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

A destination folder for the generated Java code is set by using Rebel Preferences -> 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/rebel 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.

Preferences

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

Rebel preferences
Preferences Dialog

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

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.
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.
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 Extended Model Properties tab.
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.
Spring
Enable Spring If set, Spring aspect will be enabled in the project. Using Extended Model Properties tab, you will be able to specify whether a class is a Spring component, service, repository, etc. Default value is false.
Spring Data
Enable Spring Data If enabled, Rebel will create Spring Data Repositories for all persistent classes. Default value is false.
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 Extended Model Properties tab. 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.

StarUML with Extended Model Properties
StarUML User Interface

StarUML User Interface

Throughout your work, you will often use these elements of StarUML user interface:
  • Model Explorer. Think of Model Explorer as of tree-like navigator throughout the model. Visualy similar to the filesystem elements, in the Model Explorer you can browse and select packages, classes, enumerations and other model elements. Before starting your project, be sure to differentiate model and diagrams.
  • Properties Editor. Whatever model element you select either throught the current UML diagram, or in the Model Explorer, you can edit its properties in the Properties Editor. Properties bound to this view are standard UML attributes of selected element.
  • Documentation Editor. Documentation that you write in the Documentation Editor will be formatted as javadoc and will find itself in the generated Java source files.
  • Toolbox. Whenever you want to introduce a new model element (i.e. class, association, enumeration,etc.) to the project, you need to use the Toolbox. A small hint: in case you want to introduce several model elements at the moment (classes or associations, for instance), you can 'lock' a particular tool by double-clicking it.
Even though using StarUML is rather intuitive, after starting using it, you may additionally sharpen your skills by reading its concise and easy to follow official documentation.

Rebel User Interface Elements

When you successfully install Rebel in the StarUML, you will see additional elements of user interface:

  • Rebel menu, available in the StarUML menu bar.
  • Extended Model Properties panel, displayed at the bottom of the editor.
  • Preferences page, already explained here.

Each one of them will be displayed below.

Rebel Menu

Rebel menu has several menu items:

  • Generate. Clicking 'Generate' triggers code generation. You will interact with Rebel most frequently using this action item. You can also access it using keyboard shortcut: F5.
  • Configure. Opens Preferences dialog. For more details, see Preferences.
  • Getting Started. Opens the online Getting Started guide.
  • Upgrade to Rebel Plus. Takes users to the Rebel Plus upgrade page.
  • About. Gives some basic information about the Rebel.

Extended Model Properties

In order to effectively apply Model Driven Development, Rebel introduces different UML extensions: custom Rebel profiles.

Extended Model Properties panel enables you to edit Rebel specific extensions of the currently selected model element.

Information displayed in the Extended Model Properties panel is context sensitive. In other words, Rebel takes care to show extended model (element) properties that are relevant for the selected model element.

For more information on custom Rebel profiles, please see the following section.

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 elements. 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's Extended Properties Editor.

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

Java Profile

Java Profile contains set of modeling extensions used by the Java code generator. They are listed below:

Name Description Note
Base package A common namespace prefix to be applied to all generated model elements. Available only for the package having stereotype root. Typical value could be reversed company Internet domain name, like com.archetypesoftware or org.hibernate.
Generate code If unchecked, Java code will not be generated for that model element. Available for classes, enumerations and interfaces.
Default value is true.
Is immutable If set, setters will not be generated. Available for classes.

Generate code should be unchecked very rarely. It should be used when you want additional level of customization of the generated code. For some reason, you can decide to fully customize source code for the class, still you use it and keep it within the model.

Another useful example for using this option is when you want to reference externally defined classes in your project. For instance, if you want to model your Exception hierarchy, you could define a class java.lang.RuntimeException, set Generate code to false (as it is provided by the JDK) and use it throughout your project.

Persistence Profile

The purpose of the Persistence profile is to bring together UML modeling and the Java Persistence API (JPA) and its most used implementation: the Hibernate.

The Persistence profile contains a set of modeling extensions used to describe the persistent nature of domain concepts, processed by the JPA code generator.

Persistence modeling extensions are either related to classes, attributes or association ends. All possible values are explained below:

Name Description Note
Class Persistence
persistent If set, class will be treated as a JPA Entity. Default value is false.
inheritanceMapping Mapping of class inheritance to database tables, defined for a particular class hierarchy. Applicable only for class hierarchies, i.e. classes having their subclasses. Available options are Joined, Single Table and Table per class.
tableName Table name to be used for this particular JPA entity. Gives additional possibility to customize class persistence.
useOptimisticLocking If set, persistent @Version attribute will be automatically added to the generated JPA entity. Default value is true.
idGeneratorType Generator type to be used for the JPA Entity. Available options include: auto, sequence, identity and table.
generatorName Name of @Id generator to be used. Enables further customization of persistent classes.
Attributes
transient If transient, class attribute will not be persisted. Transient attributes will be annotated with @Transient JPA annotation.
columnName The name of the database column. Gives you the possibility to customize name of the database column used for a particular attribute.
columnLength Maximum length of the database column. Imposes additional persistence constraints upon a (persistent) attribute.
largeObject Is this attribute a large object? Large objects will be annotated with @Lob JPA annotation.
unique Is this attribute unique? Marks a persistent attribute as a unique one.
updatable Is this attribute updatable? Default value is true.
insertable Is this attribute insertable? Default value is true.
Association Ends
transient If transient, association end will not be persisted. There may be the cases when you decide not to persist one end of an association. Association ends are persistent by default.
fetchType Fetch type to be used for the particular association end. Possible options include: default, lazy and eager.

Rebel does not generate @Generator JPA annotations - they need to be explicitly defined by the developer. This is considered to be implementation detail, out of modeling scope.

Please keep in mind that you would not be able to smoothly use Rebel without some knowledge of Java Persistence.
Therefore, we will mention some resources that turned out to be very valuable from our own experience:

  • Thoughts on Java provides very nice and concise information about Java Persistence.
  • Baeldung provides great resources for those interested in Java Persistence and Spring.
  • Vlad Mihalcea's great tutorial provides information that could be interesting to both experts and beginners.
Finally, not to forget book lovers, Java Persistence with Hibernate will give you systematic knowledge of everything you need to know to understand and use Hibernate.

Spring Profile

The purpose of the Spring profile is to bring together UML modeling and the Spring Framework.

Very simple at the moment, Spring profile offers some basic options, as shown below.

Name Description Note
Spring
Component kind Enables you to declare a class as a Spring component. Possible values include none, component, repository, controller, service, etc.
Component name Enables you to define a name for the Spring component.

Spring Data Profile

The purpose of Spring Data profile is to bring together UML modeling and the Spring Data project.

The basic idea behind the Spring Data profile is to automate the creation of Spring Data Repositories so that you do not need to think about it! Once you model a persistent class, the Rebel will automatically generate a corresponding Spring Data Repository for you.

While the project-scoped customization options are available within project preferences, class specific customization can be done using a single profile property described below:

Name Description Note
Spring Data
Suppress repository generation If set, Rebel will not create Repository for the selected model class. Available only for persistent classes. Rebel will create Repositories by default.

Important note: Rebel will place all repository classes within package having stereotype repository. If package with this stereotype does not exist in the model, repositories will not be created.

Jackson Profile

The purpose of Jackson profile is to enable custom serialization of your domain classes into JSON or XML by modeling them. In other words, the Jackson profile brings together UML modeling and the Jackson project.

Profile properties are described below.

Name Description Note
Jackson
Serializable All model elements are serializable by default. Available for UML classes, attributes and association ends.
Property name Custom property name to be used. Available for UML attributes and association ends.

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 Conventions
Properly named associations
Great work provides a great integrity.