Devonfw Guide V2.4.0

User Manual:

Open the PDF directly: View PDF .
Page Count: 986

Download
Open PDF In Browser	View PDF

Devonfw Guide
v2.4.0
Written by the Devonfw community. This documentation is licensed under the Creative Commons
License (Attribution-NoDerivatives 4.0 International).

Table of Contents
1. Quick Start with Devonfw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2. Devonfw Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1. Building Blocks of the Platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.2. Devonfw Technology Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.3. Custom Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.4. Devonfw Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Why should I use Devonfw? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2. Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4. Download and Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.1. Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.2. Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.3. Setup the workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
5. Running Sample Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.1. Basics of My Thai Star . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.2. Running My Thai Star . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6. Getting Started Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
6.1. Service Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
7. OASP4J. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
7.1. OASP4J Technology stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
7.2. OASP4J Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
8. Configuring and Running OASP4J Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
8.1. Configuring the Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
8.2. Running the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
9. OASP4Fn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.2. What is Serverless Computing?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.3. What does OASP4Fn provide on Serverless? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
10. OASP4Fn Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
10.1. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
10.2. Import and Use the Library in Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
11. Running OASP4Fn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
11.1. Run. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
11.2. Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
11.3. Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
12. Getting Started Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
12.1. Client Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
13. OASP4JS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

13.1. OASP4JS Technology Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
13.2. OASP4JS Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
14. Download and Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
14.1. Download My Thai Star . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
14.2. Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
15. Running OASP4JS Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
15.1. Run the Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
15.2. Run the MyThaiStar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
16. Devon4sencha. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
16.1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
16.2. The Universal Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
16.3. Legal Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
17. Sencha Cmd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
17.1. Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
18. Devon4sencha Sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
18.1. Running the sample restaurant application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
19. Topical Guides for Devonfw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
19.1. A Closer Look. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
20. Devonfw Outline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
20.1. Why do we use an open source core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
20.2. Devonfw and Open Source. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
20.3. Contributing to Devonfw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
21. Devcon User Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
21.1. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
21.2. Download Devcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
21.3. Devcon structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
21.4. Devcon basic usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
21.5. First steps with Devcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
21.6. Devcon command reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
22. The Devon IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
22.1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
22.2. Cobigen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
22.3. IDE Plugins: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
23. Creating your First Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
23.1. Using Devcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
23.2. Using the Archetype. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
24. Design Philosophy : Jump the Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
24.1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
24.2. User Stories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
24.3. UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
24.4. Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

25. Devonfw Distribution Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
25.1. Understanding the structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
26. Database Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
26.1. Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
26.2. Database configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
26.3. Further Details on Database Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
27. CRUD operations and DAO implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
27.1. Create CRUD functionality for an entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
28. Bean-Mapping using Dozer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
28.1. Why use Bean-Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
28.2. Bean-Mapper Dependency. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
28.3. Bean-Mapper Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
29. Write Unit Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
29.1. Unit Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
29.2. TDD Test-driven development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
30. Logging and Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
30.1. Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
30.2. Auditing with Hibernate Envers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
31. Getting Started Cobigen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
31.1. Preparing Cobigen for first use. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
31.2. Creating a CRUD with Cobigen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
32. Creating user permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Step 1: Define the permissions and roles

143

Step 2: Generate the PermissionConstants class

143

32.3. Fixing context problems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
33. Transfer-Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
33.1. Business-Transfer-Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
33.2. Service-Transfer-Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
34. Deployment on Tomcat (Client/Server) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
34.1. General description of the packaging process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
34.2. Preparing the client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
34.3. Preparing the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
34.4. Packaging the apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
34.5. Deploy on Tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
34.6. Running Bootified War . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
35. Cookbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
35.1. Devonfw Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
36. The Reporting module - Report generation with JasperReports . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
36.1. Include Reporting in a Devon project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
36.2. Basic implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
36.3. Working with templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

36.4. Subreports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
37. The Winauth-AD module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
37.1. Authentication with Active Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
38. The Winauth-SSO module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
38.1. Single Sign On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
39. The i18n module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
39.1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
39.2. The i18n Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
40. Devon-locale module(i18n resource converter) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
40.1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
40.2. Devon locale structure and working . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
41. The async module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
41.1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
41.2. The async module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
42. The Integration Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
42.1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
42.2. Stack of technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
42.3. Installing Apache Active MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
42.4. Using Apache Active MQ with Docker. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
42.5. Integration module details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
43. Microservices in Devonfw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
43.1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
43.2. Microservices schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
43.3. How to create microservices in Devonfw? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
43.4. Devonfw archetypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
43.5. Create New Microservices infrastructure application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
43.6. Create New Microservices Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
43.7. How to use microservices in Devonfw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
43.8. How to modify the UserDetails information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
43.9. How to start with a microservice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
43.10. Calls between microservices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
44. Compose for Redis module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
44.1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
44.2. Include Compose for Redis in a Devon project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
44.3. Basic implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
44.4. Available operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
45. Cookbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
45.1. Advanced Topics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
46. Devon Security Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
46.1. Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
46.2. Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

46.3. Suggestions on the access model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
46.4. Vulnerabilities and Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
47. Data-Access Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
47.1. Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
47.2. Database Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
47.3. Data-Access Layer Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
48. Set up and maintain database schemas with Flyway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
48.1. Why use flyway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
48.2. How it works for setting up the database and maintaining it. . . . . . . . . . . . . . . . . . . . . . . . . . . 274
48.3. How to set up a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
49. Logic Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
49.1. Component Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
49.2. Component Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
49.3. Passing Parameters Among Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
49.4. Logic Layer Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
50. Service Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
50.1. Types of Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
50.2. Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
50.3. Interoperability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
50.4. Protocol. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
50.5. Details on Rest Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
50.6. Details of SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
50.7. Service Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
50.8. Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
51. Web Services (JAX WS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
51.1. What are Web Services? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
51.2. Why use Web Services? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
51.3. Characteristics of Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
51.4. Components of SOAP based Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
51.5. Apache CXF and JAX WS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
51.6. Creation of Web Service using Apache CXF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
51.7. Soap Custom Mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
51.8. SOAP Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
52. Batch Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
52.1. Batch architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
52.2. Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
53. Integrating Spring Data in OASP4J . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
53.1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
53.2. Existing Structure of Data Access Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
53.3. Structure of Data Access Layer with Spring Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
53.4. Query Creation in Spring Data JPA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

53.5. Query creation by method names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
53.6. Implementing Query with QueryDsl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
53.7. Paging and Sorting Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
53.8. References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
54. WebSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
54.1. WebSocket configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
55. File Upload and Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
55.1. File download from CXF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
55.2. File upload from CXF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
55.3. MIME Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
56. Docker. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
56.1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
56.2. Install Docker on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
56.3. Use Docker manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
56.4. Fabric8io plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
56.5. Docker tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
57. Production Line for Beginners (Practical Guide) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
57.1. Production Line description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
57.2. Jenkins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
57.3. Nexus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
58. Production Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
58.1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
58.2. Continuous Delivery benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
58.3. The Production Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
58.4. Devonfw Continuous Delivery infrastructure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
58.5. Production Line implementation for Devonfw projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
59. Devon in Bluemix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
59.1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
59.2. Bluemix Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
59.3. Logs in Bluemix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
60. Configuring and Running Bootified WAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
60.1. Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
61. Deployment on Wildfly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
62. Deploy oasp4j application to WebSphere Liberty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
62.1. Setup and Configure WebSphere Liberty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
63. Deployment on WebLogic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
63.1. Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
63.2. Sencha. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
63.3. Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
64. Cobigen advanced use cases: SOAP and nested data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
64.1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

64.2. CobiGen with SOAP functionality (without nested data) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
64.3. CobiGen with nested data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
65. Compatibility guide for JAVA and TOMCAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
65.1. What this guide contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
65.2. Using JAVA7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
65.3. Using java8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
65.4. Using Tomcat8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
65.5. Using Tomcat7 for deploying. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
65.6. Linux and Windows Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
66. Dockerfile for the maven based spring.io projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
66.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
66.2. Dockerfile Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
66.3. Multi-stage builds. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
67. Introduction to generator-jhipster-DevonModule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
67.1. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
67.2. Download and install the generator-jhipster-DevonModule . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
67.3. Registering the generator-jhipster-DevonModule in your project . . . . . . . . . . . . . . . . . . . . . . . 397
67.4. Generate files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
67.5. Interesting links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
68. Cookbook OSS Compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
68.1. Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
68.2. Obligations when using OSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
68.3. Automate OSS handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
68.4. Configure the Mojo Maven License Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
68.5. Retrieve licenses list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
68.6. Create an OSS inventory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
68.7. Create a THIRD PARTY file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
68.8. Download and package OSS SourceCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
68.9. Handle OSS within CI-process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
69. Topical Guides for Service Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
70. OASP4J . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
70.1. A Closer Look. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
71. Creating New OASP4J Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
71.1. Getting Devonfw distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
71.2. Initialize the distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
71.3. Create the Server Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
71.4. Import and Run the Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
71.5. What is generated? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
72. OASP4J Application Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
72.1. The OASP4J project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
72.2. The components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

72.3. The component structure (layers) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
73. OASP4J Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
74. OASP4J Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
74.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
74.2. OASP4J Component example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
75. OASP4J Component Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
75.1. Layers implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
75.2. Data Access layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
76. OASP4J and Spring Boot Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
76.1. Internal Application Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
76.2. Externalized Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
77. OASP4J Validations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
77.1. My Thai Star Validations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
77.2. Add your own Validations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
78. Testing with OASP4J . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
78.1. Testing: My Thai Star. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
78.2. Testing: Jump the Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
78.3. Additional Test functionalities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
78.4. Running the Tests with Maven . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
79. OASP4J Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
79.1. The server Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
79.2. Running the app with Maven . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
79.3. Packaging the app with Maven. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
79.4. Deploying the war file on Tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
80. OASP4J . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
80.1. Cookbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
81. OASP4J Project without Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
81.1. Add Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
81.2. Remove annotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
82. Create your own Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
82.1. Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
83. Creating Component’s Structure with Cobigen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
83.1. Importing Cobigen templates

481

83.2. Cobigen Health Check

481

83.3. Visitor component structure

483

83.4. Access Code component structure

492

83.5. Run the app

492

84. OASP4J Adding Custom Functionality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
84.1. Returning the Access Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
84.2. List visitors with their access code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
85. Spring boot admin Integration with OASP4J. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500

85.1. Configure the Spring boot admin for the OASP4J App. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
85.2. Register the client app. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
85.3. Loglevel management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
85.4. Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
85.5. Integrate Spring boot admin with module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
86. OASP4Fn. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
86.1. A Closer Look. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
87. Creating new OASP4Fn Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
87.1. Install tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
87.2. Postman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
87.3. Starting our project through a template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
87.4. Local database set up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
87.5. AWS credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
87.6. Adding Typings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
87.7. Start the development. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
87.8. Generating the configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
87.9. Build and run your handlers locally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
88. Application structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
89. Application Program Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
90. Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
90.1. Types of adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
91. Application Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
91.1. File structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
91.2. Handler configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
91.3. Default configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
92. Command Line Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
92.1. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
93. Testing OASP4Fn Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
93.1. Install global dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
93.2. Writing the tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
94. OASP4Fn Application Deplyment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
95. Topical Guides for Client Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
96. OASP4JS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
96.1. A Closer Look. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
97. Creating new OASP4JS Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
97.1. End Result is Jump The Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
97.2. Installing Global Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
97.3. Creating Basic Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
97.4. Working with Google Material and Covalent Teradata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
97.5. Alternative : ng-seed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
97.6. Start the development. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543

97.7. Making Calls to Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
98. An OASP4JS Application Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
98.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
99. OASP4JS Architecture Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
99.1. Basic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
99.2. Additional Functionalities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
100. Angular Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
100.1. What are Angular Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
100.2. Create a new component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
100.3. Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
100.4. Root Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
100.5. Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
100.6. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
100.7. Teradata Covalent components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
101. Angular Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581
101.1. What are Angular Services? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581
101.2. Dependency Injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581
101.3. Create a new service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
101.4. Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
101.5. Guards. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
101.6. Server communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
102. OASP4JS Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
103. OASP4JS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
103.1. Cookbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
104. OASP4JS NPM-Yarn Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586
104.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586
105. OASP4JS i18n internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596
106. OASP4JS i18n approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
106.1. Install NGX Translate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
106.2. Configure NGX Translate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
106.3. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598
106.4. Service translation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
107. Accessibility Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601
107.1. Key Concerns of Accessible Web Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601
107.2. Visual Assistance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
107.3. Accessibility with Angular Material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
108. Angular CLI common issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
109. Angular CLI update guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
110. Devon4Sencha . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
110.1. A Closer Look . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
111. Creating a new application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611

112. Application architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
112.1. MVC (Model, View, Controller): . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
112.2. MVVM (Model, View, Controller, ViewModel, ViewController): . . . . . . . . . . . . . . . . . . . . . . . . 615
112.3. Structure of a Devon4sencha application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616
112.4. Universal Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
113. Project Layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
113.1. Main Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
114. Code conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
114.1. Controllers, ViewModels and ViewControllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
114.2. Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
114.3. Event Names and listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
114.4. Code style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
115. Sencha Client and Sencha Architect project generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
115.1. Getting ready. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
115.2. Generating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
115.3. Deploying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
116. Creating a new page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
116.1. Step 1: ViewModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
116.2. Step 2: ViewController . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
116.3. Step 3: View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
116.4. Step 4: MenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633
116.5. Step 5: Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
117. Create a CRUD page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
117.1. CRUD Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
117.2. Step 1: Add a CRUD page to the application menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
117.3. Step 2: Controller, a view factory and REST endpoints definition . . . . . . . . . . . . . . . . . . . . . . 637
117.4. Step 3: Create a model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639
117.5. Step 4: Create the Store. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639
117.6. Step 5: Create the view and viewController . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
117.7. Step 6: Create i18n literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
118. Complete CRUD example (Create, Read, Update and Delete) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
118.1. Extending the CRUD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
119. Extending the CRUD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
119.1. Refreshing the grid after changing some tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
119.2. Double-click functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
120. Extending the CRUD: ViewModels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
121. Pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666
122. Extending the CRUD: searching and filtering tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
123. Extending the CRUD: Adding an inbox to search tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
124. Extending the CRUD: Change the state of a table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
125. Extending the CRUD: Editing menu order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684

125.1. Create Edit Order View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
125.2. Drag and drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
126. Extending the CRUD: Working with layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
127. Extending the CRUD: Grid editable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699
127.1. Creating the grid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699
127.2. Cellediting plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703
127.3. Rowediting plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
127.4. Add empty records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
128. Extending the CRUD: Custom plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
129. The class system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
129.1. Ext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
129.2. Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
130. Rest endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
130.1. URL template resolution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
130.2. Query string. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
130.3. Alternative PUT format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
130.4. Automatic JSON response decode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
130.5. Base Url configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
131. Sencha data package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
131.1. Devon.restproxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
131.2. Pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
131.3. Sorting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
132. Ext.window.Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
132.1. Basic Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
132.2. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
133. Layouts and Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
133.1. Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
133.2. Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
134. Grids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742
134.1. Basic Grid Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742
135. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
135.1. Basic Form Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
136. Devon4Sencha . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
136.1. Cookbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
137. CORS support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748
137.1. Configure CORS support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748
137.2. Bypass CORS security check during development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748
138. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751
138.1. Login process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751
138.2. User security info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
138.3. Controlling visibility of controls based on user roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752

139. Theming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
139.1. Configuring Theme Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
139.2. Using a Theme in an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
139.3. Making changes in the Theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
139.4. Adding customs UI’s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
140. Error processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
141. Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
141.1. Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
141.2. Message bundles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
141.3. Change language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
142. Mocks with Simlets: simulating server responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764
142.1. Simlet Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764
142.2. JSON Simlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764
143. Simlets in Devon4Sencha. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766
143.1. Use Simlets in your client application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768
143.2. Simlets Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769
144. Devon4Sencha Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
144.1. Bad formed code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
144.2. Excessive or unnecessary nesting of component structures. . . . . . . . . . . . . . . . . . . . . . . . . . . 770
144.3. Memory leaks caused by failure to cleanup unused components . . . . . . . . . . . . . . . . . . . . . . 771
144.4. Poor folder structure for source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774
144.5. Use of global variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
144.6. Use of id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
144.7. Unreliable referencing of components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777
144.8. Failing to follow upper or lowercase naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778
144.9. Making your code more complicated than necessary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
144.10. Nesting callbacks are a nightmare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780
144.11. Caching and references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782
144.12. Identation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783
144.13. One class per file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784
144.14. Too much work to return. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784
144.15. Comments or Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
144.16. Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786
144.17. Be lazy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
144.18. Knowing this . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
144.19. Additional resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788
145. Devon4Sencha Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
145.1. Code Analysis Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
145.2. Analysing code with Sencha Cmd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
145.3. Sonar for JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
146. How to do effective Devon4Sencha code reviews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791

146.1. Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
146.2. Best practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
146.3. How to handle code reviews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
146.4. On mindset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
146.5. Code review tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
147. Devon4Sencha testing tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794
147.1. Tools for testing your Sencha code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794
147.2. Sencha Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794
148. Adapting devon4sencha apps to microservices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
148.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
148.2. Security changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
149. Versions used to create this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
149.1. How to start a cordova project from a sencha project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
149.2. Steps to do on the Sencha project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
149.3. Steps to do on the Cordova project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802
149.4. Steps to run the Sencha project in the Cordova project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804
150. IDE and Project Setup with Eclipse Oomph. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
151. IDE Setup with the Oomph Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
151.1. Quick start guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
151.2. Detailed Walkthrough. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
151.3. Tweaking the installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
151.4. Packaging the Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814
152. Devon IDE Oomph Setup Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815
152.1. P2 Director (Devon 2.1.1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815
152.2. Compounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815
152.3. Projects Import import.cobigen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819
152.4. Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819
153. Using Oomph in the IDE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820
153.1. Checking out a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820
153.2. Updating a Oomph based Product and Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821
154. Oomph Tasks Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822
155. Adding Content to the Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824
155.1. Structure of the Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824
155.2. Adding a Catalog to the Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825
155.3. Adding a Product or a Project to a Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825
156. Creating an Oomph Product based on devon-ide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
156.1. Tasks already provided by the Product Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
156.2. Customizing the devon-ide Product. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
157. Creation of Projects in the devon Project Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832
157.1. Tasks already provided by the Project Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832
157.2. Example Github Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832

157.3. Additional Project Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836
158. Troubleshooting Oomph Setups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837
158.1. Unkown Variables show up on the Variables Page during installation . . . . . . . . . . . . . . . . . 837
158.2. P2 Task fails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837
158.3. Packaged IDE : Setup Tasks are not triggered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837
159. Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839
160. Wiki Contributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840
160.1. Text styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840
160.2. Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840
160.3. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841
160.4. Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841
160.5. Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841
161. Code Contributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843
161.1. Notes on Code Contributions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843
161.2. Introduction to Git and GitHub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843
161.3. Structure of our projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843
161.4. Contributing to our projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844
161.5. Reviewing Pull Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846
162. Development Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 848
163. Working with forked repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849
163.1. Fork a repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849
163.2. Configuring a remote for a fork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849
163.3. Syncing a fork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850
164. Contributor Covenant Code of Conduct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
164.1. Our Pledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
164.2. Our Standards. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
164.3. Our Responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
164.4. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853
164.5. Enforcement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853
164.6. Attribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853
165. Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854
166. devonfw Release notes 2.4 “EVE”. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
166.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
166.2. Changes and new features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
167. Devonfw Release notes 2.3 "Dash" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862
167.1. Release: improving & strengthening the Platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862
167.2. An industrialized platform for the ADcenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862
167.3. Changes and new features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863
168. Devonfw Release notes 2.2 "Courage". . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
168.1. Production Line Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
168.2. OASP4js 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869

168.3. A new OASP Portal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
168.4. New Cobigen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
168.5. MyThaiStar: New Restaurant Example, reference implementation & Methodology

870

showcase
168.6. The new OASP Tutorial. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
168.7. OASP4j 2.4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871
168.8. Microservices Netflix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
168.9. Devonfw distribution based on Eclipse OOMPH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
168.10. Visual Studio Code / Atom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
168.11. More I18N options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
168.12. Spring Integration as devonfw Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
168.13. Devonfw Harvest contributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
168.14. More Deployment options to JEE Application Servers and Docker/CloudFoundry . . . . . . 873
168.15. Devcon on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873
168.16. New OASP Incubators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873
169. Release notes Devonfw 2.1.1 "Balu" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875
169.1. Version 2.1.2: OASP4J updates & some new features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875
169.2. Version 2.1.1 Updates, fixes & some new features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 876
169.3. Version 2.1 New features, improvements and updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877
170. Frequently Asked Questions (FAQ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883
170.1. Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883
170.2. Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
170.3. Configuration issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
170.4. Crosscutting concerns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889
171. Working with Git and Github . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890
171.1. What is a version control system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890
171.2. What are Git and Github . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890
171.3. Devon and OASP4J Workflow for Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890
171.4. OASP Issue Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898
171.5. Code Contribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899
172. Devonfw Dist IDE Developers Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901
172.1. Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901
172.2. Updating OASP4Js module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904
172.3. Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909
172.4. Updating node.js. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912
173. Devcon Command Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916
173.1. dist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916
173.2. doc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920
173.3. github . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920
173.4. help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921
173.5. oasp4j . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922

173.6. oasp4js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
173.7. project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
173.8. sencha . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935
173.9. workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938
173.10. system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939
174. Devcon Command Developer’s guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941
174.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941
174.2. Creating your own Devcon modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942
174.3. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957
175. Devon module Developer’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958
175.1. Creation of module template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958
175.2. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959
175.3. Structure of created module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961
176. List of Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
176.1. Devonfw Release 2.2.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
177. Steps to use Devon distribution in Linux OS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968

Devonfw Guide v2.4.0

Chapter 1. Quick Start with Devonfw

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

1

Devonfw Guide v2.4.0

Chapter 2. Devonfw Introduction

Welcome to Devonfw, the Devon Framework. This is a product of the CSD industrialization effort to
bring a standardized platform for custom software development within Capgemini APPS2. This
platform is aimed at engagements where clients do not force the use of a determined technology so
we can offer a better alternative coming from our experience as a group.
Devon framework is a development platform aiming for standardization of processes and
productivity boost, that provides an architecture blueprint for Java/JavaScript applications,
alongside a set of tools to provide a fully functional out-of-the-box development environment.

2.1. Building Blocks of the Platform

Devonfw uses a state-of-the-art open source core reference architecture for the server (today
considered as commodity in the IT-industry) and on top of it an ever increasing number of highvalue assets that are developed by Capgemini.

2.2. Devonfw Technology Stack
Devonfw is composed of an Open Source part that can be freely used by other people and
proprietary addons which are Capgemini IP and can be used only in Capgemini engagements.The
Open Source part of Devonfw is called The Open Application Standard Platform (OASP) . It consist of

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

2

Devonfw Guide v2.4.0

2.2.1. Back-end solutions
• OASP4J: server implemented with Java. The OASP platform provides an implementation for
Java based on Spring and Spring Boot.
• OASP4FN: serverless implementation based on node.js.
• Dot Net implementation. (Upcoming)

2.2.2. Front-end solutions
For client applications, Devonfw includes two possible solutions based on JavaScript:
• OASP4JS: the OASP implementation based on Angular framework.
• devon4sencha: a client solution based on the Sencha framework.
Check out the links for more details.

2.3. Custom Tools
2.3.1. Pre-installed Software
• Eclipse: pre-configured and fully functional IDE to develop Java based apps.
• Java: all the Java environment configured and ready to be used within the distribution.
• Maven: to manage project dependencies.
• Node: a Node js environment configured and ready to be used within the distribution.
• Sencha: Devonfw also includes a installation of the Sencha Cmd tool.
• Sonarqube: a code quality tool.
• Tomcat: a web server ready to test the deploy of our artifacts.

2.3.2. Devcon
For project management and other life-cycle related tasks, Devonfw provides also Devcon, a
command line and graphic user interface cross platform tool.
With Devcon, users can automate the creation of new projects (both server and client), build and
run those and even, for server projects, deploy locally on Tomcat.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

3

Devonfw Guide v2.4.0

All those tasks can be done manually using Maven, Tomcat, Sencha Cmd, Bower, Gulp, etc. but with
Devcon users have the possibility of managing the projects without the necessity of dealing with all
those different tools.

2.3.3. Cobigen
Cobigen is a code generator included in the context of Devonfw that allows users to generate all the
structure and code of the components, helping to save a lot of time wasted in repetitive tasks.

2.4. Devonfw Modules
As a part of the goal of productivity boosting, Devonfw also provides a set of modules to the
developers, created from real projects requirements, that can be connected to projects for saving all
the work of a new implementation.
The current available modules are:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

4

Devonfw Guide v2.4.0

• async: module to manage asynchronous web calls in a Spring based server app.
• i18n: module for internationalization.
• integration: implementation of Spring Integration.
• microservices: a set of archetypes to create a complete microservices infrastructure based on
_Spring Cloud_Netflix.
• reporting: a module to create reports based on Jasper Reports library.
• winauth active directory: a module to authenticate users against an Active Directory.
• winauth single sign on: module that allows applications to authenticate the users by the
Windows credentials.
Find more about devonfw here.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

5

Devonfw Guide v2.4.0

Chapter 3. Why should I use Devonfw?
Devonnfw aims at providing a framework which is oriented at development of web applications
based on the Java EE programming model using the Spring framework project as the default
implementation.

3.1. Objectives
3.1.1. Standardization
It means that to stop reinventing the Wheel in thousands of projects, hundreds of centers, dozens of
countries. This also includes rationalize, harmonize and standardize all development assets all over
the group and industrialize the software development process

3.1.2. Industrialization of Innovative technologies & “Digital”
devonfw needs to standardize & industrialize. But not just large volume, “traditional” custom
software development. devonfw needs to offer a standardized platform which contains a range of
state of the art methodologies and technology options. devonfw needs to support agile development
by small teams utilizing the latest technologies for Mobile, IoT and the Cloud

3.1.3. Deliver & Improve Business Value

3.1.4. Efficiency
• Up to 20% reduction in time to market with faster delivery due to automation and reuse.
• Up to 25% less implementation efforts due to code generation and reuse.
• Flat pyramid and rightshore, ready for juniors.

3.1.5. Quality
• State of the Art architecture and design.
• Lower cost on maintenance and warranty.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

6

Devonfw Guide v2.4.0

• Technical debt reduction by reuse.
• Risk reduction due to assets continuous improvement.
• Standardized automated quality checks.

3.1.6. Agility
• Focus on business functionality not on technical.
• Shorter release cycles.
• DevOps by design - Infrastructure as Code.
• Continuous Delivery Pipeline.
• On and Off-premise flexibility.
• PoCs and Prototypes in days not months.

3.2. Features
3.2.1. Everything in a single zip
The Devonfw distributions is packaged in a zip file that includes all the Custom Tools, Software and
configurations.
Having all the dependencies self-contained in the distribution’s zip file, users don’t need to install
or configure anything. Just extracting the zip content is enough to have a fully functional Devonfw.

3.2.2. Devonfw, the package
Devonfw package provides:
• Implementation blueprints for a modern cloud-ready server and a choice on JS-Client
technologies (either open source AngularJs or a very rich and impressive solution based on
commercial Sencha UI).
• Quality documentation and step-by-step quick start guides.
• Highly integrated and packaged development environment based around Eclipse and Jenkins.
You will be ready to start implementing your first customer-specific use case in 2h time.
• Iterative eclipse-based code-generator that understands "Java" and works on higher
architectural concepts than Java-classes.
• Example application as a reference implementation.
• Support through large community + industrialization services (Standard Platform as a service)
available in the iProd service catalog.
To read in details about Devonfw features read here

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

7

Devonfw Guide v2.4.0

Chapter 4. Download and Setup
In this section, you will learn how to setup the Devonfw environment and start working on first
project based on Devonfw.
The Devonfw environment contains all software and tools necessary to develop the applications
with Devonfw.

4.1. Prerequisites
In order to setup the environment, following are the prerequisites:
• Internet connection (including details of your proxy configuration, if necessary)
• 2GB of free disk space
• The ZIP containing the latest Devonfw distribution

4.2. Download
The Devonfw distributions can be obtained from the TeamForge releases library and are packaged
in a zip file that includes all the needed tools, software and configurations

Using devcon

NOTE

You can do it using devcon with the command devon dist install, learn more here.
After a successful installation, you can initialize it with the command devon dist
init, learn more here.

4.3. Setup the workspace
1. Unzip the Devonfw distribution into a directory of your choice. The path to the Devonfw
distribution directory should contain no spaces, to prevent problems with some of the tools.
2. Run the batch file "create-or-update-workspace.bat".

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

8

Devonfw Guide v2.4.0

This will configure the included tools like Eclipse with the default settings of the Devonfw
distribution.
The result should be as seen below

The working Devonfw environment is ready!!!
Note : If you use a proxy to connect to the Internet, you have to manually configure it in Maven,
Sencha Cmd and Eclipse. Next section explains about it.

4.3.1. Manual Tool Configuration
Maven
Open the file "conf/.m2/settings.xml" in an editor

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

9

Devonfw Guide v2.4.0

Remove the comment tags around the  section at the beginning of the file.
Then update the settings to match your proxy configuration.

If your proxy does not require authentication, simply remove the  and 
lines.
Sencha Cmd
Open the file software/Sencha/Cmd/default/sencha.cfg in an editor

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

10

Devonfw Guide v2.4.0

Search for the property definition of "cmd.jvm.args" (around line 45).
Comment the existing property definition and uncomment the line above it.
Then update the settings to match your proxy configuration.

If your proxy does not require authentication, simply remove the "-Dhttp.proxyUser", "DhttpProxyPassword", "-Dhttps.proxyUser" and "-Dhttps.proxyPassword" parameters.
Eclipse
Open eclipse by executing "eclipse-main.bat".

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

11

Devonfw Guide v2.4.0

In the Eclipse preferences dialog, go to "General - Network Connection".

Switch from "Native" to "Manual"
Enter your proxy configuration

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

12

Devonfw Guide v2.4.0

Thats All!!!

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

13

Devonfw Guide v2.4.0

Chapter 5. Running Sample Application
Devonfw showcases "My Thai Start" as a sample application, which has the most common features
of a Devonfw application and its proposed best practices. The sample application also serves as a
final test to make sure that your environment is setup correctly. Devonfw distribution comes with a
latest Master version of My Thai Star application.

5.1. Basics of My Thai Star
The My Thai Star application is a solution for managing the online booking and orders of a
restaurant, it is addressed as a showcase app but designed with real requirements although trying
to serve as example of common use cases in web apps (master-detail model, login, authorization
based on roles, pagination, search with filters, etc.).

Setup Devonfw environment and follow the below steps:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

14

Devonfw Guide v2.4.0

5.2. Running My Thai Star
5.2.1. Server
All Spring boot application have their own embedded Tomcat server. This feature help us to deploy
the application in the develop time without the need to create an server. To run the application
with this mode, you need to open Eclipse of your Devonfw distribution and perform the following
steps:
Step 1: Import the project
First of all, import above Sample Application into Eclipse using the following steps:
1. Open Eclipse by executing "eclipse-main.bat" from "Devon-dist" folder.
2. Select "File → Import".
3. Select "Maven → Existing Maven Projects" as shown below:

4. Select the directory "workspaces/examples/my-thai-star" as shown below and later press "OK":

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

15

Devonfw Guide v2.4.0

5. Then press "Finish".

6. Wait for Eclipse to finish importing the sample projects. This process might take several

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

16

Devonfw Guide v2.4.0

minutes, depending on the speed of your internet connection.
Step 2: Run the application
Using Spring Boot features, run your Java back-end applications using the Run as → Java application
over the SpringBootApp.java main class as shown below:

Once, you see the console messages like :

Tomcat started on port(s): 8081 (http)
Started SpringBootApp in 15.985 seconds (JVM running for 16.833)
you can start consuming the Java back-end.
Step 3: Test the application
To see the back-end services results, you can use Postman plugin for Chrome, although you can use
any other similar application.
Now, with Postman, you can do a simple GET request to obtain the information of a dish with id=1
(http://localhost:8081/mythaistar/services/rest/dishmanagement/v1/dish/1). And you will get a
result like this:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

17

Devonfw Guide v2.4.0

Now, Server is running successfully!!!

5.2.2. Client
Make sure that the SERVER is Up and Running!
Step 1: Install Dependencies
To run MyThaiStar front-end, you need to globally install the following dependencies:
1. Node
2. Angular CLI
3. Yarn
Install or update the project

If older versions already exist on your machine, then in order to update Angular CLI globally run
following commands sequentially:

$ npm uninstall -g angular-cli @angular/cli
$ npm cache clean
$ npm install -g @angular/cli
If you have a previous version of this project, you must update the node modules as per your
operating system. There are two different ways to do it, using npm or yarn.
1. Using NPM

Go to the project folder
"workspaces\examples\my-thai-star\angular" and run the following commands:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

18

Devonfw Guide v2.4.0

For Windows:

$ rmdir /s node_modules
$ rmdir /s dist
$ npm install
For Linux or macOS:

$ rm -rf node_modules dist
$ npm install
To test the application as a PWA, you will need a small http server:

$ npm i -g http-server
Or run yarn using below steps.
2. Using Yarn

The project is also tested with the latest Yarn version. After installing the above dependencies, you
can go to the project folder
"workspaces\examples\my-thai-star\angular"
and execute the following command for yarn installation:

yarn install
After finishing, you will see something like:

Otherwise, if you have a previous version of yarn, then run the following commands:

$ rm -rf node_modules dist
$ yarn
If you face any problem with installing dependencies, kindly refer following links:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

19

Devonfw Guide v2.4.0

1. NPM and Yarn Workflow
2. My Thai Start - Angular
Step 2: Run the application
The simple way to run the My Thai Star Angular client is using npm or yarn commands:

$ npm run serve

# OASP4J server

If everything goes well, the console output will be something like this:

Alternatively, you can also run using yarn.

$ yarn serve

# OASP4J server

Step 3: Test the application
Now, go to your browser and open

localhost:4200
and you can see MyThaiStar client running! You can login to the application using:
username: waiter
password: waiter
Also shown below:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

20

Devonfw Guide v2.4.0

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

21

Devonfw Guide v2.4.0

Chapter 6. Getting Started Guides
6.1. Service Layers

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

22

Devonfw Guide v2.4.0

Chapter 7. OASP4J
For Java based back-end solutions, OASP includes OASP4 Java(OASP4J) that provides a standardized
architecture blueprint, an open best-of-breed technology stack as well as industry proven best
practices and code conventions for a cloud ready Spring based server.
Included in the Devon framework as a default server solution, OASP4J is the result of applying OASP
principles in a Java based technology stack. With OASP4J, developers are able to create web
application back-end in a fast and reliable way. Even it simplifies the tasks for generating web
services (REST, SOAP) that can be consumed by web clients.

7.1. OASP4J Technology stack
As mentioned earlier, OASP4J is not only a framework but alos a set of tools and conventions.
OASP4J provides a Java back-end solution based on the following technologies:
• Spring framework as the main development framework.
• Spring Boot as project accelerator.
• Maven as project and dependencies management tool. The Maven projects use the POM file to
store all the necessary information for building the project (project configuration,
dependencies, plugins, etc.). You can get more details about POM files here.
Some of the main features of Spring Boot are:
• Creation of stand-alone Spring applications in an easy way.
• Embedded Tomcat directly (no need to deploy WAR files).
• Provide 'starter' POMs to simplify Maven configuration.
• Automatically configure Spring (whenever possible).
• Provide production-ready features such as metrics, health checks and externalized
configuration.
• No requirement for XML configuration.
For persistence and data access, OASP4J implements:
• JPA and Hibernate
• QueryDsl as query manager
• H2 instance embedded as out-of-the-box database. It will be launched every time, when the
application has been started. Therefore, the developers are able to start working with a real
data access from scratch.
• Flyway as a tool for version control of the database.
• Apache CXF service framework. It provides the support for REST services through JAX-RS and
SOAP services through JAX-WS

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

23

Devonfw Guide v2.4.0

7.2. OASP4J Tools
7.2.1. IDE
As part of the Devon framework, OASP4J projects are integrated in a customized Eclipse instance
that provides several pre-configurations and pre-installed plugins focusing on the code quality and
productivity boosting.

7.2.2. Devon Tools
Besides all the methodologies regarding the mentioned frameworks, the Devon/Oasp ecosystem
also has other tools that are crucial for boosting the productivity and enhancing the organization of
the Java projects.
• Cobigen : a generic incremental generator for end to end code generation that will allow us to
automate the generation of the main parts of the components of our apps. Starting from an
Entity, Cobigen can generate all its CRUD functionality for us, starting from the service and
ending up in the persistance data layer.
• Devcon : A Devon is an internal tool to manage Devon based projects. Among many other tasks,
it can create, run or deploy OASP4J applications avoiding users to do it manually.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

24

Devonfw Guide v2.4.0

Chapter 8. Configuring and Running OASP4J
Application
Devonfw distribution comes with a latest Master version of My Thai Star application.

8.1. Configuring the Application
8.1.1. Step 1: Setup the Devonfw Environment
Configure the Devonfw environment using following steps given here.

8.1.2. Step 2: Import the project
First of all, import above Sample Application into Eclipse using the following steps:
1. Open Eclipse by executing "eclipse-main.bat" from Devon-dist folder.
2. Select "File → Import".
3. Select "Maven → Existing Maven Projects" as shown below:

4. Select the directory "workspaces/examples/my-thai-star" as shown below:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

25

Devonfw Guide v2.4.0

5. Press "Finish"

6. Wait for Eclipse to finish importing the sample projects. This process might take several

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

26

Devonfw Guide v2.4.0

minutes, depending on the speed of your internet connection.

8.2. Running the Application
8.2.1. Step 1: Run the application
Using Spring Boot features, run your Java back-end applications using the Run as → Java application
over the SpringBootApp.java main class as shown below:

Once you see the console messages like :

Tomcat started on port(s): 8081 (http)
Started SpringBootApp in 15.985 seconds (JVM running for 16.833)
you can start consuming the Java back-end.

8.2.2. Step 2: Test the application
You can use Postman plugin for Chrome to see the back-end services results, although you can use
any other similar application.
Now, with Postman, you can do a simple GET request to obtain the info of a dish with id=1
(http://localhost:8081/mythaistar/services/rest/dishmanagement/v1/dish/1). And you get a result
like:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

27

Devonfw Guide v2.4.0

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

28

Devonfw Guide v2.4.0

Chapter 9. OASP4Fn
9.1. Introduction
Serverless is a framework that allows developers to build auto-scalable applications, pay-perexecution, event-driven apps on AWS Lambda, Microsoft Azure, IBM OpenWhisk and Google Cloud
Platform.
OASP4Fn is a npm package full of functionality independent of the goal of the developments made
over this framework. It provides many different features following this approach in order to allow
the developers to use the features that fit in their needs. Also, to build, test and deploy applications
in an easy, fast and clean way using the Serverless framework.

9.2. What is Serverless Computing?
Serverless computing consists of the following concepts and benefits:
• Functions as a Service (FaaS).
• Cloud provider automatically manages starting, stopping and scaling instances for functions.
• More cost-efficient.
• The business or person that owns the system does not have to purchase, rent or provision
servers or virtual machines for the back-end code to run on.
• It can be used in conjunction with the code written in traditional server style, such as
microservices.
• Functions in FaaS are triggered by the event types defined by the provider. For example:
◦ HTTP requests.
◦ AWS S3 updates.
◦ Messages added to a message bus.
Besides the automatic horizontal scaling, the biggest benefit is that you only pay for the compute
that you need. Depending on your traffic scale and shape, this may be a huge economic win in
many projects.
It solves common and inefficient situations such as occasional requests, where an application with
a few small requests per minute makes the CPU idle most of time, or like inconsistent traffic
where the traffic profile of an application is very speaky. For example:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

29

Devonfw Guide v2.4.0

In a traditional environment, you may need to increase your total hardware capability by a factor
of 10 to handle the spikes, even though they only account for less than 4% of total machine uptime.

9.3. What does OASP4Fn provide on Serverless?
The following picture shows what OASP4Fn offers in order to facilitate Serverless development.

Currently, the OASP4Fn architecture defines a series of adapters to help developers to build
applications and make use of different cloud providers.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

30

Devonfw Guide v2.4.0

9.3.1. TypeScript
The Serverless framework is not prepared by default to use TypeScript. OASP4Fn allows the
developer to use TypeScript as the programming language in any development, as it provides the
types definitions and a pre-configured web-pack building system that automates the
transpilation of the different handlers.

9.3.2. Infrastructure as Code
The service made with OASP4Fn must follow a specified structure, that along with a configuration
file will allow the user to avoid having to configure his service manually.

/handlers
/Http
/get
handler1.ts
handler2.ts
…
handlerN.ts
/post
handler1.ts
handler2.ts
/put
…
/S3
...
/{EventName}
/{TriggerMethod}
{HandlerName}.ts
The logic of our application must be stored in a folder, called handlers, inside it we will have a
folder for each event used to trigger the handler and inside a folder with the name of the method
that triggers the handler.
Furthermore of the specified before, in the file oasp4fn.config.js, it is specified the configuration of
the events, deployment information and the runtime environment in which the handlers will run.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

31

Devonfw Guide v2.4.0

9.3.3. Annotations
In addition to the configuration file, we can specify to each handler a concrete configuration,
related to the event that triggers the handler, using a dummy function that adds or modifies the
configuration specified in OASP4Fn configuration file.

// ...
oasp4fn.config({path: 'attachments/{id}'});
export async function getAttachment (event: HttpEvent, context: Context, callback:
Function) {
// ...
}
These annotations will be only interpreted by the framework, so they do not inject or add any kind
of functionality to the actual handler.

9.3.4. Cloud adapters
OASP4Fn also comes with a simple interface that allows the user to have access to different services
of cloud providers using adapters.
That interface makes use of this adapters to retrieve data to the user through Promises, and let the
user query that retrieved data.
Currently available adapters:
• AWS
◦ AWS DynamoDB
◦ AWS S3
◦ AWS Cognito

9.3.5. Command Line Interface
OASP4Fn provides a simple command line interface, that using the resources and the information
provided by Infrastructure as Code, will help the user generate the proper files to build, deploy and
test our application.

Usage: oasp4fn [provider] [options]
or: fun [provider] [options]
Supported Providers: aws (by default aws)
Options:
-o, --opts file
file with the options for the yml generation
-p, --path directory directory where the handlers are stored
-e, --express
generates an express app.ts file
-h, --help
display the help

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

32

Devonfw Guide v2.4.0

Chapter 10. OASP4Fn Installation
10.1. Requirements
In order to develop, build, test and deploy the Serverless applications with OASP4Fn, it is necessary
to install the following packages globally:
• typescript as it is the programming language supported.
• ts-node is a TypeScript execution environment to run TypeScript applications locally.
• mocha is the testing framework.
• nodemon to run, monitor changes and restart automatically the node server in the
development environment.
• serverless to use the Serverless framework.
• @oasp/oasp4fn to make the commands oasp4fn and its shortcut fun globally available.
To install them, run the following command in a terminal:

$ npm install -g typescript ts-node mocha nodemon serverless @oasp/oasp4fn

10.1.1. Database Dependencies
First of all, download DynamoDB in order to work with it locally using this link here.
Running DynamoDB Local
Go to the folder where you unzip the DynamoDB, and run the command:

$ java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar

Create tables
Go back to the project folder and run the command:

$ npm run database
or

$ yarn database

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

33

Devonfw Guide v2.4.0

10.2. Import and Use the Library in Source Code
After installing OASP4Fn, you can import the package in your source code using the import line. It
must be added in the imports section:

import oasp4fn from '@oasp/oasp4fn';
import s3 from '@oasp/oasp4fn/dist/adapters/fn-s3';
import dynamo from '@oasp/oasp4fn/dist/adapters/fn-dynamo';
// Then, oasp4fn will be already available in the code
oasp4fn.setDB(dynamo, {endpoint: 'https://...'});
oasp4fn.setStorage(s3);
oasp4fn.config({path: 'getItem/{id}'});
//...

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

34

Devonfw Guide v2.4.0

Chapter 11. Running OASP4Fn
11.1. Run
Execute the command:

$ npm run fun
This command will generate the necessary files to deploy and build the handlers.

11.2. Start
Execute the command:

$ npm run offline

11.3. Testing
Before executing any test, you must create a new database for this purpose:

$ npm run database:test
or

$ yarn database:test
Then, you can test the correct behavior of the business logic using the command:

$ npm run test

Additional step

Also, you can visualize if some of the changes are wrong when you save it, without executing every
time the previous command. To do this, you can run the next command on a new shell:

$ npm run test:auto

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

35

Devonfw Guide v2.4.0

Chapter 12. Getting Started Guides
12.1. Client Layers

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

36

Devonfw Guide v2.4.0

Chapter 13. OASP4JS
[OASP4JS] is the OASP front-end implementation based on Angular framework. It supports the
development of Angular applications. OASP4JS includes Google Material Design as a main visual
language, to take the maximum advantage of Angular possibilities and Material components. This
makes it possible to build a modular, well-designed and responsive front-end applications.

13.1. OASP4JS Technology Stack
OASP4JS works on the top of Angular but also, it provides several tools, libraries and code
conventions to make your Angular apps easier to develop based on the following technologies:
• Angular Framework as the main development framework.
• Google Material2 as visual language and components.
• Covalent Teradata as Component and utilities library working with Google Material.
• Yarn as a Project dependencies management tool.
The main advantages of these technologies are:
• Teradata provides:
◦ 4 available layouts that fits nowadays design necessities.
◦ Several tools and utilities regarding style conventions such as text size, padding, margins…
◦ Complex components as: Data tables, Chips with autocomplete, pagination…
• Google Material component library is composed by a number of fancy components like tabs,
cards, buttons…
• Yarn is quite faster than NPM and provides some more functionalities to manage dependencies.

13.2. OASP4JS Tools
13.2.1. IDE
There is no integrated IDE with the framework. Therefore, you are free to use any IDE that fits your
needs. Even though, we recommend the use of Visual Studio Code, along with a Guide of the most
interesting plugins to make your development even easier, with Typescript and Angular.

13.2.2. Angular/Cli
This Angular CLI helps the developer to automatize some common processes. It comes with
Webpack as a main bundler. It is widely used in the Angular community, thanks to the boost of the
productivity that it provides at the time of creating new projects from scratch, serving and testing
the project, creating new components, services, directives…

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

37

Devonfw Guide v2.4.0

13.2.3. Testing
Testing helps the developers to be sure that all the typescripts in services and components are
working properly. Moreover, it can also tests the HTML tags and properties. There are many
options to test an Angular app, the default option is Karma and Jasmine.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

38

Devonfw Guide v2.4.0

Chapter 14. Download and Setup
14.1. Download My Thai Star
You can download or clone the latest version of My Thai Star application from the GitHub
repository. It is recommended to use the Git Bash to work with the repository of GitHub. You can
download Git and Git Bash for Windows system here. Also, you can learn more about the Devonfw
best practices to work with Git and GitHub here.
To clone the repository, open the Git Bash console and run the following command:

git clone https://github.com/oasp/my-thai-star.git

14.2. Setup
14.2.1. Install Dependencies
To run MyThaiStar front-end, you need to globally install the following dependencies:
1. Node,
2. Angular CLI
3. Yarn
Once you have installed these dependencies, you can go to the project folder:
"workspaces\examples\my-thai-star\angular"
and execute the following command for the installation of project specific dependencies:

yarn install
After finishing, you will see something like:

OR,
execute the following command:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

39

Devonfw Guide v2.4.0

npm install
Now, the environment setup is ready!

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

40

Devonfw Guide v2.4.0

Chapter 15. Running OASP4JS Application
15.1. Run the Server
Make sure that the SERVER (OASP4J) is Up and Running! Otherwise, you wont be able to
access any back-end functionalities.
You can setup the server part using steps mentioned here.

15.2. Run the MyThaiStar
15.2.1. Step 1: Install Dependencies
To run MyThaiStar front-end, you need to globally install the following dependencies:
1. Node
2. Angular CLI
3. Yarn
Install or update the project
If older versions already exist on your machine, then in order to update Angular CLI globally run
following commands sequentially:

$ npm uninstall -g angular-cli @angular/cli
$ npm cache clean
$ npm install -g @angular/cli
If you have a previous version of this project, you must update the node modules as per your
operating system. There are two different ways to do it, using npm or yarn.
1. Using NPM
Go to the project folder
"workspaces\examples\my-thai-star\angular" and run the following commands:
For Windows:

$ rmdir /s node_modules
$ rmdir /s dist
$ npm install
For Linux or macOS:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

41

Devonfw Guide v2.4.0

$ rm -rf node_modules dist
$ npm install
To test the application as a PWA, you will need a small http server:

$ npm i -g http-server
Or run yarn using below steps.
2. Using Yarn
The project is also tested with the latest Yarn version. After installing the above dependencies, you
can go to the project folder
"workspaces\examples\my-thai-star\angular"
and execute the following command for yarn installation:

yarn install
After finishing, you will see something like:

Otherwise, if you have a previous version of yarn, then run the following commands:

$ rm -rf node_modules dist
$ yarn
If you face any problem with installing dependencies, kindly refer following links:
1. NPM and Yarn Workflow
2. My Thai Start - Angular

15.2.2. Step 2: Run the application
The simple way to run the My Thai Star Angular client is using npm or yarn commands:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

42

Devonfw Guide v2.4.0

1. Using NPM
Run the following command:

$ npm run serve

# OASP4J server

Also, there are following alternatives in order to run My Thai Star Angular client with the different
server technologies and environments:

$ npm run serve:aot
$ npm run serve:pwa
$ npm run serve:prod
$ npm run serve:prod:aot
$ npm run serve:prodcompose
$ npm run serve:prodcompose:aot
Docker compose
$ npm run serve:node
$ npm run serve:node:aot
server

#
#
#
#
#
#

AOT compilation with OASP4J server
Build and run the app as PWA
Production server
AOT compilation with production server
Production server with Docker compose
AOT compilation with production server with

# Node.js or local Serverless server
# AOT compilation with Node.js or local Serverless

If everything goes well, the console output will be something like this:

2. Using Yarn
Alternatively, you can also run using yarn. Make use of one of the following commands:

$ yarn serve
$ yarn serve:aot
$ yarn serve:pwa
$ yarn serve:prod
$ yarn serve:prod:aot
$ yarn serve:prodcompose
$ yarn serve:prodcompose:aot
compose
$ yarn serve:node
$ yarn serve:node:aot
server

#
#
#
#
#
#
#

OASP4J server
AOT compilation with OASP4J server
Build and run the app as PWA
Production server
AOT compilation with production server
Production server with Docker compose
AOT compilation with production server with Docker

# Node.js or local Serverless server
# AOT compilation with Node.js or local Serverless

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

43

Devonfw Guide v2.4.0

Step 3: Test the application
Now, go to the browser and open

localhost:4200
and you can see MyThaiStar client running! You can login to the application using:
username: waiter
password: waiter
as shown below:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

44

Devonfw Guide v2.4.0

Chapter 16. Devon4sencha
16.1. Introduction

Devon4Sencha is an alternative view layer for web applications developed with Devon Framework.
It is based on the proprietary libraries developed by Sencha. As it requires a license for commercial
applications it won’t be provided as Open Source (The companion OASP project).
These libraries provide support for creating SPA (Single Page Applications) with a very rich set of
components for both desktop and mobile. They also provide a clear programming model based on
the MVC and MVVM patterns. Sencha also has an excellent documentation for all the APIs in the
framework. Visit their website for more examples on this.
Devon4Sencha builds on top of Sencha libraries to further standardize the way applications are
created and to seamlessly integrate with the back-end application. We provide:
• Basic application template
• Basic layout for a tabbed based interface
• Security (CORS)
• Login and session management
• Internationalization
• Better organization of source code (following Sencha MVC pattern)
• Ajax communication simplification
Devon4sencha uses the latest Sencha Version 6. The most important change in the version 6 is that
it merges two frameworks: Ext JS (web) and Sencha Touch (mobile) into one single framework.
Now, in Ext JS 6, you can maintain a single code. For some of the views, you may need to have a
separate view code, but there will be a lot of shared code.
They merged the common code and put them as a core framework, and they brought a concept
called toolkit. A toolkit is a package with visual components, such as button, panels, and so on.
There are two toolkits: classic and modern. Ext JS visual components are placed in the classic
toolkit, and Sencha Touch components are placed in the modern toolkit.
You can simply choose the toolkit that you want to target. If you are writing an application that only
targets mobile devices, you can choose modern, and if you are targeting only for desktop, then you
can choose the classic toolkit.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

45

Devonfw Guide v2.4.0

16.2. The Universal Application
If you want to target both desktop and mobile devices, then in Ext JS 6, you can create a universal
application, which will use both the toolkits. Instead of adding the preceding toolkit config
mentioned before, you have to add the following builds config section that specifies which build
uses which toolkit and theme:

"builds": {
"classic": {
"toolkit": "classic",
"theme": "theme-triton"
},
"modern": {
"toolkit": "modern",
"theme": "theme-neptune"
}
},
The basic idea here is to have two set of toolkits in a single framework in order to target the desktop
and mobile devices. When building the application it will create two different bundles for classic
and modern.
When accessing from a desktop, the classic bundle will be used. When accessing from a
tablet/mobile the modern bundle will be selected.
The sample restaurant application is an example of an universal application targeting both
toolkits.

16.3. Legal Considerations
Devon4Sencha is based on Sencha Javascript libraries that are not free and this has to be taken into
consideration before starting with a project.
The license model for Sencha is "per developer" and each engagement should take care of having
enough licenses for developers working on the view layer.
Client should be informed of this fact and may be provided with licenses also if they retain the IP
for the project developed within Capgemini.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

46

Devonfw Guide v2.4.0

Chapter 17. Sencha Cmd
To make your Devon4sencha application development easy, you will find, included in the Devon
distribution, a tool called Sencha Cmd. It’s available for Windows, Mac, and Linux.
Sencha Cmd is a cross-platform command line tool that provides many automated tasks around the
full life-cycle of your applications from generating a new project to deploying an application to
production.
It provides a collection of powerful features that work together and in conjunction with the Sencha
Ext JS framework like code generation, javascript compiler, workspace management, mobile native
packaging, build scripts, theming and so on.
The workspace management feature allows the import of "packages" into your application. That
way you can modularize and create packages for sharing functionality between applications.
Devon provides one of these packages called devon-extjs.
The most usual way to use Cmd during application development, is just running sencha app watch to
compile and test the application on a browser. This command must be launched from the
application root folder and starts a web server with the client application ready to access from the
browser.
Sencha Cmd is not a must for Devon4sencha development application, but using it makes your life
easier. So, it’s highly recommended to use it.

17.1. Workspaces
With Sencha Cmd Workspaces we can share code and packages between Sencha applications. This
is useful because Sencha distribution files occupy quite a bit of disk space.

Using devcon

NOTE

You can create a new Sencha workspace using devcon with the devon sencha
workspace command learn more here

The easiest way to manually create a Sencha CMD workspace for your application is simply copying
the

example

workspace

of

devon4sencha

(copy

the

complete

directory

at

workspaces\examples\devon4sencha into workspaces\main\ and delete the
example application’s directory called ExtSample.
You can also create a workspace from scratch:
• Create the workspace:

sencha generate workspace /path/to/workspace

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

47

Devonfw Guide v2.4.0

• Copy ExtJS distribution to /path/to/workspace/ext.
• Copy

devon4sencha

package

from

the

example

workspace

to

/path/to/workspace/packages/devon-extjs.
• Copy

application

template

StarterTemplate

from

the

example

workspace

to

/path/to/workspace/StarterTemplate.
• Now, we can create several applications that share the ExtJS distribution and devon4sencha
package:

sencha generate app -ext --starter StarterTemplate MyApp1 /path/to/workspace/MyApp1
sencha generate app -ext --starter StarterTemplate MyApp2 /path/to/workspace/MyApp2

17.1.1. Sencha packages
With Sencha Cmd packages we can share and distribute code between Sencha applications. For
example, devon4sencha is distributed as a Sencha Cmd package that can be shared between
applications.
This code will be automatically added to the final application when building the application with
Sencha Cmd.

17.1.2. Sencha reloading
During application development, we can use the Sencha Cmd app watch feature to compile and
test the application in a browser. This command must be launched from the application root folder.

$ cd devon4sencha
$ cd ExtSample
$ sencha app watch
Any code changes to the application files will be detected by Sencha Cmd and it will update the
application being served. It requires a manual refresh on the browser though to effectively see the
changes.
Since this is intended for development and in order to speed up things, only the first "build" defined
on app.json will be processed. This means that if you are developing an "universal" app for desktop
and mobile you will have several "build" sections defined.
To trigger a concrete "build" you can name it after the watch argument

$ sencha app watch modern

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

48

Devonfw Guide v2.4.0

Speed up development

When in development, you can speed things up even more if you are not modifying
NOTE

the sass styles. You can set skip.sass=1 on the build.properties file of your
workspace

application

(i.e:

in

the

restaurant

application

it

would

be

devon4sencha/ExtSample/.sencha/app/build.properties). Don’t forget to revert to 0 if
you modify styles or change to other build type (classic/modern)

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

49

Devonfw Guide v2.4.0

Chapter 18. Devon4sencha Sample
application
Devon comes with a sample java application simulating the backend for a restaurant application.
Devon4sencha’s sample application completes the restaurant application with a user-friendly UI.

18.1. Running the sample restaurant application

Using devcon

NOTE

You can automate the following steps using devcon with the devon sencha run
command learn more here

The following steps assume that you already have setup your Devon environment, and that you
have the devonfw-sample-server running on a server on port 8081. Refer to the Devonfw Server
documentation for instructions on how to setup the Devon environment or the devon sample
application.
1. Open a Devon command prompt by executing the batch file console.bat.

2. Enter the workspaces\examples\devon4sencha\ExtSample directory

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

50

Devonfw Guide v2.4.0

3. Execute the the command sencha app watch. It might take some time the first time you run this
command.
This command will compile the devon4sencha sample application and start a webserver to
serve it and will automatically recompile the application if it detects any changes to the
application’s files.
On first run, you probably will see something similar to the image below. We do not distribute
ExtJS itself with our sample application. Instead, the ExtJS SDK is downloaded on first use if not
already available.

If you have a valid ExtJS license, you can simply copy the ExtJS 6 SDK into
workspaces\examples\devon4sencha\ext and it will automatically get picked up.
If you see an error while executing this command, first try to delete the local
sencha
NOTE

repository

located

ENVIRONMENT>\software\Sencha\Cmd\default\repo.

at
If

there

was

devon foo saySomething -message hello
where:
• foo is the module.
• saySomething is the command of the foo module to be executed.
• '-message' is the parameter that the command saySomething needs to be executed.
• hello is the value for the message parameter.
Parameters
As its mentioned before from the point of view of the commands, we have two types of parameters:
the mandatory parameters and the optional parameters. The mandatory parameters must be
provided by the user specifying the parameter identifier and the value in the command line. The
optional parameters must be also provided to the app but, if the user do not specify it, devcon will
use a default value for them.
Global parameters
Devcon handles a third type of parameter that has nothing to do with command parameters. We
are referring it as global parameters.
The global parameters are a set of parameters that works in global context, which means it will
affect the behaviour of the command in the first phase i.e. before launching the command module
itself.
As these parameters act in a global context, we do not need to provide the values for them. They
work as flags to define some internal behaviour of devcon.
In the current version of Devcon we have the following global parameters :
• global parameter gui: defined with -g or --gui
• global parameter help: defined with -h or --help.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

58

Devonfw Guide v2.4.0

• global parameter prompt: defined with -p or --prompt.
• global parameter stacktrace: defined with -s or --stacktrace.
• global parameter version: defined with -v or --version.
gui parameter

As we saw earlier the global parameter gui (-g) is the way we will launch the Devcon’s graphical
user interface. So to complete that operation we only need to execute

devon -g

help parameter

The global parameter help is very useful to show overall help info of Devcon or also for showing
more detailed info of each module and command supported. For example, if you don’t know
anything about how to start with Devcon, the option -h (or --help) will show a summary of the
devcon usage, listing the global parameters and the available modules alongside a brief description
of each one.

C:\>devon -h
Hello, this is Devcon!
Copyright (c) 2016 Capgemini
usage: devon <> <> [parameters...]
Devcon is a command line tool that provides many automated tasks around
the full life-cycle of Devon applications.
-h,--help
show help info for each module/command
-v,--version
show devcon version
List of available modules:
> help: This module shows help info about devcon
> sencha: Sencha related commands
> dist: Module with general tasks related to the distribution itself
> doc: Module with tasks related with obtaining specific documentation
> github: Module to create a new workspace with all default configuration
> workspace: Module to create a new workspace with all default configuration
As a global parameter, if you use the -h parameter with a module, it will show the help info related
to given module including a basic usage and a list of the available commands in given module.

C:\>devon foo -h
Hello, this is Devcon!
Copyright (c) 2016 Capgemini
usage: foo <> [parameters...]
This is only a test module.
Available commands for module: foo
> saySomething: This command is for say something

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

59

Devonfw Guide v2.4.0

In the same way, as a global parameter, if we use the -h parameter with a command, instead of
launching the command the help info related to the command will be shown

D:\>devon foo saySomething -h
Hello, this is Devcon!
Copyright (c) 2016 Capgemini
usage: saySomething [-message] [-signature]
This command is to say something
-message
the message to be written
-signature
the signature
Even if you specify the needed parameters, the behaviour will be the same as we stated that the
global parameters affect how devcon behaves before launching the commands

D:\>devon foo saySomething -message hello -signature John -h
Hello, this is Devcon!
Copyright (c) 2016 Capgemini
usage: saySomething [-message] [-signature]
This command is to say something
-message
the message to be written
-signature
the signature

prompt parameter

With this global parameter, you can ask devcon to prompt for all parameters (both optional and
mandatory) when launching a command.
To give an example, you can use the oasp4j create command (that creates a new server project
based on OASP4J model). In this case we would need to provide several parameters so the
command call would look like

D:\devon-dist>devon oasp4j create -servername myServer -groupid com.capgemini
-packagename com.capgemini.myServer -version 1.0
As you can see the command is defined by devon oasp4j create words and the rest of the command
line attributes are parameters.
With the global parameter -p Devcon gives the user the option to avoid defining any parameter
when launching the command and provide step by step all parameters after that, so the usage of
some commands can be way easier.
Going back to the previous example if we use the -p parameter we get

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

60

Devonfw Guide v2.4.0

D:\devon-dist>devon oasp4j create -p
Hello, this is Devcon!
Copyright (c) 2016 Capgemini
Command: devon oasp4j create
Description: This command is used to create new server project
Parameter: serverpath - where to create
->
Parameter: servername - Name of project
-> myServer
Parameter: packagename - package name in server project
-> com.capgemini.myServer_
[...]
As you can see with the -p parameter Devcon asks for each parameter related to a command (the
optional ones can be left blank as the serverpath in the example) and the user can provide them one
on one, getting rid of the concern of knowing what parameters needs a command.
version parameter

This is a simple option that returns the devcon running version and is defined with -v (or -version). As the help option this will show the devcon version even though we have defined a
command with all required parameters.

D:\>devon -v
Hello, this is Devcon!
Copyright (c) 2016 Capgemini
devcon v.1.0.0

D:\>devon foo saySomething -message hello -signature John -v
Hello, this is Devcon!
Copyright (c) 2016 Capgemini
devcon v.1.0.0

21.5. First steps with Devcon
This section describes how to start using devcon from scratch. For this, you can use the global
option -h (help) in order to figure out which commands and parameters you need to define. But in a
very first approach, only the command devon will be enough. Therefore, the first step is to look for
a module that fits your requirements. As mentioned above, you can do this with the help option
(defined as -h or --help) or with a simple command devon. If you do not specify any information, you
will see a summary of the general help information with an example of usage, a list with global
parameters and the available modules.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

61

Devonfw Guide v2.4.0

D:\>devon
Hello, this is Devcon!
Copyright (c) 2016 Capgemini
usage: devon <> <> [parameters...]
Devcon is a command line tool that provides many automated tasks around
the full life-cycle of Devon applications.
-h,--help
show help info for each module/command
-v,--version
show devcon version
List of available modules:
> help: This module shows help info about devcon
> sencha: Sencha related commands
> dist: Module with general tasks related to the distribution itself
> doc: Module with tasks related with obtaining specific documentation
> github: Module to create a new workspace with all default configuration
> workspace: Module to create a new workspace with all default configuration
Once you have the list of modules and an example of how to use it, you may need to get the devon
distribution to go deeper in module *dist*, for that you can again use the help option after the
module definition.

D:\>devon dist -h
Hello, this is Devcon!
Copyright (c) 2016 Capgemini
usage: dist <> [parameters...]
Module with general tasks related to the distribution itself
Available commands for module: dist
> install: This command downloads the distribution
> s2: Initializes a Devon distribution for use with Shared Services.
Now, you know that the dist module has two commands, the install command and the s2 command
and you can see a brief description of each one therefore you can decide which one you need to
use. In case you have to get a devon distribution, it can be found by the install command with the
help option.

D:\>devon dist install -h
Hello, this is Devcon!
Copyright (c) 2016 Capgemini
usage: install [-password] [-path] [-type] [-user]
This command downloads the distribution
-password
the password related to the user with permissions to download
the Devon distribution
-path
a location for the Devon distribution download
-type
the type of the distribution, the options are:
'oaspide' to download OASP IDE
'devondist' to download Devon IDE
-user
a user with permissions to download the Devon distribution

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

62

Devonfw Guide v2.4.0

So now you know that the install command of the dist module needs:
• user with permissions to download the distribution.
• the related password.
• the path where the distribution file must to be downloaded.
• the type of distribution that can be 'oaspide' or 'devondist'.
With all the information, you can launch a fully functional command such as:

D:\>devon dist install -user john -password 1234 -path D:\Temp\MyDistribution -type
devondist
Regarding the order of the command parameters, devcon will order them internally so that you
don’t have to concern about that point and you can specify them in the order you want. The only
requirement is that all mandatory parameters should be provided.

21.6. Devcon command reference
For a full reference of all the available commands in Devcon, see the Devcon Command Reference

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

63

Devonfw Guide v2.4.0

Chapter 22. The Devon IDE
22.1. Introduction
The Devon IDE is the general name for two distinct versions of a customized Eclipse which comes in
a Open Source variant, called OASP4J-IDE, and a more extended version included in the "Devon
Dist" which is only available for Capgemini engagements.

22.1.1. Features and advantages
Devonfw comes with a fully featured IDE in order to simplify the installation, configuration and
maintenance of this instrumental part of the development environment. As it is being included in
the distribution, the IDE is ready to be used and some specific configuration of certain plugins only
takes a few minutes.

As with the remainder of the distribution, the advantage of this approach is that you can have as
many instances of the -ide "installed" on your machine for different projects with different tools,
tool versions and configurations. No physical installation and no tweaking of your operating system
required. "Installations" of the Devon distribution do not interfere with each other nor with other
installed software.

22.1.2. Multiple Workspaces
There is inbuilt support for working with different workspaces on different branches. Create and
update new workspaces with a few clicks. You can see the workspace name in the title-bar of your
IDE so you do not get confused and work on the right branch.

22.2. Cobigen
In the Devon distribution we have a code generator to create CRUD code, called Cobigen. This is a
generic incremental generator for end to end code generation tasks, mostly used in Java projects.
Due to a template-based approach, CobiGen generates any set of text-based documents and
document fragments.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

64

Devonfw Guide v2.4.0

Cobigen is distributed in the Devon distribution as an Eclipse plugin, and is available to all Devon
developers for Capgemini engagements. Due to the importance of this component and the scope of
its functionality, it is fully described here.

22.3. IDE Plugins:
Since an application’s code can greatly vary, and every program can be written in lots of ways
without being semantically different, IDE comes with pre-installed and pre-configured plugins that
use some kind of a probabilistic approach, usually based on pattern matching, to determine which
pieces of code should be reviewed. These hints are a real time-saver, helping you to review
incoming changes and prevent bugs from propagating into the released artifacts. Apart from
Cobigen mentioned in the previous paragraph, the IDE provides CheckStyle, SonarQube, FindBugs
and SOAP-UI. Details of each can be found in subsequent sections.

22.3.1. CheckStyle
What is CheckStyle
CheckStyle is a Open Source development tool to help you ensure that your Java code adheres to a
set of coding standards. Checkstyle does this by inspecting your Java source code and pointing out
items that deviate from a defined set of coding rules.
With the Checkstyle IDE Plugin, your code is constantly inspected for coding standard deviations.
Within the Eclipse workbench, you are immediately notified with the problems via the Eclipse
Problems View and source code annotations similar to compiler errors or warnings. This ensures
an extremely short feedback loop right at the developers fingertips.
Why use CheckStyle
If your development team consists of more than one person, then obviously a common ground for
coding standards (formatting rules, line lengths etc.) must be agreed upon - even if it is just for
practical reasons to avoid superficial, format related merge conflicts. Checkstyle Plugin helps you
define and easily apply those common rules.
The plugin uses a project builder to check your project files with Checkstyle. Assuming the IDE
Auto-Build feature is enabled, each modification of a project file will immediately get checked by

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

65

Devonfw Guide v2.4.0

Checkstyle on file save - giving you immediate feedback about the changes you made. To use a
simple analogy, the Checkstyle Plug-in works very much like a compiler but instead of producing
.class files, it produces warnings where the code violates Checkstyle rules. The discovered
deviations are accessible in the Eclipse Problems View, as code editor annotations and via
additional Checkstyle violations views.
Installation of CheckStyle
After IDE installation, IDE provides default checkstyle configuration file which has certain check
rules specified . The set of rules used to check the code is highly configurable. A Checkstyle
configuration specifies which check rules are validated against the code and with which severity
violations will be reported. Once defined a Checkstyle configuration can be used across multiple
projects. The IDE comes with several pre-defined Checkstyle configurations. You can create custom
configurations using the plugin’s Checkstyle configuration editor or even use an existing Checkstyle
configuration file from an external location.
You can see violations in your workspace as shown in below figure.

Usage
So, once projects are created, follow steps mentioned below, to activate checkstyle:
1. Open the properties of the project you want to get checked.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

66

Devonfw Guide v2.4.0

2. Select the Checkstyle section within the properties dialog .

3. Activate Checkstyle for your project by selecting the Checkstyle active for this project check box
and press OK

Now Checkstyle should begin checking your code. This may take a while depending on how many
source files your project contains. The Checkstyle Plug-in uses background jobs to do its work - so
while Checkstyle audits your source files you should be able to continue your work. After
Checkstyle has finished checking your code please look into your Eclipse Problems View. There
should be some warnings from Checkstyle. This warnings point to the code locations where your
code violates the preconfigured Checks configuration.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

67

Devonfw Guide v2.4.0

You can navigate to the problems in your code by double-clicking the problem in you problems
view. On the left hand side of the editor an icon is shown for each line that contains a Checkstyle
violation. Hovering with your mouse above this icon will show you the problem message. Also note
the editor annotations - they are there to make it even easier to see where the problems are.

22.3.2. FindBugs
What is FindBugs
FindBugsis an open source project for a static analysis of the Java bytecode to identify potential
software bugs. Findbugs provides early feedback about potential errors in the code.
Why use FindBugs
It scans your code for bugs, breaking down the list of bugs in your code into a ranked list on a 20point scale. The lower the number, the more hardcore the bug.This helps the developer to access
these problems early in the development phase.
Installation and Usage of FindBugs
IDE comes preinstalled with FindBugs plugin.
You can configure that FindBugs should run automatically for a selected project. For this right-click
on a project and select Properties from the popup menu. via the project properties. Select FindBugs
→ Run automatically as shown below.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

68

Devonfw Guide v2.4.0

To run the error analysis of FindBugs on a project, right-click on it and select the Find Bugs… →
Find Bugs menu entry.

Plugin provides specialized views to see the reported error messages. Select Window → Show View
→ Other… to access the views. The FindBugs error messages are also displayed in the Problems
view or as decorators in the Package Explorer view.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

69

Devonfw Guide v2.4.0

22.3.3. SonarLint
what is SonarLint
SonarLint is an open platform to manage code quality. It provides on-the-fly feedback to developers
on new bugs and quality issues injected into their code..
Why use SonarLint
It covers seven aspects of code quality like junits, coding rules,comments,complexity,duplications,
architecture and design and potential bugs. SonarLint has got a very efficient way of navigating, a
balance between high-level view, dashboard and defect hunting tools. This enables to quickly
uncover projects and / or components that are in analysis to establish action plans.
Installation and usage of SonarLint
IDE comes preinstalled with SonarLint. To configure it , please follow below steps:
First of all, you need to start sonar service. For that , go to software folder which is extracted from
Devon-dist zip, choose sonarqube→bin→-→and
execute startSonar bat file.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

70

Devonfw Guide v2.4.0

If your project is not already under analysis, you’ll need to declare it through the SonarQube web
interface as described here. Once your project exists in SonarQube, you’re ready to get started with
SonarQube in Eclipse.
SonarLint in Eclipse is pre-configured to access a local SonarQube server listening on
http://localhost:9000/. You can edit this server, delete it or add new ones.By default, user and
password is "admin".If sonar service is started properly, test connection will give you successful
result.

For getting a project analysed on sonar, refer this http://docs.sonarqube.org/display/SONAR/
Analyzing+Source+Code [link].
Linking a project to one analysed on sonar server.

In the SonarQube project text field, start typing the name of the project and select it in the list box:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

71

Devonfw Guide v2.4.0

Click on Finish. Your project is now associated to one analyzed on your SonarQube server.
Changing Binding
At any time, it is possible to change the project association.
To do so, right-click on the project in the Project Explorer, and then SonarQube > Change Project
Association.

Unbinding a Project
To do so, right-click on the project in the Project Explorer, and then SonarQube > Remove
SonarQube Nature.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

72

Devonfw Guide v2.4.0

Advanced Configuration
Additional settings (such as markers for new issues) are available through Window > Preferences >
SonarLint

To look for sonarqube analysed issue, go to Window→Show View→ Others→SonarLint→SonarLint
Issues. Now you can see issues in soanrqube issues tab as shown

Or you can go to link http://localhost:9000 and login with admin as id and admin as password and
goto Dashboard.you can see all the statistics of analysis of the configured projects on sonar server.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

73

Devonfw Guide v2.4.0

Chapter 23. Creating your First Application
In devonfw, you can create new project using two different ways:
• Using Devcon and jumpthequeue Project
• Using Archetype

23.1. Using Devcon
You can refer the following Creating New OASP4J Application page for more details.

23.2. Using the Archetype
In order to create a new application, you must use the archetype provided by devon which uses the
maven archetype functionality.
There are two alternatives for using the archetype to create a new application. One is to create
using command line. Another way is within eclipse, which is a more visual manner.

23.2.1. Using the Command Line
Step 1: Open the console
Open the Devonfw console by executing the batch file console.bat from the Devonfw distribution. It
is a pre-configured console which automatically uses the software and configuration provided by
the Devonfw distribution.
Step 2: Change the directory
You can create the project anywhere you want, but it is a good practice to create the projects in
your workspace directory. Therefore, run the following command in the console to change to the
directory to workspaces\main.

cd workspaces\main
This is the default location on Devonfw to create new applications. It is also possible to have your
own workspace.
Step 3: Create the new application
To create a new application, you need to execute one of the following commands:
• WAR packaging (arguments before archetype:generate identify the OASP4J archetype):

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

74

Devonfw Guide v2.4.0

mvn -DarchetypeVersion= -DarchetypeGroupId=io.oasp.java.templates
-DarchetypeArtifactId=oasp4j-template-server archetype:generate -DgroupId
= -DartifactId= -Dversion
= -Dpackage= -DdbType=
For example

mvn -DarchetypeVersion=2.5.0 -DarchetypeGroupId=io.oasp.java.templates
-DarchetypeArtifactId=oasp4j-template-server archetype:generate -DgroupId
=io.oasp.application -DartifactId=sampleapp -Dversion=0.1-SNAPSHOT -Dpackage
=io.oasp.application.sampleapp -DdbType=h2

This will create a new directory inside workspaces\main with the name of your application with the
created application inside.

23.2.2. Using the Eclipse
If you use a proxy to connect to the Internet, then the above steps will not work as
NOTE

Eclipse has a known bug where the archetype discovery does not work behind a
proxy. In this case, please use the command line version documented above.

To create a new application using Eclipse, you should have installed Devonfw distribution. Then,
follow below steps to create a new application:
Step 1 - Create a new Maven Project
Open Eclipse from a Devonfw distribution, by executing the batch file eclipse-main.bat, then go to
File > New > Maven Project. If you don’t see the option, click File > New > Other and use the filter to
search the option Maven Project
Step 2 - Choose the archetype
In the New Maven Project wizard, you need to choose the oas4j-template-server archetype, as shown
in below image.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

75

Devonfw Guide v2.4.0

If you are not able to access the archetype even after checking the Include snapshot
archetypes option, then try adding the archetype repository manually. You can do it
with the Configure button located next to the Catalogs dropdown and then clicking
the Add Remote Catalog button. Finally, you need to add the repository URL
https://repo1.maven.org/maven2 and as Description you can use Maven Central.

NOTE

Use the Verify button to check the connection. Subsequently, you will see a message
with the amount of found archetypes.
Step 3 - Configure the application properties
Fill the Group Id, Artifact Id, Version and Package for your project. Also in Properties available from
archetype

section

update

dbtype

as

required

with

any

of

values

(h2|postgresql|mysql|mariadb|oracle|hana|db2)

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

76

Devonfw Guide v2.4.0

• Click on the Finish button and the project will be ready for execution.

23.2.3. What is generated
To read more about the OASP4J application structure, click here.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

77

Devonfw Guide v2.4.0

Chapter 24. Design Philosophy : Jump the
Queue

24.1. Introduction
When visiting public (free) or private (paid) events there are often large queues creating significant
waiting times. Ideally the organizer of the event would like to streamline the entry of people. That
would be possible by allowing people privileged access or, alternatively, offer an incentive for
people to arrive in time or to get into line more efficiently. A way of doing this would be to have a
website or application which would allow visitors to "Jump the Queue". This document describes
the design for such an application: “JumpTheQueue”.
Note that the document is intended to reflect a hypothetical but real use case. The
design reflects this by trying to be complete. But the implementation is simplified in
NOTE

order to serve as an example. Where implementation differs from design, this is
noted with an icon or symbol like : ⇒ and a comment about the nature of the
difference.

24.2. User Stories

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

78

Devonfw Guide v2.4.0

As a < type of user >, I want < some goal > so that < some reason >

24.2.1. Epic: Register Event
As a visitor to an event I want to be able to visit a website or use an app - called JumpTheQueue,
which provides me with a code (and optional date/time) after registration so that I can get a
privileged access to the event
User Story: register
As a user of JumpTheQueue, I want to register with my name and either Email, Phone number or
both so that I comply with the requirements to obtain the access code
Acceptance Criteria

A full name is mandatory. Either Email, Phone or both can be given. These must be valid. Validation
is a separate, asynchronous process.
US: terms and conditions
As a user of JumpTheQueue, I accept that the organiser of the event can store my personal data so
they can send me commercial notices (“spam”)
As a user of JumpTheQueue, I want to read the statement “By pressing ‘Request it’ you agree to the
Terms and Conditions” so that I can implicitly agree to aforementioned terms & conditions.
US: List queued visitors
As a user of JumpTheQueue I want to show the list of users ahead of me in the queue with optional
data & time so I can see how long I have to wait and optionally at what time I have to appear at the
access gate.
Etcetera
As a user of JumpTheQueue, I have to confirm either Email or Phone number by replying to a
message send to the account if entered so the data can be verified.
⇒ this is not further developed nor implemented
As a visitor , I want to go the the privileged access queue with my valid (i.e. validated) access code
so I can get direct access.
⇒ this is not further developed nor implemented

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

79

Devonfw Guide v2.4.0

24.3. UI
24.3.1. Flow
The basic flow of the application can be:

• Fill in a form to give your name and private data and then press a button with “Register”
• In case of validation errors, an error message will be shown
• If there are no errors then an Access Code will be generated which will be shown on a next
page. The access code can optionally be provided with proposed access time.
• From this page you can show a view of the current Queue, with the list of people queued

24.3.2. Mock-ups

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

80

Devonfw Guide v2.4.0

24.4. Model

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

81

Devonfw Guide v2.4.0

⇒ the Event item is not further developed nor implemented

24.4.1. Predicates

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

82

Devonfw Guide v2.4.0

Definition

< function name > = < parameters > => < *pure* function >
or

< function name > = trivial : < trivial description >

isnull = (v) => v === null
notnull = (v) => !isnull(v)
isempty = (s: string) => s.length === 0
notempty = (s: string) => !notempty(s)
isEmailAddress = trivial: notnull + notempty + consists of @
isTelephoneNumber = trivial: notnull + notempty + consists of sequence of numbers or
spaces (i.e. “4 84 28 81”)

24.4.2. Types
Definition

type < alias > :: < type defs > with predicated: < list of predicates >
or

type < alias > :: trivial: < trivial description >

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

83

Devonfw Guide v2.4.0

type ID :: trivial: Unique Atomic Identifier
type NamedItem :: string
with predicates: notnull, notempty
type EmailAddress :: string
with predicates: isEmailAddress
type TelephoneNumber :: string
with predicates: isTelephoneNumber
type Option :: None | T
type Result :: Error | T
type Error :: trivial: Error information with code & error description

24.4.3. Entities & Value Objects
Sequence (Entity)
Field

Type

Id

ID

Number

nameItem

AccessCode (Entity)
Field

Type

Id

ID

Code

NamedItem

Valid

boolean

Visitor

NamedItem

Telephone

Option

Email

Option

Request
Field

Type

Name

NameItem

Telephone

Option

Email

Option

ProvidedAccessCode
Field

Type

Name

NamedItem

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

84

Devonfw Guide v2.4.0

ProvidedAccessCode
Code

NamedItem

QueueName

NamedItem

Date&Time

Option

There must be a 1 - 1 relationship between a ProvidedAccessCode and an AccessCode.

24.4.4. Service Catalog
Definition

< service/function name > :: < parameters> => < return type >

registerEvent :: ( sequence: Sequence ) => Result
Send Sequence and obtain an AccessCode or Error result.

showList :: ( accesscode: NamedItem ) => Result>
Send AccessCode and receive an ordered list of access code with visitor name etc or Error result.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

85

Devonfw Guide v2.4.0

Chapter 25. Devonfw Distribution Structure
In this section, you will find outlook on the Devonfw distribution structure that you will find right
after downloading the zip. In short, the use of each file and folder will be explained here.
Therefore, after unzipping the Devonfw distribution, you will find the following directory structure
as shown in the image:

25.1. Understanding the structure
In the above image, you can find different folders and executable .bat files. You will find below the
use of create-or-update-workspace.bat and update-all-workspaces.bat files. These are the scripts
which you will execute to obtain the whole Devonfw structure:
• The create-or-update-workspace.bat file will create the conf directory that stores the Maven
local repository and two configuration files (the settings.json with distribution information and
the settings.xml with the Maven connection settings). Alongside with that it will create the
eclipse-main.bat to start Eclipse.
• The update-all-workspaces.bat file sets some Eclipse preferences for workspaces and creates
all the Eclipse .bat launchers related to the projects in the workspace directory.
Hence, after executing these two scripts, following structure will be generated:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

86

Devonfw Guide v2.4.0

Thereon, You will have the new conf directory as expected and the eclipse-main.bat and the eclipseexamples.bat related to the main and examples directories within the workspaces folder.
This is the final structure. A detailed explanation for each file and folder is given below:

25.1.1. conf
As mentioned previously, this directory is generated by executing the create-or-updateworkspace.bat. This is the directory where Maven will store its local repository, in a .m2/repository
path. Moreover, in the conf directory, you can find two settings files. The settings.json with
distribution information and the settings.xml with the Maven connection settings.

25.1.2. doc
Here, you can find, the documentation related to both, the starting development tasks with the
framework and implementing its more advanced features in pdf format.

25.1.3. scripts
This folder stores the scripts referenced in the .bat files in the root directory. These scripts are
related to internal tasks of the distribution.

25.1.4. settings
This directory stores the elements required for internal functionality of the distribution. Here, you
can find the configuration files of different software, included in the distribution, such as Eclipse,
Maven, Sonarqube and several more.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

87

Devonfw Guide v2.4.0

25.1.5. software
All the software resources that the distribution needs are stored in this folder. Internally, the
distribution will search here for available software. Therefore, all the programs, plugins and tools
needed by the distribution must be located in this directory.

25.1.6. system
This is another directory with internal elements. In system folder, you can find some files related to
the environment configuration.

25.1.7. workspaces
This is the directory to store all the projects. One must keep in mind that the content of this folder
will be associated with a Eclipse .bat launcher files through the update-all-worksapces.bat script. So
if you want the separated Eclipse instances for two different projects, you must declare these
projects in separate directories within the workspaces folder.
To conclude, if you have a workspaces/project01 and a workspaces/project02 projects, then the
update-all-workspaces.bat script will create a eclipse-project01.bat launcher and a eclipseproject02.bat launcher in the root folder of the distribution. Thus, you can have access to the
different Eclipse instances with different configurations for each project.

Using devcon

NOTE

You can automate this operation using devcon with the devon workspace create
command learn more here

25.1.8. console.bat
This script launches the distribution’s cmd. Meaning, within this cmd, you have access to the
software located in the software folder, so that you can use the tools "installed" in that folder
although you don’t have this installed on your machine. Therefore, it is important to always run
this cmd (launching the console.bat script) to make use of the software related to the distribution.

25.1.9. create-or-update-workspace.bat
This script is already explained at the beginning of this chapter.

25.1.10. EclipseConfigurator.log
This is a file for internal usage and records the logs of the create-or-update-workspace.bat and the
update-all-workspaces.bat scripts.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

88

Devonfw Guide v2.4.0

25.1.11. eclipse-project.bat
These files are used to have different Eclipse instances related to the different projects located into
the workspaces directory. Therefore, for each project in the workspaces directory, the update-allworkspaces.bat script will create an Eclipse launcher with structure eclipse-.bat. In
such a way, you can have different Eclipse environments with different configurations related to
the different projects of the workspace directory.

25.1.12. s2-create.bat and s2-init.bat
These scripts relate to the Shared Services functionality included in Devonfw. The s2-init.bat
configures the settings.xml file to connect to an Artifactory Repository. The s2.create.bat generates a
new project in the workspaces directory and does a checkout of a Subversion repository inside.
Each script needs to be launched from the distribution’s cmd (launching the console.bat script) and
some parameters to work properly.

25.1.13. update-all-workspaces.bat
This script is already explained at the beginning of this chapter.

25.1.14. variables.bat
This script is related to the internal functionality of the distribution. The script stores some
variables that are used internally by the distribution scripts.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

89

Devonfw Guide v2.4.0

Chapter 26. Database Configuration
In this tutorial, you will see how to configure your application to connect with a real database of
your choice. For different Database Configuration we only need to give input to archetype at time of
project creation which DB you need to configure i.e. if you are using command line tool for
generating project you need to add dbtype (h2|postgresql|mysql|mariadb|oracle|hana|db2)

mvn -DarchetypeVersion= -DarchetypeGroupId=io.oasp.java.templates
-DarchetypeArtifactId=oasp4j-template-server archetype:generate -DgroupId
= -DartifactId= -Dversion= -Dpackage= -DdbType=
If you want to configure database such as MySQL, MS SQL or PostGre SQL, refer below sections.

26.1. Dependencies
Dependency for database in pom.xml file will be added automatically. For e.g if we are configuring
mysql database in our application the below dependency will be there in your pom.xml file:
MySQL:


mysql
mysql-connector-java


Note: This driver should NOT be used in a production environment because of the license issues.
See below for an alternative.

26.2. Database configuration
Database

configuration

will

be

automatically

generated

in

src/resources/config/application.properties_ file. Update the required values accordingly.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

90

Devonfw Guide v2.4.0

MySQL:

server.port=8081
server.context-path=/
spring.datasource.url=jdbc:mysql://address=(protocol=tcp)(host=localhost)(port=3306)/<
db>
spring.datasource.password=
# Enable JSON pretty printing
spring.jackson.serialization.INDENT_OUTPUT=true
# Flyway for Database Setup and Migrations
flyway.enabled=true
flyway.clean-on-validation-error=true
Database configuration will be automatically generated in src/resources/application.properties_
file. Update the required values accordingly.
MySQL:

spring.application.name=myapplication
server.context-path=/
security.expose.error.details=false
security.cors.enabled=false
spring.jpa.hibernate.ddl-auto=validate
# Datasource for accessing the database
spring.jpa.database=mysql
spring.datasource.username=mysqluser
spring.jpa.hibernate.naming.implicit-strategy=org.hibernate.boot.model.naming
.ImplicitNamingStrategyJpaCompliantImpl
spring.jpa.hibernate.naming.physical-strategy=org.hibernate.boot.model.naming
.PhysicalNamingStrategyStandardImpl
spring.batch.job.enabled=false
# Flyway for Database Setup and Migrations
flyway.locations=classpath:db/migration,classpath:db/type/mysql

26.3. Further Details on Database Configurations
26.3.1. MySQL
The use of the MySQL has already been illustrated in the above example. However, as mentioned,
the GPL licensed (native) MySQL driver should not be used in a production environment. As an
alternative, the free and liberally licensed "mariaDB" (a MySQL clone) library could be used.
The dependency declaration consists of:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

91

Devonfw Guide v2.4.0


org.mariadb.jdbc
mariadb-java-client
1.5.4

And the library can be used such as MySQL but with a slight change in the configuration:

spring.datasource.driver-class-name=org.mariadb.jdbc.Driver

26.3.2. PostgreSQL
The below dependency will be added in pom for postgres database:


org.postgresql
postgresql

Ultimately, the following configuration will be added for the postgresql driver and database:
Configuration in file : src/resources/application.properties_ file

spring.application.name=myapplication
server.context-path=/
security.expose.error.details=false
security.cors.enabled=false
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.database=postgresql
spring.datasource.username=
spring.jpa.hibernate.naming.implicitstrategy=org.hibernate.boot.model.naming.ImplicitNamingStrategyJpaCompliantImpl
spring.jpa.hibernate.naming.physicalstrategy=org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl
spring.batch.job.enabled=false
flyway.locations=classpath:db/migration,classpath:db/type/postgresql
Configuration in file : src/resources/config/application.properties_ file

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

92

Devonfw Guide v2.4.0

server.port=8081
server.context-path=/
spring.datasource.url=jdbc:postgresql://localhost:5432/<>
spring.datasource.password=
spring.jackson.serialization.INDENT_OUTPUT=true
flyway.enabled=true
flyway.clean-on-validation-error=true

26.3.3. Microsoft MSSQL Server
The Microsoft JDBC drivers are not available on Maven Central; they need to be downloaded from
the Microsoft site.
Once downloaded, they should be installed in the local Maven repository (.m2 folder on the local
machine). It can be done with the following command:

mvn install:install-file -DgroupId=com.microsoft.sqlserver -DartifactId=sqljdbc4
-Dversion= -Dpackaging=jar -DgeneratePom=true -Dfile=
Once installed, the below library will be there in the project’s pom.xml file. The dependency
declaration should be something like


com.microsoft.sqlserver
mssql-jdbc
6.4.0.jre8

Ultimately, the following configuration will be added for the MSSQL server driver and database:
Configuration in file : src/resources/application.properties_ file

spring.application.name=mssqltest
server.context-path=/
security.expose.error.details=false
security.cors.enabled=false
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.database=mssql
spring.datasource.username=
spring.jpa.hibernate.naming.implicitstrategy=org.hibernate.boot.model.naming.ImplicitNamingStrategyJpaCompliantImpl
spring.jpa.hibernate.naming.physicalstrategy=org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl
spring.batch.job.enabled=false
flyway.locations=classpath:db/migration,classpath:db/type/mssql

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

93

Devonfw Guide v2.4.0

Configuration in file : src/resources/config/application.properties_ file

server.port=8081
server.context-path=/
spring.datasource.password=
spring.datasource.url=jdbc:mssql:TODO
spring.jackson.serialization.INDENT_OUTPUT=true
flyway.enabled=true
flyway.clean-on-validation-error=true
For further information see: MS SQL Server and MS JDBC Driver

26.3.4. DB2
The dependency with DB2 is explained below:


com.ibm.db2.jcc
db2jcc4
10.1


com.ibm.db2
db2jcc_license_cisuz
9.7


com.ibm.db2
db2java
9.7

And the properties are explained below:
Configuration in file : src/resources/application.properties_ file

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

94

Devonfw Guide v2.4.0

spring.application.name=db2test
server.context-path=/
security.expose.error.details=false
security.cors.enabled=false
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.database=db2
spring.datasource.username=
spring.jpa.hibernate.naming.implicitstrategy=org.hibernate.boot.model.naming.ImplicitNamingStrategyJpaCompliantImpl
spring.jpa.hibernate.naming.physicalstrategy=org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl
spring.batch.job.enabled=false
flyway.locations=classpath:db/migration,classpath:db/type/db2
Configuration in file : src/resources/config/application.properties_ file

server.port=8081
server.context-path=/
spring.datasource.password=
spring.datasource.url=jdbc:db2:TODO
spring.jackson.serialization.INDENT_OUTPUT=true
flyway.enabled=true
flyway.clean-on-validation-error=true
If you want to learn more about URL format, you can see SQLJ type 4 connectivity and SQLJ type 2
connectivity URL syntax.
NOTE

The IBM Drivers are not freely distributed, so you can’t find them in Maven. You
need to contact IBM or just find the license in required IBM software product.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

95

Devonfw Guide v2.4.0

Chapter 27. CRUD operations and DAO
implementation
27.1. Create CRUD functionality for an entity
In this tutorial, we are going to create an entity for the application and provide services for the
typical Create, Read, Update and Delete operations for that entity.
If you want to create the application from scratch:
• Launch the console.bat script.
• Go to a desired directory and use the Maven command

mvn -DarchetypeVersion=2.5.0 -DarchetypeGroupId=io.oasp.java.templates
-DarchetypeArtifactId=oasp4j-template-server archetype:generate
-DgroupId=com.capgemini.devonfw.application -DartifactId=tutorial -Dversion=0.1
-SNAPSHOT -Dpackage=devonfw.tutorial
• Open Eclipse and Import the new tutorial project as Existing Maven Project
If you want to know more about how to create a new application you can visit the Create New
Application section.
Before continue it is important to keep in mind the packaging convention that Devonfw proposes.
Devonfw uses a strict packaging convention to map technical layers and business components to
the code. Devonfw uses the following Java-Package schema:

...[.]*
In our example application we find the different classes in this packages:
• Entity and DAO: devonfw.tutorial.tablemanagement.dataaccess.api[.]
• Logic: devonfw.tutorial.tablemanagement.logic[.]
• Services: devonfw.tutorial.tablemanagement.services[.]
This convention is based on the OASP4J conventions, which you can consult in the OASP4J Coding
conventions documentation

27.1.1. Step 1: Add the database schema
As first step we are going to add the database schema to our database.
In the script resources/db/migration/V0001__Create_schema.sql we add:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

96

Devonfw Guide v2.4.0

CREATE CACHED TABLE PUBLIC.RESTAURANTTABLE(
id BIGINT NOT NULL,
modificationCounter INTEGER NOT NULL,
number BIGINT NOT NULL CHECK (NUMBER >= 0),
state INTEGER,
waiter_id BIGINT
);
And in the same path, we are going to create a new file to add the default data to the
RestaurantTable created. We create V0002__Master_data.sql file.

INSERT
1, 2);
INSERT
2, 0);
INSERT
3, 0);
INSERT
4, 0);
INSERT
5, 0);

INTO RESTAURANTTABLE (id, modificationCounter, number, state) VALUES (101, 1,
INTO RESTAURANTTABLE (id, modificationCounter, number, state) VALUES (102, 1,
INTO RESTAURANTTABLE (id, modificationCounter, number, state) VALUES (103, 1,
INTO RESTAURANTTABLE (id, modificationCounter, number, state) VALUES (104, 1,
INTO RESTAURANTTABLE (id, modificationCounter, number, state) VALUES (105, 1,

27.1.2. Step 2: Create the JPA entity
We are going to create a Table entity and its related interface (that will be reused between all the
objects involved with tables in the different layers).
This tutorial uses the same use-cases and scenario as the OASP4J sample
NOTE

application: Modelling a restaurant.
Do not confuse Table with a DB-table. In this context, we mean a table where the
guests of the restaurant are seated.

Create the devonfw.tutorial.tablemanagement.common.api package in the tutorial-server-core
project, by right-clicking on the project, and selecting New > Package.
Create the interface Table inside the devonfw.tutorial.tablemanagement.common.api package (you can
do it by right-clicking on the package and selecting New > Interface), and copy & paste the following
code:

package devonfw.tutorial.tablemanagement.common.api;
import devonfw.tutorial.general.common.api.ApplicationEntity;
import devonfw.tutorial.tablemanagement.common.api.datatype.TableState;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

97

Devonfw Guide v2.4.0

/**
* This is the interface for a table of the restaurant. It has a unique {@link
#getNumber() number} can be
* {@link TableState#isReserved() reserved}, {@link TableState#isOccupied() occupied}
and may have a
* {@link #getWaiterId() waiter} assigned.
*/
public interface Table extends ApplicationEntity {
/**
* @return the unique table number.
*/
@NotNull
@Min(0)
Long getNumber();
/**
* @param number is the new {@link #getNumber() number}.
*/
void setNumber(Long number);
/**
* @return the current {@link TableState state} of this {@link Table}.
*/
TableState getState();
/**
* @param state is the new {@link #getState() state}.
*/
void setState(TableState state);
/**
* @return the {@link
devonfw.tutorial.staffmanagement.common.api.StaffMember#getId() ID} of the waiter
*
currently responsible for this table.
*/
Long getWaiterId();
/**
* Sets the field 'waiterId'.
*
* @param waiterId New value for waiterId
*/
void setWaiterId(Long waiterId);
}

NOTE

You may have compilation errors related to TableState that is not yet implemented.
We will take care of that in the next step.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

98

Devonfw Guide v2.4.0

As you can see, Table extends ApplicationEntity class, as is recommended for standard mutable
entities of an application. This class provides the necessary methods for a mutable entity (ID getter
and setter basically).
In the above Table class, we save the state of the table by using a TableState enum, which we will
create now:
Create the package devonfw.tutorial.tablemanagement.common.api.datatype, and inside this package,
create a new class (actually an enum) called TableState and copy & paste the code below (as
mentioned before you can use the right-click option over the datatype package and select New >
Enum.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

99

Devonfw Guide v2.4.0

package devonfw.tutorial.tablemanagement.common.api.datatype;
/**
* Represents the {@link devonfw.tutorial.tablemanagement.common.api.Table#getState()
state} of a
* {@link devonfw.tutorial.tablemanagement.common.api.Table}.
*/
public enum TableState {
/** The state of a free {@link devonfw.tutorial.tablemanagement.common.api.Table}.
*/
FREE,
/** The state of a reserved {@link
devonfw.tutorial.tablemanagement.common.api.Table}. */
RESERVED,
/** The state of a occupied {@link
devonfw.tutorial.tablemanagement.common.api.Table}. */
OCCUPIED;
/**
* @return {@code true} if {@link #FREE}, {@code false} otherwise.
*/
public boolean isFree() {
return (this == FREE);
}
/**
* @return {@code true} if {@link #RESERVED}, {@code false} otherwise.
*/
public boolean isReserved() {
return (this == RESERVED);
}
/**
* @return {@code true} if {@link #OCCUPIED}, {@code false} otherwise.
*/
public boolean isOccupied() {
return (this == OCCUPIED);
}
}

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

100

Devonfw Guide v2.4.0

It is possible that Eclipse removed the import of the TableState enum in the Table
NOTE

interface, if you saved the file before creating the TableState class.
If Eclipse shows errors still, after you’ve created the TableState enum, open the
Table interface and press Ctrl-Shift-O to automatically fix the 'class' imports.

Finally,

we

should

create

the

entity

implementation.

Create

the

package

devonfw.tutorial.tablemanagement.dataaccess.api, create the class TableEntity inside it and paste
the following code:

package devonfw.tutorial.tablemanagement.dataaccess.api;
import devonfw.tutorial.general.dataaccess.api.ApplicationPersistenceEntity;
import devonfw.tutorial.tablemanagement.common.api.Table;
import devonfw.tutorial.tablemanagement.common.api.datatype.TableState;
import javax.persistence.Column;
import javax.persistence.Entity;
/**
* {@link ApplicationPersistenceEntity Entity} representing a {@link Table} of the
restaurant. A table has a unique
* {@link #getNumber() number} can be {@link TableState#isReserved() reserved}, {@link
TableState#isOccupied() occupied}
* and may have a {@link
devonfw.tutorial.staffmanagement.dataaccess.api.StaffMemberEntity waiter}
* assigned.
*/
@Entity
// Table is a reserved word in SQL/RDBMS and can not be used as table name
@javax.persistence.Table(name = "RestaurantTable")
public class TableEntity extends ApplicationPersistenceEntity implements Table {
private static final long serialVersionUID = 1L;
private Long number;
private Long waiterId;
private TableState state;
@Override
@Column(unique = true)
public Long getNumber() {
return this.number;
}
@Override
public void setNumber(Long number) {

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

101

Devonfw Guide v2.4.0

this.number = number;
}
@Override
@Column(name = "waiter_id")
public Long getWaiterId() {
return this.waiterId;
}
@Override
public void setWaiterId(Long waiterId) {
this.waiterId = waiterId;
}
@Override
public TableState getState() {
return this.state;
}
@Override
public void setState(TableState state) {
this.state = state;
}
}

Validation
We want tables to never have negative numbers, so we are going to add a validation to our
TableEntity. Change the definition of the getNumber method of the TableEntity class as follows:

@Min(0)
@Column(unique = true)
public Long getNumber() {
return this.number;
}

You may need to solve the import of the @Min annotation by right clicking over the
NOTE

annotation and selecting import javax.validation.constraints.Min. You can read more
about validation in the OASP4J guide about validation

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

102

Devonfw Guide v2.4.0

27.1.3. Step 3: Create persistence layer
Data Access Objects (DAOs) are part of the persistence layer. They are responsible for a specific
entity and should be named as Dao[Impl]. The DAO offers the so called CRUDfunctionalities (create, retrieve, update, delete) for the corresponding entity. Additionally a DAO
may offer advanced operations such as search or locking methods.
For each DAO there is an interface named Dao that defines the API. For CRUD support and
common

naming

methods

we

derive

it

from

the

interface

devonfw.tutorial.general.dataaccess.api.dao.ApplicationDao, which was automatically generated
while using the OASP4J archetype to generate your application
For the sake of simplicity, in the rest of this tutorial, we will no longer specifically
NOTE

tell you to create java packages for new java classes.
Instead, we ask you to pay attention to the first line of each new java file, and
create, if necessary, the class' package.

Create the following DAO interface for our Table entity:
Listing 1. TableDao.java

package devonfw.tutorial.tablemanagement.dataaccess.api.dao;
import devonfw.tutorial.general.dataaccess.api.dao.ApplicationDao;
import devonfw.tutorial.tablemanagement.dataaccess.api.TableEntity;
import io.oasp.module.jpa.dataaccess.api.MasterDataDao;
import java.util.List;
/**
* {@link ApplicationDao Data Access Object} for {@link TableEntity} entity.
*/
public interface TableDao extends ApplicationDao, MasterDataDao
 {
/**
* Returns a list of free restaurant tables.
*
* @return {@link List} of free restaurant {@link TableEntity}s
*/
List getFreeTables();
}

Define querys
Before we proceed to the implementation of this DAO interface, we will create the SQL query.
OASP4J advises to specify all queries in one mapping file called orm.xml located in
src/main/resources/META-INF. So we are going to create a query to return all free tables that we will

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

103

Devonfw Guide v2.4.0

use in TableDaoImpl.
Listing 2. src/main/resources/META-INF/orm.xml







To avoid redundant occurrences of the query name we are going to use a constants class where we
are going to define the constants for each named query:
Listing 3. NamedQueries.java

package devonfw.tutorial.general.common.api.constants;
/**
* Constants of the named queries defined in ``NamedQueries.xml``.
*
*/
public abstract class NamedQueries {
// put your query names from NamedQueries.xml as constants here
/** @see
devonfw.tutorial.tablemanagement.dataaccess.impl.dao.TableDaoImpl#getFreeTables() */
public static final String GET_FREE_TABLES = "get.free.tables";
}
Note that changing the name of the java constant can be done easily with refactoring (right-clicking
over the property and Refactor > Rename. Further you can trace where the query is used by
searching the references of the constant.
Implementation of DAO interface
Implementing a DAO is quite simple. We create a class named DaoImpl that extends
ApplicationMasterDataDaoImpl class and implements our DAO interface.
This is the DAO implementation for our TableDao interface:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

104

Devonfw Guide v2.4.0

Listing 4. TableDaoImpl.java

package devonfw.tutorial.tablemanagement.dataaccess.impl.dao;
import java.util.List;
import javax.inject.Named;
import javax.persistence.Query;
import
import
import
import

devonfw.tutorial.general.common.api.constants.NamedQueries;
devonfw.tutorial.general.dataaccess.base.dao.ApplicationMasterDataDaoImpl;
devonfw.tutorial.tablemanagement.dataaccess.api.TableEntity;
devonfw.tutorial.tablemanagement.dataaccess.api.dao.TableDao;

/**
* Implementation of {@link TableDao}.
*/
@Named
public class TableDaoImpl extends ApplicationMasterDataDaoImpl implements
TableDao {
/**
* The constructor.
*/
public TableDaoImpl() {
super();
}
@Override
public Class getEntityClass() {
return TableEntity.class;
}
@Override
public List getFreeTables() {
Query query = getEntityManager().createNamedQuery(NamedQueries.GET_FREE_TABLES,
TableEntity.class);
return query.getResultList();
}
}
As you can see ApplicationMasterDataDaoImpl already implements the CRUD operations so you
only have to implement the additional methods that you have declared in your Dao
interface.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

105

Devonfw Guide v2.4.0

27.1.4. Step 4: Business logic
The business logic of our application is defined in the logic layer, as proposed by the OASP4J Guide.
The logic layer also maps entities from the dataaccess layer to/from transfer objects, so we do not
expose internal details of the applications implementation to higher layers.
In Devonfw applications, there are several different types of Transfer Objects (short TO). One is the
Entity Transfer Object (ETO) used to transfer a representation of an Entity.
As a first step, we will define an ETO for the Table entity, to be used in the interface of our logic
layer.
Create the following file:
Listing 5. TableEto.java

package devonfw.tutorial.tablemanagement.logic.api.to;
import devonfw.tutorial.general.common.api.to.AbstractEto;
import devonfw.tutorial.tablemanagement.common.api.Table;
import devonfw.tutorial.tablemanagement.common.api.datatype.TableState;
import javax.validation.constraints.Max;
/**
* {@link AbstractEto ETO} for {@link Table}.
*/
public class TableEto extends AbstractEto implements Table {
private static final long serialVersionUID = 1L;
private Long waiterId;
@Max(value = 1000)
private Long number;
private TableState state;
/**
* The constructor.
*/
public TableEto() {
super();
}
@Override
public Long getNumber() {
return this.number;

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

106

Devonfw Guide v2.4.0

}
@Override
public void setNumber(Long number) {
this.number = number;
}
@Override
public Long getWaiterId() {
return this.waiterId;
}
@Override
public void setWaiterId(Long waiterId) {
this.waiterId = waiterId;
}
@Override
public TableState getState() {
return this.state;
}
@Override
public void setState(TableState state) {
this.state = state;
}
@Override
public int hashCode() {
final int prime = 31;
int result = super.hashCode();
result = prime * result + ((this.state == null) ? 0 : this.state.hashCode());
result = prime * result + ((this.waiterId == null) ? 0 : this.waiterId.
hashCode());
return result;
}
@Override
public boolean equals(Object obj) {
if (this == obj) {
return true;
}
if (obj == null) {
return false;

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

107

Devonfw Guide v2.4.0

}
if (getClass() != obj.getClass()) {
return false;
}
if (!super.equals(obj)) {
return false;
}
TableEto other = (TableEto) obj;
if (this.state != other.state) {
return false;
}
if (this.waiterId == null) {
if (other.waiterId != null) {
return false;
}
} else if (!this.waiterId.equals(other.waiterId)) {
return false;
}
return true;
}
}
In Devonfw, we define CRUD logic into a management class. So we are going to create our
Tablemanagement interface and implementation:
Listing 6. Tablemanagement.java

package devonfw.tutorial.tablemanagement.logic.api;
import devonfw.tutorial.tablemanagement.logic.api.to.TableEto;
import java.util.List;
import javax.validation.Valid;
/**
* Interface for TableManagement component.
*
*/
public interface Tablemanagement {
/**
* Returns a restaurant table by its id 'id'.
*
* @param id The id 'id' of the restaurant table.
* @return The restaurant {@link TableEto} with id 'id'
*/
TableEto findTable(Long id);
/**
* Returns a list of all existing restaurant tables.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

108

Devonfw Guide v2.4.0

*
* @return {@link List} of all existing restaurant {@link TableEto}s
*/
List findAllTables();
/**
* Returns a list of all existing free restaurant tables.
*
* @return {@link List} of all existing free restaurant {@link TableEto}s
*/
List findFreeTables();
/**
* Deletes a restaurant table from the database by its id 'id'.
*
* @param tableId Id of the restaurant table to delete
*/
void deleteTable(Long tableId);
/**
* Creates a new restaurant table and store it in the database.
*
* @param table the {@link TableEto} to create.
* @return the new {@link TableEto} that has been saved with ID and version.
*/
TableEto saveTable(@Valid TableEto table);
}
Listing 7. TablemanagementImpl.java

package devonfw.tutorial.tablemanagement.logic.impl;
import
import
import
import
import
import
import
import

devonfw.tutorial.general.common.api.constants.PermissionConstants;
devonfw.tutorial.general.common.api.exception.IllegalEntityStateException;
devonfw.tutorial.general.logic.base.AbstractComponentFacade;
devonfw.tutorial.tablemanagement.common.api.datatype.TableState;
devonfw.tutorial.tablemanagement.dataaccess.api.TableEntity;
devonfw.tutorial.tablemanagement.dataaccess.api.dao.TableDao;
devonfw.tutorial.tablemanagement.logic.api.Tablemanagement;
devonfw.tutorial.tablemanagement.logic.api.to.TableEto;

import java.util.List;
import java.util.Objects;
import
import
import
import

javax.annotation.security.RolesAllowed;
javax.inject.Inject;
javax.inject.Named;
javax.validation.Valid;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

109

Devonfw Guide v2.4.0

/**
* Implementation of {@link Tablemanagement}.
*/
@Named
public class TablemanagementImpl extends AbstractComponentFacade implements
Tablemanagement {
/** Logger instance. */
private static final Logger LOG = LoggerFactory.getLogger(TablemanagementImpl.
class);
/** @see #getTableDao() */
private TableDao tableDao;
/**
* The constructor.
*/
public TablemanagementImpl() {
super();
}
@Override
@RolesAllowed(PermissionConstants.FIND_TABLE)
public TableEto findTable(Long id) {
LOG.debug("Get table with id '" + id + "' from database.");
return getBeanMapper().map(getTableDao().findOne(id), TableEto.class);
}
@Override
@RolesAllowed(PermissionConstants.FIND_TABLE)
public List findAllTables() {
LOG.debug("Get all restaurant tables from database.");
List tables = getTableDao().findAll();
return getBeanMapper().mapList(tables, TableEto.class);
}
@Override
@RolesAllowed(PermissionConstants.FIND_TABLE)
public List findFreeTables() {
LOG.debug("Get all free restaurant tables from database.");
List tables = getTableDao().getFreeTables();
return getBeanMapper().mapList(tables, TableEto.class);
}
@Override
@RolesAllowed(PermissionConstants.DELETE_TABLE)

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

110

Devonfw Guide v2.4.0

public void deleteTable(Long tableId) {
TableEntity table = getTableDao().find(tableId);
if (!table.getState().isFree()) {
throw new IllegalEntityStateException(table, table.getState());
}
getTableDao().delete(table);
}
@Override
@RolesAllowed(PermissionConstants.SAVE_TABLE)
public TableEto saveTable(@Valid TableEto table) {
Objects.requireNonNull(table, "table");
TableEntity tableEntity = getBeanMapper().map(table, TableEntity.class);
// initialize
if (tableEntity.getState() == null) {
tableEntity.setState(TableState.FREE);
}
getTableDao().save(tableEntity);
LOG.debug("Table with id '{}' has been created.", tableEntity.getId());
return getBeanMapper().map(tableEntity, TableEto.class);
}
/**
* @return the {@link TableDao} instance.
*/
public TableDao getTableDao() {
return this.tableDao;
}
/**
* @param tableDao the {@link TableDao} to {@link Inject}.
*/
@Inject
public void setTableDao(TableDao tableDao) {
this.tableDao = tableDao;
}
}

NOTE

You may have problems with the PermissionConstants properties because are not
implemented yet. We will do that in the next step.

At this point we have defined all the necessary classes in the logic layer, so we have our API ready,

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

111

Devonfw Guide v2.4.0

with the exception of finishing its security aspect.
Secure the application
OASP4J proposes role-based authorization to cope with the authorization of executing use cases of
an application. OASP4J use the JSR250 annotations, mainly @RolesAllowed, as you have seen, for
authorizing method calls against the permissions defined in the annotation body.
So, finally, we have to create a class to declare the actual roles we use as values for the
@RolesAllowed annotation:

package devonfw.tutorial.general.common.api.constants;
/**
* Contains constants for the keys of all
* {@link io.oasp.module.security.common.api.accesscontrol.AccessControlPermission}s.
*
*/
public abstract class PermissionConstants {
/** {@link io.oasp.module.security.common.api.accesscontrol.AccessControlPermission}
to retrieve table. */
public static final String FIND_TABLE = "FindTable";
/** {@link io.oasp.module.security.common.api.accesscontrol.AccessControlPermission}
to save table. */
public static final String SAVE_TABLE = "SaveTable";
/** {@link io.oasp.module.security.common.api.accesscontrol.AccessControlPermission}
to remove table. */
public static final String DELETE_TABLE = "DeleteTable";
}

27.1.5. Step 5: Create REST endpoints
Web applications need to get data from the server, so we have to expose the methods defined in the
logic layer to these applications. We need a class that exposes methods as URLs to allow the
applications to get the data. By convention, we call this class managementRestServiceImpl.
This is an example of a REST API for our Table use case using JAX-RS.
Also note that the implementation does not follow the dogmatic RESTFUL approach as Devonfw
proposes a more pragmatic way to use REST. Please refer to the guide Creating Rest Service for
more information on the subject.
Listing 8. TablemanagementRestServiceImpl.java

package devonfw.tutorial.tablemanagement.service.impl.rest;
import java.util.List;

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

112

Devonfw Guide v2.4.0

import
import
import
import
import
import
import
import
import
import
import
import

javax.inject.Inject;
javax.inject.Named;
javax.ws.rs.BadRequestException;
javax.ws.rs.Consumes;
javax.ws.rs.DELETE;
javax.ws.rs.GET;
javax.ws.rs.NotFoundException;
javax.ws.rs.POST;
javax.ws.rs.Path;
javax.ws.rs.PathParam;
javax.ws.rs.Produces;
javax.ws.rs.core.MediaType;

import org.springframework.transaction.annotation.Transactional;
import devonfw.tutorial.tablemanagement.logic.api.Tablemanagement;
import devonfw.tutorial.tablemanagement.logic.api.to.TableEto;
/**
*
* The service class for REST calls in order to execute the methods in {@link
Tablemanagement}.
*/
@Path("/tablemanagement/v1") ②
@Named("TablemanagementRestService")
@Consumes(MediaType.APPLICATION_JSON) ①
@Produces(MediaType.APPLICATION_JSON)
@Transactional
public class TablemanagementRestServiceImpl {
private Tablemanagement tableManagement;
/**
*
* This method sets the field tableManagement.
*
*
*
* @param tableManagement the new value of the field tableManagement
*/
@Inject
public void setTableManagement(Tablemanagement tableManagement) {
this.tableManagement = tableManagement;
}
/**

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

113

Devonfw Guide v2.4.0

*
* Delegates to {@link Tablemanagement#findTable}.
*
*
*
* @param id the ID of the {@link TableEto}
*
* @return the {@link TableEto}
*/
@GET
@Path("/table/{id}/")
public TableEto getTable(@PathParam("id") String id) {
Long idAsLong;
if (id == null) {
throw new BadRequestException("missing id");
}
try {
idAsLong = Long.parseLong(id);
} catch (NumberFormatException e) {
throw new BadRequestException("id is not a number");
} catch (NotFoundException e) {
throw new BadRequestException("table not found");
}
return this.tableManagement.findTable(idAsLong);
}
/**
*
* Delegates to {@link Tablemanagement#findAllTables}.
*
*
*
* @return list of all existing restaurant {@link TableEto}s
*/
@GET
@Path("/table/")

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

114

Devonfw Guide v2.4.0

public List getAllTables() {
List allTables = this.tableManagement.findAllTables();
return allTables;
}
/**
*
* Delegates to {@link Tablemanagement#findFreeTables}.
*
*
*
* @return list of all existing free {@link TableEto}s
*/
@GET
@Path("/freetables/")
public List getFreeTables() {
return this.tableManagement.findFreeTables();
}
/**
*
* Delegates to {@link Tablemanagement#saveTable}.
*
*
*
* @param table the {@link TableEto} to be created
*
* @return the recently created {@link TableEto}
*/
@POST
@Path("/table/")
public TableEto saveTable(TableEto table) {
return this.tableManagement.saveTable(table);
}
/**
*
* Delegates to {@link Tablemanagement#deleteTable}.
*
*
*
* @param id ID of the {@link TableEto} to be deleted

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

115

Devonfw Guide v2.4.0

*/
@DELETE
@Path("/table/{id}/")
public void deleteTable(@PathParam("id") Long id) {
this.tableManagement.deleteTable(id);
}
}
① We send and receive the information in JSON format.
② We specify the version of the entire API inside its path.
As you can see, we have defined the REST URLs for our Table user case. Now, for example, you can
find all tables on this URL:

http://:/application-name/services/rest/tablemanagement/v1/table/

DTO conversion
In the logic API, the methods of the classes should return Data Transfer Object (DTO) instead of
entities. So, in OASP4J we have a mechanism to convert the entities into DTOs.
This is an example of how to convert an entity into a DTO:

// Conversion for lists
getBeanMapper().mapList(tableList, TableDto.class);
// Conversion for objects
getBeanMapper().map(table, TableDto.class);
In the example, we use the function getBeanMapper(). This function provides us an API to convert
entities into DTOs. In the logic layer, we only have to extend the class AbstractComponentFacade to get
access to this functionality.

27.1.6. Step 6: Add pagination
To add pagination support to our Table CRUD, the first step is creating a new Table TO that extends
the SearchCriteriaTo class. This class forms the foundation for every request which needs search or
pagination functionality.
Listing 9. TableSearchCriteriaTo.java

package devonfw.tutorial.tablemanagement.logic.api.to;
import io.oasp.module.jpa.common.api.to.SearchCriteriaTo;

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

116

Devonfw Guide v2.4.0

import devonfw.tutorial.tablemanagement.common.api.datatype.TableState;
/**
*
* This is the {@link SearchCriteriaTo search criteria} {@link
net.sf.mmm.util.transferobject.api.TransferObject TO}
*/
public class TableSearchCriteriaTo extends SearchCriteriaTo {
/** UID for serialization. */
private static final long serialVersionUID = 1L;
private Long waiterId;
private Long number;
private TableState state;
/**
*
* The constructor.
*/
public TableSearchCriteriaTo() {
super();
}
/**
*
* @return waiterId
*/
public Long getWaiterId() {
return this.waiterId;
}
/**
*
* @param waiterId the waiterId to set
*/
public void setWaiterId(Long waiterId) {
this.waiterId = waiterId;

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

117

Devonfw Guide v2.4.0

}
/**
*
* @return state
*/
public TableState getState() {
return this.state;
}
/**
*
* @param state the state to set
*/
public void setState(TableState state) {
this.state = state;
}
/**
*
* @return number
*/
public Long getNumber() {
return this.number;
}
/**
*
* @param number the number to set
*/
public void setNumber(Long number) {
this.number = number;
}
}
Now we will create a new POST REST endpoint (pagination request have to be POST) in our

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

118

Devonfw Guide v2.4.0

TablemanagementRestServiceImpl class.

/**
* Delegates to {@link Tablemanagement#findTableEtos}.
*
* @param searchCriteriaTo the pagination and search criteria to be used for finding
tables.
* @return the {@link PaginatedListTo list} of matching {@link TableEto}s.
*/
@Path("/table/search")
@POST
public PaginatedListTo findTablesByPost(TableSearchCriteriaTo
searchCriteriaTo) {
return this.tableManagement.findTableEtos(searchCriteriaTo);
}

NOTE

Make sure to press Ctrl-Shift-O after inserting this new method, to make Eclipse
auto-import the dependencies of PaginatedListTo and TableSearchCriteriaTo.

Consequently we have to declare this new method findTableEtos in the table management classes
in our logic layer:
Listing 10. Tablemanagement.java

/**
* Returns a list of restaurant tables matching the search criteria.
*
* @param criteria the {@link TableSearchCriteriaTo}.
* @return the {@link List} of matching {@link TableEto}s.
*/
PaginatedListTo findTableEtos(TableSearchCriteriaTo criteria);
Listing 11. TablemanagementImpl.java

@Override
public PaginatedListTo findTableEtos(TableSearchCriteriaTo criteria) {
criteria.limitMaximumPageSize(MAXIMUM_HIT_LIMIT); ①
PaginatedListTo tables = getTableDao().findTables(criteria);
return mapPaginatedEntityList(tables, TableEto.class);
}
① As you can see, we have limited the maximum results per page to prevent clients from
requesting pages with too big a size.
And finally, we have to define our pagination method in our DAO class.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

119

Devonfw Guide v2.4.0

Listing 12. TableDao.java

/**
* Finds the {@link TableEntity orders} matching the given {@link
TableSearchCriteriaTo}.
*
* @param criteria is the {@link TableSearchCriteriaTo}.
* @return the {@link List} with the matching {@link TableEntity} objects.
*/
PaginatedListTo findTables(TableSearchCriteriaTo criteria);
Listing 13. TableDaoImpl.java

@Override
public PaginatedListTo findTables(TableSearchCriteriaTo criteria) {
TableEntity table = Alias.alias(TableEntity.class);
EntityPathBase alias = Alias.$(table);
JPAQuery query = new JPAQuery(getEntityManager()).from(alias);
Long waiterId = criteria.getWaiterId();
if (waiterId != null) {
query.where(Alias.$(table.getWaiterId()).eq(waiterId));
}
Long number = criteria.getNumber();
if (number != null) {
query.where(Alias.$(table.getNumber()).eq(number));
}
TableState state = criteria.getState();
if (state != null) {
query.where(Alias.$(table.getState()).eq(state));
}
return findPaginated(criteria, query, alias);
}

NOTE

While auto-completing the new imports using Ctrl-Shift-O after adding the above
methods, select com.mysema.query.alias as the import for the Alias class.

In this case, we have used QueryDSL to create the query. You can read more about QueryDSL at
www.querydsl.com.

27.1.7. Step 7: Sort the results
In OASP4J exists a special TO (Transfer Object) called ´OrderByTo` to transmit sorting parameters
from client to server. This is the JSON format that the server expects when using this TO:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

120

Devonfw Guide v2.4.0

{
sort: [
{
name:"sortingCriteria1",
direction:"ASC"
},
{
name:"sortingCriteria2",
direction:"DESC"
},
...
]
}
Devonfw proposes to use POST as the HTTP method for endpoints implementing search or
pagination support.
By default, in Devonfw, SearchCriteriaTo class is already embedding this sorting TO, so we only
need to manage sorting in TableDaoImpl.java because our pagination method does not need any
modification.
If our method needs sorting but not pagination we need to manually add to our own transfer object
the following variable (and its setter and getter methods):

private List sort;
We are going to modify the method findTables in our TableDaoImpl. Insert the following line right
before the final return statement:

// Add order by fields
addOrderBy(query, alias, table, criteria.getSort());
Now add the following method to TableDaoImpl:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

121

Devonfw Guide v2.4.0

private void addOrderBy(JPAQuery query, EntityPathBase alias,
TableEntity table, List sort) {
if (sort != null && !sort.isEmpty()) {
for (OrderByTo orderEntry : sort) {
if ("number".equals(orderEntry.getName())) {
if (OrderDirection.ASC.equals(orderEntry.getDirection())) {
query.orderBy(Alias.$(table.getNumber()).asc());
} else {
query.orderBy(Alias.$(table.getNumber()).desc());
}
} else if ("waiterId".equals(orderEntry.getName())) {
if (OrderDirection.ASC.equals(orderEntry.getDirection())) {
query.orderBy(Alias.$(table.getWaiterId()).asc());
} else {
query.orderBy(Alias.$(table.getWaiterId()).desc());
}
} else if ("state".equals(orderEntry.getName())) {
if (OrderDirection.ASC.equals(orderEntry.getDirection())) {
query.orderBy(Alias.$(table.getState()).asc());
} else {
query.orderBy(Alias.$(table.getState()).desc());
}
}
}
}
}
As you can see, we have added a private method to add sorting filter to our query depending on the
sort parameters received.

27.1.8. Step 8: Test the example
In order to test the example we are going to use the user chief to obtain the tables. To be able to
access to that data we need first to grant permissions to the chief user. We can do it specifying the
role

and

the

permissions

in

the

access-control-schema.xml

file

located

in

src/main/resources/config/app/security/.







This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

122

Devonfw Guide v2.4.0

Now if we run the application we can access to the tables data with the URL

http:////services/rest/tablemanagement/v1/table/
And, after logging as chief, the server response should be:

[{"id":101,"modificationCounter":1,"revision":null,"waiterId":null,"number":1,"state":
"OCCUPIED"},{"id":102,"modificationCounter":1,"revision":null,"waiterId":null,"number"
:2,"state":"FREE"},{"id":103,"modificationCounter":1,"revision":null,"waiterId":null,"
number":3,"state":"FREE"},{"id":104,"modificationCounter":1,"revision":null,"waiterId"
:null,"number":4,"state":"FREE"},{"id":105,"modificationCounter":1,"revision":null,"wa
iterId":null,"number":5,"state":"FREE"}]

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

123

Devonfw Guide v2.4.0

Chapter 28. Bean-Mapping using Dozer
28.1. Why use Bean-Mapping
A mapping framework is useful in a layered architecture, where you can create layers of
abstraction by encapsulating changes to particular data objects vs. propagating these objects to
other layers (i.e. External service data objects, domain objects, data transfer objects, internal
service data objects). A mapping framework is an ideal and can be used within Mapper type classes
that are responsible for mapping data from one data object to another.
The challenge in distributed systems is passing the domain objects between different systems.
Typically, you don’t want internal domain objects to be exposed to the outside world and not allow
external domain objects to bleed into your system.
Mapping between the data objects has been traditionally addressed by hand coding value object
assemblers (or converters) that copy data between the objects. Most programmers will develop
some sort of custom mapping framework and spend countless hours and thousands of lines of code
mapping to and from their different data object.
A generic mapping framework solves these problems. Dozer (which is configured and used in
Devonfw) is an open source mapping framework that is robust, generic, flexible, reusable, and
configurable.
Typically, Dozer works as shown below:

For decoupling, you sometimes need to create separate objects (beans) for a different view. For
example, for an external service, you will use a transfer-object instead of the persistence entity, so
internal changes to the entity do not implicitly change or break the service.
Therefore, you have the need to map similar objects which creates a copy. This is advantageous as
the modifications to the copy has no side-effect on the original source object. However, to

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

124

Devonfw Guide v2.4.0

implement such mapping code by hand is very tedious and error-prone as shown below (if new
properties are added to beans but not to mapping code):

public PersonTo mapPerson(PersonEntity source) {
PersonTo target = new PersonTo();
target.setFirstName(source.getFirstName());
target.setLastName(source.getLastName());
...
return target;
}
Therefore, BeanMapper is used for this purpose, which indirectly makes this task a lot easier.

28.2. Bean-Mapper Dependency
To get access to the BeanMapper, you can use this dependency in your pom.xml file:


io.oasp.java
oasp4j-beanmapping

So, (oasp4j-beanmapping) uses Dozer as dependency in its pom.xml file as shown below:

28.3. Bean-Mapper Usage
Then, you can get the BeanMapper via dependency-injection which is typically provided by an
abstract base class (e.g. AbstractUc). Now, your problem can be solved easily:

PersonEntity person = ...;
...
return getBeanMapper().map(person, PersonTo.class);

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

125

Devonfw Guide v2.4.0

So, in the above piece of code, getBeanMapper() method provides an mapper (dozer) instance , and
when map() method is called, it maps PersonEntity (source object) to PersonTo(DEstination object).
Additionally, it supports the mapping of entire collections.
Dozer has been configured as a Spring bean in Devonfw, using dependency injection. This is done
in BeanDozerConfiguration.java which is present in resources/common/configuration folder of xxxcore project, created using oasp4j template server archetype.
In this class, you can give path of mapping file (dozer-mapping.xml), which is generally placed at
config/app/common/dozer-mapping.xml.
For more information on dozer, refer here.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

126

Devonfw Guide v2.4.0

Chapter 29. Write Unit Test Cases
29.1. Unit Test
In computer programming, unit testing is a software testing method by which individual units of
source code, sets of one or more computer program modules together with associated control data,
usage procedures, and operating procedures, are tested to determine whether they are fit for the
use. Intuitively, one can view a unit as the smallest testable part of an application. For more
information, visit wikipedia.

29.1.1. Unit Test in Eclipse
In order to understand how the Unit Tests works in Eclipse, lets discuss how to create and run a
simple test.
Step 1: Create a new class
Create a class with the name MyClass.java (you can create a new application as per need). In
Eclipse, right click on the package in the application and then select New > Class. Name it MyClass
and press Finish.
Step 2: Create a JUnit test
In Project Explorer, over the new MyClass.java class, then right click and go to New > Other > and
select JUnit Test Case. Name it MyClassTest (name by default) and select source folder and package
in the application to create the test. e.g. src/test/java (this is a good practice).
Step 3: Implement the test
Fist of all, check the dependencies of the module in pom.xml file.


io.oasp.java.modules
oasp4j-test
test

In a OASP4J project, you have your own Component Test methods, so you need your new JUnit Test
class to extend AbstractComponentTest class of the OASP4J module test.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

127

Devonfw Guide v2.4.0

@SpringBootTest(classes = { SpringBootApp.class })
public class MyClassTest extends AbstractComponentTest {
@Test
public void test() {
assertThat(false).isTrue();
}
}
This is a very simple test that verifies if the boolean value true is true. And is the case to start
testing OASP4J application. As you can imagine that the test is going to fail, but you will see the
details in later part.
You are including the @SpringBootTest annotation in order to define an application
context to your test. Without the context of the application, the test gets a fatal
error, because you can’t test a non-running application.
NOTE

You can include a configuration location in the last annotation, if you need it, or use
@ContextConfiguration(locations = { "classpath:my-bean-context.xml" }). For this
tutorial, it’s unnecessary because your test is the most simplest test you can
perform.

Step 4: Run the test
Eclipse provides a very helpful view to test the applications. If you can’t see, press the menu:
Windows > Show View > Other and select JUnit.
Now, over the test, press right click Run As > JUnit test

In the above image, Eclipse shows a red rectangle because one of the tests has been failed (in this
case, a single test). The failure of the test is marked with a blue cross but you can observe three
different marks:
• Red cross: the test has some fatal error as, e.g context error, null pointer exceptions, etc.
• Blue cross: the test fails in some test method like asserThan() (like your case)
• Green check: the test is OK
In above case, you have a simple failure because your test has a assertThat(false).isTrue()
meaning check if true == false. Now, let’s discuss how to fix the failure and run the test again.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

128

Devonfw Guide v2.4.0

@SpringBootTest(classes = { SpringBootApp.class })
public class MyClassTest extends AbstractComponentTest {
@Test
public void test() {
assertThat(true).isTrue();
}
}
Now, you need to run the test again. And you will get the next result as shown in below image.

Evidently, the test ends successfully and Eclipse shows a green rectangle and the test with a green
check.
With the discussed knowledge base, you can start testing all the applications.

29.2. TDD Test-driven development
Test-driven development (TDD) is a software development process that relies on the repetition of a
very short development cycle: first the developer writes an (initially failing) automated test case
that defines a desired improvement or new function, then produces the minimum amount of code
to pass that test, and finally refactors the new code to acceptable standards.
The process of TDD is described as follows:
• Create a test
• Run all the tests
• Write the implementation code
• Run all the tests
• Refactor

29.2.1. TDD in Eclipse
Now, you are acquainted with the skills of creating, writing and running the test. Therefore, you
can start with a simple tutorial in order to get the most clear idea about TDD.
The goal is create a simple calculator that has two methods: add(int,int) and sub(int,int).

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

129

Devonfw Guide v2.4.0

Step 1: Create a test
The idea is very simple, you will create the tests for the methods of a class that needs to be
implemented later. It will allow you to get the control of the result and verify that the code is
working properly from the beginning.
You need to create a test called CalculatorTest in test package and a class Calculator in the java
package.
In this test class, you will include a variable of a class Calculator and the test to the future add() and
sub() methods of Calculator class.
Calculator.java

public class Calculator {
public Calculator() {}
public Object add(int a, int b) {
return null;
}
public Object sub(int a, int b) {
return null;
}
}
Thus, you have the wire of your calculator. In this case, the implementation is very simple, but you
can scale it to a more complex logic. Now, you need to include the test data required to run the class
CalculatorTest.
CalculatorTest.java

@SpringBootTest(classes = { SpringBootApp.class })
public class CalculatorTest extends AbstractComponentTest {
private Calculator calculator = new Calculator();
@Test
public void addTest() {
assertThat(this.calculator.add(1, 2)).isEqualTo(3);
}
@Test
public void subTest() {
assertThat(this.calculator.sub(1, 2)).isEqualTo(-1);
}
}

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

130

Devonfw Guide v2.4.0

Step 2: Run the test new test
Run the test and the result is as shown below:

Obviously, the test shows some failures as expected because the Calculator doesn’t work yet.
The fact, this is more of a metaphoric step, as the implementation is in progress and it is obvious to
get errors after running the test. As it is the cycle of the TDD, you need to write a test that will fail
certainly so that the code to satisfy the test can be written. Surely, this will help to keep the code
simple and clean.
Methods named add() and sub(), returns Object as return value because if the
NOTE

methods

return

an

int,

you

will

get

a

"red

cross

error"

pointing

NullPointerException instead of "blue cross error" of assetThat(). It’s just for this
tutorial.

Step 3: Write the implementation code
So far, you have seen a perfect test and an awful implementation of the Calculator. Let’s start with
the implementation.
Let’s implement the method add() and see what happens.

public class Calculator {
public Calculator() {}
public int add(int a, int b) {
return a + b;
}
public Object sub(int a, int b) {
return null;
}
}

Step 4: Run the test -againIf you run the test, you will get the following result:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

131

Devonfw Guide v2.4.0

Now, you have a success result for the method add() and a failure result for the method sub().
Clearly, it’s not necessary to get all the tests results as OK to run the tests, you can check the result of
the test and work on to satisfy it. This the idea of TDD.
Step 5: Refactor
Now, let’s implement the method sub()

public class Calculator {
public Calculator() {}
public int add(int a, int b) {
return a + b;
}
public int sub(int a, int b) {
return a - b;
}
}

Step 6: Run the test -return to step 2If you run the application, you will get the following result:

Finally, here is your first application implemented with TDD methodology!
Therefore, in this tutorial, you have dealt with a very simple application, so you don’t need another
round of the TDD cycle, but in the real applications, you may need to repeat the cycle several times
to get a successful result.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

132

Devonfw Guide v2.4.0

Chapter 30. Logging and Auditing
30.1. Logging
We use SLF4J as API for logging. The recommended implementation is Logback for which we
provide additional value such as configuration templates and an appender that prevents logforging and reformatting of stack-traces for operational optimizations.

30.1.1. Usage
Maven Integration
In the pom.xml of your application add this dependency (that also adds transitive dependencies to
SLF4J and logback):


io.oasp.java.modules
oasp4j-logging
2.5.0


Configuration
The configuration file is logback.xml and is to put in the directory src/main/resources of your main
application. For details consult the logback configuration manual. OASP4J provides a production
ready configuration here. Simply copy this configuration into your application in order to benefit
from the provided operational and [security] aspects. We do not include the configuration into the
oasp4j-logging module to give you the freedom of customizations (e.g. tune log levels for
components and integrated products and libraries of your application).
The provided logback.xml is configured to use variables defined on the config/application.properties
file. On our example, the log files path point to ../logs/ in order to log to tomcat log directory when
starting tomcat on the bin folder. Change it according to your custom needs.
Listing 14. config/application.properties

log.dir=../logs/

Logger Access
The general pattern for accessing loggers from your code is a static logger instance per class. We
pre-configured the development environment so you can just type LOG and hit [ctrl][space] (and
then [arrow up]) to insert the code pattern line into your class:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

133

Devonfw Guide v2.4.0

public class MyClass {
private static final Logger LOG = LoggerFactory.getLogger(MyClass.class);
...
}
Please note that in this case we are not using injection pattern but use the convenient static
alternative. This is already a common solution and also has performance benefits.
How to log
We use a common understanding of the log-levels as illustrated by the following table. This helps
for better maintenance and operation of the systems by combining both views.
Table 1. Loglevels

Loglevel

Description

Impact

FATAL

Only used for fatal
Operator has to react
errors that prevent the immediately
application to work at
all (e.g. startup fails or
shutdown/restart
required)

all

ERROR

An abnormal error
indicating that the
processing failed due to
technical problems.

Operator should check
for known issue and
otherwise inform
development

all

WARNING

A situation where
something worked not
as expected. E.g. a
business exception or
user validation failure
occurred.

No direct reaction
required. Used for
problem analysis.

all

INFO

Important information No direct reaction
such as context,
required. Used for
duration,
analysis.
success/failure of
request or process

all

DEBUG

Development
information that
provides additional
context for debugging
problems.

development and
testing

TRACE

Like DEBUG but
No direct reaction
exhaustive information required. Used for
and for code that is run problem analysis.
very frequently. Will
typically cause large
log-files.

No direct reaction
required. Used for
analysis.

Active Environments

none (turned off by
default)

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

134

Devonfw Guide v2.4.0

Exceptions (with their stacktrace) should only be logged on FATAL or ERROR level. For business
exceptions typically a WARNING including the message of the exception is sufficient.

30.1.2. Operations
Log Files
We always use the following log files:
• Error Log: Includes log entries to detect errors.
• Info Log: Used to analyze system status and to detect bottlenecks.
• Debug Log: Detailed information for error detection.
The log file name pattern is as follows:

_log___.log
Table 2. Segments of Logfilename

Element

Value

Description



info, error, debug

Type of log file



e.g. mywebserver01

Name of server, where logs are
generated



e.g. myapp

Name of application, which
causes logs



YYYY-MM-DD_HH00

date of log file

Example: error_log_mywebserver01_myapp_2013-09-16_0900.log
Error log from mywebserver01 at application myapp at 16th September 2013 9pm.
Output format
We use the following output format for all log entries to ensure that searching and filtering of log
entries work consistent for all logfiles:

[D: ] [P: ] [C: ][T: ][L: ][M: ]
• D: Date ( ISO8601: 2013-09-05 16:40:36,464)
• P: Priority (the log level)
• C: Correlation ID (ID to identify users across multiple systems, needed when application is
distributed)
• T: Thread (Name of thread)
• L: Logger name (use class name)

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

135

Devonfw Guide v2.4.0

• M: Message (log message)
Example:

[D: 2013-09-05 16:40:36,464] [P: DEBUG] [C: 12345] [T: main] [L: my.package.MyClass][M: My message...]

30.1.3. Logging and Auditing Security
In order to prevent log forging attacks we provide a special appender for logback in oasp4j-logging.
If you use it (see [configuration]) you are safe from such attacks.

30.1.4. Correlating separate requests
In order to correlate separate HTTP requests to services belonging to the same user / session, we
provide a servlet filter called "DiagnosticContextFilter". This filter first searches for a configurable
HTTP header containing a correlation id. If none was found, it will generate a new correlation id.
By default the HTTP header used is called "CorrelationId".

30.2. Auditing with Hibernate Envers
For database auditing we use hibernate envers. If you want to use auditing ensure you have the
following dependency in your pom.xml file:


io.oasp.java.modules
oasp4j-jpa-envers

Make sure that entity manager (configured in beans-jpa.xml) also scans the package from the
oasp4j-jpa[-envers] module in order to work properly.

...


io.oasp.module.jpa.dataaccess.api
...

Now let your DAO implementation extend from AbstractRevisionedDao instead of AbstractDao and
your DAO interface extend from [Application]RevisionedDao instead of [Application]Dao.
The DAO now has a method getRevisionHistory(entity) available to get a list of revisions for a given
entity and a method load(id, revision) to load a specific revision of an entity with the given ID.
To enable auditing for a entity simply place the @Audited annotation to your entity and all entity

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

136

Devonfw Guide v2.4.0

classes it extends from.

@Entity(name = "Drink")
@Audited
public class DrinkEntity extends ProductEntity implements Drink {
...
When auditing is enabled for an entity an additional database table is used to store all changes to
the entity table and a corresponding revision number. This table is called _AUD
per default. Another table called REVINFO is used to store all revisions. Make sure that these tables
are available. They can be generated by Hibernate with the following property (only for
development environments).

database.hibernate.hbm2ddl.auto=create
Another possibility is to put them in your database migration scripts like so.

CREATE CACHED TABLE PUBLIC.REVINFO(
id BIGINT NOT NULL generated by default as identity (start with 1),
timestamp BIGINT NOT NULL,
user VARCHAR(255)
);
...
CREATE CACHED TABLE PUBLIC._AUD(
,
revtype TINYINT,
rev BIGINT NOT NULL
);

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

137

Devonfw Guide v2.4.0

Chapter 31. Getting Started Cobigen
In Devonfw we have a server-side code generator called Cobigen. Cobigen is capable to create CRUD
code from an entity or generate the content of the class that defines the user permissions. Cobigen
is distributed in the Devonfw distribution as an Eclipse plugin, and is available to all Devonfw
developers.
If you want to go deeper in Cobigen you can visit the documentation of the Cobigen core.

31.1. Preparing Cobigen for first use
Before you can use Cobigen, you have to install the templates to be used by Cobigen. The Devonfw
distribution

comes

with

a

set

of

default

templates

in

the

directory

workspaces\main\CobiGen_Templates.
1. Open Eclipse by executing the batch file eclipse-main.bat
2. Select "File - Import"
3. Select "General - Existing projects into workspace"
4. Select the directory workspaces\main\CobiGen_Templates
5. Finish the import.
NOTE

In your own projects, you can create additional templates. Please refer to the
document CobiGen.pdf for further information.

31.2. Creating a CRUD with Cobigen
In an earlier chapter about CRUD functionality you saw the individual steps necessary to
implement a basic CRUD functionality.
Using Cobigen, you can save most of these steps, and get a working result in far less time. We are
going to explain how to use Cobigen to generate the code and classes related to the CRUD operations
of an entity but you can know more about the Cobigen usage in Eclipse.
Cobigen needs a starting point to generate the code of a CRUD case. In this example the starting
point is the StaffMemberEntity class, modelling a member of the staff of our restaurant. So we are
going to create a CRUD for the new StaffMemberEntity class.
Step 1: Entity creation

We are going to create a StaffMember entity. First, we are going to add the database schema to our
database.
In the script resources/db/migration/V0001__Create_schema.sql we add:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

138

Devonfw Guide v2.4.0

CREATE TABLE STAFFMEMBER(
id BIGINT NOT NULL,
modificationCounter INTEGER NOT NULL,
firstname VARCHAR(255),
lastname VARCHAR(255),
login VARCHAR(255)
);
And in the same path, we are going to create a new file (if it do not exist) to add the default data to
the StaffMember created. We create V0002__Master_data.sql file.

INSERT INTO STAFFMEMBER (id, login, firstname,
(0, 'chief', 'Charly', 'Chief', 0);
INSERT INTO STAFFMEMBER (id, login, firstname,
(1, 'cook', 'Carl', 'Cook', 0);
INSERT INTO STAFFMEMBER (id, login, firstname,
(2, 'waiter', 'Willy', 'Waiter', 0);
INSERT INTO STAFFMEMBER (id, login, firstname,
(3, 'barkeeper', 'Bianca', 'Barkeeper', 0);
Now,

we

create

a

new

lastname, modificationCounter) VALUES
lastname, modificationCounter) VALUES
lastname, modificationCounter) VALUES
lastname, modificationCounter) VALUES

StaffMember

entity

in

the

package

devonfw.tutorial.staffmanagement.dataaccess.api with the following code:
Listing 15. StaffMemberEntity.java

package devonfw.tutorial.staffmanagement.dataaccess.api;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.Table;
import devonfw.tutorial.general.dataaccess.api.ApplicationPersistenceEntity;
import devonfw.tutorial.general.dataaccess.api.StaffMember;
//Add imports with respect to the package structure.
/**
*
* The {@link devonfw.tutorial.general.dataaccess.api.ApplicationPersistenceEntity
persistent entity} for
*
* {@link StaffMember}.
*/
@Entity
@Table(name = "StaffMember")
public class StaffMemberEntity extends ApplicationPersistenceEntity implements
StaffMember {

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

139

Devonfw Guide v2.4.0

private static final long serialVersionUID = 1L;
private String name;
private String firstName;
private String lastName;
/**
* The constructor.
*/
public StaffMemberEntity() {
super();
}
@Column(name = "login", unique = true)
@Override
public String getName() {
return this.name;
}
@Override
public void setName(String login) {
this.name = login;
}
@Override
public String getFirstName() {
return this.firstName;
}
@Override
public void setFirstName(String firstName) {
this.firstName = firstName;
}
@Override
public String getLastName() {
return this.lastName;
}
@Override
public void setLastName(String lastName) {

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

140

Devonfw Guide v2.4.0

this.lastName = lastName;
}
}

Step 2: Generate classes
To generate the rest of the classes concerning the StaffMember CRUD, we only have to do a right
click on the StaffMemberEntity.java class in Eclipse Project Explorer and select "CobiGen '
Generate".

This action opens a code generator wizard, like this:

In this wizard you can select which classes you want to generate, organized by layer. In this
example, please select:
• CRUD DAO’s
• CRUD REST services
• CRUD logic layer (all in one)

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

141

Devonfw Guide v2.4.0

• Entity infrastructure
• TO’s
and continue.
In the next step you can select the fields of the entity that you want to expose via the REST service.

Afterwards, click on "Finish" to let CobiGen do its work.
It is possible that you will see a final dialog containing some warnings about
ambiguous imports. You should review the mentioned files, and fix the imports
yourself.

NOTE

In many cases, the imports are easily fixable by letting Eclipse auto-complete them
by pressing "Ctrl-Shift-O".
Cobigen also works incrementally. Cobigen merges your changes and updates all classes based on
the Entity class' fields. So you can use Cobigen to generate the structure and the different classes
and then develop custom parts of your CRUD.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

142

Devonfw Guide v2.4.0

Chapter 32. Creating user permissions
In OASP4J applications the roles and permissions are defined by the PermissionConstants class. The
content of this class is bound with the permissions defined in the access-control-schema.xml file.
Cobigen let us to automatically generate (or update) the content of the PermissionConstants class
from the access-control-schema.xml content. To achieve this we only have to follow two simple
steps.
Step 1: Define the permissions and roles
In

Eclipse

open

the

access-control-schema.xml

located

in

/oasp4j-sample-

core/src/main/resources/config/app/security/access-control-schema.xml and define the permissions to
the roles or group of roles like:










Step 2: Generate the PermissionConstants class
Right click on the access-control-schema.xml and select Cobigen > Generate…
This action opens a code generator wizard, like this:

In this case you have only one option. Select Permissions Constants and press Finish. You should see

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

143

Devonfw Guide v2.4.0

now

the

new

Permissions

added

in

the

file

/oasp4j-sample-

core/src/main/java/io/oasp/gastronomy/restaurant/general/common/api/constants/PermissionConstan
ts.java

public static final String FIND_STAFFMEMBER = "FindStaffMember";
public static final String SAVE_STAFFMEMBER = "SaveStaffMember";
public static final String DELETE_STAFFMEMBER = "DeleteStaffMember";

It is possible that you can’t press Finish button in CobiGen.

NOTE

This happens because you are using an old version of CobiGen and the wizard can’t
merge the class PermissionConstants. To work around this you need to delete the
class PermissionConstants.java and try again. Cobigen will generate for us the class
and will fill it with the updated content.

32.3. Fixing context problems
When launching the Cobigen > Generate wizard you may find problems related to the context, like
the following one

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

144

Devonfw Guide v2.4.0

This happens because you need to update the templates. So do again right click on the accesscontrol-schema.xml and select this time the Cobigen > Health Check option and you will see a
window with a message like the following

Click in Advance Health Check

Now upgrade the template to constants/security_permissions and press OK. You now should be able
to use Cobigen to generate the PermissionConstants class content.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

145

Devonfw Guide v2.4.0

Chapter 33. Transfer-Objects
The technical data model is defined in form of persistent entities. However, passing persistent
entities via call-by-reference across the entire application will soon cause problems:
• Changes to a persistent entity are directly written back to the persistent store when the
transaction is committed. When the entity is send across the application also changes tend to
take place in multiple places endangering data sovereignty and leading to inconsistency.
• You want to send and receive data via services across the network and have to define what
section of your data is actually transferred. If you have relations in your technical model you
quickly end up loading and transferring way too much data.
• Modifications to your technical data model shall not automatically have impact on your
external services causing incompatibilities.
To prevent such problems transfer-objects are used leading to a call-by-value model and decoupling
changes to persistent entities.

33.1. Business-Transfer-Objects
For each persistent entity we create or generate a corresponding entity transfer object (ETO) that
has the same properties except for relations. In order to centralize the properties (getters and
setters with their javadoc) we use a common interface for the entity and its ETO.
If we need to pass an entity with its relation(s) we create a corresponding composite transfer object
(CTO) that only contains other transfer-objects or collections of them. This pattern is illustrated by
the following UML diagram from our sample application.

Figure 1. ETOs and CTOs

Finally, there are typically transfer-objects for data that is never persistent. A common example are
search criteria objects (derived from SearchCriteriaTo in our sample application).

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

146

Devonfw Guide v2.4.0

The logic layer defines these transfer-objects (ETOs, CTOs, etc.) and will only pass such objects
instead of persistent entities.

33.2. Service-Transfer-Objects
If we need to do service versioning and support previous APIs or for external services with a
different view on the data, we create separate transfer-objects to keep the service API stable (see
service layer).

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

147

Devonfw Guide v2.4.0

Chapter 34. Deployment on Tomcat
(Client/Server)
After setting up functional server and client applications, we may want to package both in the same
.war file. To package the single war, follow the given steps.

34.1. General description of the packaging process
The application packaging is based on Maven package functionality. The general overview of the
packaging process is as follows:

34.2. Preparing the client
Firstly (1), both client applications (the Sencha and the Angular one) should contain a java directory
with a pom.xml file which executes the build process (the "production" build, creating a single,
compressed Javascript file from all the application files) through the command (2) mvn install. We
must verify that the information about the groupId, the artifactId and the version are provided
within the pom.xml file where we should find something like

...
com.capgemini.devonfw
extjs-sample
1.0.0-SNAPSHOT
...
So from the client application, in the java directory we launch the command

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

148

Devonfw Guide v2.4.0

myClientApp\java>mvn install
After that, if the process goes right, the client app should have been "installed" in the local Maven
repository of our environment so in the \conf\.m2\repository\com\capgemini\devonfw\extjssample\1.0.0-SNAPSHOT directory we should find the .jar file with the client app packaged

34.3. Preparing the server
The Java server application contains a pom.xml file (3). In this pom.xml file we should add the
dependency to the .jar client that we have just created using the references to the groupId,
artifactId and version that we have specified in the client pom.xml.
So in the pom.xml file of our server project we should add:


com.capgemini.devonfw
extjs-sample
1.0.0-SNAPSHOT
zip
web
runtime

And in the plugins of the pom.xml we should add a reference to the package again within the
 tag:

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

149

Devonfw Guide v2.4.0


org.apache.maven.plugins
maven-war-plugin



com.capgemini.devonfw
extjs-sample
zip
web
jsclient





If you are using a Sencha project as client app you must comment all the
NOTE

 tags from the exec-maven-plugin inside the jsclient profile as this
configuration is related to oasp4js projects.

Now

verify

that

the

server

redirects

to

the

client

checking

the

…

\MyServerApp\server\src\main\webapp\index.jsp file that should be
Listing 16. index.jsp

<%
response.sendRedirect(request.getContextPath() + "/jsclient/");
%>
Then we have to add some unsecured resources in the method configure(HttpSecurity http) of the
general/service/impl/config/BaseWebSecurityConfig.java class.
Edit the unsecureResources to have something like that:

@Override
public void configure(HttpSecurity http) throws Exception {
String[] unsecuredResources =
new String[] { "/login", "/security/**", "/services/rest/login",
"/services/rest/logout", "/jsclient/**"};
(...)
}

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

150

Devonfw Guide v2.4.0

34.4. Packaging the apps
Finally we are going to package both client and server applications into the same .war file. To do
that we must execute the package Maven command (4) from within the projects root directory (the
parent of the server project).

mvn package -P jsclient

34.5. Deploy on Tomcat
To deploy packaged Web Application Archive (.war) file that is integrated with client (Angular or
Sencha Client) on Tomcat7/Tomcat 8, make below changes in java core application pom.xml file.
Example: For "oasp4j" project, make following changes in core application’s "pom.xml" which is
located in "oasp4j/samples/core/pom.xml".
• Modify dependency "spring-boot-starter-web" and add exclusions.
• Add new dependency "spring-boot-starter-tomcat".

...

org.springframework.boot
spring-boot-starter-web


org.springframework.boot
spring-boot-starter-tomcat




org.springframework.boot
spring-boot-starter-tomcat
provided

...
• Comment

the

code

inside

core\src\main\java\io\oasp\gastronomy\restaurant\general\service\impl\config\ServletInitializer.
java. This is not needed as we will be overriding the 'configure' method inside
core\src\main\java\io\oasp\gastronomy\restaurant\SpringBootApp.java.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

151

Devonfw Guide v2.4.0

public class SpringBootApp extends SpringBootServletInitializer {
@Override
protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
return application.sources(SpringBootApp.class);
}
/**
* Entry point for spring-boot based app
*
* @param args - arguments
*/
public static void main(String[] args) {
SpringApplication.run(SpringBootApp.class, args);
}
}
• Activate the 'jsclient' profile in server/pom.xml. Please see the snippet below.



jsclient


true

.....
.....


Build the project and create packaged .war file.
To deploy this .war file on Tomcat 7, follow the steps given below:
1. Go

to

Tomcat

installation

folder

(TOMCAT_HOME)

→

Copy

.war

file

to

"TOMCAT_HOME/webapps" folder .
2. If Tomcat is running, stop it by running "shutdown.bat" file under "TOMCAT_HOME/bin" folder.
3. Delete "TOMCAT_HOME/temp" and "TOMCAT_HOME/work" folders if present. These folders
contain temporary files. (Mandatory to get desired output)
4. Start Tomcat by running "startup.bat" under "TOMCAT_HOME/bin" folder.
5. By default Tomcat will start on port "8080".

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

152

Devonfw Guide v2.4.0

34.6. Running Bootified War
To run bootified war file , follow the steps given below:
1. cd oasp4j\samples
2. Execute 'mvn clean install'
3. cd oasp4j\samples\server\target.
4. Execute 'java -jar oasp4j-sample-server-bootified.war'

34.6.1. Application context root
In the case of bootified war, the context root will be '/' and not 'oasp4j-sample-server'.
So, to access the application after the bootified war is launched , one has to access it via
http://localhost:8080/login or if the user wants to have a context root , then they can define the
context 'oasp4j-sample-server' in oasp4j\samples\core\src\main\resources\application.properties.
Make sure oasp4j\samples is built by executing 'mvn clean install' for this oasp4j\samples project
and access it via http://localhost:8080/oasp4j-sample-server. The context root defined in
oasp4j\samples\core\src\main\resources\config\application.properties will not be available since it
is excluded from the war that is generated.

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

153

Devonfw Guide v2.4.0

Chapter 35. Cookbook
35.1. Devonfw Modules

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

154

Devonfw Guide v2.4.0

Chapter 36. The Reporting module - Report
generation with JasperReports
Reporting is a fundamental part of the larger movement towards the improved business
intelligence and knowledge management. Often, the implementation involves extract, transform,
and load (ETL) procedures in coordination with a data warehouse and then using one or more
reporting tools. With this module, Devon provides an implementation of one of these reporting
tools based on the Jasper Reports library.
JasperReports is an open source Java reporting tool that can write to a variety of targets, such as:
screen, a printer, into PDF, HTML, Microsoft Excel, RTF, ODT, Comma-separated values or XML files.
It can be used in Java-enabled applications, including Java EE or web applications, to generate
dynamic content. It reads its instructions from an XML or .jasper file.
For more information, visit JasperReports

36.1. Include Reporting in a Devon project
The Reporting module provides you a report generator for your Devon applications. To implement
the Reporting module in a Devon project, you must follow these steps:

36.1.1. Step 1: Adding the starter in your project
Include the starter in your pom.xml, verify that the version matches the last available version of the
module.


com.devonfw.starter
devonfw-reporting-starter
${devonfw.version}


36.1.2. Step 2: Properties configuration
NOTE

This step is only needed in case you are going to generate .txt reports.

In order to use the Reporting module for creating txt reports, it is necessary to define some
parameters related to the size of the elements in the application.properties file in the project.

# Reporting module params
devon.reporting.txtConfig.CharWidth=7
devon.reporting.txtConfig.CharHeight=13.9
devon.reporting.txtConfig.PageWidthInChars=80
devon.reporting.txtConfig.PageHeightInChars=47

This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).

155

Devonfw Guide v2.4.0

36.2. Basic implementation
First and foremost, you need to add the scanner for dependency injection. To do so, you must add
the following annotations in the SpringBoot main class:

@Configuration
@ComponentScan(basePackages = { "com.devonfw.module.reporting" })
@EnableAutoConfiguration
public class MyBootApp {
[...]
}
Remember to include the package of the module in the basePackages attribute of the @ComponentScan
annotation alongside the packages for the rest of the relevant Spring Boot components.

@ComponentScan(basePackages = { "com.devonfw.module.reporting" ,
"my.other.component.location.package" })
As you can see, the basePackages of the @ComponentScan points to the Reporting module package.
Now, you can start using the module.

36.2.1. The injection of the module
To access the module functionalities, you need to inject the module in a private property, it can be
done using the @Inject annotation

public class MyClass {
@Inject
private Reporting