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.

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.

How to setup code generation
Setting up a new project

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.

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.
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 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.
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.

StarUML with Rebel Property Editor
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 through 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.
  • Rebel Property Editor, displayed at the bottom of the StarUML modeler.
  • 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.
  • Activate Rebel Plus. Opens a dialog for entering license for using Rebel Plus.
  • License Info. Displays information about the Rebel Plus license, if Rebel Plus is active.
  • 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.

Rebel Property Editor

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

Extended Model Properties Editor
Rebel Property Editor, positioned at the bottom of the StarUML window

Rebel Property Editor, shown above, enables you to edit Rebel specific extensions of the currently selected model element.

Information displayed in the Rebel Property Editor is context sensitive. In other words, Rebel takes care to show Rebel-defined, specific properties that are only relevant for the selected model element.

For more information about non-standard, Rebel specific model properties, please see the following section - Extensions: stereotypes and profiles.

Editing of extended model properties can make class diagrams too verbose. To see how to avoid this side effect, please see our section about modeling tips and tricks.

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:

Each one of them is described in more details below.

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 Rebel Plus

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.
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.

Upgrade to Rebel Plus

Spring Profile Rebel Plus

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

If you are developing a Spring application, Rebel will help you develop easier and faster by automatically creating Spring Data repositories, services and REST controllers for your persistent classes.

Basic RESTful service with CRUD functionality is available to you with no coding at all.

Unlike the generated Java code that represents your domain model; repository, service, and controller classes are generated only once. They do not use preserved sections and you can modify them in any way you want.

Rebel auto-generated Spring MVC Controller
Rebel auto-generated Spring MVC Controller

Their purpose is to help you set up a clear structure within your application and to provide you a good starting point for your further development.

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

Name Description Note
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.
Suppress repository generation If set, Rebel will not create Repository for the selected class. Available only for persistent classes. Rebel will create Repositories by default.
Suppress service generation If set, Rebel will not create Service for the selected class. Available only for persistent classes that have their Repository. Rebel will create Services by default.
Suppress controller generation If set, Rebel will not create Controller for the selected class. Available only for persistent classes having their Services. Rebel will create Controllers 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.

The same stands for services and controllers. These different kinds of Spring components will be automatically placed in packages having stereotype service and controller respectivelly.

Upgrade to Rebel Plus

Jackson Profile Rebel Plus

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
Serializable All model elements are serializable by default. Available for UML classes, attributes and association ends.
Ignore unknown properties If set, the Jackson deserializer will allow partial mapping of JSON object into the model element. Available for UML classes. For more information, see @JsonIgnoreProperties.
Suppress type info If set, Jackson generator will not create annotations for class hierarchy mapping. Available for root classes of the class hierarchies. By default, Jackson generator creates type mapping annotations.
Type-info property Name of the JSON attribute to carry information about the type mapping, similar to discriminator name of the JPA annotations. Available for root classes of the class hierarchies. Default value is type.
Type-info property value Value to be used by the Jackson runtime to identify this particular Java type, similar to discriminator value of the JPA annotations. Available for subclasses - leaves of the class hierarchies. Default value is the lower-cased name of the class.
Property name Custom property name to be used. Available for UML attributes and association ends.

Documentation Profile Rebel Plus

To establish a connection between your UML model and Swagger documentation of your RESTful service, the Rebel Plus introduces the Documentation profile.

Name Description Note
Documentation Format The documentation format to be used during code generation when processing documentation of model elements. Can be customized for packages and classes. Possible values include inherit from parent, javadoc, swagger and none.

When you select a package or a class, you can customize the Rebel Plus Documentation properties by using one of the predefined values:

  • inherit from parent,
  • javadoc,
  • swagger,
  • none.

The last three options: javadoc, swagger and none are used to customize the mapping of model documentation to one of the selected output formats. Whatever you select - will be the output format for that particular model element.

The first option, inherit from parent, the default value for documentation format, gives you the possibility to easily customize the export documentation for multiple model elements at once.

You can read more about using Documentation profile in the dedicated blog post.

Upgrade to Rebel Plus

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

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.

Suppress Properties Display
Account class displayed with and without StarUML tags

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.

Great work provides a great integrity.