This page provides information about how to put in place the business layer of your modernization project in your UML model.
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.
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.
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.
Global configuration can be added to the classes of your business layer through the following stereotypes :
|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.|
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 :
|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.|
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.
TODO : This section is incomplete and should be enhanced.
In order to represent the relational component of your database schema, BluAge UML modeling provides ways to modelize associations relationships between your entities.
The easiest way to create the associations between your entities is by creating a classes diagram next to these entities :
- Right-click on an UML package, usually the one containing the entities to work with;
- 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.
Now if you want to add an address to your Customer, select the association arrow in the MagicDraw panel.
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) :
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.
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 :
Used to add an element to a list (association).
Used to remove an element from a list (association).
|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).
|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 :
|headerText||Used to provide custom header at the top of the operation. The text is specified by the tagged value headerText.|
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.
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.
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 :
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.
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 :
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 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 :
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 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.
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 :
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.
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.
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 :
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 have the same purpose as Transient Objects based on a PK_MODEL entity modeling.
Here is an example of a bean modeling :
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
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||Defines which class is used to generate a class identifiers strategy.
See following section Generator strategies for more details.
|@inheritance||InheritanceStrategy||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 :
|@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 :
|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 :
|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 :
|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 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 :
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 firstname.lastname@example.org (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 email@example.com (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.||/|
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 :
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 :
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.
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 :
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 :
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 :
|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.
The following stereotypes are available to configure the attributes of your persistence layer associations :
|@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;
merge: Defines a MERGE cascade strategy;
refresh: Defines a REFRESH cascade strategy;
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.|
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 :
- Create a package under your PK_BUSINESS package, which will be the root of your secondary persistence unit mapped entities;
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.
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.
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.
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.