11. Tutorials

11.1. Introduction

This is an step by step tutorial for starting an devonfw server application from setting up the environment to packaging for production.

The tutorial starts by setting up the programmer environment with the aid of the devon-ide project and verifies everything is correct by running the my-thai-start restaurant sample application of the devonfw project.

Afterwards a new blank application is created by using the provided archetypes and all generated files are reviewed to explain what devonfw is providing.

A classical CRUD use case is developed for creating, retrieving updating and deleting an entity. With this entity we introduce cross cutting concerns such as exception handling, validation and securing the access from the web.

Finally the sample will be ready for deployment to a web server so we will package it on a WAR (or EAR) file.

11.2. Creating a new application

11.2.1. Running the archetype

In order to create a new application you must use the archetype provided by devon4j which uses the maven archetype functionality.

To create a new application, you should have installed devonfw IDE. You can choose between 2 alternatives, create it from command line or, in more visual manner, within eclipse.

From command Line

To create a new devon4j application from command line, you can simply run the following command:

devon java create com.example.application.sampleapp

For low-level creation you can also manually call this command:

mvn -DarchetypeVersion=3.1.0 -DarchetypeGroupId=com.devonfw.java.templates -DarchetypeArtifactId=devon4j-template-server archetype:generate -DgroupId=com.example.application -DartifactId=sampleapp -Dversion=1.0.0-SNAPSHOT -Dpackage=com.devonfw.application.sampleapp

Further providing additional properties (using -D parameter) you can customize the generated app:

Table 19. Options for app template
property comment example

dbType

Choose the type of RDBMS to use (hana, oracle, mssql, postgresql, mariadb, mysql, etc.)

-DdbTpye=postgresql

batch

Option to add an batch module

-Dbatch=batch

earProjectName

Option to add an EAR module with the given name

-DearProjectName=ear

From Eclipse
After that, you should follow this Eclipse steps to create your application:
  • Create a new Maven Project.

  • Choose the devon4j-template-server archetype, just like the image.

Select archetype
  • Fill the Group Id, Artifact Id, Version and Package for your project. If you want to add an EAR generation mechanism to your project, you should fill the property earProjectName with the value Artifact Id + "-ear". For example, "sampleapp-ear". If you only want WAR generation, you can remove the property earProjectName.

Configure archetype
  • Finish the Eclipse assistant and you are ready to start your project.

11.2.2. What is generated

The application template (archetype) generates a Maven multi-module project. It has the following modules:

  • api: module with the API (REST service interfaces, transferobjects, datatypes, etc.) to be imported by other apps as a maven dependency in order to invoke and consume the offered (micro)services.

  • core: maven module containing the core of the application.

  • batch: optional module for batch(es)

  • server: module that bundles the entire app (core with optional batch) as a WAR file.

  • ear: optional maven module is responsible to packaging the application as a EAR file.

The toplevel pom.xml of the generated project has the following features:

  • Properties definition: Spring-boot version, Java version, etc.

  • Modules definition for the modules (described above)

  • Dependency management: define versions for dependencies of the technology stack that are recommended and work together in a compatible way.

  • Maven plugins with desired versions and configuration

  • Profiles for test stages

Core Module

Core module contains the base classes and the base configuration for the application. We are going to describe each Java file and each XML configuration file that archetype has generated.

Java

Those are the different Java files contained in each package:

  • general.common

File Description

api.ApplicationEntity.java

Abstract interface for a MutableGenericEntity of this application.

api.BinaryObject.java

Interface for a BinaryObject.

api.NlsBundleApplicationRoot.java

NlsBundle for this application.

api.Usermanagement.java

Interface to get a user from its login.

api.UserProfile.java

Interface for the profile of a logged user.

api.constants.PermissionConstants.java

Constants for AccessControlPermission´s keys.

api.datatype.OrderBy.java

Enum for sort order.

api.datatype.Role.java

Enum for roles.

api.exception.ApplicationBusinessException.java

Abstract business main exception.

api.exception.ApplicationException.java

Abstract main exception.

api.exception.ApplicationTechnicalException.java

Abstract technical main exception.

api.exception.IllegalEntityStateException.java

Manage entities illegal state exceptions.

api.exception.IllegalPropertyChangeException.java

Manage entities illegal property changes exceptions.

api.exception.NoActiveUserException.java

Manage exceptions when user require to be logged in.

api.security.UserData.java

Container class for the profile of a user.

api.to.AbstractCto.java

Abstract class for Composite Transfer Object.

api.to.AbstractEto.java

Abstract class for Entity Transfer Object.

api.to.AbstractTo.java

Abstract class for a plain Transfer Object.

api.to.SearchCriteriaTo.java

Abstract class for a Transfer Object with the criteria for a search query.

api.to.UserDetailsClientTo.java

.

base.AbstractBeanMapperSupport.java

Provides access to the BeanMapper.

impl.security.ApplicationAuthenticationProvider.java

Responsible for the security aspects of authentication.

impl.security. PrincipalAccessControlProviderImpl.java

Implementation of PrincipalAccessControlProvider.

  • general.dataaccess

File Description

api.ApplicationPersistenceEntity.java

Abstract Entity for all Entities with an id and a version field.

api.BinaryObjectEntity.java

BinaryObject entity.

api.dao.ApplicationDao.java

Interface for all DAOs of the application.

api.dao.ApplicationRevisionedDao.java

Interface for all revisioned DAOs of the application.

api.dao.BinaryObjectDao.java

DAO for BinaryObject entity.

  • general.gui.api

File Description

LoginController.java

Controller for login page.

  • general.logic

File Description

api.UseCase.java

Annotation to mark all use-cases.

api.to.BinaryObjectEto.java

ETO for a BinaryObject.

base.AbstractUc.java

Abstract base class for any use case in the application.

base.UcManageBinaryObject.java

Use case for managing BinaryObject.

impl.UcManageBinaryObjectImpl.java

Implementation of the UcManageBinaryObject interface.

impl.UsermanagementDummyImpl.java

Implementation of Usermanagement.

  • general.service.impl.rest

File Description

ApplicationAccessDeniedHandler.java

Class to manage denied access.

ApplicationObjectMapperFactory.java

MappingFactory class to resolve polymorphic conflicts within the application.

SecurityRestServiceImpl.java

Class that represents REST service for security.

Resources

Those are the different XML files contained in resources folder:

  • config

File Description

app.common.beans-common.xml

Contains beans definition for application common beans like propertyConfigurer bean.

app.common.beans-dozer.xml

Beans relationated with Dozer Mappers.

app.common.dozer-mapping.xml

Dozer mapping configuration.

app.dataaccess.beans-dataaccess.xml

Parent from the other data access files.

app.dataaccess.beans-db-plain.xml

Data source configuration for profile db-plain (testing).

app.dataaccess.beans-db-server.xml

Data source configuration for profile distinct to db-plain.

app.dataaccess.beans-jpa.xml

Contains necessary beans to configure JPA.

app.dataaccess.NamedQueries.xml

app.gui.dispatcher-servlet.xml

app.logic.beans-logic.xml

Component scan configuration for classes in logic path.

app.security.access-control-schema.xml

app.security.beans-security-filters.xml

Security filters definition.

app.security.beans-security.xml

Application security configuration.

app.service.beans-monitoring.xml

app.service.beans-service.xml

Importing configuration files, REST beans definition and configuration.

app.websocket.websocket-context.xml

Scan component package definition for websockets.

app.application.default.properties

Default application properties values.

app

beans-application

Root file configuration. It starts the chain and imports other configuration files.

env

application

Specific application properties values.

  • db

File Description

migration.V0001__Create_schema.slq

Script template to create the database schema and tables definition.

Test

Those are different Java files to serve as base classes in testing:

  • general.common

File Description

AbstractSpringIntegrationTest.java

.

AccessControlSchemaXmlValidationTest.java

Tests if the access-control-schema.xml is valid.

PermissionCheckTest.java

Test to check if all relevant methods in use case implementations have permission checks.

Server Module

This module is contains two files:

  • logback.xml: This file is in the resources folder and it is the responsible to configure the log.

  • pom.xml: This file has Maven configuration for packaging the application as a WAR. Also, this file has a profile to package the Javascript client ZIP file into the WAR.

EAR Module

This module only contains a pom.xml file to packaging the application as EAR from the WAR generated.

11.2.3. Database configuration and creation

Including driver installation if oracle or other db is required.

11.2.4. Editing the pom.xml

How to edit the pom.xml file for the project to add dependencies and modules for the application.

11.2.5. Known Issues

  • Could not resolve archetype com.devonfw.java.templates:devon4j-template-server:.. from any of the configured repositories. In Eclipse: Open Window > Preferences Open Maven > Archetypes Click 'Add Remote Catalog' and add the following: Catalog File: http://repo1.maven.org/maven2/archetype-catalog.xml Description: maven catalog

Last updated 2019-11-13 14:38:09 UTC