Skip to content
BluAge Documentation

Business Modeling

This page provides information about how to put in place the business layer of your modernization project in your UML model.

Introduction

The business layer of your modernization project contains all the entities which will contribute as interfaces with your database layer as well as transient entities used for the MMI layer.

Business1

The following general rules apply to your UML business layer :

  • All your business layer must be located in a PK_BUSINESS package, which must be located under the root PK_TARGET package;
  • Multiple packages stereotyped PK_BUSINESS are allowed in your model.

Business Elements

Classes

Entities are represented by classes. This set of classes defines the database schema, as well as entities used in the generated application. Links between classes are represented by associations.

Here is an example of an UML class with an attribute named id and two operations getId and setId.

Business1

Global configuration can be added to the classes of your business layer through the following stereotypes :

Class stereotype Description
deprecated Used to mark a class as deprecated.
headerText Used to provide custom header at the top of the class. The text is specified by the tagged value headerText.

Attributes

Entities attributes are represented by classes properties. They define mapped columns of the database schema, as well as attributes used in the generated application.

Global configuration can be added to the attributes of your business layer through the following stereotypes :

Attribute stereotype Description
constant Used to mark an attribute as a constant.
deprecated Used to mark an attribute as deprecated.
headerText Used to provide custom header at the top of the attribute. The text is specified by the tagged value headerText.

Visibility

Attributes are always generated with private visibility, independently of their configured visibility in the UML model. Getters and setters are always generated alongside them to provide the access/modification logic.

Default values

TODO : This section is incomplete and should be enhanced.

Associations

In order to represent the relational component of your database schema, BluAge UML modeling provides ways to modelize associations relationships between your entities.

Association Creation

The easiest way to create the associations between your entities is by creating a classes diagram next to these entities :

  1. Right-click on an UML package, usually the one containing the entities to work with;
  2. Select Create Diagram and then Classes Diagram.

You can now drag and drop in this newly created diagram the entities you want to configure. here is an example in the following screen with two entities.

Business_Asso1 Business_Asso1

Now if you want to add an address to your Customer, select the association arrow in the MagicDraw panel.

Business_Asso2

Now click on the first entity and then on the second one to create the association between them. You can see that the attributes have been added to the model (in red) alongside the relationship (in blue) :

Business_Asso2

Association Configuration

Both ends of the association can then be configured by double-clicking on the end of the association in the Classes Diagram or directly on the newly created properties in the UML model.

The following configuration is available through MagicDraw properties :

  • name : The name of the property;
  • navigable : Whether or not this end of the association is navigable or not. It will determine if the association is unidirectional or bidirectional;
  • multiplicity : The multiplicity of this end of the association.

TODO : This section is incomplete and should be enhanced.

Class Operations

Entities operations are represented by classes operations. They define the business logic of your application.

The following operations are allowed inside your business layer objects :

Operation stereotype Description
attach Used to add an element to a list (association).
Deprecated.
detach Used to remove an element from a list (association).
Deprecated.
getter Used to mark an operation as a getter for an Entity attribute.
setter Used to mark an operation as a setter for an Entity attribute.
formula Used to mark an operation as formula, which will describe a raw implementation in all Forward target languages through its tagged values (currently Java and .NET).
  • binary_java : The Java implementation;
  • binary_net : The .NET implementation;
  • binary_ts : The TypeScript implementation.
This implementation is strongly discouraged as it breaks the "target-independent" modeling goal.
process Used to mark an operation as a process, which will provide an implementation for all Forward languages through the use of an Activity Diagram.

Global configuration can be added to the operations of your business layer through the following stereotypes :

Operation stereotype Description
headerText Used to provide custom header at the top of the operation. The text is specified by the tagged value headerText.

Getters/setters

By default, getters and setters are automatically generated by the BluAge Forward generation and don't rely on the presence of the corresponding getter/setter-stereotyped operations in the UML model.
However, you can explicitly define getters and setters in your UML model to customize your behaviors. The following rules apply to the operation used to define your custom getter or setter :

  • The operation is located in the UML class and must be a process operation;
  • The name of the operation is the capitalized name of the corresponding attribute, prefixed with get for getters, is for boolean getters and set for setters;
  • For getters, the operation has a parameter with the type of the corresponding attribute. For setters, the operation has a return value with the type of the corresponding attribute.

NOTE : Starting with BluAge products 5.5, BluAge provides a wizard to help you through the creation of getters/setters based on a previously created attribute. For more information about this wizard, please refer to the BluAge Wizards page.

Here is an example illustrating the implementation of custom getters and setters for the id attribute of an UML class. In red are the default getter and setter, optional for the BluAge Forward generation, and the overridden process operations are shown in blue, with their corresponding activity diagrams.

Business_CustomGetSet

Constructors

By default, constructors are only generated if they are explicitly needed by the BluAge Forward modeling, for instance for lists initializations.
However, you can explicitly define a constructor in your UML model to customize your behaviors. The following rules apply to the operation used to define your custom constructor :

  • The operation is located in the UML class and must be a process operation;
  • The name of the operation must be the name of the enclosing UML class;
  • The operation doesn't have a return value;

Here is an example illustrating the implementation of a custom constructor for the ExampleEntity UML class.

Business_CustomConstr

Business Classes

Entities

There are several ways to represent your entities in your UML model.

Entity / Business Object couple

The Entity / Business Object couple modeling consists in a couple of UML classes :

  • Entity : Entities are represented by classes. This set of classes defines the database schema, as well as entities used in the generated application;
  • Business Object : The UML class which inherits from the Entity to provide the business rules for the entity, such as getters, setters and process operations. It can also provide attributes which are not mapped to the underlying database.

NOTE : In BluAge products 5.4, BluAge provides a wizard to help you through the creation of the associated Business Object of a previously created Entity. For more information about this wizard, please refer to the BluAge Wizards page.

Here is an example of an Entity / Business Object couple modeling and its class diagram :

Business2 Business3

The following rules apply to all Entities and Business Objects in your UML model :

  • An entity and BO must have a unique and capitalized name. Usually the BO is named after the Entity name with the "BO" suffix;
  • An entity must be stereotyped Entity and contained in a PK_ENTITY package;
  • A Business Object must be contained in a PK_BUSINESS_OBJECT package;
  • An entity must not be used as a parameter, or as a return type in a method. Instead, the associated Business Object should be used;
  • An entity must not be used as a class attribute (except entities made from associations links, as well as BOs inheriting from those attributes).

NOTE : The Entity / Business Object couple modeling is deprecated and for compatibility only.
It is strongly advised that you use the PK_MODEL entity modeling for your entities. BluAge products provide a migration wizard to help you through this step, described here.

PK_MODEL Entity

The PK_MODEL Entity modeling consists in a single UML class, which is a "merge" of the Entity and the Business Object classes previously demonstrated. It provides all attributes and business logic.

Here is an example of a PK_MODEL Entity modeling :

Business4

The following rules apply to all PK_MODEL Entities in your UML model :

  • A PK_MODEL Entity must have a unique and capitalized name;
  • A PK_MODEL Entity must be stereotyped Entity and contained in a PK_MODEL package.

Transient Entities

Transient Entities are the non-persisted side of the previous section. They are used to carry information and logic used in the generated application but not related to the database layer.

Here is an example of a Transient Entity modeling based on a PK_MODEL Entity modeling :

Business_Transient

The following rules apply to all Transient Entities in your UML model :

  • The rules specified in the Entities section also apply here, depending on your Entities modeling choice;
  • A Transient Entity must in addition be stereotyped TransientObject.

Transient Attributes

Transient Attributes may be added to a non transient (persisted) entity. In order to achieve this, a TransientAttribute stereotype is available.

NOTE : With the previous Entity / Business Object couple modeling, you could also put your transient attributes in the BO (versus persisted attributes in the entity).
NOTE 2 : A @transient stereotype also exists, with the added effect to also add a transient keyword in java.

Value Objects

A Value Object is an object used in the MMI layout and which is an image of a persisted entity. These elements are untied from the persistence layout and are so easily handleable.

Here is an example of a Value Object modeling mirroring a PK_MODEL Entity :

Business_VO

The following rules apply to all Value Objects in your UML model :

  • A Value Object must have a unique and capitalized name. Usually the VO is named after its mirrored Entity name with the "VO" suffix;
  • A Value Object must be stereotyped VO and contained in a PK_VALUE_OBJECT package;
  • The tagged value entity of the VO stereotype must be filled with the associated Entity class.

NOTE : BluAge provides a wizard to help you through the creation of a Value Object based on a previously created Entity. For more information about this wizard, please refer to the BluAge Wizards page.

FieldAsString attributes

Since the Value Object is the MMI layout representation of an Entity, and its attributes are meant to be printed and modified, each attribute can be coupled with a fieldAsString attribute which is its String representation. This behavior is shown in blue in the preceding screen.

Getters and setters for this associated field as string are also present. The BluAge generation stack adds several utility methods to process all type conversions in order to convert the original attribute to its String representation and to modify back the original value after a screen submit for instance.

The following rules apply to all fieldAsString in your Value Objects :

  • A String representation of an attribute must be stereotyped fieldAsString;
  • The tagged value @field of the fieldAsString stereotype must be filled with the associated attribute.

Constants

A Constant class is simply an UML Class used to store constant attributes which can be used by other classes.

Here is an example of a constant class modeling :

Business_Constant

The following rules apply to all Constants classes in your UML model :

  • A constant class must have a unique and capitalized name;
  • A constant class must be stereotyped constant and contained in package under the PK_BUSINESS package.
  • All attributes in a constant class are considered as constants attributes;
  • All attributes must follow the target language convention for constants naming.

Beans

Beans have the same purpose as Transient Objects based on a PK_MODEL entity modeling.

Here is an example of a bean modeling :

Business_Bean

The following rules apply to all beans in your UML model :

  • A bean must have a unique and capitalized name;
  • A bean must be stereotyped bean and contained in package under the PK_BUSINESS package.

Persisted Elements Configuration

Classes Configuration

Regardless of your persisted entities modeling, the Entity-stereotyped Entities of your UML model can be customized to cover your persistence usages. The following tagged values are configurable inside the Entity stereotype :

NOTE : Depending on your BluAge Forward generation stack, some of these values may not be taken into account. They also can be overridden/defaulted by specific workflow values. For more information, please refer to the documentation related to your BluAge Forward generation stack.

Tagged value Type ( = default value ) Description
@cache Cache = undefined Specifies the cache strategy for the entity
See following section Cache strategies for more details.
@cache.maxElementInMemory Int = 0 Specifies the max number of cached elements.
@cache.overflowToDisk Boolean = false Specifies whether elements can be stored on the disk.
@cache.timeToIdleSeconds Int = 0 Specifies an element inactivity period before cache expires.
@cache.timeToLiveSeconds Int = 0 Specifies an element survival time before cache expires.
@defaultOrder String Specifies the default order of the query list results provided by generic services.
@entity.dynamicInsert Boolean [0..1] = false Specifies whether the SQL INSERT order shall be generated during the execution or if it must only contain columns without « null » values.
@entity.dynamicUpdate Boolean [0..1] = false Specifies whether the SQL UPDATE order must be generated during the execution or if it must only contain columns with values that have changed.
@generator.class GeneratorClass[1] Defines which class is used to generate a class identifiers strategy.
See following section Generator strategies for more details.
@inheritance InheritanceStrategy[1] Defines the inheritance strategy.
See following section Inheritance strategies for more details.
@sequence.allocationSize Int = 1 Specifies the size allocated for the sequence in case of sequence strategy.
@sequence.name String Specifies an existing sequence in the database.
@version String Specifies the name of the version column.
@versionColumn String Defines a value for each entity.
@versionMappingType String Specifies a custom version strategy.

Additional persistence information can be carried by the Entity through the following stereotypes :

Class stereotype Description
@DiscriminatorValue Specifies the discriminator value used to discriminate each record in a SINGLE_TABLE inheritance strategy.
@table Specifies the table name corresponding to the entity in JOINED and TABLE_PER_CLASS inheritance strategies.
@schema Specifies the table schema corresponding to the entity in JOINED and TABLE_PER_CLASS inheritance strategies.
NoVersionException Specifies that the Entity should not have a version attribute used for optimistic lock.

Cache Strategies (JPA Hibernate target only)

The following Hibernate cache strategies can be selected :

Cache strategy Description
nonstrict-read-write Used to provide a non strict read & write cache to your Entity. It can be useful if the application only occasionally needs to update data (i.e. if it is extremely unlikely that two transactions would try to update the same item simultaneously), and strict transaction isolation is not required.
read-only Used to provide a read-only cache to your Entity. It can be useful if your application needs to read, but not modify, instances of a persistent class.
read-write Used to provide a strict read & write cache to your Entity. It can be useful if the application needs to update data on a regular basis and if serializable transaction isolation level is not required.

Generator Strategies (JPA Hibernate target only)

The following Hibernate generator strategies are supported for Entities identifiers :

Generator strategy Description
assigned The Identifier value is manually assigned. It has the same behavior as setting the @assigned.identifier tagged value of all identifiers to true.
increment In association with a concrete inheritance strategy, it will result in a TABLE generation type, which relies on a database table to store and update values. Otherwise, it will result in an IDENTITY generation type, which relies on an auto-incremented database column.
sequence Use a database sequence to generate the Identifier. It will result in a SEQUENCE generation type, will trigger the use of a sequence generator configurable through the @sequence.name and @sequence.allocationSize tagged values of the Entity.

Other generation strategies assignable from the GeneratorClass enum are not used and will result in an AUTO generation type.

Inheritance Strategies (JPA Hibernate target only)

The following Hibernate inheritance strategies are supported for Entities :

Inheritance strategy Description
class Symbolize a SINGLE_TABLE inheritance strategy. This strategy creates one table for each class hierarchy.
concrete Symbolize a TABLE_PER_CLASS inheritance strategy. This strategy maps each entity to its table which contains all the properties of the entity, including the ones inherited. Abstract entities in the hierarchy are marked as MappedSuperClass.
interface Strictly equivalent to concrete. Deprecated.
subclass Symbolize a JOINED inheritance strategy. Using this strategy, each class in the hierarchy, abstract or not, is mapped to its database table. The only column which repeatedly appears in all the tables is the identifier, which will be used for joining them when needed.

Embeddable Entities

Embeddable entities are used to carry common information aimed to be shared by multiple persisted entities.

In order to reproduce this behavior in your UML model, the following rules must be applied :

  • An Embeddable class is a standard persisted Entity, with the addition of the Embeddable stereotype;
  • When using the Embeddable class as an attribute in your persisted Entity, the attribute must have the Embedded stereotype.

Here is an example of an Embeddable class Address, used in the persisted Entity Customer :

Business_Embeddable

Attributes Configuration

The following stereotypes are allowed for your persisted entities attributes :

Stereotype Description Tagged values and notes
@column Defines the name of the column mapped to the attribute. If this stereotype is not applied, the mapped column name is computed from the name of the attribute.
@column.length Defines the length of the column mapped to the attribute. @column.length (String) : Defines the length of the mapped column. You can also specify the precision by separating the two numbers by a comma and the scale for decimal types.
DiscriminatorColumn Defines the attribute as a discriminator value for the entity. /
Embedded Defines the attribute as Embedded, overriding existing attributes by the ones specified in the attributeOverrides tagged value. attributeOverrides (List) : Comma-separated list of key=value. Each key refers to the name of the attribute being overridden and the value refers to the column name of the attribute which overrides the key.
Identifier Defines the attribute as a primary key. @assigned.identifier (Boolean) : specifies if the identifier is automatically assigned by the database manager or manually defined. Default is automatic assignment.
The @generator.class tagged value of the Entity stereotype specifies the generator strategy for Identifiers.
@insert Defines the attribute as insertable or not. @insert (Boolean) : insertable when true, false otherwise.
Not applying this stereotype is equivalent to true.
password Defines the attribute as a user password for login operations. /
Required Defines the attribute as non-nullable. requiredMsg (String) : deprecated.
role Defines the attribute as representing a role (actor). /
temporal Defines the temporal type of the attribute for Date attributes, through the temporalType tagged value. temporalType (Enum) : DATE, TIME or TIMESTAMP.
Default is DATE when the stereotype is not applied or the tagged value not filled.
TransientAttribute Defines the attribute as transient (excluded from database persistence). When applied, this stereotype also disables all other potential persistence stereotypes applied to the attribute.
@transient Defines the attribute as transient. Same as above, and in addition, will also exclude attribute from serialization.
Unique Defines the attribute as unique. /
@update Defines the attribute as updatable or not. @update (Boolean) : updatable when true, false otherwise. Not applying this stereotype is equivalent to true.
userid Defines the attribute as a username for login operations. /

Associations Configuration

Associations Types

One2One

This is the most basic association binding a [0..1] multiplicity attribute of an entity to a [0..1] multiplicity of an other entity's attribute.

Here is an example of a One2One configuration :

Business_O2O

One2Many / Many2One

This association binds a [0..1] multiplicity attribute of an entity to a [0..*] multiplicity of an other entity's attribute.

Here is an example of a bidirectional One2Many configuration :

Business_O2M

In bidirectional relationships, Customer is said to have a One2Many association with Product and, at the opposite, Product is said to have a Many2One association with Customer.

Many2Many

This association binds a [0..*] multiplicity attribute of an entity to a [0..*] multiplicity of an other entity's attribute.

Here is an example of a Many2Many configuration :

Business_M2M

ElementCollection

This special association is used to define a collection of instances of a basic type or embeddable class. It binds a [0..*] multiplicity attribute of an entity to the primitive datatype used in the collection. The attribute side of the association must be stereotyped ElementCollection.

Here is an example of a ElementCollection association :

Business_O2M

Associations Configuration

Collection types

Except for One2One associations, the collection type used to store the * sides of your associations can be parametrized through the @collection.type tagged value of the @collection.type stereotype and the following enumeration values :

@collection.type Description
bag Similar to list.
list The generated collection type is a list.
map The generated collection type is a map.
set The generated collection type is a set.

The default collection type if you don't provide the stereotype is list.

Bidirectional / Unidirectional association

The unidirectional / bidirectional parameter of the relationship is configurable through the navigable MagicDraw property at both ends of the association. For instance, in the previous example, if you want Customer to have its list of Product but don't want each Product to keep the reference to its owner, you can turn off the navigable property of the Product end of the relationship to create a unidirectional One2Many association.

Persistence configuration

The following stereotypes are available to configure the attributes of your persistence layer associations :

Stereotype Description Tagged values
@cascade Specifies the cascade strategy to adopt when an entity with children entities is subjected to operations.
Available for One2One, One2Many and Many2One associations.
@cascade (Enum) :
all: Defines a ALL cascade strategy;
all-delete-orphan: Defines a ALL cascade strategy;
create: Defines a PERSIST cascade strategy;
delete: Defines a REMOVE cascade strategy;
evict: Unsupported;
lock: Unsupported;
merge: Defines a MERGE cascade strategy;
refresh: Defines a REFRESH cascade strategy;
replicate: Unsupported;
save-update: Defines a PERSIST/MERGE cascade strategy;
@foreignkey.constraint Specifies that the attribute has a foreign key constraint applied on it. /
@lazy Specifies the retrieve strategy to adopt when an entity is fetched.
Available for all associations except ElementCollection associations.
@lazy (boolean) : when true, a proxy is loaded instead of the actual attribute when the entity is fetched, and the attribute has to be specifically fetched to be access and/or modified. Otherwise, the actual attribute is automatically fetched when the parent entity is fetched.
@collection.index For list association collection types, specifies the order column. Its allows you to maintain the persistent order of list when being inserted into the database and want to retrive the list in the order it was inserted.
Available for One2Many, Many2Many and ElementCollection associations.
/
ElementCollection For ElementCollection associations, the collectionTable tagged value allows to specify the table name used to store the collection values. collectionTable (String) : The table name used to store the values of the collection.
@orderByColumns Specifies the ordering of the elements of a collection valued association or element collection.
Available for One2Many, Many2Many and ElementCollection associations.
@orderByColumns (List) : The comma-separated list of ordered column names.

Multi-datasource Configuration

The standard hierarchy of your PK_BUSINESS packages is mapped to the default database configured in the BluAge Forward process.

However, you can configure your UML model in order to map different sets of persisted entities to different persistence units. If you want to add an other persistence unit and map it to some UML Entities, the following steps are required :

  1. Create a package under your PK_BUSINESS package, which will be the root of your secondary persistence unit mapped entities;
  2. Add the URL_Connection stereotype to this package;

    NOTE : In SpringBoot BluAge products, you can also use the newer PersistenceUnit stereotype, which works exactly the same way but is more readable.

  3. Fill the dbkey tagged value of the URL_Connection with the key of your secondary persistence unit;

    NOTE : The PersistenceUnit tagged value equivalent is name.

  4. Configure the connection information of your secondary persistence unit by creating a group property with the name of the tagged value you provided and adding appropriate workflow properties in this group property;

    NOTE : For more information about the BluAge Forward launch configuration, please refer to the BluAge Launch Config page.

  5. You can now add a new hierarchy of packages under this root package, and each modeled persisted entity will here be mapped to the secondary database.