Structure of UML Model
In this section we will describe a proposal how to structure your UML model in combination with MagicDraw UML our recommended UML Modelling Tool (also see UML Modelling Tools).
Of course JEAF and JEAF Generator do not require this structure but as part of our modelling guidelines we also would like to make a proposal how to structure your UML model.
Hopefully this will provide some benefit to you. If not just ignore it.
Rule # | Topic | Recommendation | Sample Model |
|---|---|---|---|
1.1 | Services | Services and their related service objects etc. should be located in the same package. If you wish to separate services interfaces from their data objects it’s still possible to do that in the JEAF Generator configuration even though they are in the same package. | 4️⃣ |
1.2 | Components | Components should either be placed in a sub package of the service they provide or in another part of the package hierarchy. Placing components in the same package as the service however is not recommend as this breaks the concept of separation between interfaces and their implementation. | 3️⃣ |
1.3 | Persistent / Domain Objects | Persistent / domain objects define the domain model of a component which is an internal implementation detail of a component. So we recommend to put them into a sub package of the component e.g. named | 1️⃣ |
1.4 | Internal Services | Services that are used to improve the internal structure of a component should be modeled in a sub package of the component to which they belong. Same should also be done for related service objects etc. Components implementing an internal service should be placed again in a sub package of the internal service. | 2️⃣ |
Mandatory Rules
The following table contains a set of mandatory modelling rules. Mandatory means that in case that they are not fulfilled it is expected that JEAF Generator won’t be able to produce legal code. May be code generation will be even interrupted for such model elements.
Rule # | Topic | Model element / type | Rule |
|---|---|---|---|
2.1 | void | Operations | For operations with return type  |
2.2 | Byte Arrays | Properties, Parameters, Return values | If you want to use a byte array as property, parameter or return type then you need to use the primitive type  |
2.3 | Java Collections | Properties | Java Collection classes like For the concrete type mapping please refer to JEAF Generator and Java Collection Types  |
2.4 | Exceptions | Operations | Exceptions that are thrown by an operation need to be declared on the operation in the UML model. |
2.5 | String | Datatype | When using type |
Recommendations / Best Practices
The table below contains a set of recommendations and best practices about UML modelling. It’s up to you if you follow them or not. It’s just a recommendation and will not have any impact on the process of code generation with JEAF Generator.
Rule # | Topic | Model element / type | Recommendation / Best Practice |
|---|---|---|---|
3.1 | Documentation | all | It’s strongly recommended to add documentation to all classes, interfaces, attributes, associations, operations, parameters etc. When ever possible the comment should explain what is the semantics of an model element. To ensure high quality of comments also meaningful examples are very helpful. Please be aware that JEAF Generator will use to comments from the UML model also for the generated code. Due to that documentation should also be compatible with Javadoc guidelines. |
3.2 | Primitive Types | Properties | We strongly recommend to either only use primitive types or only Java wrapper types. There are pro’s and con’s for both approaches. So most important is that your model is consistent |
3.3 | Primitive Types | Operations of business objects | We strongly recommend to not use primitive types nor its Wrappers as parameters / return types for business operations. Instead whenever possible real objects that represent the business should be used. |
3.4 | Primitive Types | Service operations | We strongly recommend to not use primitive types nor its Wrappers as parameters / return types for service operations. Instead whenever possible real objects that represent the business should be used. |
3.5 | Enumerations | Properties | We strongly recommend to use enumerations instead of primitive types / wrappers in case that you have lists of possible values. |
3.6 | Exception | We recommend to make use of JEAF’s Exception Handling concept. It distinguishes between technical and business exceptions. They can be easily modeled using stereotypes Please also refer to How to model Exceptions | |
3.7 | Deprecations | Any model element | Over time software changes and some functionality may be outdated. It’s still there but it should not be used any longer and it will be removed sooner or later. In this case you should make use of so called deprecations. Deprecations are markers that indicate that a specific model element should not be used any longer. To do so, you just have to apply the stereotype JEAF Generator will also mark the generated code as deprecated. Remark:
|
3.8 | Source Code Management | Any | Even though source code is generated it is best practice that it is managed by a version control system like Git, SVN etc. If you do so you have the following benefits:
|
3.9 | Code Generation as part of build | Any | It's strongly recommended that code generation is always a mandatory part of the build process. This way manual changes to the generated code can be prevented very effectively. |
