Guide - EFrame - SimpleMES

Micronaut is designed to produce microservices that are small and easy to implement. Why use a microservice framework for an enterprise application? Because many of the Micronaut features are very useful for an enterprise application. For example, quick startup time is very important if the app is host on a cloud provider.

The application (SimpleMES) is designed as a monolith. Why use a microservice toolkit for this type of application? Because we envision the application starting as monolith and evolving into a microservice app as needed. To do this, we chose to build the application in separate modules that work together inside of a single JVM. As the need arises, we can separate these modules into their own microservice.

This is monolith-to-microservice evolution is one reasonable way to build an app quickly and then evolve when needed. Not every app needs to start as a microservice-based app. There is a large cost to starting as a microservice. Some of the high costs include:

All of these add to the initial development cost. If the app is a success and needs to evolve, then we already have clear lines to break the app into microservices. This evolution is shown below:

The initial release of the application bundles all of the modules into one service. These all communicate using internal JVM calls. This allows simple database transaction control and supports easy rollback.

When needed, one of the modules (Track) is moved to its own microservice. This means we will develop a distributed transaction mechanism like Saga pattern to keep the data in synch.

This whole approach means the initial release will be simpler and easier to develop. As the requirements grow over time, we can decide to pay the extra cost of supporting multiple microservices.

This does force us to keep the modules as separate entities and minimize the the method calls to other modules. Micronaut makes this easy, but it does require some discipline.

Boiler-plate code should be kept to a minimum. This means anything that you have to do over and over in your application should be handled by the framework with minimal trouble.

Complexity kills productivity. To reduce the complexity, we just implement features/flexibility as it is needed.

Why choose Groovy over Java or Kotlin? One simple reason: clarity.

The biggest cost of successful software is the cost of maintaining the code for years or decades after you have written it. Clarity becomes critical when looking at code that was written a long time ago. For that reason, all decisions on this framework and application are driven by the need to appear simple to the user and to minimize the complexity for the application developer.

Groovy is clearer because:

We don’t want to write a 10 page summary of why Groovy is clearer, but here is a short example using a pattern often seen in application code. We need to call methods on a nested set of objects that may return null.

Using just two Groovy features reduces the code complexity significantly. Later versions of Java help in some areas (e.g. use of var), but the overall code clarity still suffers in Java (see Streams).

One caveat: Groovy has some terse and cryptic syntax. We have chosen to avoid those types of features that are not clear to the user. Features such as method pointers are wonderfully short, but not very clear. See Groovy Features to Use or Avoid for details.

Most modules have 3 main sets of documents:

The intent of the guide is to give you a general overview of feature, but not overwhelm you with details of the implementation. The reference documentation will explain most key fields, API calls and options. The guide generally has many links into the reference documentation.

Dashboards are fairly complex. To manage this in the documents, we use the guide for concept introduction and sometime simple examples. The reference document will explain all of the activities, events and scan actions for the dashboard. Each module will have additional activities, events and scan actions. These will be documented in a similar way:

These follow the basic Micronaut conventions, but add a few conventions for simplicity. The common suffixes used are:

These are not hard and fast restrictions, since Micronaut typically allows almost any name for the defined beans. You can deviate from these conventions if needed in your application.

Most standard objects will have these typical fields:

Quantity fields typically start with 'qty' and have a BigDecimal type.

This indicates something be beware of. This is frequently used to flag things that may become an issue someday. We want these flagged in a standard way to easily identify possible source of problems when a library module is upgraded. This includes some highlighting in the JavaDoc.

For example:

You will be developing modules for this framework to provide application functionality. To simplify your build.gradle file, the framework lists most development-time dependencies as compile. This means the dependencies section of your build.gradle file can be as simple as:

The application.yml file controls many of the features of your application. To avoid issues with the framework, you should use these settings:

See Security Setup for specifics on the security elements.

See Dependencies for details on the changes needed in build.gradle for required plugins.

Since the source code is usually re-formatted on check-in (Intellij IDEA option), the source format is important. Using a consistent format helps identify the 'real' changes between versions. The standards we follow are:

Groovy allows untyped fields/variables in your classes. This is great for internal uses. However, all APIs should use proper Java-style typing where possible. This means method parameters should not use def or Object when a real type is known.

Internal variables in methods can use the def syntax.

There is a programming concept called 'Fluid API' that makes a lot of sense. This approach is needed when more than 2 values need to be passed to a method/class. After 2 values, the meaning of each value is not always obvious without a good IDE. For example:

In this example, it is not clear what each number is doing. To avoid this problem, the framework generally uses the Groovy map constructor approach:

This make it very clear what each number is and Groovy enforces basic types and naming with the default Map constructor.

Groovy generally creates this constructor for you, but you can create your own. When you need to define your own constructor, you can use this code to emulate the Groovy Map constructor logic:

You will frequently need to log records with the user who performed some action. The obvious solution is to add a User to the domain and just store a reference to the user in database. This is simple, but it does have one big drawback: The referential integrity constraints in the database makes it difficult to remove user records.

To increase database flexibility, we will use the user name itself for these types of logging actions. This also reduces the chance of accidentally exporting the user/password info in a generic JSON export. This is important for archiving since we don’t want to archive the user records or force re-creation of deleted user records when un-archiving.

An example domain record below will record the user name for a component that has been assembled:

This reduces the code since the default for the new component is the current user. No extra database access is needed.

In contrast, the logic needed to store a full reference to the User object would be slower and more complex.

The normal Java style enums can be used in your application. These enums are displayed in the standard GUIs as a drop-down list with the enums toStringLocalized(Locale) text as the displayed value for each valid value.

Your enum should have these fields/methods to support storage in the database and display of human-readable values for each enum:

The localization can use any .properties file entry you like, but the standard approach is to use a naming convention like this (for a time interval enumeration):

An example toStringLocalized(Locale) method looks like this:

When the enums list of valid values is shown in list (e.g. a drop-down list in a GUI), then the list of valid values is displayed in the default Java order. This is the order that the enum values are defined in the class. This means you should put the most common values first in your enum .groovy file.

When it is time to throw an exception, you have to decide what type of exception to throw. In most cases, it comes down to how important the message is when monitoring a live system. What exceptions should show up in the server log (main log or StackTrace.log)? The framework follows a simple rule: If an exception is a BusinessException , then it won’t show up in the log files. These type of exceptions are usually returned to the caller or displayed in the GUI.

This means most business logic should throw a BusinessException when the problem is not a system type problem. This means most errors that should be fixed by the caller will be BusinessExceptions.

More critical exceptions are thrown with the MessageBasedException . These exceptions are logged.

The BusinessException uses an error code to define specific errors. The error ranges are allocated to the modules as follows:

In enterprise apps, it is quite common to display information and warning messages to the user. In an HTTP request/response world, it is difficult returning multiple messages from multiple levels in a method call hierarchy. We solve this by allowing your code to accumulate messages in a MessageHolder that is shared by all methods in the current thread. This is done using the ServerRequestContext.currentRequest to store the messages as a request attribute.

The controller will then use these messages in building its response.

The MessageHolder supports multiple messages with levels of severity. It also provides methods to store the messages in the current HTTP request as an attribute.

An example set of messages will look like this in JSON:

The standard clients will usually display all of the messages with proper styling (color/icon) in a standard message area (near the top of the page/panel).

Many utility classes in the framework are simple calculations that really do not need the full Micronaut bean support. Instead, we have built them with a simple static Singleton instance to access the utility method. See ControllerUtils for an example:

This singleton approach allows easier mocking of these methods without the overhead of making them full-fledged beans.

The general rule: if any method in the *Utils class needs to be mocked easily, then the whole class should use the .instance approach.

This is probably a tricky subject that almost everyone will disagree with :). In most complex programs, you will likely need to return multiple values from a method. The traditional Java approach to this is to create a new Java class (POJO) and populate its fields with the values. Java could also return a Map with the name/value pairs, but that is frowned upon by some in the Java programming world.

Groovy is much more flexible. It can return multiple values with multiple assignment, return a Map with the proper elements or return a simple Groovy class (POGO) with the right fields. Each of these has different pros and cons.

Groovy is sometimes called 'a better Java'. It has a lot of features that we use to enhance clarity. It does have some features that we avoid because they are not very clear:

There are also many features we try to use because they enhance clarity:

These are just a few of the useful features that make things clear in Groovy. There is an excellent series of blog posts Groovy Goodness that covers many of the features of Groovy.

The ASCIIDoctor library is the source for documents such as this Guide. It has a few quirks that you need to be aware of when creating .adoc files.

Most markers use a default label for most fields. This means you won’t need to specify the label in your HTML pages. It just requires an entry in your messages.properties file. For example, the [efDefinitionList] marker will use the field’s name to generate the list column header. For example, if you display a field order in your list, then the label for the header will be taken from the messages.properties file:

If this entry is not in the messages.properties file, then the text order.label will be used.

Labels and tooltips are usually automatically determined by the framework for most common scenarios. Some cases require your application to specify a custom label/tooltip. For example, adding buttons to a standard list.

To simplify this, the framework follows a standard way to specify the label and tooltip with one entry.

This standard labelling logic is provided by GlobalUtils method lookupLabelAndTooltip().

If a given label is not found in the messages.properties file, then the lookup key is used instead.

Validation within a domain object and its children is generally handled by the domain class. This is done to always ensure data integrity of all domain objects. If the validation spans multiple top-level domains, then we generally handle this in a service. One domain should not know very much about the details of another top-level domain.

Most GUIs needs some standard Javascript, CSS and assets to work correctly. To make this simpler, all of your pages should include the standard header:

Most GUIs need to display messages at some time. We have standardized on showing most error/info messages at the top of the page. Most messages will be shown by framework logic in this standard messages DIV created by the standard header.ftl:

The standard header.ftl above uses the [efMessages] marker to create the standard <div> marker to position the messages at the top of the page.

For example, server-side errors found by the javascript Ajax function ef.get are usually displayed in this standard area with a red highlight:

The standard message area (id='messages') is created by the header.ftl and is located under the standard header/toolbar.

The server-side code can store these messages using the StandardModelAndView :

These messages will be displayed by the [efMessages] marker in the Standard Header.

The standard Message Display logic relies on the messages being stored in a common place in the Freemarker data model. The messages are accessible like this:

To trigger the initial data load on startup, you will need to add a method to your domain class. This method will be executed on application startup. The method should check for the existence of the record before attempting to create it. You should also minimize the logic to reduce startup time. Don’t add extensive or slow logic if you can avoid it.

An example is shown below:

Keep this initialDataLoad() method simple. Any errors could affect startup, which will frustrate your users. If you want to avoid this problem, then you can write code to handle exceptions and allow the startup. In most cases, this would not be wise. Your application may not run properly without these records.

If you need to load data for domains that are in a module (e.g. new User Roles for the module), then look at Loading from Non-Domains.

The order these initial data records are loaded is sometimes important. Validation of references to other records can fail if the records are loaded in the wrong order. To solve simple precedence problems, we support simple 'load after' and 'load before' features.

These 'load after' and 'load before' are defined in the domain that needs the precedence. These are lists that define which other domains should be loaded before or after the domain. The list can contain full class names (including packages) or the Class object itself.

Below are two examples of their use:

Sometimes, a module will need to add records to a core module’s database. This is common with user Roles. To avoid creating dummy domain classes for this, we suggest you use a feature for Addition. See Initial Data Loaders and Additions for details.

Functional tests that use the embedded test server will use an in-memory database. This database is active for the entire test suite, so each test needs to clean up it test data as described in Test Data Pollution.

The problem is with the data loaded by initial data loaders. This data should be left alone since later tests may need it.

For example, a module adds some roles to the database for its security checks. We don’t want those records to be considered Test Data Pollution. This would cause every test to fail. We want those records left in the database after every test.

To avoid this, your initial data load method should return a list of values that will be ignored by the test data pollution check.

This example will create a record for the admin user. The returned map is used by BaseSpecification to know which records to ignore for each domain class.

With this approach, the timeouts for the JWT and JWT_REFRESH_TOKEN are important. If the values are too small or too large, then performance may suffer or your exposure to security lapses may be too large.

See Security Setup for details on setting these timeouts.

The basic refresh flow is:

The browser client-side logic requires no changes. The normal browser cookie handling logic should cover mode cases.

Any non-browser clients can request a refresh using a process similar to OAuth /oauth/access_token Endpoint Use mechanism.

Internally, the logic is a little more complex. There are two Micronaut beans involved in this:

These two beans, along with the RefreshTokenService will only allow the refresh token to be used a limited number of times. If used too many times, then the existing refresh tokens for the user will be disabled and force a new login.

This endpoint is intentionally broken. The replacement /login/access_token provides a limited-use replacement refresh token cookie when used. The RefreshTokenService.getUserDetails() RefreshTokenPersistence implementation intentionally prevents use of the tokens via the OAuth /oauth/access_token endpoint.

Your application’s application.yml needs a few entries for security to work as expected:

This configures JWT Security to force all controller requests to be authenticated. It also allows access to some pages/assets without a login. (See Roles below for details).

By default all controller methods must be secured. See Controller Security for details.

Users with this role manage day-to-day operations of the system.

Users with this role create non-GUI extensions to the system. These include new fields and logic that can have far-reaching impact on performance, behavior and data integrity.

Users with this role can make GUI-level changes to the system. This generally has a smaller impact on the system, but still has the potential to impact large number of users but not as big an impact on data integrity.

Frequently, you will want to specify a controller is accessible for multiple roles. For example, you might want to allow ADMIN and MANAGER roles. To make this simpler, some combine role arrays are defined in the Roles class:

The Micronaut Data persistence module is used by this framework to help you persist your data. We use the Micronaut Data JDBC approach to avoid bringing in Hibernate or too many JPA modules.

Why Micronaut Data? Simply, the GORM/Hibernate approach is very complex and brings in many dependencies. The most important problems include:

Because of these fragility issues, we decided to move closer to JDBC/SQL by using Micronaut Data. This means we had to add some usability features (e.g. save() methods on @DomainEntity, etc). But, the odd and bewildering exceptions for Hibernate are gone.

We found that very few of the Hibernate features were very important. This includes:

The features we did not really need include:

The drawbacks for Hibernate out-weighed the benefits, so we migrated to a simpler solution.

You define domain entities using annotations from Micronaut Data and this enterprise framework. These annotations, along with repositories (see Repository Requirements), provide a simplified API on the domain to process domain records. It adds methods such as:

A short example is shown below:

This framework has features that slightly restrict the name of the domain classes you can created. This is mainly because of the way [Markers and Models] work. A few names are used to store elements in the marker model (a Map). You should avoid the names used by the [StandardModelAndView].

There are a few requirements needed to implement domains in this framework:

Sometimes, you have common features that have the same fields in two or more related domains. Normally, you could use inheritance to define a common base class with the common fields. This would reduce the duplicate code to define the fields in multiple places. The enterprise framework could use this with the common fields used by the FlexField and FieldExtension .

Micronaut-data currently does not really support use of sub-classes as domain classes. This means you will have to duplicate the fields in both domains.

This duplication is not as bad as it seems. Domains are usually simple data objects with no real behavior. Any common logic should be placed in a common service that can act on the related domains. You should use a normal interface to define the getters/setters for the common fields. This will let the service work with all of the related domains.

This also has one other side-effect: the domains will be stored in separate tables. This could be avoided with some annotations, if needed.

Almost every piece of text displayed in a web-based GUI should be translatable to the user’s language. Since most of the fields in your domain classes will be displayed somewhere, the framework uses some labelling conventions to reduce the boiler-plate code in your application.

Most of the GUI markers will determine the right label needed for a domain field based on the field’s name. For example, if you want to display a list of orders, you would use the [efDefinitionList] marker in your pages like this:

The messages.properties file for you application would include these entries:

Note the use of the plural form of "Order" that is used for fields that show multiples (e.g. for the list’s message '1 to 8 of 200 Orders'). Most fields will not use a plural, but they are used frequently for the top-level domain elements in GUI lists.

If you have not defined the entry in the messages.properties file, then the framework will show the key ('order.label', etc).

Micronaut Data and this framework use several domain field names for internal use and your domains must have them:

All domain objects in most enterprise applications need some sort of key field definitions. These are the specific key(s) needed to find and uniquely identify the object. A common example is an order object. It will have a unique order name (ID) that customers will reference when creating or working with the order.

A number of the framework features rely on this key field definition to make your application coding simpler. For example, the [efDefinitionList] marker relies on the key field to implement the standard filter/search feature and the hyper-links in lists.

Sometimes, you need an unlimited length text field in your domains. To do this, you will need to specify the column type for the DB:

Frequently, the framework features will need to list or display your domain fields in a logical order. Framework markers such as [efShow] will show the fields in any order you like, but you would have to update the <@efShow/> marker for every new field added to the domain class. To simplify this maintenance task, the framework supports an optional fieldOrder static variable in domain classes.

Field ordering is not traditionally part of a domain class’s definition. Following the 'Don’t Repeat Yourself' philosophy, a central place to store the field ordering 'hints' is needed. We chose the domain class. This is optional. If you don’t want to embed field ordering in your domain classes, then you can specify the field ordering on the respective efShow markers in your HTML files. This means updating 3 files whenever you add a new field to a domain class. This is your choice.

See fieldOrder for more details.

To make life easier for the end users, we provide several mechanisms for default values. The simplest is the default value in the domain fields (e.g. String title="ABC"). This works well for most cases, but fails for some client-side use cases. In particular, the adding of new rows in inline grids on the client requires some special client-side processing.

To support this client-side default mechanism, you can add a static property to your domain to provide the default values. For example, the fields for Flex Types uses as sequence default to reduce the user input on the client. This is defined in the FlexField using this definition:

The _max() method is defined for the inline grid client-side element. The default string is javascript than is executed on the client when the user clicks the 'Add' row button.

There are many annotations that the enterprise framework has been tested with Micronaut Data. This includes:

Standard Repository Methods

A repository is a Micronaut Data mechanism to access your data. These repositories follow a number common patterns such as extending specific interfaces and implementing specific methods. Most methods in the repository are automatically added to your domain class, so you rarely need to use the repository directly.

Base interfaces include:

The object life-cycle events methods are called when certain events take place:

validate Method beforeValidate Method beforeSave Method beforeDelete Method

You can add domain-specific validations to your domains with the validate() method:

Sometimes you need to execute some logic in your domain class before validate() is called. For example, you need to encrypt a password on save/validate. If you define a beforeValidate() method on your domain, then it will be executed by the helper’s validate() method. For example:

This will call the encryptPassword() before the validation is performed on the domain.

Sometimes you need to execute some logic in your domain class before every save(). For example, you need to encrypt a password on save. If you define a beforeSave() method on your domain, then it will be executed by the domain’s save() method.

Sometimes you need to execute some logic in your domain class before every delete(). For example, you need to remove related records from other domains.

Database transactions are critical to enterprise applications. The data must be saved in a consistent state across several domains. To support this, the framework uses Micronaut Data for database access and forces transactions around all database updates/insert/deletes.

Most transactions are initiated at the Services layer, but also sometimes in the controllers. You can use the @Transactional annotation in beans or the withTransaction() method.

The @Transactional annotation only works in classes that are processed as beans in Micronaut. This means you can’t use this annotation in most test classes or in POGO/POJO logic.

Database locking is a tricky subject. We take a very simplistic approach to locking: Most updates take place using optimistic locking with a version field. Pessimistic locking is possible with a specific query annotation.

Also, we enforce that all UPDATE/INSERT SQL requests must be in a database transaction.

DB Creation Scripts Indexes and Constraints

Simple Foreign Reference Parent/Child Relationships (One-To-Many) Many-to-Many Relationships

Domain relationships are generally defined in the domain classes and handled with the @DomainEntity annotation. This annotation adds the correct save(), delete and lazy loader methods for some of the more common relationships.

Simple foreign references are supported by the framework. This means your domains can refer to other domains and access the other domain’s members as needed. To do this, you have to define your domain in a very specific way:

This adds a lazy loader mechanism in the getProduct() method. On first access, this will read the Product (if not-null).

Parent/Child relationships are quite common in enterprise applications. The children are fully-owned by the parent. Updates and deleting on the parent should update/delete the children.

The @DomainEntity annotation will add a lazy loader method (e.g. getChildren() in the example below). This loader uses the findAllByParent() method in the repository.

Also, if the child class implements the Java Comparable interface, then the list will be sorted before it is saved and after it is loaded. Do not implement this interface if the list is likely to be huge (>1000 records).

Many-to-Many relationships are implemented using a join table that contains a reference to the parent and to the related record. This is sometimes referred to as a list of foreign references. You can implement them in two different ways:

You can use either approach or a combination of the two. If you don’t define a JOIN option on the find() method, then you can still rely on the lazy loader to load the list on demand. The @DomainEntity annotation adds the save() and delete() logic to handle this join table.

Both approaches require a @ManyToMany annotation.

The Join approach requires the finders be defined with a @Join annotation to join the values from the DB. This uses the @ManyToMany annotation (from Jakarta) and a @Join annotation to the findBy…​() method in your repository.

An example is shown below:

This will create a user_role table with a user_id and role_id field to link the two records.

The lazy loader approach is simpler. It just requires the @ManyToMany annotation (from Jakarta). On first access, the list of references will be loaded and the foreign domain will be populated.

An example is shown below:

This will create a users_role table with a user_id and role_id field to link the two records.

You will frequently need to present your user with a drop-down list of options to choose from. This list can be fairly static, expandable or database-driven.

You can create these list in several ways:

Dates and timezones are a common problems with enterprise systems. Most common SQL databases don’t support timezones for values stored in the original SQL date/time columns. Also, the GUI toolkit doesn’t support timezones. The toolkit doesn’t need to know the timezone since the GUI elements don’t need it.

To keep the date/times consistent in the database, we always force the time to be stored in the UTC timezone. Then, when the date/time is displayed to the user, a global UI timezone is used. This global UI default timezone is set to eastern US timezone by default.

To make this work, the JVM’s default timezone is set to UTC by the StartupHandler. This means the JDBC drivers and the data layer will store the time in UTC. Then, when the value is retrieved from the database and sent to a client using JSON, the ISO date is sent with the timezone offset. Then on the client, the Javascript time is created by discarding the timezone offset. This means the time will be displayed by the toolkit with no adjustments.

Many GUI-related parts of the framework need a short, human-readable format of your domain objects. For example, you want to display the Order ID in drop-down, but the toString() method returns all of the order’s fields. The framework supports a standardized toShortString() method on most domains for this display. This is normally a short string for the given object (e.g. its primary key).

By default, this short string is usually just the first key field (as a string). The TypeUtils utility class provides an easy way to get this short string.

If the first key field is not suitable, then you can implement a toShortString() method. This is useful when the first key is another domain object.

This mechanism allows you to use the normal toString() methods to display detailed information for use in log messages. The TypeUtils.toShortString(object) utility will use your toShortString() method, if defined.

A number of places in the framework rely on the toStringLocalized() in the GlobalUtils utility class. This allows the framework to provide a human-readable representation of your domain record for display. For example, this is used in the [efDefinitionList] marker to build the hyper-link text for the links generated. Also, drop-down lists and archiving use this short string format.

Most domains will not need to implement this method. You won’t need to implement this methods if your domain has a single key and it is the first field in the fieldOrder static value.

Sometimes, you just have to use SQL directly in your application code. This is needed when the where clause criteria is flexible and changes based on user input. You will need to use the SQL directly. This framework provides some helper classes to make this easier. It also tries to make sure you use safe and portable SQL capabilities.

If you need dynamic sorting, then we recommend you the Pageable support on most list() repository methods. See Standard Repository Methods for an example.

The most common scenario is to use a dynamically-generated SQL statement to find domain records. The framework provides a simplified way to handle the most common case:

This will return a list of objects that match the selection criteria. You need to make sure the SQL includes at least one replaceable parameter.

You can also use Map as the result class in the query. This makes simple SQL COUNT(*) cases easier to use:

As an alternative, you can process the result set yourself if the normal binding mechanism doesn’t handle the cases you need (complex joins, etc).

Your domain will need to handle most validations on the values entered for the configurable type. For enforcement of the simple required flag on the field, you can use the ExtensibleFieldHelper method validateConfigurableTypes() to validate the added field(s). For example:

The current 'type' is typically stored in the domain record field (e.g. the FlexType rmaType field above). The actual values are stored in the normal custom field location for Field Extensions.

See ExtensibleFieldHolder Annotation for details on the storage and internal format. An example of the raw data stored in the database column is shown below.

See Configurable Type API Access for details on accessing these fields.

The framework markers that support these configurable types include:

The above markers use Javascript to dynamically build the input fields for a given configurable type. The BaseCrudController provides support for this.

Programmatic access to these values is provided by accessor methods based on the FlexType field name (first letter uppercase shifted):

The access to the configurable types via the API Formats is similar. The field names are the same as described in Configurable Type Persistent Storage above. An example of the JSON format for an RMA is shown below:

Configurable types such as Flex Types are normally used with domain classes, but they can also be used with POGO classes. This limits the Configurable Type API Access to just these features:

This is designed to work with transfer objects that copy values between POGOs and domain objects.

For example, you might use this transfer POGO with the above RMA examples:

When you need to copy the values between this POGO and the domain, you will need to copy both fields:

The controller name is the same as the page. For example, controller Order has these views:

In the controller, you have these methods:

This allows some underlying code (such as BaseCrudController) to handle a lot of the basic features of the show and index pages. This reduces the amount of code you have to write.

The BaseCrudController has a few optional fields/methods you can use to adjust the behavior of the standard methods. For example, you can specify a different domain class than the default name.

The BaseCrudRestController has a the normal Rest-style API endpoints:

The ID-based methods use the URL to define the UUID or primary key for the the record being processed. See Rest API for details.

To overcome these issues, we decided to use Vue with PrimeVue components. This provides the best user experience with a larger developer base than the other choices.

To work around the drawbacks of this approach, some conventions will be followed:

In particular, all pages will be generated with the Vue/JS world. This means all UI features are built/configured in the node/JS world. The node/npm world will generate the client assets which will be served up by the server-side.

This means most development will be done while running the npm/VueCLI in development mode, then doing a build to create the assets for the server-side core to serve.

The npm/VueCLI will run the app in developer mode. The access to the server-side will be to another process on a different port. This is done to keep the development mode code the same as the production as much as possible.

The axios module use a proxy for development mode to access http://localhost:8080/ while the client code is run on http://localhost:8081/.

The basic structure for the modular application will look something like this:

Each module can supply a client one or more sub-modules with the assets needed for the clients. These client sub-modules will be built using the npm processes typically used for Vue applications.

The application pages will be organized like this during the production deployment:

Each of these URIs is called a GUI Entry Page. It is an HTML page that is accessible directly from within the browser. Typically, these pages all show up in the [Task Menu].

GUI development involves working with the client sub-module and then moving it to the production server for deployment. The basic flow is:

Vue supports multi-page applications. These are web applications that allow display of multiple pages at different URLs. This fits well with enterprise apps.

To make this work, you will need to define each entry page. For the most part, each domain object definition page is an entry page (e.g. Flex Type definition is page, User definition is a page, etc). Other complex pages (such as a dashboard) are also entry points. This framework does not directly support the Vue router concept for single page applications.

See GUI Module Structure for an overview of the client module layout and Entry Page Structure for details.

You will need to create some files for each page. The templates folder contains a sample GUI page and related files. See GUI Setup - New Client Module for details.

You will need to edit the vue.config.js for your module. It should have an entry like this (for the FlexType example):

You will need to change the publicPath and the 'flexType' entry above for your entry page(s).

Each entry page is made up of two main elements:

The files for the Flex Type definition page is shown below.

The GUI Entry Page needs to be served up by the server. The entry page assets are packaged by the Gradle command npmBuild. See GUI Related Gradle/NPM Tasks for more details on these tasks.

The controller is usually a sub-class of BaseController . This provide the standard index() method to serve-up the normal client assets. The controller will look something like this:

You will need to change the value for the indexView to match where your entry page is located. See GUI Entry Page.

The service for FlexType CRUD pages is shown below. This particular service is needed for the CrudTable component. Other components may need other services. It is recommended that all interaction between the client and server be handled by a service-style script.

The basic methods needed include:

The common components provided by the framework are provided in the eframe-lib pseudo-module. This is copied from the eframe source tree to the client module’s src folder using the gradle command copyEframeLib. This does a simple copy to avoid the whole npm package creation logic.

Normal client module developers will only need to run this gradle command when the eframe-lib changes. If you are developing inside of the eframe-lib, you will need to run this command more frequently.

There are a number of npm and Gradle tasks used to run/build the client GUI pages.

Install node and npm. This provides the npm tool, which is used to install all of the javascript modules such as Vue and related modules.

Creating a new client module is somewhat complex. The easiest solution is to copy the eframe/src/templates/client/sample folder to a new client folder in your module. It should be copied to the module/src/client/module folder (replace module with your ne module’s name).

Creating a new client module without the template is a complex task. Don’t attempt this without a good reason.

To run your client project, you can run the local development server that was created by the vue create command above:

This runs the template client for testing purposes. You will replace most of the template html, javascript and Vue files for your module.

Once you have cloned the GIT repository, you will need to run these Gradle tasks:

These setup actions apply to new and existing installations.

The IDEA setup for npm development is fairly simple. There are two basic run configurations.

The first is to run the development server as localhost:8081. This lets you change your client code and the server will update with those changes without restarting.

The second is the task to build the production assets for the client pages. You will run this and then start/restart the micronaut application server to test your client in a live server. This will build the assets and store them in the src/main/resources/client so the development server will have access to them for use in the live server.

npm uses two files for version control:

The package.json and package-lock.json files are updated when you install a new module as we did above with the tasks in GUI Setup - New Client Module.

When building the client modules on other systems from the git source, we use the command npm install. This installs all of the dependencies specified in the package-lock.json file. This uses the exact version from the package-lock.json file. The version from the package.json is not used for this scenario.

The BaseGUISpecification tests will need to verify that labels are looked up correctly from the en/de.js files. This is done with the utility WebClientLookup . The WebClientLookup class parses the en/de.js file(s) and uses the values from the .js files for the lookup.

This avoids two mechanisms for localization (.js and .properties).

The framework uses the standard Log4j logging levels:

By default, Error and Fatal messages are logged. You can configure the system to log other messages for all classes or for specific classes.

The Info, Debug and Trace levels are normally documented in the Javadoc for the class that issues the log message.

Logging can be a big performance drain if done incorrectly. The framework uses the simplest Slf4j approach for best performance and clarity:

This also helps with code coverage metrics.

It is best to avoid using these approaches:

This works fine, but can hurt performance even if the log message is not written to the log. The second option is more verbose.

The framework uses the normal logging mechanism from Micronaut (logback.groovy). See Logback for details.

The framework provides a GUI to display and temporarily adjust the logging levels for many elements. This allows you to set the logging levels for controllers, domains and services. It also provides other logger settings such as SQL tracing.

Logging changes made in this GUI are not persistent. You will need to use the Micronaut logback.groovy approach for persistent changes.

This dynamic logging page shows all possible domains, controllers,services and client pages that might have logging available. Not all entries listed have logging messages in their code.

During development and testing, you generally want stack trace logged. You can do this on specific controllers (or the BaseController) as needed.

If you want to see some exception stack traces, then you can set the logging level for 'StackTrace' to debug. This will make sure the stack trace is printed out in a number of cases (e.g. from BaseController).

Many of the framework’s javascript libraries and UIs use the JSNLog logging framework for this client-side logging. The messages are logged to the javascript console in the browser and optionally to the application server logs. The JSNLog library is part of the normal assets loaded into all pages by the header.ftl include file.

This [efGUISetup] will check the systems logging level for the given page and set it when the page is displayed. If the logging level is changed on the server, the page must be refreshed to use the new logging level.

The logging levels can also be configured from the standard Micronaut logback.groovy file or from Dynamic Logging Configuration page. There is a section that lists all of the views and their current levels. There are also two important entries at the top:

An example use of the logging framework is shown below:

The default behavior of the client side logging is:

The search logic is broken into layers. Generally, most application code should start at the service/helper layers and let the lower layers handle the details. The layers and important objects involved are:

The SearchService provide the important search method:

If you need to unit test your application code, then refer to the existing search tests such as SearchHelperSpec. These tests use the MockSearchEngineClient to simulate most search engine actions.

This framework’s use of Elasticsearch is designed around a single index for each domain class and an archive index for each archived domain class. This provides a structured way to search for data and still allows for a global search capability.

The search index name is the domain’s class name (minus package), in lower-case with a hyphen for a delimiter between words. For example, the index for FlexType is 'flex-type'.

The archive index has '-arc' added to it. Also, archived domains have a special field added: '_archiveReference' that stores the archive file reference.

The paging mechanism for searches is slightly different from the normal Toolkit and database paging mechanisms. This makes for confusing overlaps with the other paging values. The paging names and meanings are shown below:

The threadInitSize value is the initial number of threads created to handle background search indexing requests. This should be fairly small for most cases. (Default: 4).

The threadMaxSize value is the maximum number of threads created to handle background search indexing requests. This should be no larger than your search engine server can handle. If it is too small, then request may back up in the queue and indexing will lag. If it is too big, then the search engine may slow down significantly. (Default: 10).

The bulkBatchSize value max batch bulk re-index requests. Used when rebuilding all indices. This helps reduce the load on the search engine server when forcing a full index rebuild. A larger value may be needed with extremely big databases, but it will increase the load on the the search engine server. (Default: 50).

If you set this to a very large value, then the each request will be large and may consume too much memory. If too small, then this will generate a huge number of small requests to process. The default is a good compromise.

These are the search engine servers that you will use. Only one is required for the search feature to work correctly. Multiples are supported. No default is provided. (Required).

This defines the servers to connect to for the external search engine.

To speed testing and reduce setup time, you don’t have to use a search engine. Instead, the places where the search engine is used will either be disabled or will fall back to simpler SQL-based searches.

The standard definition List pages will use SQL searches on the primary key field. Most other search features will be disabled.

The goal of the fallback is not to provide the entire set of search features. The goal is to make sure you can test other aspects of your application without the overhead of an external search engine. To make this even easier on you, the initial connection to the external search engine is only made when it is first used.

By default, domains are not searchable. You will need to add a static field to the domain class to tell the framework that the domain is searchable. The simplest approach is:

In general, you should make the important top-level objects searchable. You should not mark child elements of these top-level domains. They will be part of the nested JSON document sent to the search engine. This allows you to search for nested values more easily. It does have the drawback of using larger documents in the index. Of course, it means fewer documents in the index too.

The domains have some requirements to make indexing work:

When the domain object is indexed, there are other options.

The following options are allowed in the searchable value:

See SearchDomainSettings for the specific settings that can be defined for a domain.

As shown in Index Options, you can excluded specific fields from indexing in the search engine. This is done to speed up searches and to reduce the database size in the search server.

Some additional fields are automatically removed from the index:

Elastic Search 6.x and above have deprecated the use of an index type. This means each domain will be indexed into its own index with a type set to doc. The name is the same as the domain class (hyphenated with all lower case letters). The domain Order will be indexed under the index order.

This means you need to never have domains that only differ in class case (e.g. two domains 'RMA' and 'Rma' is not allowed).

The default mapping is the same as for the API Formats. This means child records will be indexed fully. Foreign references to other domains will be indexed with only their key fields. This means you can search for domains that have a foreign reference to the FlexType 'SERIAL' and the global search will find them.

It is very common for the application to update a child record without updating the parent record. For example, an Order might have some order line item records. If one of those child records is updated without updating the parent, then the search engine logic won’t be automatically called.

Instead, you should explicitly let the framework know that you updated the child record. This is done for assembly records using logic like this: