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.

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.

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

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.

void

Operations

For operations with return type void the datatype void from the UML standard profile has to be used.

Open

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 byte and set its multiplicity to 0..*.

Java Collections

Properties

Java Collection classes like List, Set etc. must not be used as type for properties of classes. Instead associations to the related classes need to be defined. The type of collection can be controlled by defining Multiplicity, Is Ordered and Is Unique in the UML model.

For the concrete type mapping please refer to JEAF Generator and Java Collection Types

Exceptions

Operations

Exceptions that are thrown by an operation need to be declared on the operation in the UML model.

String

Datatype String in UML model

When using type String in the UML model you need to ensure that it is java.lang.String that is provided through the Java Profile.

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.

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

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.

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.

Enumerations

Properties

We strongly recommend to use enumerations instead of primitive types / wrappers in case that you have lists of possible values.

Exceptions

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 «ApplicationException» and «SystemException».

Please also refer to How to model Exceptions

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 «JEAFDeprecated» to the model element. This can be anything from a whole class or interface to an parameter of an operation.

JEAF Generator will also mark the generated code as deprecated.

Remark:

• Please be aware that in MagicDraw UML there is an build in stereotype «deprecated» and stereotype «JEAFDeprecated» from JEAF Meta Model. Stereotype from MagicDraw Profile is not supported by JEAF Generator.

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:

• Developers are able to identify and detect changes in the generated source as there are diffs to the previous version

• Analyzing of the behavior of the existing application is way simpler as also the generated code is always present.

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.

To support this as much as possible JEAF Generator is provided as Maven Plugin for a seamless integration (Integrate JEAF Generator into Maven Build ).