Server `DSL`

Theme-sets declare icons, colors, themes, theme-variants and styles.

Labels enable the internationalization (i18n) of the user-interface. All user-facing text is replaced by label-codes. These codes are grouped together into label-sets, and translated using standard Java i18n property-files.

Label declarations can contain the following key-words:

For example, DSL declaration:

The label set has an identifier (TRD_Labels), and every label has a code (actionConfirmLabel, etc.). Together with the package name, these comprise the fully qualified name of the label.

The actionConfirmLabel, for example, is imported in the following action declaration:

These buttons are part of order-confirmation:

The Undo button will only appear once the order has been confirmed, in stead of Confirm and Remove buttons.

All labels are imported into the application, and for convenience reasons, they are referenced only by label name. This means that label names should be globally unique in order to avoid conflicts.

Global application configurations are contained in one or more configuration DSL files. They define the label-sets available in the application:

Value types are immutable objects that represent business concepts which are identified by its value.

Examples of Value Types are Amount, Price, Quantity and Confirmed.

Value types are identified by their content, an amount of 100 equals an amount of 4*25:

This in contrast to entities which are considered equal if the entity-identifiers (primary-keys) match.

Value Types wrap Java primitive types in order to provide additional abstraction and validation. The following value types are supported:

Value Types make business code more readable and concise. Consider, for example, the following createOrder method:

The input parameters are very concise. The caller has to provide a Document which will be defined as a string, of a specific length and without spaces. The Reference is a much longer string which does allow spaces. The OrderDate is defined to be different from an InvoiceDate. The Quantity has a smaller scale than Price.

Compare this with the same method without value type abstraction:

Much of the semantics is lost. More over, this method allows the quantity and price to be mixed up. It accepts documents where a customer reference is expected, and there is no guarantee that the provided values do not exceed the field length of the database.

Only valid value-type instances can be created. Decimals are rounded upon creation to fit the precision and scale. String value types will throw an exception upon creation if they exceed the defined length. And, as value-types are classes, new validation logic can be added to the constructor.

Wercstat provides a convenient way to declare value types. For example:

DSL Value Types are based on the Value Types described in the `Wercstat Domain` manual. Because the DSL uses code-generation, it can add static methods which are not available through inheritance.

This section will only describe usage of the Value Type DSL and the additional static methods. A more detailed explanation of value types can be found in the `Wercstat Domain` manual.

Value-type DSL declarations generate an abstract and a concrete class, both in the generated source folder. The abstract class extends a base value-type class (DomainBoolean, DomainString, etc.) and adds static constructors. The concrete class is a skeleton that can be moved to the manual source folder and customized to add validation or functionality.

For example:

Boolean value type DSL declaration:

The abstract class extends DomainBoolean and adds static constructors and TRUE/FALSE constants:

For convenience there is an additional constructor that allows null values:

Date value type DSL declaration:

The abstract class extends DomainDate and adds static constructors:

and convenience methods:

DateTime value type DSL declaration, including precision:

The precision can be milliseconds, seconds or minutes. New instances will be truncated according to their precision.

The abstract class extends DomainDateTime and adds static constructors:

and convenience methods:

Decimal value type DSL declaration, including respectively, the precision, scale and rounding:

The rounding can be ceiling, down, floor, half_down, half_even, half_up or up.

The abstract class extends DomainDecimal and adds static constructors:

and convenience methods:

Note that the of static constructor can also be used for converting types:

Assuming Price is declared as follows:

then convert an Amount to a Price is simple:

Conversion is only possible if the domains are compatible:

The DSL declaration for an Enumerate value type with three options; 'Yes', 'No', 'Unknown':

The labels are defined as follows:

The enumerate implements DomainEnumerate and includes a static of constructor:

empty or invalid enumerate-codes are not allowed:

Note that the enumerate constants are the same as the label text. For example YesNoUnknown.UNKNOWN. The UNKNOWN is derived from the yesNoUnknownLabel_U label. The actual code stored in the database is U. Every enumerate item has a getPersistentCode() method to retrieve the database value.

This approach ensures that enumerates in source-code are expressive, while the code in the database can remain short. However, this also means that changes in label-text will require changes in the source-code.

Integer value type DSL declaration, including the lower- and upper-bound for values:

The abstract class extends DomainInteger and adds static constructors and the constants ONE and ZERO:

with convenience methods:

The instantiated objects must conform to the integer value range of 0 to 60:

String value type DSL declaration, including maximum number of characters:

The abstract class extends DomainString and adds static constructors:

assuming there is a Name value type:

the static of constructor can be used for conversion:

provided the value is not more than 10 characters for Name:

and the convenience methods:

Time value type DSL declaration, including precision:

The precision can be milliseconds, seconds or minutes. New instances are truncated according to their precision.

The abstract class extends DomainTime and adds static constructors:

and convenience methods:

Value Types can be extended with custom logic by adding the custom keyword to the declaration. For example:

The custom keyword will move the concrete subclass from the generated-code folder to the manual-code folder.

Now new logic or validation can be added to the value type class.

Domain Entities are mutable objects, typically persisted to a table in a database.

The Wercstat DSL provides an extended syntax to declare entities that not only includes persistence but also other aspects of the application like validation, nullability and consistency.

Entities have both a surrogate key and a business key.

The surrogate key is a technical key, invisible to the end-user and immutable. In Wercstat it is implemented as a number or GUI which uniquely identifies every record in the entity table. The surrogate key is required to implement foreign keys, i.e. relations to other tables.

The business key is visible to the end-user. It consists of one or more fields that uniquely identity an entity. For example TermsOfDeliveryCode or SalesOrderNumber. Business keys are allowed to change, but that should only be done with care, as they are communicated-to and used-by the outside world.

The business-key must be declared at the start of the entity-declaration.

search-paths is an optional list of field-paths, which are searched when entering a search-term to find a single entity.

Any time there is an input-form with a relation field, we can enter either the business-key, or a search term.

Wercstat will first check if the input-value is a business-key, if so the entity is selected.

If the input is not a business-key, Wercstat will try a substring search (like in SQL) on all search-fields as defined in the entity.

Should one entity be found, it is automatically selected. Otherwise a selection-list is shown with all the entities that fit the search-term.

A Partner is defined as follows:

The sales order form has a field to select a Partner:

select-paths is a optional list of grid- field-paths which are displayed when selecting an entity from a list.

Wercstat creates a table index for the business-key, and for all foreign relation fields.

This will create a SalesOrder table with an uniqueness-constraint on column documentCode, and an index on column customer.

The entity is often searched by customer reference, so an extra findByAllByReference method is declared in the Sales Order Repository.

However, this might cause a performance problem as there is no table index on the reference field. The database will scan all records to find a specific reference.

This can be solved by defining an additional index on the entity:

This will create an extra JPA Index annotation on the Java entity class, which in turn adds the index to the database.

Entity fields are grouped in to sets. The final-field set contains fields that only get a value once, and can not be changed. And of course the field has only getters, no setters.

The value must be provided when an object is instantiated, either by:

Wercstat will ensure that final-fields are added to the entity constructor if required.

User fields can be updated both in the user-interface and in code.

In order to make it clear to the programmer that the field is intended for an end-user, the setters must be accessed via a user() method.

Updating the fields:

Operational fields can only be updated in code, not via the user-interface. The setters must be accessed via an update() method.

access in code:

transient entities are not persisted, i.e. not stored in the database. No repository reader or writer classes are generated.

Adding the custom-entity keyword to an entity declaration moves the concrete entity class to the manual source folder.

The concrete Java class has the following structure:

The concrete User can now be extended by overriding constructors, getters, setters and adding new methods.

With a custom-writer new business logic can be triggered when entities are persisted or deleted. Adding the custom-writer keyword to an entity declaration moves the concrete entity-writer class to the manual source folder.

The following methods can be implemented:

With a custom-reader new queries can be added to the Spring data repository. Adding the custom-reader keyword to an entity declaration moves the Spring Data repository interface to the manual source folder.

The repository has default finders for the business-key and optional find-by fields.

relation-validation enforces field-validation spanning multiple entities.

If two entities are related, and both have a field of the same entity type, then it must be specified whether both fields have the same value.

For example the Company entity. It might be used in entities SalesOrder, Customer and SalesContract.

relation-validation enforces validation of the company relation between these entities. If two entities are related, and both have a field of type Company, then it must be specified whether both fields have the same value.

If a Customer is assigned to a SalesOrder, then they must both belong to the same company. The same applies to the SalesOrder and the SalesContract.

Given the following entities:

Because SalesOrder has both a company field, and a relation with a table that also has a company field (SalesContract), the entity-validate becomes mandatory.

The entity-status keyword provides default logic and validation for common status fields, like confirmed, released, blocked, canceled, completed, processed and retired.

The finance-release-task entity is defined as follows:

By providing this additional information, Wercstat can provide additional logic:

Interface declarations and implementation can be defined in the Wercstat DSL. The actual implementations and interface definition must be done in the generated Java classes.

for example:

this will generate a default interface Java class in the main source tree.

Keyword table-name specifies the name of the table in the database, if it differs from the name in the entity. This is required if the table-name corresponds with a reserved keyword in the database. Of course it is always better to avoid reserved keywords as table-names.

The entity is named SalesOrder, but the table-field has name sales_order.

Entities have one or more fields, which can be attributes or a relations.

For example:

All fields support keywords optional, calculate, transient, find-by and column-name.

Attributes represent value-types like Name, Amount.

Attributes have a value-type, a name, an optional label, and optional properties like optional, calculated or transient.

the Name (with capital N) refers to the value-type Name, and the name is the actual field name.

All attributes are mandatory by default, this means:

Enumerates and booleans are always mandatory.

The name in the example above is mandatory. A null or empty value when creating the entity will result in an exception.

Relations declare foreign keys to other entities.

Relations have a name, an optional label, and optional properties like optional, calculated or transient.

As with attributes, all relations are mandatory by default, which means not-null.

Both attributes and relations can be defined as optional, for example:

Fields with keyword optional can be empty, meaning value null, 0 or "" depending on the field-type.

Note that Enumerates and Booleans must always have a value.

All fields that do not have the optional keyword are considered mandatory. As a rule entities can only be instantiated if all mandatory fields are not empty. What is considered an empty value depends on the field type:

Mandatory fields are checked both in the entity constructor and in the field setters. An exception will be thrown when assigning an empty value to a mandatory field.

The entity constructor consists of the business-key, plus all the fields required to make sure mandatory fields have non-empty values.

In practice this means the constructor includes all mandatory fields except when they are defined as calculated, transient or have a default value.

Domain entities implement method isMandataory(String fieldPath) which can be extended to make fields optional or mandatory at run-time. Note, it is not possible to make fields optional which are mandatory in the entity declaration.

calculated fields are updated by logic of the entity itself. Calculated fields have a protected setter (with a double underscore prefix '__' ) to indicate that they are not part of the public API of the domain entity.

Calculated field setters are defined as 'protected' and can only be accessed from within the package of the entity class.

Consider a User entity with calculated fields notesLastUpdate, and Age.

Wercstat will generate default getter-methods for calculated fields. In order to implement these the User entity must be marked with keyword custom-entity. This will move the User.java class from the generated to the main source folder.

The notesLastUpdate field is store in the database, so we only have to make sure it is updated when the notes field changes.

The Age field can not be stored as it changes continuously. In this case we simple calculate the value on every getter request.

transient fields are not persisted, i.e. not stored in the database.

This also means they must be optional unless they have a default value. Otherwise it would not be possible to load a valid entity from the database.

The find-by keyword will create a method in the repository reader to retrieve all instances of the entity, given a value of the field.

Keyword column-name specifies the name of the field in the database, if it differs from the name in the entity. This is required if the field-name corresponds with a reserved keyword in the database. Of course it is always better to avoid reserved keywords as field-names.

The entity-field is description, but the table-field has name desc.

The default keyword only applies to attribute fields. It sets the initial attribute value during object construction.

For example:

Default attribute values are mainly used to provide initial values to enumerate fields.

The one keyword only applies to relation fields. It defines a one-to-one relation between entities.

The Company is defined in the common module and holds a range of company defaults. With the introduction of a production module, more company-related defaults are required. However, to keep the module hierarchy intact, the Company entity must not reference entities in the production module.

For this reason a ProductionCompany entity is introduced. It holds all defaults related to the trade module. As there can only be one ProductionCompany for every Company, and visa versa, the appropriate relation is one-to-one.

The ProductionCompany entity has no surrogate key of its own. It is identified by the Company, so the surrogate primary key of the ProductionCompany entity is company in stead of the normal id field.

Assume the Company entity has the following fields:

then the ProductionCompany will have fields:

The ViewModel is a server-side representation of a user-interface form. Any changes to the view-model will be reflected in the UI, and any changes in the UI (e.g. user presses a button or enters a text-field) will be propagated to the view-model.

This allows the developer to add UI business-logic on the server side (in Java), with full transaction management and dependency injection.

Examples of view-model business logic:

By extending the view-model it is possible to:

Server-side exceptions are displayed to the user and logged in the cloud for help-desk support. When an exception occurs the current database transaction is aborted.

Adding the custom keyword to a view-model declaration moves the concrete view-model class from the generated source code folder, to the manual source code folder.

The concrete Java class has the following structure:

If the view-model is linked to an entity. it contains getters for all the entity fields, and setters for all entity user-fields.

All fields in the view-model are always optional. This reflects the fact that all fields in the UI can (temporarily) be empty while the user is entering new data, or altering existing records.

Business logic can be added to both the entity and view-model concrete classes. As a rule of thumb: business logic that assists the user while entering data should reside in the view-model. Business logic that executes workflow should be in actions or entity classes.

View grids are, as a default, ordered by business-key. This can be changed by adding one or more sorting-fields to the view-model entity.

The form section of a view-model defines fields which are not linked to an entity.

Some view-models only have a form, and no relation to an entity. For example the stock-move form that is used on mobile scanners:

A view-model contains actions to link buttons in user-interface, to methods in the server-side view-model.

Actions have two optional parameters:

All the actions that have an empty group, are added to the default tool-bar.

This will create the following abstract methods in the AbstractMRequestViewModel class that must be implemented in the MRequestViewModel class:

The returned ComponentStatus has the following options: